toki/agent-shell
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agent-shell/agent-ops/skills/common/sync-agent-ui/SKILL.md

12 KiB
Raw Blame History

name version description
sync-agent-ui 1.1.0 정합화된 agent-ui 변경분을 코드에 직접 반영하거나, 코드 작업 규모에 따라 plan 또는 roadmap/milestone 작업으로 라우팅한다. 직접 반영이 검증된 경우에만 .sync-state.json 기준점을 갱신한다. "agent-ui와 코드 동기화", "화면정의서대로 코드 반영" 요청 시 사용한다.

sync-agent-ui

목적

정합화된 agent-ui/ 변경분을 실제 UI 코드에 반영한다. 기본 동작은 .sync-state.json의 last_synced_head 이후 agent-ui 변경분만 반영하며, 사용자가 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다. 코드 반영 전에 코드 작업 규모를 판정해 작은 작업은 직접 반영하고, 중간 작업은 plan 루프로, Milestone이 필요한 큰 코드 작업은 update-roadmap의 Milestone/Epic/Task 갱신으로 넘긴다. plan-required 또는 milestone-required로 라우팅한 경우에는 이 스킬 실행 안에서 코드 구현, status 전환, sync state 갱신, commit/push를 하지 않는다.

언제 호출할지

  • 사용자가 "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 중 하나 (선택)
  • execution-route: auto, direct-sync, plan-required, milestone-required 중 하나. 기본값은 auto (선택)
  • 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. 코드 반영 방식 판정

    • 이 판정은 agent-ui 문서 작업의 크기가 아니라, 정합화된 agent-ui 변경분을 코드에 반영하는 구현 작업의 크기와 위험만 대상으로 한다.
    • execution-route=auto이면 코드 반영 대상의 크기와 위험을 direct-sync, plan-required, milestone-required 중 하나로 판정한다.
    • direct-sync는 다음 조건을 모두 만족할 때만 사용한다.
      • 단일 view/component/frame 또는 한 화면 안의 국소 변경이다.
      • 기존 route, shell, navigation, shared state, design token, package boundary를 그대로 사용한다.
      • 새 정보구조, 새 주요 workflow, 새 공통 component 체계, 제품 방향 결정이 필요 없다.
      • 변경 후보 코드가 소수 파일로 좁혀지고 검증 명령이 명확하다.
    • plan-required는 목표와 범위는 명확하지만 독립 리뷰 가능한 구현 루프가 필요할 때 사용한다.
      • 여러 view/component에 걸친 반영, shared component 추출, route/shell 조정, 테스트/검증 보강, UI 상태와 코드 변경을 함께 다루는 작업이 여기에 속한다.
      • 이 경우 직접 코드 반영을 시작하지 않고 plan 스킬로 전환한다.
      • plan에는 반영 대상 agent-ui 문서, 코드 후보, 최종 validate-agent-ui, code evidence 기준을 포함한다.
      • plan이 만드는 CODE_REVIEW-*-G??.md에는 Agent UI Completion 섹션을 넣어 code-review PASS 때 listed agent-ui 문서를 구현됨으로 전환하게 한다.
    • milestone-required는 코드 구현이 제품 UI 구조나 장기 작업 단위까지 바꾸는 경우 사용한다.
      • navigation/information architecture 재정렬, 외부 제품 UI 분석 기반 재설계, 여러 workflow/role/surface를 묶는 작업, 활성 Milestone 범위 밖 작업이 여기에 속한다.
      • 이 경우 직접 코드 반영과 plan 생성을 시작하지 않고 update-roadmap으로 Milestone/Epic/Task 배치를 먼저 남긴다.
      • 이 Milestone에는 완료 리뷰의 agent-ui 상태 반영: 대기를 남기고, status: 구현됨 전환은 plan 완료가 아니라 Milestone 종료 검토 항목으로 둔다.
    • plan-required 또는 milestone-required로 판정하면 agent-ui 문서 status를 구현됨으로 바꾸지 않고, sync state와 commit/push도 갱신하지 않는다.

  3. 코드 반영

    • 이 단계는 execution-route=direct-sync일 때만 수행한다. plan-required 또는 milestone-required 판정이면 Step 2의 라우팅 결과를 보고하고 해당 스킬 흐름으로 전환한다.
    • 계획 상태의 view/component/frame 요구사항을 UI 코드에 반영한다.
    • existing component, route, shell, widget 구조를 우선하고 새 구조를 임의로 만들지 않는다.
    • definition이 요구하는 정보 우선순위, region, action, state, component 참조를 코드 반영 기준으로 삼는다.
    • wireframe/frame은 layout, density, visual relationship 보조 근거로만 사용하고 definition을 대체하지 않는다.

  4. 검증

    • 관련 domain rule과 agent-test rule에 맞는 최소 검증을 실행한다.
    • 검증 실패가 명확하고 에이전트가 해결 가능하면 수정과 검증을 반복한다.
    • 구현 방향 충돌, 환경/권한 차단, 반복 실패, 사용자 판단이 필요한 시각 결과는 agent-ui/USER_REVIEW.md에 남기고 중단한다.
    • USER_REVIEW로 중단하면 commit/push하지 않고 .sync-state.json도 갱신하지 않는다.
    • USER_REVIEW로 중단할 때 관련 작업트리 변경은 사용자 결정과 충돌하지 않으면 보존하고, 재개 진입점과 변경 파일을 USER_REVIEW에 남긴다.
    • execution-route=direct-sync에서 코드 반영과 검증이 모두 통과한 항목은 이 스킬 실행 안에서 agent-ui 문서의 status를 구현됨으로 갱신하고 Source Evidence에 코드 경로를 남긴다.

  5. sync state와 commit/push

    • 이 단계는 execution-route=direct-sync에서 코드 반영, 검증, agent-ui status/code evidence 갱신이 모두 통과한 경우에만 수행한다.
    • 검증이 통과하면 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한다.

  6. 결과 보고

    • sync mode와 scope
    • execution route와 판정 근거
    • 반영한 agent-ui 파일과 코드 파일
    • 변경한 status
    • 실행한 검증
    • sync 결과 commit hash와 sync-state commit/push 결과
    • USER_REVIEW 생성/갱신 여부

