docs(agent-ui): 기준선을 생성한다

2026-06-25 10:52:13 +09:00 · 2026-06-25 10:52:13 +09:00 · d25edf8c67
commit d25edf8c67
parent b9842b76bf
9 changed files with 263 additions and 0 deletions
--- a/agent-ui/README.md
+++ b/agent-ui/README.md
@ -0,0 +1,36 @@
+---
+ui_doc_type: readme
+surface_type: ops-dev
+---
+
+# agent-ui
+
+이 디렉터리는 AI agent와 사람이 Gito UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다.
+
+## 대상
+
+- 1차 대상: ops/dev UI
+- 현재 기준: Flutter control surface scaffold
+- 확장 후보: product UI 레이어는 요청이 있을 때 brand, content, assets, tokens, motion을 추가한다.
+
+## 구조
+
+- `definition/`: 현재 UI 정의 source of truth
+- `frame/`: visual source가 있는 view의 wireframe 연결
+- `.sync-state.json`: agent-ui -> code 동기화 기준점
+- `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문
+- `archive/user-review/`: 해결된 사용자 리뷰 로그
+
+## 기본 규칙
+
+- 현재 기준은 `definition/**`에 둔다.
+- visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다.
+- `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다.
+- 초기 생성 이후 기본 흐름은 `agent-ui -> code` 방향이다.
+- `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다.
+
+## 생성 기준
+
+- Source mode: `code-first`
+- Baseline evidence: `apps/client/lib/main.dart`, `README.md`, `docs/architecture.md`, `agent-roadmap/phase/agent-shell-iop-execution/PHASE.md`, `agent-roadmap/phase/agent-shell-iop-execution/milestones/iop-agent-run-bridge.md`
+- 생성일: 2026-06-25
--- a/agent-ui/archive/user-review/.gitkeep
+++ b/agent-ui/archive/user-review/.gitkeep
@ -0,0 +1 @@
+
--- a/agent-ui/definition/archive/components/.gitkeep
+++ b/agent-ui/definition/archive/components/.gitkeep
@ -0,0 +1 @@
+
--- a/agent-ui/definition/archive/views/.gitkeep
+++ b/agent-ui/definition/archive/views/.gitkeep
@ -0,0 +1 @@
+
--- a/agent-ui/definition/components/index.md
+++ b/agent-ui/definition/components/index.md
@ -0,0 +1,18 @@
+---
+ui_doc_type: components-index
+components: []
+---
+
+# Component Definitions
+
+## Component List
+
+| Component ID | Status | Evidence | Description |
+|--------------|--------|----------|-------------|
+| 없음 | - | - | 현재 반복 component로 분리할 구현 근거가 없다. |
+
+## Rules
+
+- component 정의는 구현 API가 아니라 UI 사용 규칙을 다룬다.
+- view별 변형이 필요하면 `<component-id>/<variant>.md` 또는 하위 디렉터리를 사용한다.
+- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다.
--- a/agent-ui/definition/index.md
+++ b/agent-ui/definition/index.md
@ -0,0 +1,65 @@
+---
+ui_doc_type: definition-index
+surface_type: ops-dev
+source_evidence:
+  - type: code
+    path: apps/client/lib/main.dart
+    notes: MaterialApp home으로 GitoHomePage가 연결된 단일 Flutter control surface scaffold.
+  - type: docs
+    path: README.md
+    notes: Gito는 platformless Git control plane이며 Flutter client는 control surface 경계만 잡혀 있음.
+  - type: docs
+    path: docs/architecture.md
+    notes: agent-shell은 UI package, iop는 backend/runtime을 소유하는 구조.
+  - type: docs
+    path: agent-roadmap/phase/agent-shell-iop-execution/milestones/iop-agent-run-bridge.md
+    notes: 현재 Milestone은 Flutter UI를 범위 제외로 두고 backend bridge를 다룸.
+  - type: user
+    path: null
+    notes: 사용자가 agent-ui 생성을 요청함.
+---
+
+# UI Definition
+
+## Purpose
+
+Gito의 Flutter control surface scaffold를 기준으로 현재 구현된 화면과 향후 UI 동기화 기준을 기록한다. 초기 기준은 ops/dev UI이며, product UI 전용 레이어는 아직 생성하지 않는다.
+
+## Surface Type
+
+- Type: ops-dev
+- Notes: 현재 Flutter client는 control surface 경계만 있는 상태다. Product UI 확장은 별도 요청 또는 agent-shell 통합 결정 이후 추가한다.
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/main.dart` | `MaterialApp`의 `home`이 `GitoHomePage`로 연결되어 있고, 본문은 `Gito control surface` 텍스트만 표시한다. |
+| docs | `README.md` | Flutter client는 control surface 경계만 잡혀 있으며, agent interaction UI는 sibling `../agent-shell` package를 사용하는 방향이다. |
+| docs | `docs/architecture.md` | `../agent-shell`은 UI/domain package, `../iop`는 backend/runtime 소유로 분리한다. |
+| docs | `agent-roadmap/phase/agent-shell-iop-execution/milestones/iop-agent-run-bridge.md` | 현재 Milestone은 Flutter UI를 범위 제외로 두며 backend bridge를 다룬다. |
+| user | 없음 | 사용자가 agent-ui 생성을 요청했다. |
+
+## Structure
+
+- `views/`: 화면 또는 업무 단위 정의
+- `components/`: 반복 UI 구성요소 정의
+- `archive/`: 현재 기준이 아닌 과거 정의/결정 로그
+
+## Reading Rules
+
+- 현재 UI 동기화는 이 디렉터리의 활성 문서를 기준으로 한다.
+- `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다.
+
+## Sync Rules
+
+- frame-view가 있으면 view region id와 frame region id는 동일해야 한다.
+- view에서 참조한 component id는 `components/` 아래에 정의되어야 한다.
+- frame은 definition을 대체하지 않는다.
+- `구현됨`, `계획`, `가정`, `불명확` 상태는 근거 기준과 맞춰 쓴다.
+- 기본 코드 동기화는 `.sync-state.json` 기준 이후 변경분만 대상으로 한다.
+- 전체 동기화는 사용자가 명시한 경우에만 수행한다.
+
+## Decision History
+
+- 2026-06-25: 기존 Flutter scaffold와 프로젝트 문서를 근거로 `code-first` agent-ui 기준선을 생성했다.
--- a/agent-ui/definition/views/home/index.md
+++ b/agent-ui/definition/views/home/index.md
@ -0,0 +1,83 @@
+---
+ui_doc_type: view
+view_id: home
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: apps/client/lib/main.dart
+    notes: GitoHomePage가 Scaffold body 중앙에 "Gito control surface" 텍스트를 표시한다.
+  - type: docs
+    path: README.md
+    notes: Flutter client는 control surface scaffold 상태이며 operation event 구독과 화면 구성은 아직 구현 전이다.
+  - type: docs
+    path: docs/architecture.md
+    notes: agent interaction UI는 sibling agent-shell package로 붙이고 backend/runtime은 iop가 소유한다.
+  - type: user
+    path: null
+    notes: 사용자가 agent-ui 생성을 요청했다.
+regions:
+  - home.body
+---
+
+# Home
+
+View ID: `home`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/main.dart` | `GitoHomePage`가 `Scaffold` body 중앙에 `Gito control surface` 텍스트를 표시한다. |
+| docs | `README.md` | Flutter client는 control surface scaffold 상태이며 operation event 구독과 화면 구성은 아직 구현 전이다. |
+| docs | `docs/architecture.md` | agent interaction UI는 sibling `agent-shell` package로 붙이고 backend/runtime은 `iop`가 소유한다. |
+| user | 없음 | 사용자가 agent-ui 생성을 요청했다. |
+
+## Purpose
+
+Gito Flutter client의 현재 진입 화면이다. 아직 실제 operation, repository, event 정보를 보여주지 않고 control surface placeholder 역할만 한다.
+
+## Primary Users
+
+- Gito 운영자 또는 개발자
+
+## Primary Tasks
+
+- 앱이 control surface scaffold로 실행되는지 확인한다.
+
+## Information Priority
+
+1. 현재 앱이 Gito control surface임을 알리는 placeholder text
+2. 향후 repository, workspace operation, event stream을 담을 화면 영역
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `home.body` | 단일 placeholder body 영역 | 없음 | high | 현재는 centered text만 구현되어 있다. |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| 없음 | 없음 | 없음 | 없음 |
+
+## States
+
+- loading: 현재 구현 없음
+- empty: 현재 구현 없음
+- error: 현재 구현 없음
+- permission-denied: 현재 구현 없음
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-25: `apps/client/lib/main.dart`의 `GitoHomePage`를 `home` view 기준선으로 등록했다.
--- a/agent-ui/definition/views/index.md
+++ b/agent-ui/definition/views/index.md
@ -0,0 +1,32 @@
+---
+ui_doc_type: views-index
+views:
+  - home
+---
+
+# View Definitions
+
+## View Tree
+
+| View ID | Status | Evidence | Description |
+|---------|--------|----------|-------------|
+| `home` | 구현됨 | `apps/client/lib/main.dart` | Gito Flutter client의 현재 단일 home view. |
+
+## Navigation
+
+- 현재 구현된 route/navigation 분기는 없다. `MaterialApp.home`이 `home` view로 직접 연결된다.
+
+## Common States
+
+- loading
+- empty
+- error
+- permission-denied
+
+## Common Permissions
+
+- 없음: 현재 구현된 권한 분기나 action guard가 없다.
+
+## Open Questions
+
+- 없음
--- a/agent-ui/frame/index.md
+++ b/agent-ui/frame/index.md
@ -0,0 +1,26 @@
+---
+ui_doc_type: frame-index
+frames: []
+---
+
+# UI Frames
+
+## Purpose
+
+이 디렉터리는 visual source가 있는 view의 wireframe과 definition 연결 정보를 보관한다.
+
+## Frame Sources
+
+- `views/<view-id>/index.md`: visual source가 있는 view의 frame 연결 문서
+- `views/<view-id>/wire.excalidraw`: 선택 visual source
+
+## Rules
+
+- frame은 definition을 대체하지 않는다.
+- visual source가 있으면 대응되는 frame index에 기록한다.
+- visual source가 없으면 `views/<view-id>/`를 만들지 않는다.
+- frame-view가 있으면 frame region id는 definition region id와 동일해야 한다.
+
+## Current Frames
+
+- 없음: 현재 visual source가 없어 view별 frame 문서를 만들지 않았다.