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.153
+1.1.156

agent-ops/rules/common/_templates/test-env-rules-template.md

@@ -1,15 +1,15 @@
 ---
-test_env: <local|dev|qa|prod>
+test_env: <env>
 last_rule_updated_at: <YYYY-MM-DD>
 ---
 
-# <test_env> 테스트 규칙
+# <env> 테스트 규칙
 
 **현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
 
 ## 공통 규칙
 
-- <test_env> 테스트/검증은 이 파일을 기준으로 판단한다.
+- <env> 테스트/검증은 이 파일을 기준으로 판단한다.
 - 작업 완료 검증은 변경 범위 기준으로 선택한다.
 - 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
 - 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
@@ -18,17 +18,22 @@ last_rule_updated_at: <YYYY-MM-DD>
 ## 기본 환경
 
 - host:
-- port:
+- repo root:
+- sync 기준:
 - runtime:
 - package manager:
-- docker:
 - external service:
-- model endpoint:
 - credential:
 
+## 프리플라이트
+
+- plan 작성 시 필수 검증이 현재 checkout을 벗어나 원격 runner, 외부 서비스, Docker/code-server, emulator/device, 공유 장기 runtime을 사용하면 먼저 테스트 환경 프리플라이트를 계획에 기록한다.
+- 테스트 환경 프리플라이트에는 runner, repo root/workdir, branch/HEAD/dirty 상태, local 변경과 원격 source 동기화 여부, binary/artifact 경로와 필요한 help/version 출력, config path, runtime identity, port/process 상태, 외부 host, OS/arch 가정을 포함한다.
+- 프리플라이트에서 dirty/divergent checkout, stale artifact, 잘못된 identity, missing command, closed port, host OS 불일치, source 미동기화가 확인되면 plan은 먼저 setup/sync/rebuild 단계를 만들거나 blocker로 보고한다.
+
 ## 라우팅
 
-- <domain 또는 project-wide> / <verification-type> / <scope 요약>: `agent-test/<test_env>/<test-profile>.md`
+- <domain 또는 project-wide> / <verification-type> / <scope 요약>: `agent-test/<env>/<test-profile>.md`
 
 ## 라우팅 규칙
 

agent-ops/rules/common/philosophy.md

@@ -53,7 +53,7 @@
 - 그룹 간 연결은 사용자 명령, 런타임 이벤트, 또는 판별 가능한 파일 상태로만 한다.
 - 구현 작업 그룹은 `plan`과 `code-review`의 PLAN/CODE_REVIEW 루프를 소유한다.
 - 로드맵 그룹은 `create-roadmap`과 `update-roadmap`의 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신 흐름을 소유한다.
-- Phase/Milestone 상태 전환, 구현 잠금 동기화, archive 이동, 완료 이벤트 반영처럼 결정적으로 판별 가능한 action은 NomadCode Core 또는 런타임이 있으면 그쪽 책임으로 둔다.
+- Phase/Milestone 상태 전환, 구현 잠금 동기화, archive 이동, 완료 이벤트 반영처럼 결정적으로 판별 가능한 action은 Core/MCP 또는 런타임이 있으면 그쪽 책임으로 둔다.
 - `code-review`가 남긴 PASS 완료 이벤트를 로드맵에 반영할지, 언제 반영할지는 런타임이 판단하고 Core/MCP action이 있으면 그쪽으로, 없으면 `update-roadmap` file-based fallback 흐름으로 넘긴다.
 - cross-project 잠금이나 `.agent-roadmap-sync` 같은 workspace-level 상태는 로드맵 그룹, Core, 런타임의 공동 경계다. `plan`과 `code-review`에 의존성 동기화 규칙을 넣지 않는다.
 - 새 스킬을 만들기 전에 기존 그룹의 자연스러운 입력, 상태 전환, 후처리 지점에 넣을 수 있는지 먼저 본다. 다만 다른 그룹 경계를 침범해야 하면 런타임 이벤트로 분리한다.

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/agent-contract/SKILL.md

@@ -20,7 +20,7 @@ description: agent-contract index와 제공/소비 계약 문서를 생성하거
 
 ## 입력
 
-- `contract-id`: 계약 식별자, 예: `iop.openai-compatible-api` (필수)
+- `contract-id`: 계약 식별자, 예: `billing.public-api` 또는 `auth.session-events` (필수)
 - `mode`: `provided` 또는 `consumed` (필수)
 - `contract-path`: 계약 원문 경로 또는 외부 source 경로 (필수)
 - `trigger-conditions`: 계약 문서를 읽어야 하는 조건 목록 (필수)

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/create-test/SKILL.md

