---
name: sync-agent-ui
version: 1.0.0
description: 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-state.json 기준점을 갱신한다. "agent-ui와 코드 동기화", "화면정의서대로 코드 반영" 요청 시 사용한다.
---

# sync-agent-ui

## 목적

정합화된 `agent-ui/` 변경분을 실제 UI 코드에 반영한다.
기본 동작은 `.sync-state.json`의 `last_synced_head` 이후 agent-ui 변경분만 반영하며, 사용자가 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다.

## 언제 호출할지

- 사용자가 "agent-ui와 코드 동기화", "화면정의서대로 코드 반영", "wireframe 변경사항 구현"을 요청할 때
- `update-agent-ui` 또는 `validate-agent-ui`가 code sync 필요성을 판단했고 현재 범위에 미해결 USER_REVIEW가 없을 때
- 사용자가 "agent-ui와 코드 전체 동기화"처럼 full sync를 명시할 때

## 입력

- `mode`: `incremental` 또는 `full`. 기본값은 `incremental` (선택)
- `scope`: `all`, `view:<view-id>`, `component:<component-id>` 중 하나. 기본값은 `all` (선택)
- `validated`: `true` 또는 `false`. 기본값은 `false` (선택)
- `sync-intent-source`: `manual`, `update-agent-ui`, `validate-agent-ui` 중 하나 (선택)
- `push`: `true` 또는 `false`. 기본값은 `true` (선택)

## 먼저 확인할 것

- [ ] `agent-ops/rules/common/rules-agent-ui.md`를 읽는다.
- [ ] `agent-ui/`와 `agent-ui/definition/index.md` 존재 여부를 확인한다.
- [ ] `validated=true`가 아니면 먼저 `validate-agent-ui`를 실행한다.
- [ ] `agent-ui/USER_REVIEW.md`가 있으면 현재 sync 범위와 관련된 미해결 항목이 없는지 확인한다.
- [ ] `agent-ui/.sync-state.json`을 읽는다. 없고 `mode=incremental`이면 legacy baseline migration 필요로 보고 code sync를 시작하지 않는다.
- [ ] 수정할 UI 코드 경로에 해당하는 project/domain rule을 먼저 읽는다.
- [ ] 코드 변경 검증이 필요하면 작업 환경의 `agent-test/<env>/rules.md`를 읽는다. 환경 미지정은 `local`로 본다.
- [ ] `git status --short`와 현재 `HEAD`를 확인한다.
- [ ] unrelated dirty worktree가 있으면 sync commit 전에 범위를 보고하고, agent-ui와 관련 코드 파일만 stage한다.
- [ ] 이전 sync 실패로 남은 관련 작업트리 변경이 있으면 보존할지, 사용자 결정과 충돌하는지 확인한다.

## 실행 절차

1. **동기화 범위 확정**
   - `.sync-state.json`이 없고 `mode=incremental`이면 현재 agent-ui를 legacy baseline 후보로 본다.
   - legacy baseline 후보는 `validate-agent-ui` 통과 후 agent-ui baseline commit과 `.sync-state.json` commit을 남기는 migration으로 처리하고, 같은 실행에서 코드 반영은 하지 않는다.
   - `mode=incremental`이면 `.sync-state.json.last_synced_head` 이후 현재 `HEAD`/worktree까지의 agent-ui 변경분을 확인한다.
   - 변경분 판정에서 `agent-ui/.sync-state.json` 자체는 제외한다.
   - `mode=full`이면 현재 활성 `agent-ui/definition/**`과 `agent-ui/frame/**` 전체를 코드와 대조한다.
   - `mode=full`에서 `.sync-state.json`이 없으면 code sync 성공 후 새 sync state를 만든다.
   - `가정` 또는 `불명확` 상태 항목은 코드 반영 대상에서 제외하고 USER_REVIEW로 남긴다.
   - 현재 범위에 미해결 USER_REVIEW가 있으면 중단한다.

2. **코드 반영**
   - `계획` 상태의 view/component/frame 요구사항을 UI 코드에 반영한다.
   - existing component, route, shell, widget 구조를 우선하고 새 구조를 임의로 만들지 않는다.
   - definition이 요구하는 정보 우선순위, region, action, state, component 참조를 코드 반영 기준으로 삼는다.
   - wireframe/frame은 layout, density, visual relationship 보조 근거로만 사용하고 definition을 대체하지 않는다.
   - 코드 반영이 끝난 항목은 agent-ui 문서의 `status`를 `구현됨`으로 갱신하고 Source Evidence에 코드 경로를 남긴다.

