From 5704bf5a4e13daceccc5fe77eaa2aca3d9c776ea Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 24 Jun 2026 15:30:49 +0900 Subject: [PATCH] add agent-ui related rules, skills and update common rules --- .clinerules | 2 + .cursorrules | 2 + AGENTS.md | 2 + CLAUDE.md | 2 + GEMINI.md | 2 + agent-ops/rules/common/rules-agent-ui.md | 95 ++++++++++++++ agent-ops/rules/common/rules.md | 2 + agent-ops/rules/project/rules.md | 4 + .../agent-ui/archive-log-template.md | 15 +++ .../agent-ui/component-index-template.md | 35 +++++ .../agent-ui/components-index-template.md | 11 ++ .../agent-ui/definition-index-template.md | 31 +++++ .../agent-ui/frame-index-template.md | 16 +++ .../agent-ui/frame-view-index-template.md | 27 ++++ .../_templates/agent-ui/readme-template.md | 22 ++++ .../agent-ui/user-review-template.md | 15 +++ .../agent-ui/view-index-template.md | 50 ++++++++ .../agent-ui/views-index-template.md | 24 ++++ .../skills/common/create-agent-ui/SKILL.md | 98 ++++++++++++++ agent-ops/skills/common/router.md | 3 + .../skills/common/update-agent-ui/SKILL.md | 102 +++++++++++++++ .../skills/common/validate-agent-ui/SKILL.md | 121 ++++++++++++++++++ agent-ui-struct.txt | 68 ++++++++++ 23 files changed, 749 insertions(+) create mode 100644 agent-ops/rules/common/rules-agent-ui.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/archive-log-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/component-index-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/components-index-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/definition-index-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/frame-index-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/readme-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/user-review-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/view-index-template.md create mode 100644 agent-ops/skills/common/_templates/agent-ui/views-index-template.md create mode 100644 agent-ops/skills/common/create-agent-ui/SKILL.md create mode 100644 agent-ops/skills/common/update-agent-ui/SKILL.md create mode 100644 agent-ops/skills/common/validate-agent-ui/SKILL.md create mode 100644 agent-ui-struct.txt diff --git a/.clinerules b/.clinerules index cc67f4a..2befc28 100644 --- a/.clinerules +++ b/.clinerules @@ -9,6 +9,7 @@ - 불확실하면 단정하지 말고 후보를 제시한다. - `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, 또는 plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우에만 필요한 파일을 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. - `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. +- `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. - 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. @@ -29,6 +30,7 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- agent-ui 생성/갱신/검증, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 diff --git a/.cursorrules b/.cursorrules index cc67f4a..2befc28 100644 --- a/.cursorrules +++ b/.cursorrules @@ -9,6 +9,7 @@ - 불확실하면 단정하지 말고 후보를 제시한다. - `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, 또는 plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우에만 필요한 파일을 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. - `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. +- `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. - 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. @@ -29,6 +30,7 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- agent-ui 생성/갱신/검증, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 diff --git a/AGENTS.md b/AGENTS.md index cc67f4a..2befc28 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,7 @@ - 불확실하면 단정하지 말고 후보를 제시한다. - `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, 또는 plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우에만 필요한 파일을 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. - `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. +- `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. - 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. @@ -29,6 +30,7 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- agent-ui 생성/갱신/검증, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 diff --git a/CLAUDE.md b/CLAUDE.md index cc67f4a..2befc28 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,7 @@ - 불확실하면 단정하지 말고 후보를 제시한다. - `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, 또는 plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우에만 필요한 파일을 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. - `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. +- `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. - 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. @@ -29,6 +30,7 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- agent-ui 생성/갱신/검증, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 diff --git a/GEMINI.md b/GEMINI.md index cc67f4a..2befc28 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -9,6 +9,7 @@ - 불확실하면 단정하지 말고 후보를 제시한다. - `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, 또는 plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우에만 필요한 파일을 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. - `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. +- `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. - 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. @@ -29,6 +30,7 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- agent-ui 생성/갱신/검증, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 diff --git a/agent-ops/rules/common/rules-agent-ui.md b/agent-ops/rules/common/rules-agent-ui.md new file mode 100644 index 0000000..cf8373c --- /dev/null +++ b/agent-ops/rules/common/rules-agent-ui.md @@ -0,0 +1,95 @@ +# agent-ui 규칙 + +`agent-ui/`가 있는 프로젝트 또는 agent-ui 생성, 갱신, 검증 요청에서 적용한다. + +## 목적 + +`agent-ui/`는 AI agent와 사람이 UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다. +초기 기준은 ops/dev UI이며, product UI는 같은 구조 위에 brand, content, assets, tokens, motion 같은 레이어를 추가할 수 있다. + +## 기본 구조 + +```text +agent-ui/ + README.md + USER_REVIEW.md # 선택: 사용자 판단이 필요한 활성 리뷰 + archive/ + user-review/ + user_review_001.log + + definition/ + index.md + views/ + index.md + / + index.md + components/ + index.md + / + index.md + archive/ + views/ + / + index.log + components/ + / + index.log + + frame/ + index.md + views/ + / + index.md + wire.excalidraw # 선택: 1차 visual source 후보 +``` + +## Source of Truth + +- `agent-ui/definition/**`은 현재 UI 정의의 source of truth다. +- `agent-ui/frame/**`은 와이어프레임과 visual source를 연결하는 보조 자료다. +- `.excalidraw` 파일만으로 현재 UI 기준을 확정하지 않는다. 반드시 대응되는 `frame/views//index.md`가 있어야 한다. +- `frame/views//index.md`는 대응되는 `definition/views//index.md`를 가리켜야 한다. +- 화면 의도, 상태, 액션, 정보 우선순위는 definition에 둔다. +- 배치, 밀도, 시각적 영역 관계는 frame에 둔다. + +## 명명 규칙 + +- view id, component id, 파일명, 디렉터리명은 kebab-case를 사용한다. +- view 기준 문서는 `definition/views//index.md`에 둔다. +- component 기준 문서는 `definition/components//index.md`에 둔다. +- 같은 레벨에서 `.md`와 `/`를 함께 두지 않는다. +- 하위 정의가 필요하면 `/index.md`와 `/.md`를 사용한다. + +## ID 규칙 + +- region id는 `.` 형식을 사용한다. +- 하위 region은 `..` 형식을 사용할 수 있다. +- component id는 `definition/components/` 아래 경로에서 `index.md`를 제외한 path id로 본다. 예: `data-table`, `data-table/job-list`. +- view 정의서의 region id와 frame 정의서의 region id는 동일해야 한다. +- view에서 참조한 component id는 대응되는 component 정의 문서가 있어야 한다. + +## Archive 접근 + +- `agent-ui/definition/archive/**`는 일반 작업에서 읽지 않는다. +- `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. +- 예외: 사용자가 과거 결정 확인, 복원, 비교, 특정 archive 경로 확인, 해결된 user review 확인을 요청한 경우에만 필요한 파일을 좁게 읽는다. +- validate 작업은 archive 경로 존재 여부와 tree 대응 여부를 확인할 수 있지만, 위 예외가 없으면 archive 본문을 읽지 않는다. + +## USER_REVIEW + +- agent가 확정할 수 없는 UI 의도, 화면 구조, region 추가/삭제, component 신규 생성 여부, page/drawer/split 같은 UX 결정은 `agent-ui/USER_REVIEW.md`에 남긴다. +- 해결된 user review는 `agent-ui/archive/user-review/user_review_N.log`로 이동할 수 있다. +- `USER_REVIEW.md`가 있으면 관련 agent-ui 갱신이나 검증 결과에 남은 review id를 보고한다. + +## Excalidraw + +- 1차 visual source 후보는 `wire.excalidraw`다. +- VS Code Excalidraw extension은 초기 편집 워크플로우로 사용할 수 있다. +- excalidraw.com import/export 워크플로우는 기본 표준으로 삼지 않는다. +- Excalidraw self-host는 R&D 후보이며, 기본 agent-ui scaffold의 필수 조건이 아니다. + +## 스킬 + +- agent-ui 초기 scaffold 생성은 `create-agent-ui`를 사용한다. +- view, component, frame 갱신은 `update-agent-ui`를 사용한다. +- 구조와 정합성 검사, 자동 보정, USER_REVIEW 생성은 `validate-agent-ui`를 사용한다. diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index cc67f4a..2befc28 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -9,6 +9,7 @@ - 불확실하면 단정하지 말고 후보를 제시한다. - `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, 또는 plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우에만 필요한 파일을 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. - `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. +- `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. - 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. @@ -29,6 +30,7 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- agent-ui 생성/갱신/검증, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index cda06d6..a11a549 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -116,6 +116,7 @@ proto/ # OTO runner/server protobuf contract ## 스킬 기반 작업 흐름 - agent-ops 초기화, domain rule 생성, skill 생성, commit/push, agent-ops sync 계열 요청은 사용자가 명시적으로 요청한 경우에만 `agent-ops/skills/common/router.md`를 먼저 읽고 해당 `SKILL.md`를 따른다. +- agent-ui 생성/갱신/검증, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의 요청은 `agent-ops/skills/common/router.md`를 먼저 읽고 해당 `SKILL.md`를 따른다. - 도메인 룰 갱신/검토 요청은 `agent-ops/skills/common/update-domain-rule/SKILL.md`를 따른다. - 새 도메인 rule 생성이 필요한 경우 `agent-ops/skills/common/create-domain-rule/SKILL.md`를 따른다. - YAML 작성 요청은 코드 분석보다 `sample` 도메인 rule과 `apps/runner/assets/yaml/sample/**`를 우선 참조한다. @@ -181,6 +182,9 @@ proto/ # OTO runner/server protobuf contract | 도메인 업데이트, domain rule 갱신, 도메인 검토, domain 스캔 | `agent-ops/skills/common/update-domain-rule/SKILL.md` 수행 | | domain rule 만들어줘, rules.md 생성, 새 도메인 규칙 | `agent-ops/skills/common/create-domain-rule/SKILL.md` 수행 | | skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` 수행 | +| agent-ui 생성, UI 스캐폴드 생성, UI 정의 구조 생성, 화면 정의 구조 생성, agent-ui scaffold | `agent-ops/skills/common/create-agent-ui/SKILL.md` 수행 | +| agent-ui 갱신, agent-ui 업데이트, view 추가, component 추가, frame 추가, wireframe 추가, 화면 정의 갱신, 화면 정의서 갱신 | `agent-ops/skills/common/update-agent-ui/SKILL.md` 수행 | +| agent-ui 검증, agent-ui validate, UI 정의 정합성 확인, wireframe 정합성 확인, UI 스캐폴드 검사 | `agent-ops/skills/common/validate-agent-ui/SKILL.md` 수행 | | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` 수행 | | 로드맵 업데이트, roadmap 갱신, 마일스톤 갱신, phase 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` 수행 | | 계획 세워줘, 구현 계획, PLAN.md, plan | `agent-ops/skills/common/plan/SKILL.md` 수행 | diff --git a/agent-ops/skills/common/_templates/agent-ui/archive-log-template.md b/agent-ops/skills/common/_templates/agent-ui/archive-log-template.md new file mode 100644 index 0000000..7ab7fb7 --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/archive-log-template.md @@ -0,0 +1,15 @@ +# log + +## + +### Changed + +- <변경 또는 폐기된 정의> + +### Reason + +- <변경 이유> + +### Superseded + +- <대체된 이전 기준 또는 없음> diff --git a/agent-ops/skills/common/_templates/agent-ui/component-index-template.md b/agent-ops/skills/common/_templates/agent-ui/component-index-template.md new file mode 100644 index 0000000..fdbcbd1 --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/component-index-template.md @@ -0,0 +1,35 @@ +# + +Component ID: `` + +## Purpose + +<이 component가 해결하는 UI 문제를 적는다.> + +## Used By + +- ``: <사용 위치 또는 region id> + +## Anatomy + +- <구성 부분> + +## Variants + +- default: <기본 사용> + +## States + +- default +- loading +- empty +- error +- disabled + +## Rules + +- <사용 규칙> + +## Decision History + +- : <현재 기준으로 남길 결정 요약> diff --git a/agent-ops/skills/common/_templates/agent-ui/components-index-template.md b/agent-ops/skills/common/_templates/agent-ui/components-index-template.md new file mode 100644 index 0000000..bf65304 --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/components-index-template.md @@ -0,0 +1,11 @@ +# Component Definitions + +## Component List + +- ``: <반복 UI 구성요소 설명> + +## Rules + +- component 정의는 구현 API가 아니라 UI 사용 규칙을 다룬다. +- view별 변형이 필요하면 `/.md` 또는 하위 디렉터리를 사용한다. +- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다. diff --git a/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md b/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md new file mode 100644 index 0000000..ec81702 --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md @@ -0,0 +1,31 @@ +# UI Definition + +## Purpose + +<이 agent-ui가 다루는 UI 표면과 목표를 적는다.> + +## Surface Type + +- Type: ops-dev +- Notes: + +## Structure + +- `views/`: 화면 또는 업무 단위 정의 +- `components/`: 반복 UI 구성요소 정의 +- `archive/`: 현재 기준이 아닌 과거 정의/결정 로그 + +## Reading Rules + +- 현재 UI 동기화는 이 디렉터리의 활성 문서를 기준으로 한다. +- `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다. + +## Sync Rules + +- view region id와 frame region id는 동일해야 한다. +- view에서 참조한 component id는 `components/` 아래에 정의되어야 한다. +- frame은 definition을 대체하지 않는다. + +## Decision History + +- : <초기 결정 또는 변경 요약> diff --git a/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md b/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md new file mode 100644 index 0000000..cda599c --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md @@ -0,0 +1,16 @@ +# UI Frames + +## Purpose + +이 디렉터리는 view별 wireframe, visual source, definition 연결 정보를 보관한다. + +## Frame Sources + +- `views//index.md`: view별 frame 연결 문서 +- `views//wire.excalidraw`: 선택 visual source + +## Rules + +- frame은 definition을 대체하지 않는다. +- visual source가 있으면 대응되는 frame index에 기록한다. +- frame region id는 definition region id와 동일해야 한다. diff --git a/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md b/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md new file mode 100644 index 0000000..8934a03 --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md @@ -0,0 +1,27 @@ +# Frame + +Definition: +- `../../../definition/views//index.md` + +Visual Source: +- `wire.excalidraw` + +## Frame Intent + +- <이 frame이 검증하려는 배치, 밀도, 시선 흐름을 적는다.> + +## Required Regions + +- `.`: + +## Layout Notes + +- desktop: <배치 기준> +- tablet: <배치 기준> +- mobile: <배치 기준> + +## Sync Rules + +- visual source의 박스 라벨은 가능한 한 region id를 포함한다. +- definition에 없는 region을 frame에 추가하지 않는다. 필요한 경우 `agent-ui/USER_REVIEW.md`에 남긴다. +- frame에서 제거한 region은 definition에서도 제거 대상인지 확인한다. diff --git a/agent-ops/skills/common/_templates/agent-ui/readme-template.md b/agent-ops/skills/common/_templates/agent-ui/readme-template.md new file mode 100644 index 0000000..679adfb --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/readme-template.md @@ -0,0 +1,22 @@ +# agent-ui + +이 디렉터리는 AI agent와 사람이 UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다. + +## 대상 + +- 1차 대상: ops/dev UI +- 확장 후보: product UI + +## 구조 + +- `definition/`: 현재 UI 정의 source of truth +- `frame/`: view별 wireframe과 visual source 연결 +- `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문 +- `archive/user-review/`: 해결된 사용자 리뷰 로그 + +## 기본 규칙 + +- 현재 기준은 `definition/**`에 둔다. +- visual wireframe은 `frame/**`에 둔다. +- `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다. +- `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다. diff --git a/agent-ops/skills/common/_templates/agent-ui/user-review-template.md b/agent-ops/skills/common/_templates/agent-ui/user-review-template.md new file mode 100644 index 0000000..5bba20c --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/user-review-template.md @@ -0,0 +1,15 @@ +# agent-ui 사용자 리뷰 + +이 문서는 agent가 확정할 수 없는 UI 결정을 사용자에게 넘기기 위한 활성 리뷰 문서다. +해결된 항목은 `agent-ui/archive/user-review/user_review_N.log`로 이동할 수 있다. + +## Review Items + +- [ ] [UIR-001] <결정이 필요한 질문> + - Context: <관련 view/component/frame 경로> + - Options: <후보가 있으면 적는다> + - Needed For: <차단되는 작업> + +## Notes + +- 없음 diff --git a/agent-ops/skills/common/_templates/agent-ui/view-index-template.md b/agent-ops/skills/common/_templates/agent-ui/view-index-template.md new file mode 100644 index 0000000..0cea395 --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/view-index-template.md @@ -0,0 +1,50 @@ +# + +View ID: `` + +Frame: +- `../../../frame/views//index.md` + +## Purpose + +<이 view의 목적을 1-3줄로 적는다.> + +## Primary Users + +- <사용자 역할> + +## Primary Tasks + +- <사용자 작업> + +## Information Priority + +1. <가장 먼저 보여야 하는 정보> +2. <다음 우선순위 정보> + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `.` | <역할> | `` | high | <비고> | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `.` | <사용자 입력> | <결과> | <권한/상태 조건> | + +## States + +- loading: <표시 기준> +- empty: <표시 기준> +- error: <표시 기준> +- permission-denied: <표시 기준> + +## Open Questions + +- 없음 + +## Decision History + +- : <현재 기준으로 남길 결정 요약> diff --git a/agent-ops/skills/common/_templates/agent-ui/views-index-template.md b/agent-ops/skills/common/_templates/agent-ui/views-index-template.md new file mode 100644 index 0000000..1814bac --- /dev/null +++ b/agent-ops/skills/common/_templates/agent-ui/views-index-template.md @@ -0,0 +1,24 @@ +# View Definitions + +## View Tree + +- ``: <화면 또는 업무 단위 설명> + +## Navigation + +- `` -> ``: <이동 조건 또는 사용자 작업> + +## Common States + +- loading +- empty +- error +- permission-denied + +## Common Permissions + +- <권한 이름>: <허용되는 view/action> + +## Open Questions + +- 없음 diff --git a/agent-ops/skills/common/create-agent-ui/SKILL.md b/agent-ops/skills/common/create-agent-ui/SKILL.md new file mode 100644 index 0000000..778c205 --- /dev/null +++ b/agent-ops/skills/common/create-agent-ui/SKILL.md @@ -0,0 +1,98 @@ +--- +name: create-agent-ui +version: 1.0.0 +description: agent-ui 기본 스캐폴드와 UI 정의, view/component/frame 문서 baseline을 생성하는 스킬 +--- + +# create-agent-ui + +## 목적 + +프로젝트에 `agent-ui/` 기본 구조를 생성한다. +ops/dev UI를 1차 대상으로 하며, definition과 frame을 분리해 AI와 사람이 UI 의도를 동기화할 수 있게 만든다. + +## 언제 호출할지 + +- 사용자가 agent-ui 생성, UI 스캐폴드 생성, 화면 정의 구조 생성을 요청할 때 +- 프로젝트에 `agent-ui/`가 없고 UI 정의 문맥을 만들 때 +- ops/dev UI를 위한 view/component/frame 문서 baseline이 필요할 때 + +## 입력 + +- `surface-type`: `ops-dev` 또는 `product`. 기본값은 `ops-dev` (선택) +- `views`: 초기 생성할 view id 목록, kebab-case (선택) +- `components`: 초기 생성할 component id 목록, kebab-case 또는 path id (선택) + +## 먼저 확인할 것 + +- [ ] `agent-ops/rules/common/rules-agent-ui.md`를 읽는다. +- [ ] 생성 대상 `agent-ui/` 존재 여부를 확인한다. +- [ ] 기존 `agent-ui/`가 있으면 덮어쓰지 않고 `update-agent-ui` 또는 `validate-agent-ui` 대상인지 보고한다. +- [ ] 템플릿 경로 `agent-ops/skills/common/_templates/agent-ui/` 하위 파일을 확인한다. + +## 실행 절차 + +1. **생성 대상 확정** + - 생성 루트는 `agent-ui/`로 고정한다. + - `surface-type`이 없으면 `ops-dev`로 둔다. + - product UI가 명시되어도 기본 구조는 유지하고 product 전용 레이어는 요청된 경우에만 추가 후보로 보고한다. + +2. **기본 구조 생성** + - 다음 활성 문서를 템플릿 기준으로 만든다. + - `agent-ui/README.md` + - `agent-ui/definition/index.md` + - `agent-ui/definition/views/index.md` + - `agent-ui/definition/components/index.md` + - `agent-ui/frame/index.md` + - 다음 archive/user-review 디렉터리가 빈 상태로 필요하면 `.gitkeep`을 둘 수 있다. + - `agent-ui/definition/archive/views/` + - `agent-ui/definition/archive/components/` + - `agent-ui/archive/user-review/` + - `USER_REVIEW.md`는 사용자 판단 항목이 있을 때만 만든다. + +3. **초기 view 생성** + - `views`가 주어지면 각 view마다 다음 문서를 만든다. + - `agent-ui/definition/views//index.md` + - `agent-ui/frame/views//index.md` + - `.excalidraw` 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다. + - view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다. + +4. **초기 component 생성** + - `components`가 주어지면 각 component마다 `agent-ui/definition/components//index.md`를 만든다. + - component id가 path id이면 하위 디렉터리 구조로 만든다. + - view에서 참조하지 않는 component도 사용자가 명시했으면 생성할 수 있다. + +5. **결과 보고** + - 생성한 파일 + - 생성하지 않은 선택 항목 + - product UI 확장 후보 + - 후속 권장 작업 + +## 실행 결과 검증 + +- [ ] `agent-ui/README.md`가 생성되었는가 +- [ ] `definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md`가 생성되었는가 +- [ ] view/component는 folder-first + `index.md` 구조를 사용하는가 +- [ ] 같은 레벨에 `.md`와 `/`가 함께 생기지 않았는가 +- [ ] archive 본문 파일을 불필요하게 생성하지 않았는가 +- 검증 실패 시: 누락된 scaffold만 보완하고 기존 문서를 덮어쓰지 않는다. + +## 출력 형식 + +```md +## 생성 완료 + +- 루트: agent-ui/ +- 생성 파일: <목록> +- 초기 views: <목록 또는 없음> +- 초기 components: <목록 또는 없음> +- 생성하지 않은 항목: <목록 또는 없음> +- 후속 권장: validate-agent-ui 실행 +``` + +## 금지 사항 + +- 기존 `agent-ui/` 문서를 덮어쓰지 않는다. +- `.excalidraw` 파일을 현재 UI source of truth로 만들지 않는다. +- product UI 전용 레이어를 요청 없이 추가하지 않는다. +- `definition/archive/**`나 `archive/user-review/**`에 현재 기준 문서를 만들지 않는다. diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index 94fb278..b644121 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -12,6 +12,9 @@ | agent-ops 세팅해줘, scaffold 만들어줘, 초기화해줘 | `agent-ops/skills/common/init-agent-ops/SKILL.md` | | domain rule 만들어줘, rules.md 생성, 새 도메인 규칙 | `agent-ops/skills/common/create-domain-rule/SKILL.md` | | skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` | +| agent-ui 생성, UI 스캐폴드 생성, UI 정의 구조 생성, 화면 정의 구조 생성, agent-ui scaffold | `agent-ops/skills/common/create-agent-ui/SKILL.md` | +| agent-ui 갱신, agent-ui 업데이트, view 추가, component 추가, frame 추가, wireframe 추가, 화면 정의 갱신, 화면 정의서 갱신 | `agent-ops/skills/common/update-agent-ui/SKILL.md` | +| agent-ui 검증, agent-ui validate, UI 정의 정합성 확인, wireframe 정합성 확인, UI 스캐폴드 검사 | `agent-ops/skills/common/validate-agent-ui/SKILL.md` | | create-test, 테스트 룰 작성, 테스트 룰 생성, 테스트 규칙 작성, 테스트 규칙 생성, 테스트 환경 생성, 상황별 테스트 문서 생성, 도메인별 테스트 문서 생성, 검증 시나리오별 테스트 문서 생성, test rule 생성, agent-test 생성 | `agent-ops/skills/common/create-test/SKILL.md` | | update-test, 테스트 룰 수정, 테스트 룰 갱신, 테스트 규칙 수정, 테스트 규칙 갱신, 테스트 환경 수정, 상황별 테스트 문서 수정, 도메인별 테스트 문서 수정, 검증 시나리오별 테스트 문서 수정, test rule 수정, agent-test 수정 | `agent-ops/skills/common/update-test/SKILL.md` | | agent-contract 생성, agent-contract 갱신, 계약 문서 작성, 계약 문서 정리, 제공 계약 추가, 소비 계약 추가, 외부 계약 포인터 관리 | `agent-ops/skills/common/agent-contract/SKILL.md` | diff --git a/agent-ops/skills/common/update-agent-ui/SKILL.md b/agent-ops/skills/common/update-agent-ui/SKILL.md new file mode 100644 index 0000000..7d4ec91 --- /dev/null +++ b/agent-ops/skills/common/update-agent-ui/SKILL.md @@ -0,0 +1,102 @@ +--- +name: update-agent-ui +version: 1.0.0 +description: 기존 agent-ui의 view, component, frame, wireframe 연결, decision history를 갱신하는 스킬 +--- + +# update-agent-ui + +## 목적 + +기존 `agent-ui/`의 UI 정의를 갱신한다. +view, component, frame index, Excalidraw visual source 연결을 현재 기준에 맞게 수정하고, 오래된 기준은 필요한 경우 archive log로 분리한다. + +## 언제 호출할지 + +- 화면 정의서, view 정의, component 정의를 추가하거나 수정할 때 +- wireframe 또는 Excalidraw visual source 연결을 추가하거나 수정할 때 +- agent-ui 문서의 decision history, open question, user review를 갱신할 때 +- ops/dev UI 정의를 제품 진행 상황에 맞춰 동기화할 때 + +## 입력 + +- `change`: 갱신할 내용 요약 (필수) +- `view-id`: 대상 view id (선택) +- `component-id`: 대상 component id 또는 path id (선택) +- `frame-source`: 예: `wire.excalidraw`, `overview.png` (선택) +- `mode`: `definition`, `frame`, `component`, `mixed` 중 하나. 기본값은 `mixed` (선택) + +## 먼저 확인할 것 + +- [ ] `agent-ops/rules/common/rules-agent-ui.md`를 읽는다. +- [ ] `agent-ui/` 존재 여부를 확인한다. 없으면 `create-agent-ui` 대상이라고 보고하고 중단한다. +- [ ] `agent-ui/definition/index.md`와 `agent-ui/frame/index.md`를 읽는다. +- [ ] 대상 view/component/frame 문서가 있으면 해당 활성 문서만 읽는다. +- [ ] `agent-ui/USER_REVIEW.md`가 있으면 현재 변경과 관련된 항목만 확인한다. +- [ ] `definition/archive/**`와 `archive/user-review/**`는 사용자가 과거 확인, 복원, 비교를 요청한 경우가 아니면 읽지 않는다. +- [ ] 필요한 템플릿만 `agent-ops/skills/common/_templates/agent-ui/`에서 읽는다. + +## 실행 절차 + +1. **대상 분류** + - `view-id`가 있으면 view 정의와 대응 frame 문서를 대상으로 삼는다. + - `component-id`가 있으면 component 정의를 대상으로 삼는다. + - `frame-source`가 있으면 대응 `frame/views//index.md`에 visual source를 연결한다. + - 대상이 모호하면 추정으로 새 문서를 만들지 않고 `agent-ui/USER_REVIEW.md`에 결정 항목을 남긴다. + +2. **정의 갱신** + - 현재 기준은 `definition/**` 활성 문서에 반영한다. + - view 문서에는 purpose, tasks, information priority, regions, actions, states, open questions, decision history를 유지한다. + - component 문서에는 purpose, used by, anatomy, variants, states, rules, decision history를 유지한다. + - 오래된 결정이 현재 기준을 흐리면 대응되는 `definition/archive/**.log`로 이동하거나 추가한다. + +3. **frame 갱신** + - 대응되는 `frame/views//index.md`가 없으면 템플릿으로 만든다. + - visual source가 있으면 `Visual Source`에 기록한다. + - Excalidraw visual source의 기본 후보 파일명은 `wire.excalidraw`다. + - frame의 required region id는 view definition의 region id와 맞춘다. + - 정의에 없는 region이 frame에 필요하면 바로 확정하지 않고 open question 또는 USER_REVIEW로 분리한다. + +4. **USER_REVIEW 처리** + - agent가 확정할 수 없는 화면 의도, region 추가/삭제, component 신규 생성 여부, page/drawer/split 선택은 `agent-ui/USER_REVIEW.md`에 남긴다. + - 기존 USER_REVIEW 항목을 해결하는 변경이면 항목 상태를 갱신하고, 필요하면 `agent-ui/archive/user-review/user_review_N.log`로 이동한다. + - 해결 로그를 만들 때는 현재 변경과 직접 관련된 항목만 이동한다. + +5. **결과 보고** + - 수정한 활성 정의 문서 + - 수정한 frame 문서와 visual source + - archive log 변경 여부 + - USER_REVIEW 생성/갱신 여부 + - 남은 정합성 확인 항목 + +## 실행 결과 검증 + +- [ ] view/component는 folder-first + `index.md` 구조를 유지하는가 +- [ ] view region id와 frame region id가 충돌하지 않는가 +- [ ] view에서 참조한 component id가 존재하거나 USER_REVIEW에 남았는가 +- [ ] visual source가 있으면 대응 frame index에 기록되었는가 +- [ ] 현재 기준이 archive에만 남지 않았는가 +- [ ] 확정할 수 없는 UI 결정이 임의로 확정되지 않았는가 +- 검증 실패 시: 자동 보정 가능한 것은 보완하고, 판단이 필요한 것은 `agent-ui/USER_REVIEW.md`에 남긴다. + +## 출력 형식 + +```md +## 갱신 완료 + +- 수정 파일: <목록> +- view: +- component: +- frame source: <파일 또는 없음> +- archive 변경: <내용 또는 없음> +- USER_REVIEW: <생성/갱신/없음> +- 확인 필요: <항목 또는 없음> +``` + +## 금지 사항 + +- `definition/archive/**`를 현재 기준으로 사용하지 않는다. +- 사용자 판단이 필요한 UI 의도를 임의로 확정하지 않는다. +- view/component id를 명시적 요청 없이 바꾸지 않는다. +- `.excalidraw` 파일만 만들고 frame index를 생략하지 않는다. +- agent-ui 갱신과 무관한 앱 구현 파일을 수정하지 않는다. diff --git a/agent-ops/skills/common/validate-agent-ui/SKILL.md b/agent-ops/skills/common/validate-agent-ui/SKILL.md new file mode 100644 index 0000000..8502a62 --- /dev/null +++ b/agent-ops/skills/common/validate-agent-ui/SKILL.md @@ -0,0 +1,121 @@ +--- +name: validate-agent-ui +version: 1.0.0 +description: agent-ui scaffold, definition/frame/component 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬 +--- + +# validate-agent-ui + +## 목적 + +`agent-ui/` 구조와 문서 간 정합성을 검사한다. +파일 규약처럼 결정적으로 고칠 수 있는 문제는 자동 보정하고, UI 의도 판단이 필요한 문제는 `agent-ui/USER_REVIEW.md`에 남긴다. + +## 언제 호출할지 + +- agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때 +- view/component/frame 문서가 서로 어긋났는지 확인할 때 +- Excalidraw visual source와 frame index 연결을 검사할 때 +- agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때 + +## 입력 + +- `scope`: `all`, `view:`, `component:`, `frame:` 중 하나. 기본값은 `all` (선택) +- `repair`: `true` 또는 `false`. 기본값은 `true` (선택) + +## 먼저 확인할 것 + +- [ ] `agent-ops/rules/common/rules-agent-ui.md`를 읽는다. +- [ ] `agent-ui/` 존재 여부를 확인한다. 없으면 `create-agent-ui` 대상이라고 보고하고 중단한다. +- [ ] `agent-ui/definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md` 존재 여부를 확인한다. +- [ ] scope에 해당하는 활성 definition/frame 문서만 읽는다. +- [ ] archive는 경로와 tree 대응만 확인하고, 사용자가 과거 내용 확인을 요청하지 않았으면 본문을 읽지 않는다. +- [ ] 필요한 템플릿만 `agent-ops/skills/common/_templates/agent-ui/`에서 읽는다. + +## 실행 절차 + +1. **인벤토리 작성** + - `definition/views/**/index.md`에서 view 목록을 만든다. + - `definition/components/**/index.md`에서 component 목록을 만든다. + - `frame/views/**/index.md`에서 frame 목록을 만든다. + - 같은 레벨의 `.md`와 `/` 혼재 여부를 확인한다. + +2. **구조 검증과 자동 보정** + - 필수 루트 문서가 없고 `repair=true`이면 템플릿으로 생성한다. + - view/component/frame 디렉터리에 `index.md`가 없고 의도가 명확하면 템플릿으로 생성한다. + - `.excalidraw` 파일이 하나 있고 frame index의 visual source가 비어 있으면 해당 파일을 등록한다. + - archive/user-review 디렉터리가 없고 필요하면 생성한다. + - `.md`와 `/`가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다. + +3. **definition 정합성 검사** + - region id가 `.` 또는 `..` 형식인지 확인한다. + - view 문서에서 참조한 component id가 component 목록에 있는지 확인한다. + - 없는 component가 단순 누락이고 생성 의도가 명확하면 `repair=true`일 때 component skeleton을 만든다. + - 새 component로 만들지 기존 component로 바꿀지 판단이 필요하면 USER_REVIEW로 남긴다. + +4. **frame 정합성 검사** + - view가 있는데 대응 frame index가 없으면 `repair=true`일 때 만든다. + - frame index가 가리키는 definition 경로와 visual source가 실제 존재하는지 확인한다. + - frame required region과 view definition region을 비교한다. + - definition에 있는 region이 frame index에만 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다. + - frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다. + - region 추가/삭제 의도 판단이 필요하면 USER_REVIEW로 남긴다. + +5. **USER_REVIEW 생성 또는 갱신** + - active review 파일은 `agent-ui/USER_REVIEW.md`를 사용한다. + - 새 항목 id는 기존 최대 `UIR-NNN` 다음 번호를 사용한다. + - 같은 경로와 같은 질문의 중복 항목은 만들지 않는다. + - 항목에는 Context, Options, Needed For를 포함한다. + +6. **결과 판정** + - `PASS`: 자동 수정도 USER_REVIEW도 필요 없는 상태 + - `WARN`: 자동 수정이 있었거나 USER_REVIEW가 생성/갱신된 상태 + - `FAIL`: 구조가 너무 모호해서 자동 보정과 리뷰 작성 모두 불완전한 상태 + +## 자동 수정 허용 범위 + +- 누락된 필수 디렉터리와 index 문서 생성 +- 명확한 단일 후보 visual source 등록 +- 명확한 단일 후보 상대 링크 보정 +- definition에 이미 있는 region의 frame index 누락 보완 +- 빈 archive/user-review 디렉터리 생성 +- 템플릿 필수 섹션 누락 보완 +- 의도가 명확한 component skeleton 생성 + +## USER_REVIEW 대상 + +- 정의에는 없는 region이 frame에 있고 추가/삭제 의도 판단이 필요한 경우 +- frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우 +- component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우 +- `.md`와 `/`가 모두 있고 둘 다 의미 있는 내용이 있는 경우 +- drawer/page/split, 테이블/리스트, modal/page 같은 UX 방향 결정이 필요한 경우 + +## 실행 결과 검증 + +- [ ] 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가 +- [ ] folder-first + `index.md` 구조가 유지되는가 +- [ ] view/component/frame 참조가 끊기지 않는가 +- [ ] 자동 수정한 파일 목록이 보고되는가 +- [ ] 사용자 판단이 필요한 항목이 `agent-ui/USER_REVIEW.md`에 남는가 +- [ ] archive 본문을 일반 검증에서 읽지 않았는가 +- 검증 실패 시: 판정을 `FAIL`로 보고하고 자동 수정하지 못한 이유를 남긴다. + +## 출력 형식 + +```md +## agent-ui 검증 결과: + +- Scope: +- Auto Fixed: <파일/항목 목록 또는 없음> +- User Review: +- Remaining Issues: <목록 또는 없음> +- Checked Files: <활성 파일 목록> +``` + +## 금지 사항 + +- UI 의도 판단이 필요한 문제를 자동 수정하지 않는다. +- archive 본문을 일반 검증 컨텍스트로 읽지 않는다. +- `.excalidraw` 내용을 현재 UI 기준으로 단독 확정하지 않는다. +- 사용자 확인 없이 의미 있는 문서를 병합하거나 삭제하지 않는다. +- agent-ui 검증과 무관한 앱 구현 파일을 수정하지 않는다. diff --git a/agent-ui-struct.txt b/agent-ui-struct.txt new file mode 100644 index 0000000..0748e7b --- /dev/null +++ b/agent-ui-struct.txt @@ -0,0 +1,68 @@ +agent-ui/ + README.md + USER_REVIEW.md # 선택: 사용자 판단이 필요한 활성 리뷰 + + archive/ + user-review/ + user_review_001.log + + definition/ + index.md # UI 정의 전체 인덱스, 원칙, view/component/frame 참조 규칙 + + views/ # 화면/업무 단위의 현재 UI 정의 source of truth + index.md # 전체 view tree, navigation 관계, 공통 상태/권한 규칙 + + dashboard/ + index.md # dashboard view의 기준 정의서 + job-dashboard.md # dashboard 내부의 job 요약/상태 영역 정의 + job-detail-dashboard.md # dashboard 내부의 job 상세 요약 영역 정의 + + jobs/ + index.md # jobs view의 기준 정의서 + build.md # jobs 하위 build 흐름/영역 정의 + + components/ # 반복 UI 구성요소의 정의. 구현 API가 아니라 사용 규칙 중심 + index.md # component 목록, 공통 작성 규칙, view 정의서와의 연결 규칙 + + data-table/ + index.md # data-table component의 기준 정의서 + build-result.md # build result table 변형/컬럼/상태 정의 + job-list.md # job list table 변형/컬럼/상태 정의 + + status-badge/ + index.md # status-badge component의 기준 정의서 + + archive/ # 현재 기준이 아닌 과거 결정/폐기 정의 로그. 기본 작업에서는 읽지 않음 + views/ # views와 동일 tree 구조를 유지하고 .log로 보관 + dashboard/ + index.log + job-dashboard.log + job-detail-dashboard.log + + jobs/ + index.log + build.log + + components/ # components와 동일 tree 구조를 유지하고 .log로 보관 + data-table/ + index.log + build-result.log + job-list.log + + status-badge/ + index.log + + frame/ + index.md # 와이어프레임 인덱스. view별 frame 파일 위치와 형식을 안내 + + views/ + dashboard/ + index.md # dashboard frame과 definition 연결 문서 + wire.excalidraw + job-dashboard.png + job-detail-dashboard.png + + jobs/ + index.md # jobs frame과 definition 연결 문서 + wire.excalidraw + build.png