update agent-ui templates and skills

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

@@ -51,6 +51,9 @@ agent-ui/
 - `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` 항목을 구현 완료처럼 설명하지 않는다.
 
 ## 명명 규칙
 

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

@@ -2,6 +2,16 @@
 
 Component ID: `<component-id>`
 
+Status: `<implemented|planned|assumed|unknown>`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `<path>` | <구현 근거. 없으면 `없음`> |
+| docs | `<path>` | <컨셉/계획 근거. 없으면 `없음`> |
+| user | `<request>` | <사용자 명시 입력. 없으면 `없음`> |
+
 ## Purpose
 
 <이 component가 해결하는 UI 문제를 적는다.>

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

@@ -2,7 +2,9 @@
 
 ## Component List
 
-- `<component-id>`: <반복 UI 구성요소 설명>
+| Component ID | Status | Evidence | Description |
+|--------------|--------|----------|-------------|
+| `<component-id>` | `<implemented|planned|assumed|unknown>` | `<path>` | <반복 UI 구성요소 설명> |
 
 ## Rules
 

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

@@ -9,6 +9,14 @@
 - Type: ops-dev
 - Notes: <product UI 레이어가 필요한 경우 brand/content/assets/tokens/motion 확장 후보를 적는다.>
 
+## Source Evidence
+
+| Type | Path | Usage |
+|------|------|-------|
+| code | `<path>` | <UI 구현 근거 요약> |
+| docs | `<path>` | <컨셉/계획 근거 요약> |
+| user | `<request>` | <사용자 명시 입력 요약> |
+
 ## Structure
 
 - `views/`: 화면 또는 업무 단위 정의
@@ -25,6 +33,7 @@
 - view region id와 frame region id는 동일해야 한다.
 - view에서 참조한 component id는 `components/` 아래에 정의되어야 한다.
 - frame은 definition을 대체하지 않는다.
+- `implemented`, `planned`, `assumed`, `unknown` 상태를 섞어 쓰지 않는다.
 
 ## Decision History
 

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

@@ -5,6 +5,16 @@ View ID: `<view-id>`
 Frame:
 - `../../../frame/views/<view-id>/index.md`
 
+Status: `<implemented|planned|assumed|unknown>`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `<path>` | <구현 근거. 없으면 `없음`> |
+| docs | `<path>` | <컨셉/계획 근거. 없으면 `없음`> |
+| user | `<request>` | <사용자 명시 입력. 없으면 `없음`> |
+
 ## Purpose
 
 <이 view의 목적을 1-3줄로 적는다.>

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

@@ -2,7 +2,9 @@
 
 ## View Tree
 
-- `<view-id>`: <화면 또는 업무 단위 설명>
+| View ID | Status | Evidence | Description |
+|---------|--------|----------|-------------|
+| `<view-id>` | `<implemented|planned|assumed|unknown>` | `<path>` | <화면 또는 업무 단위 설명> |
 
 ## Navigation
 

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

@@ -1,25 +1,27 @@
 ---
 name: create-agent-ui
-version: 1.0.0
+version: 1.1.0
-description: agent-ui 기본 스캐폴드와 UI 정의, view/component/frame 문서 baseline을 생성하는 스킬
+description: 프로젝트 코드 또는 문서 근거를 분석해 agent-ui 기본 스캐폴드와 동기화된 UI 정의 초안을 생성하는 스킬
 ---
 
 # create-agent-ui
 
 ## 목적
 
-프로젝트에 `agent-ui/` 기본 구조를 생성한다.
+프로젝트의 기존 UI 코드나 컨셉 문서를 근거로 `agent-ui/` 기본 구조와 UI 정의 초안을 생성한다.
-ops/dev UI를 1차 대상으로 하며, definition과 frame을 분리해 AI와 사람이 UI 의도를 동기화할 수 있게 만든다.
+ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분해 AI와 사람이 UI 의도를 동기화할 수 있게 만든다.
 
 ## 언제 호출할지
 
 - 사용자가 agent-ui 생성, UI 스캐폴드 생성, 화면 정의 구조 생성을 요청할 때