3. **검증**
   - 관련 domain rule과 agent-test rule에 맞는 최소 검증을 실행한다.
   - 검증 실패가 명확하고 에이전트가 해결 가능하면 수정과 검증을 반복한다.
   - 구현 방향 충돌, 환경/권한 차단, 반복 실패, 사용자 판단이 필요한 시각 결과는 `agent-ui/USER_REVIEW.md`에 남기고 중단한다.
   - USER_REVIEW로 중단하면 commit/push하지 않고 `.sync-state.json`도 갱신하지 않는다.
   - USER_REVIEW로 중단할 때 관련 작업트리 변경은 사용자 결정과 충돌하지 않으면 보존하고, 재개 진입점과 변경 파일을 USER_REVIEW에 남긴다.

4. **sync state와 commit/push**
   - 검증이 통과하면 agent-ui/code 변경을 먼저 commit한다.
   - 방금 만든 sync 결과 commit hash를 `agent-ui/.sync-state.json`의 `last_synced_head`에 기록한다.
   - `.sync-state.json`이 없으면 `agent-ops/skills/common/_templates/agent-ui/sync-state-template.json` 기준으로 새로 만든다.
   - `.sync-state.json`에는 `last_sync_mode`, `last_synced_at`, `agent_ui_paths`, `code_paths`, `notes`를 갱신한다.
   - `.sync-state.json` 변경을 별도 commit한다.
   - commit message는 예를 들어 `sync: apply agent-ui to code`와 `sync: record agent-ui sync state`처럼 목적이 분리되게 쓴다.
   - `push=true`이면 두 commit을 push한다.

5. **결과 보고**
   - sync mode와 scope
   - 반영한 agent-ui 파일과 코드 파일
   - 변경한 status
   - 실행한 검증
   - sync 결과 commit hash와 sync-state commit/push 결과
   - USER_REVIEW 생성/갱신 여부

## 실행 결과 검증

- [ ] `validate-agent-ui`가 먼저 실행되었거나 `validated=true` 근거가 있는가
- [ ] 현재 sync 범위에 미해결 USER_REVIEW가 없는가
- [ ] `가정` 또는 `불명확` 항목을 코드로 반영하지 않았는가
- [ ] 코드 반영된 항목의 status가 `구현됨`이고 code evidence가 있는가
- [ ] 관련 검증이 통과했는가
- [ ] 실패 또는 차단 시 commit/push와 `.sync-state.json` 갱신을 하지 않았는가
- [ ] 실패 또는 차단 시 재개 진입점과 남은 변경 파일이 USER_REVIEW에 기록되었는가
- [ ] 성공 시 sync 결과 commit과 `.sync-state.json` commit이 분리되었는가
- [ ] `.sync-state.json.last_synced_head`가 sync 결과 commit hash를 가리키는가
- [ ] unrelated dirty file이 sync commit에 포함되지 않았는가
- 검증 실패 시: 에이전트가 해결할 수 없으면 `agent-ui/USER_REVIEW.md`에 남기고 중단한다.

## 출력 형식

```md
## agent-ui 코드 동기화 결과: <PASS|USER_REVIEW|FAIL>

- Mode: <incremental|full>
- Scope: <scope>
- Agent UI Changes: <파일 목록 또는 없음>
- Code Changes: <파일 목록 또는 없음>
- Status Updates: <구현됨 전환 목록 또는 없음>
- Verification: <명령과 결과>
- Sync Commit: <hash 또는 없음>
- Sync State Commit/Push: <완료/생략/실패>
- USER_REVIEW: <생성/갱신/없음>
- Remaining Issues: <목록 또는 없음>
```

## 금지 사항

- `validate-agent-ui`를 거치지 않고 코드 동기화를 시작하지 않는다.
- 미해결 USER_REVIEW가 있는 범위를 코드에 반영하지 않는다.
- `가정` 또는 `불명확` 상태 항목을 코드로 구현하지 않는다.
- 검증 실패나 사용자 판단 차단 상태에서 commit/push하지 않는다.
- `.sync-state.json`을 agent-ui 변경분 판정 대상으로 삼지 않는다.
- 정의서와 충돌하는 wireframe만을 근거로 코드 구현을 확정하지 않는다.
- 실패한 sync의 작업트리 변경을 사용자 결정 없이 되돌리지 않는다.