@@ -49,6 +49,7 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
 - [ ] 테스트 명령 확인을 위해 프로젝트의 대표 설정 파일을 가볍게 확인한다. 예: `package.json`, `Makefile`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `docker-compose*.yml`, `.github/workflows/**`.
 - [ ] `agent-ops/rules/common/_templates/test-env-rules-template.md`를 읽는다.
 - [ ] `agent-ops/rules/common/_templates/test-case-rule-template.md`를 읽는다.
+- [ ] 프로젝트에 `agent-test/_templates/env-rules-template.md` 또는 `agent-test/_templates/test-profile-template.md`가 있으면 해당 프로젝트 템플릿을 공통 템플릿보다 우선한다.
 - [ ] `agent-test/<env>/rules.md` 존재 여부를 확인한다.
 - [ ] `agent-test/<env>/rules.md`가 있으면 읽고 missing / blank-skeleton / structured-incomplete / usable 중 하나로 분류한다.
 - [ ] 도메인 baseline과 추가 생성 대상 `agent-test/<env>/*.md`의 존재 여부를 확인하고, 있으면 blank-skeleton / structured-incomplete / usable 중 하나로 분류한다.
@@ -56,7 +57,7 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
 ## 실행 절차
 
 1. **환경 rules 생성**
-   - `agent-test/<env>/rules.md`가 없으면 `test-env-rules-template.md` 형식으로 만든다.
+   - `agent-test/<env>/rules.md`가 없으면 프로젝트 `agent-test/_templates/env-rules-template.md`가 있을 때는 그 형식으로 만들고, 없으면 공통 `test-env-rules-template.md` 형식으로 만든다.
    - `agent-test/<env>/rules.md`가 구조적 blank/skeleton이면 기존 구체 값을 보존한 채 빠진 frontmatter, 정독 필수 문구, 필수 섹션, baseline 라우팅 영역만 보완한다.
    - usable한 기존 env rules는 덮어쓰지 않고 라우팅 추가가 필요한 경우에만 최소 수정한다.
    - 제목은 `# <env> 테스트 규칙`으로 쓴다.
@@ -74,7 +75,7 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
    - 도메인은 새로 발명하지 않는다. 도메인 매핑이나 domain rule에서 확인되지 않은 이름은 `project-wide`로 기록한다.
 
 3. **도메인/검증 시나리오별 문서 생성**
-   - 생성 대상 문서가 없으면 `agent-test/<env>/<test-profile>.md`를 `test-case-rule-template.md` 형식으로 만든다.
+   - 생성 대상 문서가 없으면 프로젝트 `agent-test/_templates/test-profile-template.md`가 있을 때는 그 형식으로 만들고, 없으면 공통 `test-case-rule-template.md` 형식으로 만든다.
    - 대상 문서가 이미 있고 usable하면 덮어쓰지 않는다.
    - 대상 문서가 구조적 blank/skeleton이면 기존 구체 값을 보존한 채 빠진 frontmatter와 필수 섹션을 보완한다.
    - frontmatter에는 `test_profile`, `domain`, `verification_type`, `last_rule_updated_at`을 채운다.

agent-ops/skills/common/plan/SKILL.md

@@ -175,12 +175,13 @@ Before choosing plan files or task directory names, apply the split decision pol
 
 ## Step 2 - Analyze Before Writing
 
-Complete all items below before creating active plan/review files. Work through them in order; do not proceed to the next step until every checkbox is done. The only allowed file edits before writing plan/review files are local `agent-roadmap/current.md` creation or `.gitignore` block repair needed for roadmap routing, plus `create-test` or `update-test` edits needed to make test rules usable for this plan.
+Complete all items below before creating active plan/review files. Work through them in order; do not proceed to the next step until every checkbox is done. The only allowed file edits before writing plan/review files are local `agent-roadmap/current.md` creation or `.gitignore` block repair needed for roadmap routing, plus `create-test` or `update-test` edits when the repository already uses agent-test for the relevant scope or the user explicitly asked to maintain test rules.
 
