sync: agent-ops from agentic-framework v1.1.156

.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 생성

.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 생성

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 생성

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 생성

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 생성

agent-ops/.version

@@ -1 +1 @@
-1.1.155
+1.1.156

agent-ops/rules/common/rules-agent-ui.md

@@ -0,0 +1,124 @@
+# 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
+      <view-id>/
+        index.md
+    components/
+      index.md
+      <component-id>/
+        index.md
+    archive/
+      views/
+        <view-id>/
+          index.log
+      components/
+        <component-id>/
+          index.log
+
+  frame/
+    index.md
+    views/
+      <view-id>/
+        index.md                   # visual source가 있을 때만 생성
+        wire.excalidraw            # 선택: 1차 visual source 후보
+```
+
+## Source of Truth
+
+- `agent-ui/definition/**`은 현재 UI 정의의 source of truth다.
+- `agent-ui/frame/**`은 와이어프레임과 visual source를 연결하는 보조 자료다.
+- visual source가 없는 view는 `frame/views/<view-id>/`를 만들지 않는다. view 문서의 `frame`은 `null`로 둔다.
+- `.excalidraw` 파일만으로 현재 UI 기준을 확정하지 않는다. visual source가 있으면 반드시 대응되는 `frame/views/<view-id>/index.md`가 있어야 한다.
+- `frame/views/<view-id>/index.md`는 대응되는 `definition/views/<view-id>/index.md`를 가리켜야 한다.
+- 화면 의도, 상태, 액션, 정보 우선순위는 definition에 둔다.
+- 배치, 밀도, 시각적 영역 관계는 frame에 둔다.
+- 생성된 view/component는 코드, 문서, 사용자 입력 중 어떤 근거에서 왔는지 `Source Evidence`에 남긴다.
+- 구현 코드에서 확인된 항목은 `implemented`, 문서 계획에서 온 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 표시한다.
+- `planned`, `assumed`, `unknown` 항목을 구현 완료처럼 설명하지 않는다.
+
+## Frontmatter Schema
+
+- 활성 Markdown 문서는 YAML frontmatter를 둔다.
+- `ui_doc_type`은 `readme`, `definition-index`, `views-index`, `view`, `components-index`, `component`, `frame-index`, `frame-view`, `user-review`, `archive-log` 중 하나다.
+- definition-index 문서는 `surface_type`, `source_evidence`를 둘 수 있다.
+- view 문서는 `view_id`, `status`, `frame`, `source_evidence`를 둔다.
+- component 문서는 `component_id`, `status`, `source_evidence`를 둔다.
+- view 문서의 `frame`은 frame-view 문서가 있으면 경로, 없으면 `null`로 둔다.
+- frame-view 문서는 visual source가 있을 때만 만들며 `view_id`, `definition`, `visual_source`, `regions`를 둔다.
+- `status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나다.
+- `source_evidence`는 list이며 각 항목은 `type`, `path`, `notes`를 둔다.
+- `source_evidence.type`은 `code`, `docs`, `user` 중 하나다.
+- 실제 파일 근거가 없으면 `path: null`을 사용한다. placeholder 문자열을 현재 근거처럼 남기지 않는다.
+- view에 visual source가 없으면 view 문서의 `frame`을 `null`로 두고 frame-view 문서를 만들지 않는다.
+- frame-view를 만들 때 `visual_source`는 실제 존재하는 visual source 경로여야 한다. 없는 `wire.excalidraw`를 기본 근거처럼 쓰지 않는다.
+- `implemented`는 존재하는 `code` evidence path가 있을 때만 사용한다.
+- `planned`는 문서 근거만 있을 때, `assumed`는 사용자 명시 입력만 있을 때, `unknown`은 근거나 판단이 부족할 때 사용한다.
+- frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`는 같은 기준을 말해야 한다.
+- frontmatter는 기계적 검증을 위한 최소 schema이고, 본문 Markdown은 사람과 agent가 읽는 설명을 유지한다.
+
+## 명명 규칙
+
+- view id, component id, 파일명, 디렉터리명은 kebab-case를 사용한다.
+- view 기준 문서는 `definition/views/<view-id>/index.md`에 둔다.
+- component 기준 문서는 `definition/components/<component-id>/index.md`에 둔다.
+- 같은 레벨에서 `<name>.md`와 `<name>/`를 함께 두지 않는다.
+- 하위 정의가 필요하면 `<name>/index.md`와 `<name>/<child>.md`를 사용한다.
+
+## ID 규칙
+
+- region id는 `<view-id>.<region>` 형식을 사용한다.
+- 하위 region은 `<view-id>.<region>.<subregion>` 형식을 사용할 수 있다.
+- component id는 `definition/components/` 아래 경로에서 `index.md`를 제외한 path id로 본다. 예: `data-table`, `data-table/job-list`.
+- frame-view가 있으면 view 정의서의 region id와 frame 정의서의 region id는 동일해야 한다.
+- view에서 참조한 component id는 대응되는 component 정의 문서가 있어야 한다.
+- frame-view가 있으면 frame-view frontmatter의 `regions`와 view 본문의 region id는 같은 집합이어야 한다. 단, 차이가 제품 판단을 요구하면 USER_REVIEW로 남긴다.
+
+## 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의 필수 조건이 아니다.
+- `.excalidraw`는 JSON으로 다룬다. 검증 시 가능하면 JSON parser로 `elements`의 text label 또는 `customData.region_id`를 확인한다.
+- visual source에 region label이 있으면 `frame-view.regions`와 `definition` region id의 집합과 비교한다.
+- visual source가 있는데 region label이 없으면 frame과 definition의 연결 근거가 부족한 상태로 본다.
+- visual source에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동으로 UI 의도를 확정하지 않고 USER_REVIEW로 남긴다.
+
+## 스킬
+
+- agent-ui 초기 scaffold 생성은 `create-agent-ui`를 사용한다.
+- view, component, frame 갱신은 `update-agent-ui`를 사용한다.
+- 구조와 정합성 검사, 자동 보정, USER_REVIEW 생성은 `validate-agent-ui`를 사용한다.

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 생성

agent-ops/skills/common/_templates/agent-ui/archive-log-template.md

@@ -0,0 +1,20 @@
+---
+ui_doc_type: archive-log
+target: <target>
+---
+
+# <target> log
+
+## <YYYY-MM-DD>
+
+### Changed
+
+- <변경 또는 폐기된 정의>
+
+### Reason
+
+- <변경 이유>
+
+### Superseded
+
+- <대체된 이전 기준 또는 없음>

agent-ops/skills/common/_templates/agent-ui/component-index-template.md

@@ -0,0 +1,61 @@
+---
+ui_doc_type: component
+component_id: <component-id>
+status: <implemented|planned|assumed|unknown>
+source_evidence:
+  - type: code
+    path: null
+    notes: <구현 근거. 없으면 없음>
+  - type: docs
+    path: null
+    notes: <컨셉/계획 근거. 없으면 없음>
+  - type: user
+    path: null
+    notes: <사용자 명시 입력. 없으면 없음>
+---
+
+# <Component Name>
+
+Component ID: `<component-id>`
+
+Status: `<implemented|planned|assumed|unknown>`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | 없음 | <구현 근거. 없으면 `없음`> |
+| docs | 없음 | <컨셉/계획 근거. 없으면 `없음`> |
+| user | 없음 | <사용자 명시 입력. 없으면 `없음`> |
+
+## Purpose
+
+<이 component가 해결하는 UI 문제를 적는다.>
+
+## Used By
+
+- `<view-id>`: <사용 위치 또는 region id>
+
+## Anatomy
+
+- <구성 부분>
+
+## Variants
+
+- default: <기본 사용>
+
+## States
+
+- default
+- loading
+- empty
+- error
+- disabled
+
+## Rules
+
+- <사용 규칙>
+
+## Decision History
+
+- <YYYY-MM-DD>: <현재 기준으로 남길 결정 요약>

agent-ops/skills/common/_templates/agent-ui/components-index-template.md

@@ -0,0 +1,18 @@
+---
+ui_doc_type: components-index
+components: []
+---
+
+# Component Definitions
+
+## Component List
+
+| Component ID | Status | Evidence | Description |
+|--------------|--------|----------|-------------|
+| 없음 | - | - | - |
+
+## Rules
+
+- component 정의는 구현 API가 아니라 UI 사용 규칙을 다룬다.
+- view별 변형이 필요하면 `<component-id>/<variant>.md` 또는 하위 디렉터리를 사용한다.
+- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다.

agent-ops/skills/common/_templates/agent-ui/definition-index-template.md

@@ -0,0 +1,55 @@
+---
+ui_doc_type: definition-index
+surface_type: ops-dev
+source_evidence:
+  - type: code
+    path: null
+    notes: <UI 구현 근거 요약>
+  - type: docs
+    path: null
+    notes: <컨셉/계획 근거 요약>
+  - type: user
+    path: null
+    notes: <사용자 명시 입력 요약>
+---
+
+# UI Definition
+
+## Purpose
+
+<이 agent-ui가 다루는 UI 표면과 목표를 적는다.>
+
+## Surface Type
+
+- Type: ops-dev
+- Notes: <product UI 레이어가 필요한 경우 brand/content/assets/tokens/motion 확장 후보를 적는다.>
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | 없음 | <UI 구현 근거 요약> |
+| docs | 없음 | <컨셉/계획 근거 요약> |
+| user | 없음 | <사용자 명시 입력 요약> |
+
+## 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을 대체하지 않는다.
+- `implemented`, `planned`, `assumed`, `unknown` 상태를 섞어 쓰지 않는다.
+
+## Decision History
+
+- <YYYY-MM-DD>: <초기 결정 또는 변경 요약>

agent-ops/skills/common/_templates/agent-ui/frame-index-template.md

@@ -0,0 +1,22 @@
+---
+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와 동일해야 한다.

agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md

@@ -0,0 +1,36 @@
+---
+ui_doc_type: frame-view
+view_id: <view-id>
+definition: ../../../definition/views/<view-id>/index.md
+visual_source: <frame-source>
+regions:
+  - <view-id>.<region>
+---
+
+# <View Name> Frame
+
+Definition:
+- `../../../definition/views/<view-id>/index.md`
+
+Visual Source:
+- `<frame-source>`
+
+## Frame Intent
+
+- <이 frame이 검증하려는 배치, 밀도, 시선 흐름을 적는다.>
+
+## Required Regions
+
+- `<view-id>.<region>`: <visual source의 라벨 또는 위치 설명>
+
+## Layout Notes
+
+- desktop: <배치 기준>
+- tablet: <배치 기준>
+- mobile: <배치 기준>
+
+## Sync Rules
+
+- visual source의 주요 박스 text label 또는 `customData.region_id`는 가능한 한 region id를 포함한다.
+- definition에 없는 region을 frame에 추가하지 않는다. 필요한 경우 `agent-ui/USER_REVIEW.md`에 남긴다.
+- frame에서 제거한 region은 definition에서도 제거 대상인지 확인한다.

agent-ops/skills/common/_templates/agent-ui/readme-template.md

@@ -0,0 +1,27 @@
+---
+ui_doc_type: readme
+surface_type: ops-dev
+---
+
+# agent-ui
+
+이 디렉터리는 AI agent와 사람이 UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다.
+
+## 대상
+
+- 1차 대상: ops/dev UI
+- 확장 후보: product UI
+
+## 구조
+
+- `definition/`: 현재 UI 정의 source of truth
+- `frame/`: visual source가 있는 view의 wireframe 연결
+- `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문
+- `archive/user-review/`: 해결된 사용자 리뷰 로그
+
+## 기본 규칙
+
+- 현재 기준은 `definition/**`에 둔다.
+- visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다.
+- `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다.
+- `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다.

agent-ops/skills/common/_templates/agent-ui/user-review-template.md

@@ -0,0 +1,20 @@
+---
+ui_doc_type: user-review
+status: open
+---
+
+# 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
+
+- 없음

agent-ops/skills/common/_templates/agent-ui/view-index-template.md

@@ -0,0 +1,79 @@
+---
+ui_doc_type: view
+view_id: <view-id>
+status: <implemented|planned|assumed|unknown>
+frame: null
+source_evidence:
+  - type: code
+    path: null
+    notes: <구현 근거. 없으면 없음>
+  - type: docs
+    path: null
+    notes: <컨셉/계획 근거. 없으면 없음>
+  - type: user
+    path: null
+    notes: <사용자 명시 입력. 없으면 없음>
+regions:
+  - <view-id>.<region>
+---
+
+# <View Name>
+
+View ID: `<view-id>`
+
+Frame:
+- 없음
+
+Status: `<implemented|planned|assumed|unknown>`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | 없음 | <구현 근거. 없으면 `없음`> |
+| docs | 없음 | <컨셉/계획 근거. 없으면 `없음`> |
+| user | 없음 | <사용자 명시 입력. 없으면 `없음`> |
+
+## Purpose
+
+<이 view의 목적을 1-3줄로 적는다.>
+
+## Primary Users
+
+- <사용자 역할>
+
+## Primary Tasks
+
+- <사용자 작업>
+
+## Information Priority
+
+1. <가장 먼저 보여야 하는 정보>
+2. <다음 우선순위 정보>
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `<view-id>.<region>` | <역할> | `<component-id 또는 없음>` | high | <비고> |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `<view-id>.<action>` | <사용자 입력> | <결과> | <권한/상태 조건> |
+
+## States
+
+- loading: <표시 기준>
+- empty: <표시 기준>
+- error: <표시 기준>
+- permission-denied: <표시 기준>
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- <YYYY-MM-DD>: <현재 기준으로 남길 결정 요약>

agent-ops/skills/common/_templates/agent-ui/views-index-template.md

@@ -0,0 +1,31 @@
+---
+ui_doc_type: views-index
+views: []
+---
+
+# View Definitions
+
+## View Tree
+
+| View ID | Status | Evidence | Description |
+|---------|--------|----------|-------------|
+| 없음 | - | - | - |
+
+## Navigation
+
+- `<from-view>` -> `<to-view>`: <이동 조건 또는 사용자 작업>
+
+## Common States
+
+- loading
+- empty
+- error
+- permission-denied
+
+## Common Permissions
+
+- <권한 이름>: <허용되는 view/action>
+
+## Open Questions
+
+- 없음

agent-ops/skills/common/create-agent-ui/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: create-agent-ui
+version: 1.1.0
+description: 프로젝트 코드 또는 문서 근거를 분석해 agent-ui 기본 스캐폴드와 동기화된 UI 정의 초안을 생성하는 스킬
+---
+
+# create-agent-ui
+
+## 목적
+
+프로젝트의 기존 UI 코드나 컨셉 문서를 근거로 `agent-ui/` 기본 구조와 UI 정의 초안을 생성한다.
+ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분해 AI와 사람이 UI 의도를 동기화할 수 있게 만든다.
+
+## 언제 호출할지
+
+- 사용자가 agent-ui 생성, UI 스캐폴드 생성, 화면 정의 구조 생성을 요청할 때
+- 프로젝트에 `agent-ui/`가 없고 기존 코드 또는 문서에서 UI 정의 문맥을 추출할 때
+- UI 코드가 있으면 구현 상태와 동기화된 view/component/frame 초안이 필요할 때
+- UI 코드가 아직 부족하면 README, roadmap, SDD, docs 같은 컨셉 문서 기반 최소 view tree가 필요할 때
+
+## 입력
+
+- `surface-type`: `ops-dev` 또는 `product`. 기본값은 `ops-dev` (선택)
+- `source-mode`: `auto`, `code-first`, `concept-first`, `blank` 중 하나. 기본값은 `auto` (선택)
+- `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/` 하위 파일을 확인한다.
+- [ ] `source-mode=auto`이면 UI 코드 후보와 컨셉 문서 후보를 모두 가볍게 확인한다.
+
+## 실행 절차
+
+1. **생성 대상 확정**
+   - 생성 루트는 `agent-ui/`로 고정한다.
+   - `surface-type`이 없으면 `ops-dev`로 둔다.
+   - `source-mode`가 없으면 `auto`로 둔다.
+   - product UI가 명시되어도 기본 구조는 유지하고 product 전용 레이어는 요청된 경우에만 추가 후보로 보고한다.
+
+2. **근거 수집**
+   - `code-first` 또는 `auto`에서는 UI 구현 후보를 찾는다.
+     - 예: `apps/**/lib/**`, `packages/**/lib/**`, `src/**`, `app/**`, `pages/**`, `screens/**`, `views/**`, `components/**`, `widgets/**`, route/navigation/shell 파일
+     - 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다.
+     - 코드가 많으면 전체 정독하지 말고 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다.
+   - `concept-first` 또는 `auto`에서는 컨셉 문서 후보를 찾는다.
+     - 예: `README.md`, `docs/**`, `agent-roadmap/current.md`, 활성 Phase/Milestone, 승인된 SDD, `agent-ops/rules/project/rules.md`
+     - roadmap 문서는 `agent-ops/rules/common/rules-roadmap.md`의 loading/archive 접근 규칙을 따른다.
+     - archive 문서는 사용자가 과거 근거를 명시하지 않는 한 읽지 않는다.
+   - 근거가 없거나 사용자가 빈 구조를 요청하면 `blank`로 처리한다.
+
+3. **source-mode 결정**
+   - `auto`에서 route, shell, page/view, widget/component 후보 중 하나 이상이 실제 파일 경로로 확인되면 `code-first`로 생성한다.
+   - UI 구현 후보가 부족하고 컨셉 문서 후보가 있으면 `concept-first`로 생성한다.
+   - 코드와 문서 근거가 모두 부족하면 `blank`로 생성하고 부족한 근거를 결과에 보고한다.
+   - 명시된 `views` 또는 `components`는 선택된 mode와 함께 생성 후보로 반영한다.
+
+4. **기본 구조 생성**
+   - 다음 활성 문서를 템플릿 기준으로 만든다.
+     - `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`
+   - 생성하는 활성 Markdown 문서에는 `rules-agent-ui.md`의 Frontmatter Schema를 적용한다.
+   - 다음 archive/user-review 디렉터리가 빈 상태로 필요하면 `.gitkeep`을 둘 수 있다.
+     - `agent-ui/definition/archive/views/`
+     - `agent-ui/definition/archive/components/`
+     - `agent-ui/archive/user-review/`
+   - `USER_REVIEW.md`는 사용자 판단 항목이 있을 때만 만든다.
+
+5. **초기 view 생성**
+   - `code-first`에서는 구현 코드에서 확인된 route/page/view/shell 단위를 view 후보로 만든다.
+   - `concept-first`에서는 문서에서 확인된 운영 업무, 화면, 콘솔 영역을 view 후보로 만든다.
+   - `blank`에서는 명시 `views`가 있을 때만 view 후보를 만든다.
+   - 각 view 후보마다 다음 문서를 만든다.
+     - `agent-ui/definition/views/<view-id>/index.md`
+   - view 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다.
+     - 코드 근거가 있으면 `status: implemented`
+     - 문서 근거만 있으면 `status: planned`
+     - 명시 입력만 있고 근거가 부족하면 `status: assumed`
+     - 판단 불가하면 `status: unknown`과 USER_REVIEW 항목을 남긴다.
+   - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다.
+   - visual source가 없는 초기 view 문서의 frontmatter `frame`은 `null`로 둔다.
+   - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 같은 기준을 말하게 작성한다.
+   - `.excalidraw` 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다.
+   - `.excalidraw` 또는 다른 visual source를 만들거나 연결할 때만 `agent-ui/frame/views/<view-id>/index.md`를 만든다.
+   - `.excalidraw`를 만들거나 연결하면 주요 박스 text label 또는 `customData.region_id`에 region id를 넣는다.
+   - view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다.
+
+6. **초기 component 생성**
+   - `code-first`에서는 반복 widget/component/table/filter/log/status/action 단위를 component 후보로 만든다.
+   - `concept-first`에서는 문서상 반복 패턴이 분명한 data table, status badge, filter bar, log viewer 같은 구성요소만 component 후보로 만든다.
+   - `blank`에서는 명시 `components`가 있을 때만 component 후보를 만든다.
+   - 각 component 후보마다 `agent-ui/definition/components/<component-id>/index.md`를 만든다.
+   - component 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다.
+   - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다.
+   - component id가 path id이면 하위 디렉터리 구조로 만든다.
+   - view에서 참조하지 않는 component도 사용자가 명시했으면 생성할 수 있다.
+
+7. **불확실성 분리**
+   - 코드와 문서가 충돌하면 임의로 통합하지 않고 `agent-ui/USER_REVIEW.md`에 남긴다.
+   - view 경계, component 신규 생성 여부, page/drawer/split 같은 UX 판단은 USER_REVIEW로 남긴다.
+   - 문서 근거만 있는 계획 항목을 구현 완료처럼 쓰지 않는다.
+
+8. **결과 보고**
+   - 선택된 `source-mode`
+   - 읽은 근거 파일과 생성에 사용한 evidence
+   - 생성한 파일
+   - 적용한 frontmatter schema
+   - 생성한 view/component의 status
+   - USER_REVIEW 생성 여부
+   - product UI 확장 후보
+   - 후속 권장 작업
+
+## 실행 결과 검증
+
+- [ ] `agent-ui/README.md`가 생성되었는가
+- [ ] `definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md`가 생성되었는가
+- [ ] 활성 Markdown 문서가 `ui_doc_type` frontmatter를 포함하는가
+- [ ] view/component는 folder-first + `index.md` 구조를 사용하는가
+- [ ] 생성한 view/component에 `Source Evidence`와 `Status`가 있는가
+- [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가
+- [ ] visual source가 없는 view에 빈 `frame/views/<view-id>/index.md`를 만들지 않았는가
+- [ ] 코드/문서 충돌이나 UI 의도 판단이 필요한 항목이 USER_REVIEW에 남았는가
+- [ ] 같은 레벨에 `<name>.md`와 `<name>/`가 함께 생기지 않았는가
+- [ ] archive 본문 파일을 불필요하게 생성하지 않았는가
+- 검증 실패 시: 누락된 scaffold만 보완하고 기존 문서를 덮어쓰지 않는다.
+
+## 출력 형식
+
+```md
+## 생성 완료
+
+- 루트: agent-ui/
+- source-mode: <code-first|concept-first|blank>
+- evidence: <주요 근거 파일 목록>
+- 생성 파일: <목록>
+- frontmatter schema: <적용/부분 적용/없음>
+- views: <view-id=status 목록 또는 없음>
+- components: <component-id=status 목록 또는 없음>
+- USER_REVIEW: <생성/없음>
+- 확인 필요: <항목 또는 없음>
+- 후속 권장: validate-agent-ui 실행
+```
+
+## 금지 사항
+
+- 기존 `agent-ui/` 문서를 덮어쓰지 않는다.
+- `.excalidraw` 파일을 현재 UI source of truth로 만들지 않는다.
+- 코드나 문서 근거 없이 화면 의도를 확정하지 않는다.
+- 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
+- product UI 전용 레이어를 요청 없이 추가하지 않는다.
+- `definition/archive/**`나 `archive/user-review/**`에 현재 기준 문서를 만들지 않는다.

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` |

agent-ops/skills/common/update-agent-ui/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: update-agent-ui
+version: 1.1.0
+description: 기존 agent-ui의 view, component, frame, wireframe 연결, source evidence, status, decision history를 갱신하는 스킬
+---
+
+# update-agent-ui
+
+## 목적
+
+기존 `agent-ui/`의 UI 정의를 갱신한다.
+view, component, frame index, Excalidraw visual source 연결, source evidence, status를 현재 기준에 맞게 수정하고, 오래된 기준은 필요한 경우 archive log로 분리한다.
+frame-view는 visual source가 있을 때만 활성 문서로 둔다.
+
+## 언제 호출할지
+
+- 화면 정의서, view 정의, component 정의를 추가하거나 수정할 때
+- wireframe 또는 Excalidraw visual source 연결을 추가하거나 수정할 때
+- 기존 구현 코드 또는 컨셉 문서 변화에 맞춰 Source Evidence와 Status를 갱신할 때
+- 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` (선택)
+- `evidence`: 코드, 문서, 사용자 입력 근거 경로 또는 요약 (선택)
+- `status`: `implemented`, `planned`, `assumed`, `unknown` 중 하나 (선택)
+- `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 문서가 있거나 `frame-source`가 입력된 경우에만 frame 문서를 대상으로 삼는다.
+   - `component-id`가 있으면 component 정의를 대상으로 삼는다.
+   - `frame-source`가 있으면 대응 `frame/views/<view-id>/index.md`에 visual source를 연결한다.
+   - 대상이 모호하면 추정으로 새 문서를 만들지 않고 `agent-ui/USER_REVIEW.md`에 결정 항목을 남긴다.
+
+2. **정의 갱신**
+   - 현재 기준은 `definition/**` 활성 문서에 반영한다.
+   - 활성 Markdown 문서의 frontmatter를 유지하고, 새 문서는 `rules-agent-ui.md`의 Frontmatter Schema를 적용한다.
+   - view 문서에는 status, source evidence, purpose, tasks, information priority, regions, actions, states, open questions, decision history를 유지한다.
+   - component 문서에는 status, source evidence, purpose, used by, anatomy, variants, states, rules, decision history를 유지한다.
+   - 구현 코드 근거가 확인된 항목은 `implemented`, 문서 근거만 있는 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 둔다.
+   - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다.
+   - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 충돌하지 않게 함께 갱신한다.
+   - `status`가 입력되었더라도 evidence와 맞지 않으면 임의로 확정하지 않고 USER_REVIEW로 남긴다.
+   - 새 view/component를 만들 때는 `Source Evidence`와 `Status`를 반드시 채운다.
+   - 오래된 결정이 현재 기준을 흐리면 대응되는 `definition/archive/**.log`로 이동하거나 추가한다.
+
+3. **frame 갱신**
+   - `frame-source`가 있고 대응되는 `frame/views/<view-id>/index.md`가 없으면 템플릿으로 만든다.
+   - visual source가 있으면 frontmatter `visual_source`와 본문 `Visual Source`에 함께 기록한다.
+   - visual source가 없으면 새 frame-view 문서를 만들지 않는다.
+   - 기존 frame-view 문서의 visual source가 제거되고 더 이상 연결할 visual source가 없으면 frame-view 삭제 후보로 보고한다. 판단이 명확하면 삭제하고 view 문서의 `frame`을 `null`로 둔다.
+   - Excalidraw visual source의 기본 후보 파일명은 `wire.excalidraw`다.
+   - `.excalidraw`를 만들거나 수정하면 주요 박스 text label 또는 `customData.region_id`에 region id를 넣는다.
+   - frame-view가 있으면 required region id는 view definition의 region id와 맞춘다.
+   - 정의에 없는 region이 frame-view에 필요하면 바로 확정하지 않고 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
+   - frontmatter schema 변경 여부
+   - archive log 변경 여부
+   - USER_REVIEW 생성/갱신 여부
+   - 남은 정합성 확인 항목
+
+## 실행 결과 검증
+
+- [ ] view/component는 folder-first + `index.md` 구조를 유지하는가
+- [ ] 새로 만들거나 수정한 활성 Markdown 문서가 `ui_doc_type` frontmatter를 포함하는가
+- [ ] 새로 만들거나 수정한 view/component에 `Source Evidence`와 `Status`가 있는가
+- [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가
+- [ ] frame-view가 있으면 view region id와 frame region id가 충돌하지 않는가
+- [ ] view에서 참조한 component id가 존재하거나 USER_REVIEW에 남았는가
+- [ ] visual source가 있으면 대응 frame index에 기록되었는가
+- [ ] visual source가 없는데 빈 frame-view 문서만 남아 있지 않은가
+- [ ] 현재 기준이 archive에만 남지 않았는가
+- [ ] 확정할 수 없는 UI 결정이 임의로 확정되지 않았는가
+- 검증 실패 시: 자동 보정 가능한 것은 보완하고, 판단이 필요한 것은 `agent-ui/USER_REVIEW.md`에 남긴다.
+
+## 출력 형식
+
+```md
+## 갱신 완료
+
+- 수정 파일: <목록>
+- view: <view-id 또는 없음>
+- component: <component-id 또는 없음>
+- frame source: <파일 또는 없음>
+- evidence/status: <요약 또는 없음>
+- frontmatter schema: <변경/유지/없음>
+- archive 변경: <내용 또는 없음>
+- USER_REVIEW: <생성/갱신/없음>
+- 확인 필요: <항목 또는 없음>
+```
+
+## 금지 사항
+
+- `definition/archive/**`를 현재 기준으로 사용하지 않는다.
+- 코드나 문서 근거 없이 status를 확정하지 않는다.
+- 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
+- 사용자 판단이 필요한 UI 의도를 임의로 확정하지 않는다.
+- view/component id를 명시적 요청 없이 바꾸지 않는다.
+- `.excalidraw` 파일만 만들고 frame index를 생략하지 않는다.
+- visual source 없이 빈 frame-view 문서를 만들지 않는다.
+- agent-ui 갱신과 무관한 앱 구현 파일을 수정하지 않는다.

agent-ops/skills/common/validate-agent-ui/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: validate-agent-ui
+version: 1.1.0
+description: agent-ui scaffold, definition/frame/component/source evidence/status와 구현 코드 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬
+---
+
+# validate-agent-ui
+
+## 목적
+
+`agent-ui/` 구조, 문서 간 정합성, 구현 코드와 agent-ui 정의 간 정합성을 검사한다.
+파일 규약처럼 결정적으로 고칠 수 있는 문제는 자동 보정하고, UI 의도 판단이 필요한 문제는 `agent-ui/USER_REVIEW.md`에 남긴다.
+
+## 언제 호출할지
+
+- agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때
+- view/component/frame 문서가 서로 어긋났는지 확인할 때
+- view/component의 Source Evidence와 Status가 근거와 맞는지 확인할 때
+- 실제 UI 코드와 agent-ui view/component 정의가 동기화되어 있는지 확인할 때
+- Excalidraw visual source와 frame index 연결을 검사할 때
+- agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때
+
+## 입력
+
+- `scope`: `all`, `internal`, `implementation`, `view:<view-id>`, `component:<component-id>`, `frame:<view-id>` 중 하나. 기본값은 `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 문서만 읽는다.
+- [ ] `scope=view:<view-id>` 또는 `scope=component:<component-id>`이면 해당 문서의 Source Evidence code path를 확인한다.
+- [ ] `scope=all` 또는 `scope=implementation`이면 Source Evidence의 code path와 UI 구현 후보 파일을 확인한다.
+- [ ] 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 목록을 만든다. frame이 없는 view는 visual source가 없는 정상 상태로 본다.
+   - 활성 Markdown 문서의 frontmatter에서 `ui_doc_type`, id, status, source_evidence, regions를 수집한다.
+   - 같은 레벨의 `<name>.md`와 `<name>/` 혼재 여부를 확인한다.
+
+2. **구조 검증과 자동 보정**
+   - 필수 루트 문서가 없고 `repair=true`이면 템플릿으로 생성한다.
+   - view/component 디렉터리에 `index.md`가 없고 의도가 명확하면 템플릿으로 생성한다.
+   - frame 디렉터리는 visual source가 있을 때만 `index.md` 생성 대상으로 삼는다.
+   - `.excalidraw` 파일이 하나 있고 frame index의 visual source가 비어 있으면 해당 파일을 등록한다.
+   - archive/user-review 디렉터리가 없고 필요하면 생성한다.
+   - `<name>.md`와 `<name>/`가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다.
+
+3. **definition 정합성 검사**
+   - 활성 Markdown 문서에 `ui_doc_type` frontmatter가 있는지 확인한다.
+   - `ui_doc_type`이 경로와 맞는지 확인한다. 예: `definition/views/<view-id>/index.md`는 `view`다.
+   - view/component/frame id가 경로 id와 일치하는지 확인한다.
+   - view/component 문서에 `Source Evidence`와 `Status`가 있는지 확인한다.
+   - frontmatter `source_evidence`는 list이고 각 항목은 `type`, `path`, `notes`를 가져야 한다.
+   - `source_evidence.type`은 `code`, `docs`, `user` 중 하나여야 한다.
+   - 근거 파일이 없으면 `path: null`이어야 하며, placeholder 문자열을 근거로 보지 않는다.
+   - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 충돌하는지 확인한다.
+   - `Status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나여야 한다.
+   - `implemented` 항목은 실제 존재하는 코드 근거가 있어야 한다.
+   - `implemented`의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 `repair=true`일 때 `unknown`으로 낮추고 USER_REVIEW를 남길 수 있다.
+   - `implemented`인데 code evidence 자체가 없으면 자동 변경하지 않고 USER_REVIEW로 남긴다.
+   - `planned`, `assumed`, `unknown` 항목이 구현 완료처럼 설명되면 자동 의미 변경하지 않고 USER_REVIEW로 남긴다.
+   - region id가 `<view-id>.<region>` 또는 `<view-id>.<region>.<subregion>` 형식인지 확인한다.
+   - view 문서에서 참조한 component id가 component 목록에 있는지 확인한다.
+   - 없는 component가 단순 누락이고 생성 의도가 명확하면 `repair=true`일 때 component skeleton을 만들고 `Status`와 `Source Evidence`를 채운다.
+   - 새 component로 만들지 기존 component로 바꿀지 판단이 필요하면 USER_REVIEW로 남긴다.
+
+4. **frame 정합성 검사**
+   - view가 있는데 대응 frame index가 없어도 visual source가 없으면 정상으로 본다.
+   - visual source 파일이 있는데 대응 frame index가 없으면 `repair=true`일 때 만든다.
+   - frame index가 있는데 `visual_source: null`이고 해당 view 아래 visual source 파일도 없으면 `repair=true`일 때 빈 frame index 삭제 후보로 본다.
+   - frame index가 가리키는 definition 경로가 실제 존재하는지 확인한다.
+   - `visual_source`가 `null`이면 legacy/empty frame 후보로 보고 visual source 파일 존재 여부를 함께 확인한다.
+   - `visual_source`가 값이면 해당 파일이 실제 존재하는지 확인한다.
+   - `visual_source`가 `.excalidraw`이면 JSON으로 읽고 `elements`의 text label 또는 `customData.region_id`에서 region id 후보를 수집한다.
+   - Excalidraw region id 후보가 있으면 frame required region, view definition region과 비교한다.
+   - Excalidraw region id 후보가 없고 frame required region이 있으면 USER_REVIEW로 남긴다.
+   - Excalidraw에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동 수정하지 않고 USER_REVIEW로 남긴다.
+   - Excalidraw가 JSON으로 파싱되지 않으면 visual source 손상 또는 형식 불일치로 보고한다.
+   - frame required region과 view definition region을 비교한다.
+   - visual source가 있는 frame index에서 definition region이 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다.
+   - 기존 frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다.
+   - region 추가/삭제 의도 판단이 필요하면 USER_REVIEW로 남긴다.
+
+5. **구현 정합성 검사**
+   - `scope=view:<view-id>` 또는 `scope=component:<component-id>`이면 해당 문서의 `source_evidence` 중 `type: code` 경로만 확인하고 전체 코드 후보 스캔은 하지 않는다.
+   - `scope=all` 또는 `scope=implementation`이면 전체 view/component의 `source_evidence` 중 `type: code` 경로가 실제 존재하는지 확인한다.
+   - 실제 UI 구현 후보를 찾는다.
+     - 이 후보 스캔은 `scope=all` 또는 `scope=implementation`일 때만 수행한다.
+     - 예: `apps/**/lib/**`, `packages/**/lib/**`, `src/**`, `app/**`, `pages/**`, `screens/**`, `views/**`, `components/**`, `widgets/**`, route/navigation/shell 파일
+     - 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다.
+     - 코드가 많으면 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다.
+   - 코드 후보가 명확한 route/page/view/shell이면 대응 view가 있는지 확인한다.
+   - 코드 후보가 명확한 반복 widget/component/table/filter/log/status/action이면 대응 component가 있는지 확인한다.
+   - 명확한 누락이고 `repair=true`이면 skeleton view/component를 만들 수 있다. 이때 status는 `implemented`, source evidence는 해당 code path로 둔다.
+   - 후보가 임시/dev/debug 용도인지, view인지 component인지, region인지 판단이 필요하면 USER_REVIEW로 남긴다.
+   - 코드에서 사라진 evidence는 자동 삭제하지 않고, 명시된 code evidence 경로가 깨진 경우에만 `implemented`를 `unknown`으로 낮출 수 있다.
+
+6. **USER_REVIEW 생성 또는 갱신**
+   - active review 파일은 `agent-ui/USER_REVIEW.md`를 사용한다.
+   - 새 항목 id는 기존 최대 `UIR-NNN` 다음 번호를 사용한다.
+   - 같은 경로와 같은 질문의 중복 항목은 만들지 않는다.
+   - 항목에는 Context, Options, Needed For를 포함한다.
+
+7. **결과 판정**
+   - `PASS`: 자동 수정도 USER_REVIEW도 필요 없는 상태
+   - `WARN`: 자동 수정이 있었거나 USER_REVIEW가 생성/갱신된 상태
+   - `FAIL`: 구조가 너무 모호해서 자동 보정과 리뷰 작성 모두 불완전한 상태
+
+## 자동 수정 허용 범위
+
+- 누락된 필수 디렉터리와 index 문서 생성
+- 명확한 단일 후보 visual source 등록
+- 명확한 단일 후보 상대 링크 보정
+- visual source가 있는 frame index의 region 누락 보완
+- 빈 archive/user-review 디렉터리 생성
+- 템플릿 필수 섹션과 frontmatter 누락 보완. `ui_doc_type`, `Source Evidence`, `Status` 누락 포함
+- 의도가 명확한 component skeleton 생성. 단, status/evidence를 함께 기록한다.
+- 명확한 구현 코드 후보에 대응되는 skeleton view/component 생성. 단, status/evidence를 함께 기록한다.
+- 명시된 code evidence 경로가 실제 존재하지 않는 `implemented`를 `unknown`으로 낮추고 USER_REVIEW를 남기는 보정
+
+## USER_REVIEW 대상
+
+- 정의에는 없는 region이 기존 frame-view에 있고 추가/삭제 의도 판단이 필요한 경우
+- frame-view가 있는데 frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우
+- component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우
+- 코드 후보가 view, component, region, 임시/dev/debug UI 중 무엇인지 판단이 필요한 경우
+- 코드와 agent-ui 정의가 충돌하지만 어느 쪽을 기준으로 삼을지 제품 판단이 필요한 경우
+- `<name>.md`와 `<name>/`가 모두 있고 둘 다 의미 있는 내용이 있는 경우
+- drawer/page/split, 테이블/리스트, modal/page 같은 UX 방향 결정이 필요한 경우
+
+## 실행 결과 검증
+
+- [ ] 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가
+- [ ] 활성 Markdown 문서가 유효한 `ui_doc_type` frontmatter를 갖는가
+- [ ] folder-first + `index.md` 구조가 유지되는가
+- [ ] view/component에 `Source Evidence`와 유효한 `Status`가 있는가
+- [ ] 명시된 code evidence 경로가 깨진 `implemented`가 남아 있지 않은가
+- [ ] `scope=implementation` 또는 `all`이면 명확한 UI 코드 후보가 agent-ui에 반영되었거나 USER_REVIEW에 남았는가
+- [ ] view/component/frame 참조가 끊기지 않는가
+- [ ] visual source가 없는 view는 frame 참조가 `null`이거나 비어 있는 frame-view가 없는가
+- [ ] 자동 수정한 파일 목록이 보고되는가
+- [ ] 사용자 판단이 필요한 항목이 `agent-ui/USER_REVIEW.md`에 남는가
+- [ ] archive 본문을 일반 검증에서 읽지 않았는가
+- 검증 실패 시: 판정을 `FAIL`로 보고하고 자동 수정하지 못한 이유를 남긴다.
+
+## 출력 형식
+
+```md
+## agent-ui 검증 결과: <PASS|WARN|FAIL>
+
+- Scope: <scope>
+- Auto Fixed: <파일/항목 목록 또는 없음>
+- User Review: <agent-ui/USER_REVIEW.md 생성/갱신/없음>
+- Remaining Issues: <목록 또는 없음>
+- Checked Files: <활성 파일 목록>
+- Implementation Sync: <확인/스킵/USER_REVIEW>
+```
+
+## 금지 사항
+
+- UI 의도 판단이 필요한 문제를 자동 수정하지 않는다.
+- archive 본문을 일반 검증 컨텍스트로 읽지 않는다.
+- `.excalidraw` 내용을 현재 UI 기준으로 단독 확정하지 않는다.
+- 사용자 확인 없이 의미 있는 문서를 병합하거나 삭제하지 않는다.
+- agent-ui 검증과 무관한 앱 구현 파일을 수정하지 않는다.