-- 프로젝트에 `agent-ui/`가 없고 UI 정의 문맥을 만들 때
+- 프로젝트에 `agent-ui/`가 없고 기존 코드 또는 문서에서 UI 정의 문맥을 추출할 때
-- ops/dev UI를 위한 view/component/frame 문서 baseline이 필요할 때
+- 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 (선택)
 
@@ -29,15 +31,34 @@ ops/dev UI를 1차 대상으로 하며, definition과 frame을 분리해 AI와
 - [ ] 생성 대상 `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. **기본 구조 생성**
+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`
@@ -50,21 +71,41 @@ ops/dev UI를 1차 대상으로 하며, definition과 frame을 분리해 AI와
      - `agent-ui/archive/user-review/`
    - `USER_REVIEW.md`는 사용자 판단 항목이 있을 때만 만든다.
 
-3. **초기 view 생성**
+5. **초기 view 생성**
-   - `views`가 주어지면 각 view마다 다음 문서를 만든다.
+   - `code-first`에서는 구현 코드에서 확인된 route/page/view/shell 단위를 view 후보로 만든다.
+   - `concept-first`에서는 문서에서 확인된 운영 업무, 화면, 콘솔 영역을 view 후보로 만든다.
+   - `blank`에서는 명시 `views`가 있을 때만 view 후보를 만든다.
+   - 각 view 후보마다 다음 문서를 만든다.
      - `agent-ui/definition/views/<view-id>/index.md`
      - `agent-ui/frame/views/<view-id>/index.md`
+   - view 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다.
+     - 코드 근거가 있으면 `status: implemented`
+     - 문서 근거만 있으면 `status: planned`
+     - 명시 입력만 있고 근거가 부족하면 `status: assumed`
+     - 판단 불가하면 `status: unknown`과 USER_REVIEW 항목을 남긴다.
    - `.excalidraw` 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다.
    - view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다.
 
-4. **초기 component 생성**
+6. **초기 component 생성**
-   - `components`가 주어지면 각 component마다 `agent-ui/definition/components/<component-id>/index.md`를 만든다.
+   - `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`를 반드시 남긴다.
    - component id가 path id이면 하위 디렉터리 구조로 만든다.
    - view에서 참조하지 않는 component도 사용자가 명시했으면 생성할 수 있다.
 
-5. **결과 보고**
+7. **불확실성 분리**
+   - 코드와 문서가 충돌하면 임의로 통합하지 않고 `agent-ui/USER_REVIEW.md`에 남긴다.
+   - view 경계, component 신규 생성 여부, page/drawer/split 같은 UX 판단은 USER_REVIEW로 남긴다.
+   - 문서 근거만 있는 계획 항목을 구현 완료처럼 쓰지 않는다.
+
+8. **결과 보고**
+   - 선택된 `source-mode`
+   - 읽은 근거 파일과 생성에 사용한 evidence
    - 생성한 파일
-   - 생성하지 않은 선택 항목
+   - 생성한 view/component의 status
+   - USER_REVIEW 생성 여부
    - product UI 확장 후보
    - 후속 권장 작업
 
@@ -73,6 +114,9 @@ ops/dev UI를 1차 대상으로 하며, definition과 frame을 분리해 AI와
 - [ ] `agent-ui/README.md`가 생성되었는가
 - [ ] `definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md`가 생성되었는가
 - [ ] view/component는 folder-first + `index.md` 구조를 사용하는가