-- [ ] **Load test environment rules** — because implementation plans include verification, determine `test_env` before choosing verification commands. Use the user-specified environment when provided; otherwise use `local`. Check `agent-test/<test_env>/rules.md` and read it in full when present, even if it appears blank or skeleton. If it is absent, or present but structurally blank/skeleton, invoke `create-test` with `env=<test_env>` when this repo can be edited, then re-read the generated or completed rules before writing the plan. If creation is not possible in the current task context, record the gap and fallback source; absence is not a user-review blocker by itself.
+- [ ] **Load test environment rules** — because implementation plans include verification, determine `test_env` before choosing verification commands. Use the user-specified environment when provided; otherwise use `local`. Agent-test is optional: some repositories or tasks intentionally do not have or use `agent-test/`. Check `agent-test/<test_env>/rules.md`; read it in full when present, even if it appears blank or skeleton. If it is absent, record that no agent-test rule was applied and choose fallback verification sources from repository manifests, scripts, workflows, domain rules, or direct read-only environment probes. Do not create agent-test files merely because a plan has verification. Invoke `create-test` only when the user asked for test-rule creation/maintenance, the current task is itself test-rule work, or the repository already uses agent-test for this scope and the missing/blank rule is a real maintenance gap. If creation is not appropriate or possible in the current task context, record the gap and fallback source; absence is not a user-review blocker by itself.
 - [ ] **Read all source files in full** — read every source file the change will touch, whole file. No partial reads.
-- [ ] **Resolve test profiles** — from the env rules `## 라우팅`, read every matching `agent-test/<test_env>/<test-profile>.md` in full. Use `create-test` for missing or structurally blank routes/profiles when the current task can safely fill the gap. Use `update-test` only when verified command or criteria facts are available or the user asked to maintain test rules. If a profile exists but leaves command/criteria values as `<확인 필요>`, record the incomplete values and choose fallback verification commands from repository manifests or workflows with lower confidence. Do not claim agent-test requires a command that is not written in the env rules or matched profiles.
+- [ ] **Resolve test profiles** — if env rules exist and contain `## 라우팅`, read every matching `agent-test/<test_env>/<test-profile>.md` in full. If agent-test is absent or intentionally unused for the task, skip profile resolution and record the fallback verification source. Use `create-test` for missing or structurally blank routes/profiles only when the repository already uses agent-test for this scope or the task is test-rule maintenance. Use `update-test` only when verified command or criteria facts are available or the user asked to maintain test rules. If a profile exists but leaves command/criteria values as `<확인 필요>`, record the incomplete values and choose fallback verification commands from repository manifests or workflows with lower confidence. Do not claim agent-test requires a command that is not written in the env rules or matched profiles.
-- [ ] **Read all test files in full** — read every test file that exercises the changed behavior, including files implied by the matched agent-test profiles and repository test layout.
+- [ ] **Preflight non-local test environments** — when any required verification leaves the current checkout, including remote runner, field/bootstrap, external provider, Docker/code-server, emulator/device, or shared long-running runtime, derive a read-only preflight before writing final verification commands. Use matched `agent-test` rules when they exist and apply; otherwise derive the preflight from repository manifests, scripts, workflows, domain rules, current task evidence, user-provided environment facts, and direct read-only probes. Record runner, repo root/workdir, branch/HEAD/dirty state, source sync status, binary/artifact paths, command help/version output needed by the verification, config path, runtime identity such as Edge id, ports/process state, external hosts, and OS/arch assumptions. If the preflight shows stale artifacts, dirty/divergent checkout, wrong identity, missing command, closed ports, host OS mismatch, or unsynced source, the plan must add an explicit setup/sync/rebuild step or report the blocker; do not write verification commands that silently assume profile or fallback values are already true.
+- [ ] **Read all test files in full** — read every test file that exercises the changed behavior, including files implied by matched agent-test profiles when any are used and by the repository test layout.
 - [ ] **Assess test coverage** — for each behavior change, explicitly record whether existing tests cover it.
 - [ ] **Assess split boundaries first** — identify dependency boundaries, ownership boundaries, API-vs-call-site phases, test strategy splits, risk profile splits, and independently verifiable subwork before selecting plan files. If any split gate applies or the decision is uncertain, write multiple subtask directories under one task group instead of one plan.
 - [ ] **Resolve split predecessor completion** — if the selected or proposed subtask directory has `NN+PP[,QQ...]_...`, resolve each predecessor index under the same task group. Check only the active and archive candidate patterns defined in the task directory naming rules. Record found active/archive paths, missing predecessors, or ambiguous matches in `분석 결과 > 분할 판단` and, when order matters, `의존 관계 및 구현 순서`.
