From d25edf8c672d3290df9cabf238c07da35e1eb422 Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 25 Jun 2026 10:52:13 +0900 Subject: [PATCH] =?UTF-8?q?docs(agent-ui):=20=EA=B8=B0=EC=A4=80=EC=84=A0?= =?UTF-8?q?=EC=9D=84=20=EC=83=9D=EC=84=B1=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agent-ui/README.md | 36 ++++++++ agent-ui/archive/user-review/.gitkeep | 1 + .../definition/archive/components/.gitkeep | 1 + agent-ui/definition/archive/views/.gitkeep | 1 + agent-ui/definition/components/index.md | 18 ++++ agent-ui/definition/index.md | 65 +++++++++++++++ agent-ui/definition/views/home/index.md | 83 +++++++++++++++++++ agent-ui/definition/views/index.md | 32 +++++++ agent-ui/frame/index.md | 26 ++++++ 9 files changed, 263 insertions(+) create mode 100644 agent-ui/README.md create mode 100644 agent-ui/archive/user-review/.gitkeep create mode 100644 agent-ui/definition/archive/components/.gitkeep create mode 100644 agent-ui/definition/archive/views/.gitkeep create mode 100644 agent-ui/definition/components/index.md create mode 100644 agent-ui/definition/index.md create mode 100644 agent-ui/definition/views/home/index.md create mode 100644 agent-ui/definition/views/index.md create mode 100644 agent-ui/frame/index.md diff --git a/agent-ui/README.md b/agent-ui/README.md new file mode 100644 index 0000000..f33713c --- /dev/null +++ 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 diff --git a/agent-ui/archive/user-review/.gitkeep b/agent-ui/archive/user-review/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/agent-ui/archive/user-review/.gitkeep @@ -0,0 +1 @@ + diff --git a/agent-ui/definition/archive/components/.gitkeep b/agent-ui/definition/archive/components/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/agent-ui/definition/archive/components/.gitkeep @@ -0,0 +1 @@ + diff --git a/agent-ui/definition/archive/views/.gitkeep b/agent-ui/definition/archive/views/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/agent-ui/definition/archive/views/.gitkeep @@ -0,0 +1 @@ + diff --git a/agent-ui/definition/components/index.md b/agent-ui/definition/components/index.md new file mode 100644 index 0000000..d7d7fd8 --- /dev/null +++ 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별 변형이 필요하면 `/.md` 또는 하위 디렉터리를 사용한다. +- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다. diff --git a/agent-ui/definition/index.md b/agent-ui/definition/index.md new file mode 100644 index 0000000..9f7f66f --- /dev/null +++ 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 기준선을 생성했다. diff --git a/agent-ui/definition/views/home/index.md b/agent-ui/definition/views/home/index.md new file mode 100644 index 0000000..38f25e6 --- /dev/null +++ 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 기준선으로 등록했다. diff --git a/agent-ui/definition/views/index.md b/agent-ui/definition/views/index.md new file mode 100644 index 0000000..4a56074 --- /dev/null +++ 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 + +- 없음 diff --git a/agent-ui/frame/index.md b/agent-ui/frame/index.md new file mode 100644 index 0000000..875272e --- /dev/null +++ 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//index.md`: visual source가 있는 view의 frame 연결 문서 +- `views//wire.excalidraw`: 선택 visual source + +## Rules + +- frame은 definition을 대체하지 않는다. +- visual source가 있으면 대응되는 frame index에 기록한다. +- visual source가 없으면 `views//`를 만들지 않는다. +- frame-view가 있으면 frame region id는 definition region id와 동일해야 한다. + +## Current Frames + +- 없음: 현재 visual source가 없어 view별 frame 문서를 만들지 않았다.