+- [ ] 생성한 view/component에 `Source Evidence`와 `Status`가 있는가
+- [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가
+- [ ] 코드/문서 충돌이나 UI 의도 판단이 필요한 항목이 USER_REVIEW에 남았는가
 - [ ] 같은 레벨에 `<name>.md`와 `<name>/`가 함께 생기지 않았는가
 - [ ] archive 본문 파일을 불필요하게 생성하지 않았는가
 - 검증 실패 시: 누락된 scaffold만 보완하고 기존 문서를 덮어쓰지 않는다.
@@ -83,10 +127,13 @@ ops/dev UI를 1차 대상으로 하며, definition과 frame을 분리해 AI와
 ## 생성 완료
 
 - 루트: agent-ui/
+- source-mode: <code-first|concept-first|blank>
+- evidence: <주요 근거 파일 목록>
 - 생성 파일: <목록>
-- 초기 views: <목록 또는 없음>
+- views: <view-id=status 목록 또는 없음>
-- 초기 components: <목록 또는 없음>
+- components: <component-id=status 목록 또는 없음>
-- 생성하지 않은 항목: <목록 또는 없음>
+- USER_REVIEW: <생성/없음>
+- 확인 필요: <항목 또는 없음>
 - 후속 권장: validate-agent-ui 실행
 ```
 
@@ -94,5 +141,7 @@ ops/dev UI를 1차 대상으로 하며, definition과 frame을 분리해 AI와
 
 - 기존 `agent-ui/` 문서를 덮어쓰지 않는다.
 - `.excalidraw` 파일을 현재 UI source of truth로 만들지 않는다.
+- 코드나 문서 근거 없이 화면 의도를 확정하지 않는다.
+- 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
 - product UI 전용 레이어를 요청 없이 추가하지 않는다.
 - `definition/archive/**`나 `archive/user-review/**`에 현재 기준 문서를 만들지 않는다.

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

@@ -1,7 +1,7 @@
 ---
 name: update-agent-ui
-version: 1.0.0
+version: 1.1.0
-description: 기존 agent-ui의 view, component, frame, wireframe 연결, decision history를 갱신하는 스킬
+description: 기존 agent-ui의 view, component, frame, wireframe 연결, source evidence, status, decision history를 갱신하는 스킬
 ---
 
 # update-agent-ui
@@ -9,12 +9,13 @@ description: 기존 agent-ui의 view, component, frame, wireframe 연결, decisi
 ## 목적
 
 기존 `agent-ui/`의 UI 정의를 갱신한다.
-view, component, frame index, Excalidraw visual source 연결을 현재 기준에 맞게 수정하고, 오래된 기준은 필요한 경우 archive log로 분리한다.
+view, component, frame index, Excalidraw visual source 연결, source evidence, status를 현재 기준에 맞게 수정하고, 오래된 기준은 필요한 경우 archive log로 분리한다.
 
 ## 언제 호출할지
 
 - 화면 정의서, view 정의, component 정의를 추가하거나 수정할 때
 - wireframe 또는 Excalidraw visual source 연결을 추가하거나 수정할 때
+- 기존 구현 코드 또는 컨셉 문서 변화에 맞춰 Source Evidence와 Status를 갱신할 때
 - agent-ui 문서의 decision history, open question, user review를 갱신할 때
 - ops/dev UI 정의를 제품 진행 상황에 맞춰 동기화할 때
 
@@ -24,6 +25,8 @@ view, component, frame index, Excalidraw visual source 연결을 현재 기준
 - `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` (선택)
 
 ## 먼저 확인할 것
@@ -46,8 +49,11 @@ view, component, frame index, Excalidraw visual source 연결을 현재 기준
 
 2. **정의 갱신**
    - 현재 기준은 `definition/**` 활성 문서에 반영한다.
-   - view 문서에는 purpose, tasks, information priority, regions, actions, states, open questions, decision history를 유지한다.
+   - view 문서에는 status, source evidence, purpose, tasks, information priority, regions, actions, states, open questions, decision history를 유지한다.
-   - component 문서에는 purpose, used by, anatomy, variants, states, rules, decision history를 유지한다.
+   - component 문서에는 status, source evidence, purpose, used by, anatomy, variants, states, rules, decision history를 유지한다.
+   - 구현 코드 근거가 확인된 항목은 `implemented`, 문서 근거만 있는 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 둔다.
+   - `status`가 입력되었더라도 evidence와 맞지 않으면 임의로 확정하지 않고 USER_REVIEW로 남긴다.
+   - 새 view/component를 만들 때는 `Source Evidence`와 `Status`를 반드시 채운다.
    - 오래된 결정이 현재 기준을 흐리면 대응되는 `definition/archive/**.log`로 이동하거나 추가한다.
 
 3. **frame 갱신**
@@ -72,6 +78,8 @@ view, component, frame index, Excalidraw visual source 연결을 현재 기준
 ## 실행 결과 검증
 
 - [ ] view/component는 folder-first + `index.md` 구조를 유지하는가
+- [ ] 새로 만들거나 수정한 view/component에 `Source Evidence`와 `Status`가 있는가
+- [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가
 - [ ] view region id와 frame region id가 충돌하지 않는가
 - [ ] view에서 참조한 component id가 존재하거나 USER_REVIEW에 남았는가
 - [ ] visual source가 있으면 대응 frame index에 기록되었는가
@@ -88,6 +96,7 @@ view, component, frame index, Excalidraw visual source 연결을 현재 기준
 - view: <view-id 또는 없음>
 - component: <component-id 또는 없음>
 - frame source: <파일 또는 없음>
+- evidence/status: <요약 또는 없음>
 - archive 변경: <내용 또는 없음>
 - USER_REVIEW: <생성/갱신/없음>
 - 확인 필요: <항목 또는 없음>
@@ -96,6 +105,8 @@ view, component, frame index, Excalidraw visual source 연결을 현재 기준
 ## 금지 사항
 
 - `definition/archive/**`를 현재 기준으로 사용하지 않는다.
+- 코드나 문서 근거 없이 status를 확정하지 않는다.
+- 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
 - 사용자 판단이 필요한 UI 의도를 임의로 확정하지 않는다.
 - view/component id를 명시적 요청 없이 바꾸지 않는다.
 - `.excalidraw` 파일만 만들고 frame index를 생략하지 않는다.

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

@@ -1,7 +1,7 @@
 ---
 name: validate-agent-ui
-version: 1.0.0
+version: 1.1.0
-description: agent-ui scaffold, definition/frame/component 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬
+description: agent-ui scaffold, definition/frame/component/source evidence/status 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬
 ---
 
 # validate-agent-ui
@@ -15,6 +15,7 @@ description: agent-ui scaffold, definition/frame/component 정합성을 검사
 
 - agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때
 - view/component/frame 문서가 서로 어긋났는지 확인할 때
+- view/component의 Source Evidence와 Status가 근거와 맞는지 확인할 때
 - Excalidraw visual source와 frame index 연결을 검사할 때
 - agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때
 
@@ -48,9 +49,15 @@ description: agent-ui scaffold, definition/frame/component 정합성을 검사
    - `<name>.md`와 `<name>/`가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다.
 
 3. **definition 정합성 검사**
+   - view/component 문서에 `Source Evidence`와 `Status`가 있는지 확인한다.
+   - `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을 만든다.
+   - 없는 component가 단순 누락이고 생성 의도가 명확하면 `repair=true`일 때 component skeleton을 만들고 `Status`와 `Source Evidence`를 채운다.
    - 새 component로 만들지 기존 component로 바꿀지 판단이 필요하면 USER_REVIEW로 남긴다.
 
 4. **frame 정합성 검사**
@@ -79,8 +86,9 @@ description: agent-ui scaffold, definition/frame/component 정합성을 검사
 - 명확한 단일 후보 상대 링크 보정
 - definition에 이미 있는 region의 frame index 누락 보완
 - 빈 archive/user-review 디렉터리 생성
-- 템플릿 필수 섹션 누락 보완
+- 템플릿 필수 섹션 누락 보완. `Source Evidence`와 `Status` 누락 포함
-- 의도가 명확한 component skeleton 생성
+- 의도가 명확한 component skeleton 생성. 단, status/evidence를 함께 기록한다.
+- 명시된 code evidence 경로가 실제 존재하지 않는 `implemented`를 `unknown`으로 낮추고 USER_REVIEW를 남기는 보정
 
 ## USER_REVIEW 대상
 
@@ -94,6 +102,8 @@ description: agent-ui scaffold, definition/frame/component 정합성을 검사
 
 - [ ] 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가
 - [ ] folder-first + `index.md` 구조가 유지되는가
+- [ ] view/component에 `Source Evidence`와 유효한 `Status`가 있는가
+- [ ] 명시된 code evidence 경로가 깨진 `implemented`가 남아 있지 않은가
 - [ ] view/component/frame 참조가 끊기지 않는가
 - [ ] 자동 수정한 파일 목록이 보고되는가
 - [ ] 사용자 판단이 필요한 항목이 `agent-ui/USER_REVIEW.md`에 남는가