@@ -237,9 +238,9 @@ Required sections:
 - Completion mode: check-on-pass
 ```
 - `분석 결과`: record the findings from Step 2 and Step 3. This section is the written output of the analysis — not a summary, but the actual findings that justify the plan's scope and decisions. Must include all of the following subsections:
-  - `읽은 파일`: list every source, test, and agent-test rule/profile file read during analysis, with path.
+  - `읽은 파일`: list every source and test file read during analysis, with path. List agent-test rule/profile files only when they were actually present and read.
   - `SDD 기준`: for `SDD: 필요` Milestones, list the SDD path, status, targeted Acceptance Scenario ids, their Milestone Task ids, and the Evidence Map rows that drive the plan. State explicitly how those rows shaped the implementation checklist and final verification. If the selected Milestone has `SDD: 불필요`, state the recorded reason. If the work is not Milestone-linked, state "not applicable".
-  - `테스트 환경 규칙`: state the chosen `test_env`, whether `agent-test/<test_env>/rules.md` was present and read, every matched profile path read, the concrete rules/commands applied, any structural blank/skeleton or missing rules, any `<확인 필요>` values, and any fallback verification source. If agent-test is absent or unusable, explicitly say no agent-test rule was applied and whether `create-test` or `update-test` should later fill the gap.
+  - `테스트 환경 규칙`: state the chosen `test_env`, whether `agent-test/<test_env>/rules.md` was present/read/missing/intentionally unused, every matched profile path read when any, the concrete rules/commands applied, any structural blank/skeleton or missing rules, any `<확인 필요>` values, and any fallback verification source. If any required verification leaves the current checkout, include a `테스트 환경 프리플라이트` record with runner, repo root/workdir, branch/HEAD/dirty state, source sync status, binary/artifact paths, required command help/version output, config path, runtime identity such as Edge id, ports/process state, external hosts, OS/arch assumptions, and the exact setup/sync/rebuild step or blocker derived from mismatches. If agent-test is absent or unusable, explicitly say no agent-test rule was applied, what fallback is used, and whether test-rule maintenance is actually needed or not needed for this task.
   - `테스트 커버리지 공백`: list each behavior change and whether existing tests cover it; explicitly note gaps.
   - `심볼 참조`: list renamed/removed symbols and every call site found, or state "none" if no symbols were changed.
   - `분할 판단`: state that the split decision policy was evaluated before choosing plan files. For a single plan, explain why each relevant split gate does not apply and why single-plan coordination is safer than splitting. For multi-plan output, list the shared task group plus each sibling subtask directory and dependency relationship. For dependent subtask plans, include each predecessor index and whether it is satisfied by an active or archived `complete.log`, missing, or ambiguous.
@@ -287,6 +288,7 @@ Verification fidelity rules:
 - Plan verification commands are a contract. The implementing agent must run them exactly as written.
 - If a command must be changed, the implementing agent must record the replacement command and reason in `계획 대비 변경 사항`, then paste the replacement command's actual stdout/stderr.
 - Before claiming a tool is unavailable, run and record `command -v <tool>` or the project-equivalent check.
+- Before a remote/field/external verification command assumes a checkout, binary, config, runtime identity, or listening port, the plan must include a preflight command that proves those assumptions or a setup command that makes them true.
 - Do not download, generate, or leave verification tools inside the repository. Temporary tools belong outside the repo, such as under `/tmp`, and must not become task artifacts.
 - For search commands whose output order may vary, specify deterministic options in the plan, for example `rg --sort path`.
 - `검증 결과` must contain actual stdout/stderr, not summarized or reconstructed output. If output is too long, record the saved output file path and the exact command used to create it.
@@ -459,7 +461,7 @@ Sections and their ownership:
 - If `Roadmap Targets` exists in the plan, the review stub contains the identical section. If it does not exist in the plan, the review stub omits it too.
 - If the selected Milestone has `SDD: 필요`, the plan's `분석 결과 > SDD 기준` proves that the implementation checklist and final verification were derived from the approved SDD Acceptance Scenarios and Evidence Map. Missing SDD mapping blocks plan creation.
 - If the plan is a follow-up or resumes from prior archive evidence, it has `Archive Evidence Snapshot` and the review stub contains the identical section.
-- `분석 결과 > 테스트 환경 규칙` records the selected test env, env rules read/missing/structural-blank state, matched profiles read, and any fallback verification source.
+- `분석 결과 > 테스트 환경 규칙` records the selected test env, env rules read/missing/structural-blank/intentionally-unused state, matched profiles read when any, and any fallback verification source.
 - Dependent split plans record predecessor completion using active sibling `complete.log` or matching archived `complete.log`; ambiguous archive matches are not guessed.
 - Every plan item has problem, solution, checklist, test decision, and intermediate verification.
 - The plan and review stub have matching `구현 체크리스트` item text/order, and the final checkbox is the mandatory `CODE_REVIEW-*-G??.md` completion item.

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 검증과 무관한 앱 구현 파일을 수정하지 않는다.