실행 결과 검증

  • validate-agent-ui가 먼저 실행되었거나 validated=true 근거가 있는가
  • 현재 sync 범위에 미해결 USER_REVIEW가 없는가
  • 코드 반영 전에 direct-sync, plan-required, milestone-required 중 하나로 판정했는가
  • plan-required 또는 milestone-required 판정에서 직접 코드 변경, status 구현됨 전환, sync state 갱신, commit/push를 하지 않았는가
  • direct-sync 판정에서 코드 반영과 검증이 통과한 항목은 같은 실행 안에서 agent-ui 문서 status를 구현됨으로 바꾸고 code evidence를 남겼는가
  • plan-required 판정에서 생성될 CODE_REVIEW-*-G??.md에 Agent UI Completion 섹션으로 status 전환 규칙을 넘겼는가
  • 가정 또는 불명확 항목을 코드로 반영하지 않았는가
  • direct-sync로 코드 반영된 항목의 status가 구현됨이고 code evidence가 있는가
  • direct-sync 관련 검증이 통과했는가
  • 실패 또는 차단 시 commit/push와 .sync-state.json 갱신을 하지 않았는가
  • 실패 또는 차단 시 재개 진입점과 남은 변경 파일이 USER_REVIEW에 기록되었는가
  • direct-sync 성공 시 sync 결과 commit과 .sync-state.json commit이 분리되었는가
  • direct-sync 성공 시 .sync-state.json.last_synced_head가 sync 결과 commit hash를 가리키는가
  • unrelated dirty file이 sync commit에 포함되지 않았는가
  • 검증 실패 시: 에이전트가 해결할 수 없으면 agent-ui/USER_REVIEW.md에 남기고 중단한다.

출력 형식

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

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

금지 사항

  • validate-agent-ui를 거치지 않고 코드 동기화를 시작하지 않는다.
  • 미해결 USER_REVIEW가 있는 범위를 코드에 반영하지 않는다.
  • 가정 또는 불명확 상태 항목을 코드로 구현하지 않는다.
  • plan-required 또는 milestone-required로 판정된 작업을 같은 sync-agent-ui 실행에서 직접 구현하지 않는다.
  • execution-route=milestone-required로 라우팅된 agent-ui 코드 작업의 일반 plan 완료만으로 agent-ui status를 일괄 구현됨으로 바꾸지 않는다. 종료 검토 통과와 code evidence가 있는 항목만 반영한다.
  • 검증 실패나 사용자 판단 차단 상태에서 commit/push하지 않는다.
  • .sync-state.json을 agent-ui 변경분 판정 대상으로 삼지 않는다.
  • 정의서와 충돌하는 wireframe만을 근거로 코드 구현을 확정하지 않는다.
  • 실패한 sync의 작업트리 변경을 사용자 결정 없이 되돌리지 않는다.