toki/nexo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Compare commits

base: toki:main
Branches Tags
toki:main
toki:fix/mattermost-ko-dayperiod
..
compare: toki:fix/mattermost-ko-dayperiod
Branches Tags
toki:main
toki:fix/mattermost-ko-dayperiod

3 commits
main ... fix/matter

Author SHA1 Message Date
toki
d7e044cf5c update: project documentation and build scripts 
- Add smoke-compose script for compose validation
- Update build, lint, test scripts
- Update agent roadmap and phase documentation
- Update project README and docs
 2026-05-30 19:10:05 +09:00
toki
8c07405b31 sync: agent-ops from agentic-framework v1.1.105 2026-05-30 19:05:50 +09:00
toki
e82990ddff chore: upstream sync and roadmap updates 
- Update README with latest project status
- Archive upstream-runtime milestone and update roadmap
- Update Mattermost Android build configuration
- Sync upstream references for core and push-proxy services
 2026-05-30 15:44:06 +09:00
358 changed files with 1483 additions and 36827 deletions
Show stats Expand all files Collapse all files

4
.claude/settings.json
View file

@ -1,6 +1,8 @@
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"deny": []
"deny": [
"Read(./agent-task/archive/**)"
]
}
}

14
.clinerules
View file

@ -3,19 +3,13 @@
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다.
- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`은 중앙 관리되는 공통 영역이므로 어떤 프로젝트 작업에서도 사용자가 직접 지시하지 않는 이상 절대 직접 수정하지 않는다. 프로젝트별 규칙과 스킬은 반드시 대응하는 `project/**` 영역에만 반영한다.
- 최종 답변은 한국어로 한다.
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
- 요청 범위를 넘는 변경을 하지 않는다.
- 불확실하면 단정하지 말고 후보를 제시한다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우, 또는 plan 스킬이 같은 task group의 새 index를 충돌 없이 할당하는 경우에만 필요한 범위를 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. index 할당은 같은 task group의 archived sibling directory basename만 열람하고 내부 파일은 읽지 않는다.
- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다.
- `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-spec/` 디렉터리가 있는 프로젝트에서 현재 구현 스펙 확인, 기존 기능 변경, 완료 검토, 구현 스펙 생성/갱신 요청은 세션 1회 `agent-ops/rules/common/rules-agent-spec.md`를 읽고, `agent-spec/index.md`와 매칭되는 spec 문서만 읽는다.
- `agent-spec/archive/**`는 일반 작업에서 읽지 않는다. 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-spec.md`의 archive 접근 규칙을 따른다.
- agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다.
- tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다.
- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다.
**세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다.
@ -33,16 +27,10 @@
- agent-ops 초기화
- domain rule 생성
- skill 생성
- agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW
- 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test
- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리
- agent-spec 생성/갱신, 현재 구현 스펙 문서화, 구현 스펙 업데이트, 스펙 동기화
- README 생성
- 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기
- 로드맵/마일스톤 생성·갱신
- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제
- 로드맵 현지점 / 현재 작업 지점 확인
- 마일스톤 완료 검토 / 종료 검토 / 현재 마일스톤 닫기 / 다음 마일스톤 지정
- 계획 작성 / plan 생성
- 코드 리뷰 / review 진행
- git commit / push

14
.cursorrules
View file

@ -3,19 +3,13 @@
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다.
- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`은 중앙 관리되는 공통 영역이므로 어떤 프로젝트 작업에서도 사용자가 직접 지시하지 않는 이상 절대 직접 수정하지 않는다. 프로젝트별 규칙과 스킬은 반드시 대응하는 `project/**` 영역에만 반영한다.
- 최종 답변은 한국어로 한다.
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
- 요청 범위를 넘는 변경을 하지 않는다.
- 불확실하면 단정하지 말고 후보를 제시한다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우, 또는 plan 스킬이 같은 task group의 새 index를 충돌 없이 할당하는 경우에만 필요한 범위를 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. index 할당은 같은 task group의 archived sibling directory basename만 열람하고 내부 파일은 읽지 않는다.
- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다.
- `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-spec/` 디렉터리가 있는 프로젝트에서 현재 구현 스펙 확인, 기존 기능 변경, 완료 검토, 구현 스펙 생성/갱신 요청은 세션 1회 `agent-ops/rules/common/rules-agent-spec.md`를 읽고, `agent-spec/index.md`와 매칭되는 spec 문서만 읽는다.
- `agent-spec/archive/**`는 일반 작업에서 읽지 않는다. 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-spec.md`의 archive 접근 규칙을 따른다.
- agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다.
- tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다.
- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다.
**세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다.
@ -33,16 +27,10 @@
- agent-ops 초기화
- domain rule 생성
- skill 생성
- agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW
- 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test
- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리
- agent-spec 생성/갱신, 현재 구현 스펙 문서화, 구현 스펙 업데이트, 스펙 동기화
- README 생성
- 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기
- 로드맵/마일스톤 생성·갱신
- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제
- 로드맵 현지점 / 현재 작업 지점 확인
- 마일스톤 완료 검토 / 종료 검토 / 현재 마일스톤 닫기 / 다음 마일스톤 지정
- 계획 작성 / plan 생성
- 코드 리뷰 / review 진행
- git commit / push

15
.gitignore vendored
View file

@ -8,10 +8,6 @@ Thumbs.db
*.log.jsonl
*.log.gz
# Keep roadmap/task archive logs tracked (completion records), despite *.log above
!agent-roadmap/archive/**/*.log
!agent-task/archive/**/*.log
# Local environment and secrets
.env
.env.*
@ -30,9 +26,6 @@ agent-ops/rules/private/
agent-test/local/
agent-test/runs/
# Local upstream staging clones
.upstream/
# Dart / Flutter
.dart_tool/
**/.dart_tool/
@ -118,11 +111,3 @@ services/core/mattermost.mattermost-license
*.iws
.vscode/
*.code-workspace
# BEGIN Agent-Ops managed gitignore
!agent-task/
!agent-task/**/
!agent-task/**/*.md
!agent-task/**/*.log
agent-roadmap/current.md
# END Agent-Ops managed gitignore

14
AGENTS.md
View file

@ -3,19 +3,13 @@
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다.
- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`은 중앙 관리되는 공통 영역이므로 어떤 프로젝트 작업에서도 사용자가 직접 지시하지 않는 이상 절대 직접 수정하지 않는다. 프로젝트별 규칙과 스킬은 반드시 대응하는 `project/**` 영역에만 반영한다.
- 최종 답변은 한국어로 한다.
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
- 요청 범위를 넘는 변경을 하지 않는다.
- 불확실하면 단정하지 말고 후보를 제시한다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우, 또는 plan 스킬이 같은 task group의 새 index를 충돌 없이 할당하는 경우에만 필요한 범위를 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. index 할당은 같은 task group의 archived sibling directory basename만 열람하고 내부 파일은 읽지 않는다.
- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다.
- `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-spec/` 디렉터리가 있는 프로젝트에서 현재 구현 스펙 확인, 기존 기능 변경, 완료 검토, 구현 스펙 생성/갱신 요청은 세션 1회 `agent-ops/rules/common/rules-agent-spec.md`를 읽고, `agent-spec/index.md`와 매칭되는 spec 문서만 읽는다.
- `agent-spec/archive/**`는 일반 작업에서 읽지 않는다. 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-spec.md`의 archive 접근 규칙을 따른다.
- agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다.
- tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다.
- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다.
**세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다.
@ -33,16 +27,10 @@
- agent-ops 초기화
- domain rule 생성
- skill 생성
- agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW
- 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test
- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리
- agent-spec 생성/갱신, 현재 구현 스펙 문서화, 구현 스펙 업데이트, 스펙 동기화
- README 생성
- 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기
- 로드맵/마일스톤 생성·갱신
- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제
- 로드맵 현지점 / 현재 작업 지점 확인
- 마일스톤 완료 검토 / 종료 검토 / 현재 마일스톤 닫기 / 다음 마일스톤 지정
- 계획 작성 / plan 생성
- 코드 리뷰 / review 진행
- git commit / push

14
CLAUDE.md
View file

@ -3,19 +3,13 @@
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다.
- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`은 중앙 관리되는 공통 영역이므로 어떤 프로젝트 작업에서도 사용자가 직접 지시하지 않는 이상 절대 직접 수정하지 않는다. 프로젝트별 규칙과 스킬은 반드시 대응하는 `project/**` 영역에만 반영한다.
- 최종 답변은 한국어로 한다.
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
- 요청 범위를 넘는 변경을 하지 않는다.
- 불확실하면 단정하지 말고 후보를 제시한다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우, 또는 plan 스킬이 같은 task group의 새 index를 충돌 없이 할당하는 경우에만 필요한 범위를 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. index 할당은 같은 task group의 archived sibling directory basename만 열람하고 내부 파일은 읽지 않는다.
- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다.
- `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-spec/` 디렉터리가 있는 프로젝트에서 현재 구현 스펙 확인, 기존 기능 변경, 완료 검토, 구현 스펙 생성/갱신 요청은 세션 1회 `agent-ops/rules/common/rules-agent-spec.md`를 읽고, `agent-spec/index.md`와 매칭되는 spec 문서만 읽는다.
- `agent-spec/archive/**`는 일반 작업에서 읽지 않는다. 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-spec.md`의 archive 접근 규칙을 따른다.
- agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다.
- tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다.
- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다.
**세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다.
@ -33,16 +27,10 @@
- agent-ops 초기화
- domain rule 생성
- skill 생성
- agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW
- 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test
- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리
- agent-spec 생성/갱신, 현재 구현 스펙 문서화, 구현 스펙 업데이트, 스펙 동기화
- README 생성
- 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기
- 로드맵/마일스톤 생성·갱신
- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제
- 로드맵 현지점 / 현재 작업 지점 확인
- 마일스톤 완료 검토 / 종료 검토 / 현재 마일스톤 닫기 / 다음 마일스톤 지정
- 계획 작성 / plan 생성
- 코드 리뷰 / review 진행
- git commit / push

14
GEMINI.md
View file

@ -3,19 +3,13 @@
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다.
- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`은 중앙 관리되는 공통 영역이므로 어떤 프로젝트 작업에서도 사용자가 직접 지시하지 않는 이상 절대 직접 수정하지 않는다. 프로젝트별 규칙과 스킬은 반드시 대응하는 `project/**` 영역에만 반영한다.
- 최종 답변은 한국어로 한다.
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
- 요청 범위를 넘는 변경을 하지 않는다.
- 불확실하면 단정하지 말고 후보를 제시한다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우, 또는 plan 스킬이 같은 task group의 새 index를 충돌 없이 할당하는 경우에만 필요한 범위를 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. index 할당은 같은 task group의 archived sibling directory basename만 열람하고 내부 파일은 읽지 않는다.
- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다.
- `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-spec/` 디렉터리가 있는 프로젝트에서 현재 구현 스펙 확인, 기존 기능 변경, 완료 검토, 구현 스펙 생성/갱신 요청은 세션 1회 `agent-ops/rules/common/rules-agent-spec.md`를 읽고, `agent-spec/index.md`와 매칭되는 spec 문서만 읽는다.
- `agent-spec/archive/**`는 일반 작업에서 읽지 않는다. 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-spec.md`의 archive 접근 규칙을 따른다.
- agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다.
- tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다.
- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다.
**세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다.
@ -33,16 +27,10 @@
- agent-ops 초기화
- domain rule 생성
- skill 생성
- agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW
- 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test
- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리
- agent-spec 생성/갱신, 현재 구현 스펙 문서화, 구현 스펙 업데이트, 스펙 동기화
- README 생성
- 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기
- 로드맵/마일스톤 생성·갱신
- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제
- 로드맵 현지점 / 현재 작업 지점 확인
- 마일스톤 완료 검토 / 종료 검토 / 현재 마일스톤 닫기 / 다음 마일스톤 지정
- 계획 작성 / plan 생성
- 코드 리뷰 / review 진행
- git commit / push

84
README.md
View file

@ -50,21 +50,6 @@ cp .env.example .env
docker compose up
```
## 워크스페이스 포트 기준
Nexo가 소유한 runtime 기본값은 core HTTP `18065`, push-proxy HTTP
`18066`이다. 두 포트는 외부 소비자가 있을 수 있는 compatibility
baseline이므로 즉시 바꾸지 않는다. Flutter/web preview가 필요해지는
후속 작업에서는 frontend slot `13040`을 우선 후보로 쓰고, backend
포트 이동이 필요하면 `18040` 계열 후보를 별도 migration plan에서
다룬다.
Mattermost upstream 개발 compose가 쓰는 DB/cache/object/search/mail/metrics
포트는 upstream dev auxiliary로 취급한다. Nexo compose는 기본적으로
Postgres를 host에 publish하지 않고 compose network 내부 `db:5432`로만
사용한다. 상세 inventory와 secret boundary는
`services/core/compose/README.md`의 Port And Environment Inventory를 본다.
## 주요 명령
| 목적 | 명령 | 비고 |
@ -76,10 +61,11 @@ Postgres를 host에 publish하지 않고 compose network 내부 `db:5432`로만
| 서버 Go 테스트 포함 | `NEXO_CORE_GO_TEST=1 bin/test` | 로컬 `go`가 필요하다. |
| 서버 Go vet 포함 | `NEXO_CORE_GO_LINT=1 bin/lint` | 로컬 `go`가 필요하다. |
| 서버 Go build 포함 | `NEXO_CORE_GO_BUILD=1 bin/build` | 로컬 `go`가 필요하다. |
| Flutter Web/Chrome 테스트 포함 | `NEXO_FLUTTER_WEB_TEST=1 bin/test` | `packages/messaging_flutter`에서 `flutter test --platform chrome`을 실행한다. Flutter Chrome test 환경이 필요하다. |
| `flutter-test` 호스트 직접 실행 | `cd apps/flutter-test && flutter run` | Flutter SDK가 필요하다. |
| 플러그인 직접 테스트 | `cd packages/messaging_flutter && flutter test` | Flutter SDK가 필요하다. |
| Android 네이티브 단위 테스트 실행 | `cd apps/flutter-test/android && ./gradlew testDebugUnitTest` | Android SDK가 필요하다. |
| Flutter SDK integration 테스트 포함 | `NEXO_FLUTTER_INTEGRATION_TEST=1 bin/test` | `apps/flutter-test`에서 `flutter test integration_test`를 실행한다. Flutter SDK가 필요하다. |
| Android native 단위 테스트 포함 | `NEXO_ANDROID_NATIVE_TEST=1 bin/test` | `apps/flutter-test/android`에서 `./gradlew testDebugUnitTest`를 실행한다. Java/Gradle/Android SDK가 필요하다. |
`bin/*` helper는 필요한 로컬 도구가 없으면 일부 검증을 건너뛸 수 있다. 작업 보고에는 건너뛴 검증을 함께 적는다.
@ -92,7 +78,6 @@ Postgres를 host에 publish하지 않고 compose network 내부 `db:5432`로만
| `apps/mattermost/` | Mattermost 모바일 앱 저장소 스냅샷 |
| `services/core/` | Mattermost 서버 저장소 clone과 현재 compose 런타임 |
| `services/push-proxy/` | Mattermost push-proxy 저장소 스냅샷 |
| `.upstream/mattermost/` | ignored Mattermost 원본 저장소 staging clone |
| `docs/` | 모듈 간 제품, migration, 운영 문서 |
| `bin/` | workspace helper 진입점 |
| `agent-ops/` | agent 규칙, domain rule, 공통 skill 진입점 |
@ -107,14 +92,59 @@ Postgres를 host에 publish하지 않고 compose network 내부 `db:5432`로만
- `apps/flutter-test/`는 플러그인 통합 검증용 호스트로만 본다. 제품 앱으로 키우거나 플러그인 내부 동작을 복제하지 않는다.
- `apps/mattermost`, `services/core`, `services/push-proxy`는 Mattermost 원본 저장소 clone으로 본다. nexo 소유 앱이나 독자 서버 제품으로 재정의하지 않는다.
- 명시적인 업스트림 결정 없이 `services/core/UPSTREAM.md`의 기준선 정보를 바꾸지 않는다.
- 업스트림 작업 clone은 이 저장소 안의 ignored `.upstream/mattermost/` staging 폴더에 원본 저장소별로 둔다.
- `bin/sync-upstream`은 `.upstream/mattermost/` clone 생성과 fast-forward 갱신만 담당하며, snapshot target으로 자동 복사하지 않는다.
- 업스트림 작업 clone은 이 저장소 밖의 sibling/external `mattermost/` staging 폴더에 원본 저장소별로 둔다.
- 업스트림 저장소는 기록된 branch를 따라간다. `mattermost-mobile`은 `main`, `mattermost`와 `mattermost-push-proxy`는 `master`를 기준으로 하며, branch 변경 시점이나 의도적으로 정한 갱신 시점에 스냅샷을 떠서 이 저장소로 merge 요청한다.
- 이 저장소에 들어오는 스냅샷은 원본 저장소별 정확한 commit SHA를 기록한다.
- merge 요청은 원칙적으로 업스트림 저장소별로 분리한다. `apps/mattermost`, `services/core`, `services/push-proxy` 스냅샷을 한 요청에 섞지 않는다.
- staging pull 결과를 이 저장소에 자동 반영하지 않는다. 스냅샷 diff와 관련 smoke 검증을 확인한 뒤 merge 요청한다.
- Nexo 전용 패치는 가능한 한 업스트림 스냅샷 밖의 compose, 문서, 래퍼, 작고 명시적인 패치로 둔다.
## 업스트림 스냅샷 운영
workspace script를 둘 때의 계약은 자동 merge가 아니라 snapshot 후보 준비다.
script는 외부 `mattermost/` staging clone을 기록된 branch로 update하고,
선택한 commit을 이 repo의 대응 경로로 복사할 수 있다. script 실행만으로
baseline을 변경한 것으로 보지 않는다.
snapshot 반영은 다음 단계를 분리한다.
1. staging clone update와 후보 commit 선택
2. repo별 snapshot copy: `apps/mattermost`, `services/core`, `services/push-proxy` 중 하나
3. 해당 `UPSTREAM.md`의 source, branch, tag/commit, snapshot date 갱신
4. snapshot diff 확인과 nexo-local patch inventory 정리
5. 변경 범위에 맞는 smoke 검증
6. repo별 merge 요청
release watch는 월 1회 Mattermost server/webapp release 흐름과 push-proxy
`master` 변경을 확인하고, security patch 또는 ESR 영향이 있으면 정기 주기와
별도로 snapshot 후보를 만든다. watch 결과는 해당 모듈의 `UPSTREAM.md`에
baseline 후보 또는 보류 사유로 남기고, 검증 증거는 필요하면
`docs/runtime-image-validation.md`나 merge 요청 본문에 연결한다.
## 업스트림 Patch 경계
`services/core/server`, `services/core/webapp`, `services/push-proxy`는
upstream-owned runtime으로 취급한다. Nexo 변경은 upstream snapshot과 다시
비교하기 쉬운 얇은 layer에 둔다.
webapp은 기본 메시지 앱 또는 reference front로 유지한다. branding, copy,
기능 숨김은 설정, wrapper, 작은 compatibility patch로 제한하고, 제품별 화면
흐름이나 앱별 business logic은 Nexo Flutter SDK를 소비하는 앱 쪽에서 소유한다.
대량 rename, directory 재배치, formatting-only churn, deep fork는 금지한다.
예외는 보안 패치, upstream update 차단 해소, Nexo runtime 계약 유지에 필요한
최소 변경일 때만 허용하며, 해당 모듈의 `UPSTREAM.md`에 변경 path, 사유,
rebase 위험, 검증 결과를 남긴다.
upstream 새 기능은 다음 후보로 분류한 뒤 반영한다.
| 후보 | 기준 | 처리 |
| --- | --- | --- |
| keep | runtime 호환성, 보안, 기본 메시징 동작에 필요 | snapshot에 유지하고 smoke 검증에 포함한다. |
| hide | 기본 메시지 앱에서 노출하면 혼선을 주지만 upstream 유지에는 유리 | 설정, feature flag, 얇은 UI patch로 숨긴다. |
| defer | Nexo 계약 영향이 불명확하거나 검증 비용이 큰 기능 | 별도 follow-up으로 보류 사유와 재검토 조건을 남긴다. |
| remove | 보안, 라이선스, runtime 안정성 문제로 유지할 수 없는 기능 | 제거 사유와 upstream rebase 위험을 기록하고 검증한다. |
## 개발 흐름
1. 변경할 경로의 domain rule을 읽는다.
@ -123,19 +153,6 @@ Postgres를 host에 publish하지 않고 compose network 내부 `db:5432`로만
4. workspace 수준 검증이 필요하면 `bin/test`, `bin/lint`, `bin/build`를 사용한다.
5. 서버 런타임 검증이 필요하면 `services/core/compose/`를 사용한다.
## 운영 업데이트/배포 흐름
upstream baseline이나 runtime image가 바뀌면 하나의 변경 기록에서 다음 항목을 함께 남긴다.
1. server, webapp, push-proxy baseline ref와 nexo Flutter SDK compatibility 범위.
2. 배포 후보 image tag 또는 digest, compose input hash, 적용 lane.
3. secret profile label과 주입 방식. 실제 값, credential, host, port는 tracked 문서와 task/review log에 쓰지 않는다.
4. smoke 결과와 실패 분류. 실패는 server, webapp, push-proxy, SDK contract, infra 중 하나로 후속 이슈화한다.
5. rollback ref와 rollback evidence 위치. 공개 기록에는 private run log 참조와 판정만 남긴다.
compose lane, secret 주입, rollback 기준은 `services/core/compose/README.md`의
Deployment Loop를 따른다.
## 환경 변수
### Core Compose
@ -156,7 +173,8 @@ Deployment Loop를 따른다.
| `NEXO_CORE_GO_TEST` | `bin/test`에서 서버 Go 테스트를 실행한다. | `0` |
| `NEXO_CORE_GO_LINT` | `bin/lint`에서 서버 Go vet을 실행한다. | `0` |
| `NEXO_CORE_GO_BUILD` | `bin/build`에서 서버 Go build를 실행한다. | `0` |
| `NEXO_FLUTTER_WEB_TEST` | `bin/test`에서 `packages/messaging_flutter` Chrome/web 테스트를 실행한다. | `0` |
| `NEXO_FLUTTER_INTEGRATION_TEST` | `bin/test`에서 `apps/flutter-test` integration 테스트를 실행한다. | `0` |
| `NEXO_ANDROID_NATIVE_TEST` | `bin/test`에서 `apps/flutter-test/android` Android 네이티브 단위 테스트를 실행한다. | `0` |
## 참고 문서

2
agent-ops/.version
View file

@ -1 +1 @@
1.1.171
1.1.105

91
agent-ops/bin/ai-ignore.sh
View file

@ -3,58 +3,11 @@
# Shared AI ignore / permission defaults for init and sync flows.
AGENT_OPS_TASK_ARCHIVE_IGNORE_PATTERN="agent-task/archive/**"
AGENT_ROADMAP_ARCHIVE_IGNORE_PATTERN="agent-roadmap/archive/**"
AGENT_ROADMAP_CURRENT_LOCAL_PATTERN="agent-roadmap/current.md"
AGENT_OPS_AI_IGNORE_BLOCK_BEGIN="# BEGIN Agent-Ops managed ignore"
AGENT_OPS_AI_IGNORE_BLOCK_END="# END Agent-Ops managed ignore"
AGENT_OPS_GITIGNORE_BLOCK_BEGIN="# BEGIN Agent-Ops managed gitignore"
AGENT_OPS_GITIGNORE_BLOCK_END="# END Agent-Ops managed gitignore"
AGENT_OPS_AI_IGNORE_FILES=(".geminiignore" ".aiexclude" ".cursorignore" ".clineignore")
AGENT_OPS_AI_PERMISSION_FILES=(".claude/settings.json" "opencode.json")
AGENT_OPS_AI_SYNC_FILES=(".gitignore" "${AGENT_OPS_AI_IGNORE_FILES[@]}" "${AGENT_OPS_AI_PERMISSION_FILES[@]}")
agent_ops_ensure_gitignore_task_artifact_block() {
local file="$1"
local tmp
touch "$file"
if grep -qxF "$AGENT_OPS_GITIGNORE_BLOCK_BEGIN" "$file" \
&& grep -qxF "$AGENT_OPS_GITIGNORE_BLOCK_END" "$file"; then
tmp="$(mktemp "$file.tmp.XXXXXX")"
awk \
-v begin="$AGENT_OPS_GITIGNORE_BLOCK_BEGIN" \
-v end="$AGENT_OPS_GITIGNORE_BLOCK_END" \
-v current="$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" '
$0 == begin {
print begin
print "!agent-task/"
print "!agent-task/**/"
print "!agent-task/**/*.md"
print "!agent-task/**/*.log"
print current
print end
in_block = 1
next
}
$0 == end && in_block {
in_block = 0
next
}
!in_block { print }
' "$file" > "$tmp"
mv "$tmp" "$file"
else
if [[ -s "$file" ]]; then
printf "\n" >> "$file"
fi
printf "%s\n" "$AGENT_OPS_GITIGNORE_BLOCK_BEGIN" >> "$file"
printf "%s\n" "!agent-task/" >> "$file"
printf "%s\n" "!agent-task/**/" >> "$file"
printf "%s\n" "!agent-task/**/*.md" >> "$file"
printf "%s\n" "!agent-task/**/*.log" >> "$file"
printf "%s\n" "$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" >> "$file"
printf "%s\n" "$AGENT_OPS_GITIGNORE_BLOCK_END" >> "$file"
fi
}
AGENT_OPS_AI_SYNC_FILES=("${AGENT_OPS_AI_IGNORE_FILES[@]}" "${AGENT_OPS_AI_PERMISSION_FILES[@]}")
agent_ops_ensure_ai_ignore_block() {
local file="$1"
@ -118,6 +71,8 @@ agent_ops_merge_json_with_jq() {
agent_ops_merge_claude_settings() {
local file="$1"
local filter='
def append_unique($item):
if index($item) then . else . + [$item] end;
def as_array:
if type == "array" then . elif . == null then [] else [.] end;
def as_object:
@ -127,14 +82,14 @@ def as_object:
| .permissions.deny = (
(.permissions.deny | as_array)
| map(select(. != "Read(./agent-roadmap/archive/**)"))
| map(select(. != "Read(./agent-task/archive/**)"))
| append_unique("Read(./agent-task/archive/**)")
)
'
agent_ops_merge_json_with_jq \
"$file" \
"$filter" \
"Note: .claude/settings.json exists; remove Read(./agent-task/archive/**) and Read(./agent-roadmap/archive/**) manually."
"Note: .claude/settings.json exists; add Read(./agent-task/archive/**) and remove Read(./agent-roadmap/archive/**) manually."
}
agent_ops_claude_settings_complete() {
@ -145,15 +100,14 @@ def as_array:
(.permissions.deny | as_array)
as $deny
| (($deny | index("Read(./agent-task/archive/**)")) == null)
| (($deny | index("Read(./agent-task/archive/**)")) != null)
and (($deny | index("Read(./agent-roadmap/archive/**)")) == null)
'
if command -v jq >/dev/null 2>&1; then
jq -e "$filter" "$file" >/dev/null 2>&1
else
! grep -qF "Read(./agent-task/archive/**)" "$file" \
&& ! grep -qF "Read(./agent-roadmap/archive/**)" "$file"
grep -q "agent-task/archive" "$file"
fi
}
@ -169,10 +123,10 @@ def as_object:
.permission = ((.permission // {}) | as_object)
| .permission.read = ((.permission.read // {}) | as_object)
| del(.permission.read["agent-task/archive/**"])
| .permission.read["agent-task/archive/**"] = "deny"
| del(.permission.read["agent-roadmap/archive/**"])
| .permission.glob = ((.permission.glob // {}) | as_object)
| del(.permission.glob["agent-task/archive/**"])
| .permission.glob["agent-task/archive/**"] = "deny"
| del(.permission.glob["agent-roadmap/archive/**"])
| .watcher = ((.watcher // {}) | as_object)
| .watcher.ignore = (
@ -185,7 +139,7 @@ def as_object:
agent_ops_merge_json_with_jq \
"$file" \
"$filter" \
"Note: opencode.json exists; remove agent-task/archive/** and agent-roadmap/archive/** read/glob hard deny, and add both archive paths to watcher ignore manually."
"Note: opencode.json exists; add agent-task/archive/** read/glob deny, remove agent-roadmap/archive/** read/glob hard deny, and add agent-task/archive/** plus agent-roadmap/archive/** watcher ignore manually."
}
agent_ops_opencode_config_complete() {
@ -194,8 +148,8 @@ agent_ops_opencode_config_complete() {
def as_array:
if type == "array" then . elif . == null then [] else [.] end;
(.permission.read["agent-task/archive/**"] != "deny")
and (.permission.glob["agent-task/archive/**"] != "deny")
(.permission.read["agent-task/archive/**"] == "deny")
and (.permission.glob["agent-task/archive/**"] == "deny")
and (.permission.read["agent-roadmap/archive/**"] != "deny")
and (.permission.glob["agent-roadmap/archive/**"] != "deny")
and ((.watcher.ignore | as_array) as $ignore | (($ignore | index("agent-task/archive/**")) != null) and (($ignore | index("agent-roadmap/archive/**")) != null))
@ -204,10 +158,7 @@ and ((.watcher.ignore | as_array) as $ignore | (($ignore | index("agent-task/arc
if command -v jq >/dev/null 2>&1; then
jq -e "$filter" "$file" >/dev/null 2>&1
else
grep -qF "agent-task/archive" "$file" \
&& grep -qF "agent-roadmap/archive" "$file" \
&& ! grep -qF "\"agent-task/archive/**\": \"deny\"" "$file" \
&& ! grep -qF "\"agent-roadmap/archive/**\": \"deny\"" "$file"
grep -q "agent-task/archive" "$file" && grep -q "agent-roadmap/archive" "$file"
fi
}
@ -220,8 +171,6 @@ ensure_agent_ops_ai_ignore_config() {
return
fi
agent_ops_ensure_gitignore_task_artifact_block "$target_dir/.gitignore"
for ignore_file in "${AGENT_OPS_AI_IGNORE_FILES[@]}"; do
agent_ops_ensure_ai_ignore_block "$target_dir/$ignore_file"
done
@ -232,7 +181,9 @@ ensure_agent_ops_ai_ignore_config() {
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"deny": []
"deny": [
"Read(./agent-task/archive/**)"
]
}
}
EOF
@ -244,6 +195,14 @@ EOF
cat > "$target_dir/opencode.json" <<'EOF'
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"read": {
"agent-task/archive/**": "deny"
},
"glob": {
"agent-task/archive/**": "deny"
}
},
"watcher": {
"ignore": [
"agent-task/archive/**",
@ -256,5 +215,5 @@ EOF
agent_ops_merge_opencode_config "$target_dir/opencode.json"
fi
echo " AI permission 표준 적용: archive hard deny 제거, archive ignore 적용"
echo " AI permission 표준 적용: roadmap archive hard deny 제거"
}

1
agent-ops/bin/init-agent-ops.sh
View file

@ -322,7 +322,6 @@ ensure_agent_ops_ai_ignore_config "$TARGET_DIR"
# 5. .gitignore 설정
TOUCH_GITIGNORE="$TARGET_DIR/.gitignore"
touch "$TOUCH_GITIGNORE"
agent_ops_ensure_gitignore_task_artifact_block "$TOUCH_GITIGNORE"
if ! grep -q "agent-ops/rules/private/" "$TOUCH_GITIGNORE"; then
echo "" >> "$TOUCH_GITIGNORE"
echo "# Agent-Ops Private Rules" >> "$TOUCH_GITIGNORE"

46
agent-ops/bin/sync.sh
View file

@ -88,20 +88,6 @@ common_differs() {
return 1
}
entry_files_differ() {
local rules_md="$1" target_root="$2"
local f
[[ -f "$rules_md" ]] || return 0
for f in "${AGENT_OPS_ENTRY_FILES[@]}"; do
if [[ ! -f "$target_root/$f" ]] || ! cmp -s "$rules_md" "$target_root/$f"; then
return 0
fi
done
return 1
}
create_project_agent_ops_dirs() {
local agent_ops_dir="$1"
mkdir -p "$agent_ops_dir/rules/project/domain"
@ -170,11 +156,6 @@ commit_and_push_agent_ops_scope() {
cd "$repo"
mapfile -t paths < <(agent_ops_git_paths "$include_ai_config")
git add -- "${paths[@]}"
if git ls-files --error-unmatch "$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" >/dev/null 2>&1 \
&& grep -qxF "$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" ".gitignore" 2>/dev/null; then
git rm --cached --quiet --ignore-unmatch "$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN"
paths+=("$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN")
fi
if git diff --cached --quiet -- "${paths[@]}"; then
echo " agent-ops 변경 없음: commit 건너뜀"
@ -276,11 +257,6 @@ fi
if [[ "$IS_FRAMEWORK" == "1" ]]; then
SRC_VER="$(cat "$SRC_AO/.version" 2>/dev/null || echo "0.0.0")"
echo " .agent-ops-source 감지: push 동기화에서는 버전 bump 없이 v$SRC_VER 그대로 전파"
if entry_files_differ "$SRC_AO/rules/common/rules.md" "$PROJECT_ROOT"; then
echo " 공통 원본 repo 진입 파일 재적용"
apply_agent_ops_entry_files "$SRC_AO/rules/common/rules.md" "$PROJECT_ROOT"
commit_and_push_agent_ops_scope "$PROJECT_ROOT" "sync: reapply agent-ops entry files" "0"
fi
if [[ -n "$TARGET_INPUT" ]]; then
TARGET="$(resolve_target "$TARGET_INPUT")"
if [[ -z "$TARGET" ]]; then
@ -334,31 +310,15 @@ if ! common_differs "$SRC_AO" "$DST_AO"; then
COMMON_CHANGED="0"
fi
ENTRY_FILES_CHANGED="0"
if entry_files_differ "$SRC_AO/rules/common/rules.md" "$PROJECT_ROOT" \
|| entry_files_differ "$DST_AO/rules/common/rules.md" "$TARGET"; then
ENTRY_FILES_CHANGED="1"
fi
if [[ "$COMMON_CHANGED" == "1" ]] && version_gt "$DST_VER" "$SRC_VER"; then
echo -e "${RED}⚠ 버전 충돌: 원본 repo($DST_VER) > current($SRC_VER)${RESET}"
echo -e "${YELLOW} 먼저 sync-pull로 내려받은 뒤 재시도하세요.${RESET}"
exit 1
fi
if [[ "$COMMON_CHANGED" == "0" && "$ENTRY_FILES_CHANGED" == "0" ]]; then
echo " 공통 파일/진입 파일 변경 없음: .version 차이는 무시하고 버전 갱신/커밋을 건너뜀"
echo -e "${GREEN}✓ 완료 (공통 변경 없음)${RESET}"
exit 0
fi
if [[ "$COMMON_CHANGED" == "0" ]]; then
echo " 공통 파일 변경 없음: 진입 파일만 재적용"
apply_agent_ops_entry_files "$SRC_AO/rules/common/rules.md" "$PROJECT_ROOT"
apply_agent_ops_entry_files "$DST_AO/rules/common/rules.md" "$TARGET"
commit_and_push_agent_ops_scope "$TARGET" "sync: reapply agent-ops entry files" "0"
commit_and_push_agent_ops_scope "$PROJECT_ROOT" "sync: reapply agent-ops entry files" "0"
echo -e "${GREEN}✓ 완료 (진입 파일 재적용)${RESET}"
echo " 공통 파일 변경 없음: .version 차이는 무시하고 버전 갱신/커밋을 건너뜀"
echo -e "${GREEN}✓ 완료 (공통 변경 없음)${RESET}"
exit 0
fi
@ -366,8 +326,6 @@ NEW_VER="$(bump_version "$SRC_VER")"
sync_common "$SRC_AO" "$DST_AO"
echo "$NEW_VER" > "$SRC_AO/.version"
echo "$NEW_VER" > "$DST_AO/.version"
apply_agent_ops_entry_files "$SRC_AO/rules/common/rules.md" "$PROJECT_ROOT"
apply_agent_ops_entry_files "$DST_AO/rules/common/rules.md" "$TARGET"
commit_and_push_agent_ops_scope "$TARGET" "sync: from $(basename "$PROJECT_ROOT") v$NEW_VER" "0"
commit_and_push_agent_ops_scope "$PROJECT_ROOT" "sync: to agentic-framework v$NEW_VER" "0"

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

@ -1,15 +1,15 @@
---
test_env: <env>
test_env: <local|dev|qa|prod>
last_rule_updated_at: <YYYY-MM-DD>
---
# <env> 테스트 규칙
# <test_env> 테스트 규칙
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
## 공통 규칙
- <env> 테스트/검증은 이 파일을 기준으로 판단한다.
- <test_env> 테스트/검증은 이 파일을 기준으로 판단한다.
- 작업 완료 검증은 변경 범위 기준으로 선택한다.
- 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
- 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
@ -18,22 +18,17 @@ last_rule_updated_at: <YYYY-MM-DD>
## 기본 환경
- host:
- repo root:
- sync 기준:
- port:
- 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/<env>/<test-profile>.md`
- <domain 또는 project-wide> / <verification-type> / <scope 요약>: `agent-test/<test_env>/<test-profile>.md`
## 라우팅 규칙

4
agent-ops/rules/common/philosophy.md
View file

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

108
agent-ops/rules/common/rules-agent-spec.md
View file

@ -1,108 +0,0 @@
# agent-spec 규칙
`agent-spec/`가 있는 프로젝트 또는 agent-spec 생성, 갱신, 마일스톤 종료 검토 요청에서 적용한다.
## 목적
`agent-spec/`는 사람과 AI agent가 현재 구현된 기능 목록, 동작 흐름, 계약 링크, 검증 방법을 함께 파악하기 위한 living spec 저장소다.
로드맵 완료 이력, SDD 설계 논의, 계약 원문, 사람용 가이드를 대체하지 않는다.
## 기본 구조
```text
agent-spec/
index.md
archive/
<area>/
<spec-id>.log
<area>/
<spec-id>.md
```
- `index.md`는 현재 스펙 목록과 읽기 라우팅 source of truth다.
- `<area>/<spec-id>.md`는 현재 구현 스펙 문서다.
- `archive/**`는 폐기되거나 대체된 과거 스펙 스냅샷이다.
- `<area>`와 `<spec-id>`는 소문자 영문, 숫자, 하이픈만 사용한다.
## Source of Truth
- `agent-spec/**`는 현재 구현 지도를 제공하지만 최종 truth는 코드, `agent-contract/`, 테스트, 설정 예시다.
- API, wire protocol, runtime call, event/config schema, 프로세스 간 요청/응답 계약 원문은 `agent-contract/`에 두고 agent-spec에는 링크와 사용 맥락만 남긴다.
- 코드 배치, 주요 구성 요소, 구현 진입점, 도메인 간 책임 경계, 유지할 패턴, 금지 사항은 domain rule에 둔다.
- agent-spec에는 기능 이해에 필요한 최소 경계만 적고, 코딩할 때 따라야 하는 경계 규칙을 반복하지 않는다.
- SDD는 구현 전 설계 게이트다. agent-spec은 구현 후 현재 상태를 설명한다.
- 로드맵과 complete.log는 완료 근거와 변경 힌트로 사용한다. 현재 동작은 코드와 계약으로 재확인한다.
- 사람용 최신 가이드는 `docs/`에 둔다. agent-spec은 기능 파악과 작업 문맥을 우선한다.
## Frontmatter Schema
- 활성 Markdown 문서는 YAML frontmatter를 둔다.
- `spec_doc_type`은 `index`, `spec`, `archive-log` 중 하나다.
- spec 문서는 `spec_id`, `status`, `source_evidence`를 둔다.
- 활성 spec 문서의 `status` 값은 `구현됨`, `부분`, `가정`, `불명확` 중 하나다.
- archive log의 `status` 값은 `폐기됨`을 사용할 수 있다.
- `구현됨`은 코드/계약/테스트 evidence로 현재 동작이 확인된 상태다.
- `부분`은 핵심 경로는 확인됐지만 일부 흐름, 설정, 검증, 한계가 남은 상태다.
- `가정`은 사용자 입력 또는 제한된 evidence를 바탕으로 임시 정리한 상태다.
- `불명확`은 코드와 계약 기준으로 현재 동작을 확정할 수 없는 상태다.
- `폐기됨`은 활성 spec 문서에 두지 않는다.
- `source_evidence`는 list이며 각 항목은 `type`, `path`, `notes`를 둔다.
- `source_evidence.type`은 `code`, `contract`, `roadmap`, `sdd`, `test`, `docs`, `complete-log`, `user` 중 하나다.
- 실제 파일 근거가 없으면 `path: null`을 사용한다. placeholder 문자열을 현재 근거처럼 남기지 않는다.
## 읽기 규칙
- 일반 작업마다 `agent-spec/`를 읽지 않는다.
- 기존 기능의 기능 목록, 주요 흐름, 계약 링크, 현재 구현 상태가 필요한 작업에서만 세션 1회 `agent-spec/index.md`를 읽는다.
- `index.md`에서 매칭되는 spec 문서만 읽는다.
- 매칭 spec이 없으면 스펙이 없다고 보고하고 코드, 계약, 테스트에서 직접 확인한다. 추측으로 spec 내용을 만들지 않는다.
- spec 문서가 코드/계약과 충돌하면 코드/계약을 우선하고 `update-spec` 필요를 보고한다.
- 코드 배치, 구현 위치, 패턴, 금지 사항, 도메인 간 상세 책임 경계가 필요하면 프로젝트 규칙의 도메인 매핑에 따라 domain rule을 읽는다.
- API, wire protocol, runtime call, event/config schema, 프로세스 간 요청/응답 계약에 닿으면 `agent-contract/index.md`의 규칙에 따라 매칭 계약 문서도 읽는다.
- `agent-spec/archive/**`는 일반 작업에서 읽지 않는다.
- 예외: 사용자가 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우에만 필요한 archive 문서만 좁게 읽는다.
## 생성/갱신 흐름
- agent-spec 최초 도입, 현재 구현 스펙 신규 작성, 전체 bootstrap 작성은 `create-spec`을 사용한다.
- 기존 spec을 코드/계약/테스트/완료 근거에 맞게 갱신하는 작업은 `update-spec`을 사용한다.
- 마일스톤 종료 검토에서는 `complete-milestone`이 `update-spec`을 필수 gate로 실행한다.
- `agent-spec/`가 없으면 `complete-milestone`의 spec gate는 `skipped-no-agent-spec`으로 기록할 수 있다.
- `agent-spec/`가 있으면 `complete-milestone`은 `Spec updated` 또는 `Spec update not needed`를 완료 리뷰에 남긴 뒤에만 Milestone 완료/archive를 진행한다.
- `Spec blocked` 또는 `create-spec needed`이면 Milestone 완료/archive를 진행하지 않는다.
- 새 스펙 작성이나 갱신은 현재 코드/계약/테스트 evidence를 우선하고, 완료된 roadmap archive는 사용자가 요청했거나 현재 스펙의 배경 확인이 꼭 필요한 경우에만 좁게 읽는다.
## 문서 작성 기준
- 현재형으로 작성한다.
- 과거 작업 일지, 설계 논쟁 전문, 완료된 roadmap task 전체 복사, 함수 단위 코드 설명을 넣지 않는다.
- 스펙 본문은 기능 단위의 작동 지도여야 한다. 먼저 기능 목록을 두고, 필요한 흐름만 뒤에 보강한다.
- 기능 목록은 `기능`과 `설명` 중심으로 작성한다. 활성 spec은 구현된 기능만 기록하므로 기능별 `상태` 칼럼을 기본으로 두지 않는다.
- 기능별 부분 지원, 조건부 동작, 한계는 설명 또는 `한계와 주의사항`에 짧게 적는다.
- 주요 흐름은 텍스트만 길게 나열하지 말고 Mermaid `sequenceDiagram` 또는 `flowchart`를 우선 고려한다. 단순 기능은 짧은 목록으로 충분하다.
- 책임 경계는 기능 오해를 막는 최소 수준만 허용한다. 패키지 배치, 구현 진입점, 유지할 패턴, 금지 사항은 domain rule에 둔다.
- `코드 진입점` 섹션은 기본 섹션으로 두지 않는다. 필요한 코드 근거는 frontmatter `source_evidence`와 domain rule로 좁힌다.
- 계약 원문, proto field 전체 목록, config schema 원문을 복제하지 말고 `agent-contract/` 또는 코드 경로를 링크한다.
- 불확실한 내용은 단정하지 말고 `불명확` 또는 `확인 필요`로 남긴다.
- spec 갱신이 필요 없으면 `Spec update not needed: <사유>`를 결과 보고나 Milestone 완료 리뷰에 남긴다.
## 기본 섹션
spec 문서는 아래 섹션을 기본 순서로 작성한다. 해당 spec에 의미가 없는 섹션은 만들지 않는다.
1. `목적`
2. `기능 목록`
3. `범위`
4. `주요 흐름`
5. `계약`
6. `설정/데이터/이벤트`
7. `검증`
8. `한계와 주의사항`
9. `변경 기록`
`책임 경계`가 기능 이해에 꼭 필요하면 별도 섹션으로 짧게 둘 수 있다. 이때 domain rule의 구성 요소, 코드 배치, 금지 사항을 반복하지 않는다.
## 템플릿
- `index.md`: `agent-ops/skills/common/_templates/agent-spec/index-template.md`
- spec 문서: `agent-ops/skills/common/_templates/agent-spec/spec-template.md`

161
agent-ops/rules/common/rules-agent-ui.md
View file

@ -1,161 +0,0 @@
# 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
.sync-state.json # 선택: agent-ui -> code 동기화 기준점
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`에 남긴다.
## 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`를 둔다.
- `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`를 기본 근거처럼 쓰지 않는다.
- `status` 값은 `구현됨`, `계획`, `가정`, `불명확` 중 하나다.
- `구현됨`은 코드 반영 완료 상태다. 코드 근거가 있으면 존재하는 `code` evidence path를 함께 둔다.
- `계획`은 정합화된 UI 정의지만 아직 코드 반영 전이거나 사용자 확인 후 재작업 대상인 상태다.
- `가정`은 사용자 입력 또는 추정만 있고 확정 근거가 부족한 상태다.
- `불명확`은 근거가 부족하거나 판단할 수 없는 상태다.
- `가정`과 `불명확`은 코드 동기화 대상이 아니며, sync 전에 `agent-ui/USER_REVIEW.md`로 분리한다.
- frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`는 같은 기준을 말해야 한다.
- frontmatter는 기계적 검증을 위한 최소 schema이고, 본문 Markdown은 사람과 agent가 읽는 설명을 유지한다.
## 운영 동기화 흐름
- 초기 생성 이후 기본 방향은 `agent-ui -> code` 단방향이다. 코드에서 agent-ui를 만드는 흐름은 `create-agent-ui` 최초 생성에만 사용한다.
- 화면정의서, view, component, frame, wireframe을 agent로 수정하는 요청은 `update-agent-ui`로 처리한다.
- 사용자 리뷰 결정 반영, `UIR-NNN` 해결, "화면정의서와 코드가 안 맞아" 같은 회귀 요청도 `update-agent-ui` 또는 `validate-agent-ui`로 들어와 같은 루프를 재개한다.
- `update-agent-ui`는 agent-ui 문서 갱신을 맡는다. 코드 구현 규모 판정, plan 라우팅, roadmap/milestone 라우팅은 하지 않는다.
- `update-agent-ui` 후에는 변경 범위에 따라 `validate-agent-ui` 필요 여부와 code sync intent 전달 여부만 판단한다. 실행한다면 `validate-agent-ui`가 항상 `sync-agent-ui`보다 먼저 실행된다.
- `validate-agent-ui`는 agent-ui 내부 문서 그래프를 정합화한다. definition, frame, visual source, component, archive, USER_REVIEW 사이의 누락과 충돌을 같은 수준으로 맞춘다.
- 운영 단계의 `validate-agent-ui`는 코드 후보만 보고 새 view/component를 자동 생성하지 않는다. 코드와 agent-ui가 어긋나면 agent-ui 기준 sync 대상, status 회귀, 또는 USER_REVIEW로 분리한다.
- `sync-agent-ui`는 정합화된 agent-ui 변경분을 코드에 반영하기 전에 코드 작업 규모를 판정한다. 작은 코드 작업은 직접 반영하고, 중간 코드 작업은 `plan` 루프로, Milestone이 필요한 큰 코드 작업은 `update-roadmap`의 Milestone/Epic/Task 갱신으로 넘긴다.
- `sync-agent-ui`의 기본 모드는 `.sync-state.json` 기준 이후 변경분만 동기화한다.
- 사용자가 "agent-ui와 코드 전체 동기화"처럼 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다.
- `update-agent-ui` 또는 수동 `validate-agent-ui`가 코드 반영 필요성을 판단했으면 그 판단을 다음 단계로 전달한다. 전달된 판단이 있으면 뒤 단계는 문서 정합성과 sync intent 자체를 재판단하지 않지만, `sync-agent-ui`는 실제 코드 반영 방식 판정을 수행한다.
- 직접 sync가 검증되면 반영된 view/component의 `status`를 `구현됨`으로 바꾼다.
- `sync-agent-ui`가 코드 작업을 `plan-required`로 라우팅한 경우에는 plan이 `Agent UI Completion`을 남기고, code-review PASS 시점에 해당 view/component/frame만 `구현됨`으로 반영한다. 이 경로에서는 `sync-agent-ui`가 status를 직접 변경하지 않는다.
- `sync-agent-ui`가 코드 작업을 `milestone-required`로 라우팅해 `agent-ui 상태 반영: 대기`를 남긴 Milestone만 종료 검토 통과 시 `구현됨` 반영 gate가 된다. 최종 검증과 code evidence가 확인된 view/component/frame만 반영하며, Milestone 완료만으로 agent-ui 전체 status를 일괄 변경하지 않는다.
- 사용자 확인 또는 후속 검증에서 불일치가 발견되면 해당 항목은 `계획`으로 되돌릴 수 있다.
- `sync-agent-ui`가 검증 실패, 환경 차단, 구현 방향 충돌, 반복 실패를 스스로 해결하지 못하면 commit/push하지 않고 `agent-ui/USER_REVIEW.md`에 게이트를 남긴다.
- 실패한 `sync-agent-ui`가 남긴 작업트리 변경은 사용자 결정과 충돌하지 않으면 보존하고, USER_REVIEW 해결 후 같은 변경을 이어서 재검증할 수 있다.
## Sync State
- `agent-ui/.sync-state.json`은 agent-ui 변경분을 코드에 반영한 기준점이다.
- `create-agent-ui`는 생성 결과를 최초 baseline으로 보고 `.sync-state.json`을 만든다.
- 기존 방식으로 생성되어 `.sync-state.json`이 없는 agent-ui는 legacy 상태다. 이 경우 기본 변경분 sync를 시작하지 말고 validate 후 baseline migration으로 기준점을 먼저 만든다.
- baseline은 `code-first`, `concept-first`, `blank` 모두에서 생성된 agent-ui 기준선을 뜻한다. `concept-first` baseline은 코드 구현 완료가 아니라 agent-ui 기준선 확정이다.
- `last_synced_head`는 agent-ui 변경분과 코드 반영이 들어간 sync 결과 commit hash다. `.sync-state.json` 자체를 기록한 commit hash가 아니다.
- baseline 또는 sync 완료 시 commit은 두 단계로 남길 수 있다. 먼저 agent-ui/code 변경 commit을 만들고, 그 commit hash를 `.sync-state.json`에 기록한 별도 commit을 만든 뒤 push한다.
- 변경분 판정에서는 `.sync-state.json` 자체 변경을 제외한다.
## 명명 규칙
- 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`에 남긴다.
- `agent-ui/USER_REVIEW.md`는 `update-agent-ui`, `validate-agent-ui`, `sync-agent-ui`의 통합 gate다.
- 항목에는 어느 단계에서 막혔는지 알 수 있게 `Source Skill`, `Stage`, `Blocking Step`, `Context`, `Options`, `Needed For`를 남긴다.
- 현재 동기화 범위에 미해결 USER_REVIEW 항목이 있으면 `sync-agent-ui`는 실행하지 않는다.
- 해결된 user review는 `agent-ui/archive/user-review/user_review_N.log`로 이동할 수 있다.
- USER_REVIEW 해결 요청은 관련 결정을 agent-ui 활성 문서에 반영한 뒤, 해당 항목을 archive log로 이동하고, 필요하면 `validate-agent-ui`와 `sync-agent-ui`를 순서대로 재개한다.
- `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, wireframe 갱신은 `update-agent-ui`를 사용한다.
- 구조와 정합성 검사, 문서 간 자동 보정, USER_REVIEW 생성은 `validate-agent-ui`를 사용한다.
- 정합화된 agent-ui 변경분을 코드에 반영할 때는 `sync-agent-ui`를 사용한다.

105
agent-ops/rules/common/rules-roadmap.md
View file

@ -5,26 +5,12 @@
## 구조
- 최상위 로드맵은 `agent-roadmap/ROADMAP.md`다.
- Phase를 가로지르는 전역 Milestone 실행 순서는 `agent-roadmap/priority-queue.md`에 둔다.
- 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`에 둔다.
- 활성 Milestone은 해당 Phase 아래 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`에 둔다.
- `<phase-slug>`와 `<milestone-slug>`는 소문자 영문, 숫자, 하이픈만 사용한다.
- 완료된 Phase는 scaffold 그대로 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`로 이동하고, 하위 Milestone도 `archive/phase/<phase-slug>/milestones/` 아래에 둔다.
- 진행중 Phase 안에서 완료된 Milestone은 활성 `PHASE.md`에 짧은 archive 링크를 남기고, 상세 문서는 `agent-roadmap/archive/phase/<phase-slug>/milestones/`로 이동한다.
- archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다.
- 큰 Milestone의 설계 게이트는 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`에 둔다.
- SDD 사용자 리뷰가 필요하면 같은 디렉터리에 `USER_REVIEW.md`를 둔다. 해결된 리뷰는 `user_review_N.log`로 남긴다.
- 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/`로 이동한다.
## 링크 표기
- 사용자에게 보여주는 답변과 활성 로드맵 문서의 문서 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
- 로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`에서는 `[PHASE.md](phase/example-phase/PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/example-milestone.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다.
- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase/example-phase/PHASE.md)`.
- 채팅 결과에 로드맵 문서에서 읽은 링크를 재사용할 때는 원본 Markdown 파일 위치 기준으로 target을 해석한 뒤 repo root 기준 상대경로로 다시 쓴다. 예: `agent-roadmap/current.md`에서 읽은 `(phase/foo/PHASE.md)`는 채팅 출력에서 `(agent-roadmap/phase/foo/PHASE.md)`로, `agent-roadmap/phase/foo/PHASE.md`에서 읽은 `(milestones/bar.md)`는 `(agent-roadmap/phase/foo/milestones/bar.md)`로 쓴다.
- 실제 활성 로드맵 문서에는 `<phase-slug>`, `<milestone-slug>`, `<relative-...>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 문서 생성/갱신 시 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
- 기존 raw path 또는 backtick path는 읽기 입력으로 허용한다. 갱신 범위에 포함된 활성 문서 포인터만 Markdown 링크로 보정하고, archive 스냅샷은 링크 표기만을 이유로 재포맷하지 않는다.
- `.agent-roadmap-sync/locks.yaml`의 `locked`, `rely-on.target`, Milestone identity(`<project>:agent-roadmap/...`)처럼 machine-readable 계약 값은 raw 값을 유지할 수 있다. 사용자-facing 설명에는 가능하면 별도 Markdown 문서 링크를 함께 붙인다.
## Runtime Action Boundary
@ -35,31 +21,20 @@
## 로딩
- 세션 최초 1회 `agent-roadmap/current.md`가 있으면 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다.
- `agent-roadmap/priority-queue.md`가 있으면 Phase를 가로지르는 다음 작업 후보 선택, 사용자가 요청한 순서 조정, archive/폐기/경로 변경/split/merge 후 큐 정리, 깨진 링크 복구가 필요할 때만 읽는다.
- `agent-roadmap/current.md`는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다.
- `current.md`가 없고 로드맵 기반 계획 또는 갱신이 필요하면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 로컬 파일을 만들거나 `ROADMAP.md`와 활성 `PHASE.md`에서 후보를 고른다.
- 읽기 전용 로드맵 현지점 확인에서는 `current.md`가 없어도 만들지 않고, 로컬 current 없음으로 보고한 뒤 `priority-queue.md`가 있으면 전역 실행 순서와 `ROADMAP.md`의 Phase 흐름을 보여준다.
- 세션 최초 1회 `agent-roadmap/current.md`를 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다.
- 일반 작업에서는 `ROADMAP.md`를 읽지 않는다.
- 일반 작업에서는 `priority-queue.md`를 읽지 않는다. 단, 구현 계획이나 다음 작업 선택처럼 Phase를 가로지르는 후보 선택이 필요하면 읽는다.
- 일반 작업에서는 `agent-roadmap/archive/**`를 읽지 않는다.
- 기능 추가, 구조 변경, 구현 계획 전에는 요청과 변경 파일에 맞는 활성 Phase와 활성 Milestone 문서를 읽는다.
- 선택한 Milestone의 `구현 잠금`에 `SDD: 필요`가 있으면 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`와 같은 디렉터리의 `USER_REVIEW.md` 존재 여부를 확인한다.
- 로드맵 현지점 확인은 로컬 `current.md`, `priority-queue.md`의 실행 순서, `ROADMAP.md`의 Phase 흐름, 활성 `PHASE.md`의 Milestone 흐름, 활성 Milestone의 제목/목표/상태를 기본으로 읽는다. `SDD: 필요`이면 SDD 본문을 읽지 말고 SDD 문서 링크와 `USER_REVIEW.md` 존재 여부만 확인한다.
- 로드맵 현지점 확인은 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 `PHASE.md`의 Milestone 흐름, 활성 Milestone의 제목/목표/상태만 기본으로 읽는다.
- `ROADMAP.md`는 로드맵 생성/갱신, Phase 추가/삭제/전환, 전체 구조 변경, 활성 범위 밖 작업 확인 때만 읽는다.
- 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 필요한 archive 문서만 읽는다.
## Phase와 Milestone 선택
- `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
- `priority-queue.md`는 현재 작업 위치가 아니라 Phase를 가로지르는 실행 순서 문서다. 위에 있는 항목을 먼저 검토한다.
- `priority-queue.md`는 순서 전용 문서이며, Milestone 제목 링크와 식별용 한 줄 설명만 둔다. 상태, 목표, 범위, 잠금, 기능, 완료 근거, 의존성은 Milestone 문서를 원본으로 삼는다.
- `priority-queue.md`의 순서는 사용자가 순서 조정을 요청한 경우에만 바꾼다. 단, archive/폐기 제거, 경로 변경, split/merge, 실행 의미 변경, 깨진 링크 복구는 예외다.
- `priority-queue.md` 링크가 깨졌으면 추측하지 말고 활성 Milestone 문서를 기준으로 큐를 재정렬하거나 재생성한다.
- `current.md`는 공유 진행 상태가 아니며, 공유해야 할 상태는 `ROADMAP.md`, `PHASE.md`, Milestone 문서, `.agent-roadmap-sync/locks.yaml`에 남긴다.
- 활성 Phase는 `agent-roadmap/phase/**/PHASE.md`만 대상으로 한다.
- 활성 Milestone은 `agent-roadmap/phase/**/milestones/*.md`만 대상으로 한다.
- `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 완료 근거와 archive 전환이 정리될 때까지 `[검토중]`으로 둔다.
- `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 승인 전까지 `[검토중]`으로 둔다.
- "로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 `update-roadmap` 스킬로 배치 제안 또는 file-based fallback 갱신을 처리하고, Phase/Milestone/Epic/Task 배치를 자동 판단한다.
- target 없는 신규 추가 요청은 먼저 요청 규모를 `phase`, `milestone`, `epic`, `task`, `subtask`, `context` 중 가장 작은 충분한 단위로 판정한다.
- target 없는 신규 추가 요청은 활성 창만으로 결정하지 말고 필요한 경우 `ROADMAP.md`의 Phase 흐름과 관련 Phase/Milestone 문서를 비교한다.
@ -69,38 +44,31 @@
- 부모 후보는 있고 판정 규모의 항목만 없으면 부모 아래에 새 항목을 만들고, 부모도 없을 때만 필요한 부모 항목을 함께 만든다.
- 자동 배치할 때는 선택한 Phase/Milestone/Epic/Task와 밀린 후보의 이유를 결과에 남긴다.
- `current.md`가 아카이브 경로를 가리키면 해당 항목은 활성 후보로 읽지 말고 로드맵 갱신이 필요하다고 보고한다.
- 선택한 Phase/Milestone의 목표 또는 범위 제외와 요청이 충돌하면 구현을 진행하지 않고 충돌을 보고한다. 에이전트가 확정할 수 없는 제품/범위 결정은 Milestone `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
- 선택한 Phase/Milestone의 목표 또는 범위 제외와 요청이 충돌하면 구현 전에 사용자에게 확인한다.
## 상태 표기
- Phase와 Milestone 상태 표기는 `[스케치]`, `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- `[스케치]`는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 `agent-task` 구현 계획 생성과 코드 구현을 시작하지 않는다.
- `[스케치]` 항목은 `[계획]`으로 승격하기 위한 `승격 조건`, 에이전트가 확정할 수 없는 결정, 범위 경계, 후속 Milestone 후보를 정리하는 것이 목적이다.
- `[스케치]` 항목은 `[계획]`으로 승격하기 위한 `승격 조건`, 사용자 결정, 범위 경계, 후속 Milestone 후보를 정리하는 것이 목적이다.
- `[계획]` 이상 상태의 Milestone에서 `승격 조건` 섹션은 선택 사항이다. 섹션이 없거나 `- 없음`이면 템플릿 오류로 보지 않는다.
- `[스케치]`를 `[계획]`으로 전환하려면 `승격 조건`의 미정 항목이 해소되고, 목표, 범위, 기능 Task, 직접 필요한 결정 항목, 후속 구현 단위가 구현 계획을 만들 수 있을 만큼 정리되어야 한다.
- `[계획]`은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 문서화되어 잠금 해제 후 구현 계획을 만들 수 있는 상태다.
- `[스케치]`를 `[계획]`으로 전환하려면 `승격 조건`의 미정 항목이 해소되고, 목표, 범위, 기능 Task, 직접적인 사용자 결정 항목, 후속 구현 단위가 구현 계획을 만들 수 있을 만큼 정리되어야 한다.
- `[계획]`은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 정리되어 구현 계획을 만들 수 있는 상태다.
- 갱신 범위에 포함된 기존 진행 상태 표기는 `[진행중]`으로 정리한다.
- `[검토중]`은 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 `구현 잠금`이 해제되었으나, 완료 근거 정리와 archive 전환이 아직 남은 완료 후보 상태다.
- `[검토중]`은 모든 기능 Task와 Task 안에 명시된 검증이 충족된 것으로 보이나, 사용자의 최종 완료 확인과 archive 승인이 아직 남은 완료 후보 상태다.
- `[검토중]` 항목은 활성 경로에 남기고 `current.md`의 활성 후보로 유지할 수 있다.
- 검토 결과 보완이 필요하면 별도 reopen 상태를 만들지 않고 `[진행중]`으로 되돌린 뒤 `완료 리뷰` 또는 `작업 컨텍스트`에 보완 방향을 남긴다.
- 검토 결과 보류 또는 폐기 결정이 나면 `[보류]` 또는 `[폐기]`로 전환한다.
- `ROADMAP.md`의 Phase 흐름은 실행 순서가 아니라 도메인/책임 영역의 구조적 지도다. 상태 그룹은 완료, 검토중, 진행중, 계획, 스케치 순서를 기본으로 하되 실제 다음 작업 선택은 `priority-queue.md`를 우선한다.
- `PHASE.md`의 Milestone 흐름은 해당 Phase 안의 상태 정리 흐름이다. Phase를 가로지르는 실행 순서로 해석하지 않는다.
- `ROADMAP.md`의 Phase 흐름과 `PHASE.md`의 Milestone 흐름은 완료, 검토중, 진행중, 계획, 스케치 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
## 구현 잠금
- `구현 잠금`은 승인 의식이 아니라 에이전트가 확정할 수 없는 결정이 필요한지 표시하는 얇은 상태다.
- 제품 방향, 범위, 우선순위, 책임 경계처럼 에이전트가 확정할 수 없는 항목이 남아 있으면 상태를 `잠금`으로 두고 `결정 필요` 목록에 남긴다.
- `구현 잠금`은 승인 의식이 아니라 사용자 결정이 필요한지 표시하는 얇은 상태다.
- 제품 방향, 범위, 우선순위, 책임 경계처럼 사용자만 결정할 수 있는 항목이 남아 있으면 상태를 `잠금`으로 두고 `결정 필요` 체크리스트에 질문을 적는다.
- 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 `결정 필요`가 아니라 `작업 컨텍스트`의 표준선이나 구현 가정으로 기록한다.
- Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다.
- 선택한 Milestone에 `구현 잠금` 섹션이 없거나, 상태가 `잠금`이거나, 미완료 `결정 필요` 항목이 하나라도 있으면 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
- 잠금 상태에서 허용되는 작업은 로드맵 현지점 확인, 잠금 해소, SDD gate 처리, 범위/후속 Milestone 정리 같은 roadmap-only 갱신뿐이다. 실구현 계획 요청이면 잠금 차단으로 보고하고 `PLAN-*.md`/`CODE_REVIEW-*.md`를 만들지 않는다.
- 남은 `결정 필요` 항목이 현재 Milestone 실구현 범위가 아니라면 먼저 `update-roadmap`으로 `범위 제외`, 후속 Milestone, 또는 `작업 컨텍스트`로 옮기고 `구현 잠금`을 `해제`한 뒤 별도 실구현 계획을 시작한다.
- `구현 잠금`은 SDD gate를 포함할 수 있다. `SDD: 필요`이면 SDD 상태가 `[승인됨]`이고 `SDD 잠금`이 `해제`이며 SDD `USER_REVIEW.md`가 없어야 구현 잠금 해제 후보가 된다.
- SDD 사용자 리뷰는 채팅 질문으로 직접 처리하지 않고 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md`에 남긴다. 사용자의 답변이 반영되면 `user_review_N.log`로 이동한다.
- SDD가 필요한데 문서가 없거나 gate 정보가 부족하면 Milestone 구현 잠금을 해제하지 않는다. 실구현 계획 요청은 잠금 차단으로 보고하고, SDD 작성/확인은 `roadmap-sdd` 또는 `update-roadmap` 흐름에서 처리한다.
- SDD가 불필요한 Milestone은 `SDD: 불필요`과 짧은 사유를 `구현 잠금`에 남긴다.
- 잠금 상태의 Milestone에서는 "현재 요청과 직접 관련 없음"을 이유로 실구현 계획이나 코드 구현을 진행하지 않는다. 관련 없음 판단은 잠금 해소용 roadmap-only 갱신으로 먼저 문서화한다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다.
- 선택한 Milestone에 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 사용자에게 확인한다.
- 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 표준선으로 처리 가능한 작업을 막지 않는다.
- 잠금 상태를 바꾸더라도 `기능` Task를 자동 완료 처리하지 않는다.
- `[스케치]` 상태의 Milestone은 `구현 잠금`이 `해제`로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 `[계획]`으로 승격해야 한다.
@ -113,11 +81,11 @@
- `locked`와 `rely-on[].target`은 `<project>:agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md` 형식으로 기록한다.
- Milestone 경로가 `agent-roadmap/...` 상대 경로이면 현재 프로젝트명을 prefix로 붙인다. workspace 하위 절대/상대 경로이면 workspace 바로 아래 디렉터리명을 project로 삼고, 그 뒤 `agent-roadmap/...` 경로를 붙인다.
- `locked`는 잠긴 Milestone, `rely-on.target`은 선행 조건 Milestone이다. 둘 다 같은 workspace의 어느 활성 Phase 하위 Milestone이어도 된다. 의존 대상이 `current.md`에 있어야 한다고 가정하지 않는다.
- "현재 마일스톤은 X 프로젝트 작업 뒤에 진행", "X 프로젝트 때문에 현재 작업 잠금", "의존성 설정해"처럼 잠긴 Milestone을 생략한 외부 의존 잠금 요청은 현재 프로젝트 로컬 `current.md`의 활성 Milestone 단일 후보를 잠긴 대상으로 삼는다.
- 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 로컬 `current.md`가 있을 때의 단일 후보 순서로 확정한다.
- "현재 마일스톤은 X 프로젝트 작업 뒤에 진행", "X 프로젝트 때문에 현재 작업 잠금", "의존성 설정해"처럼 잠긴 Milestone을 생략한 외부 의존 잠금 요청은 현재 프로젝트 `current.md`의 활성 Milestone 단일 후보를 잠긴 대상으로 삼는다.
- 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 `current.md` 단일 후보 순서로 확정한다.
- 정규화 비교는 소문자 변환, backtick/따옴표 제거, 영문/숫자가 아닌 연속 문자를 `-` 하나로 치환, 앞뒤 `-` 제거 후 Milestone 파일 slug와 정규화한 제목에 대조한다.
- 의존 대상 탐색은 대상 프로젝트의 `agent-roadmap/phase/*/milestones/*.md` 활성 문서만 대상으로 한다. archive 문서는 사용자가 archive 경로를 명시한 경우 외에는 읽거나 후보로 삼지 않는다.
- 후보가 없거나 둘 이상이면 locks.yaml을 만들거나 고치지 말고 모호성을 보고한다. 잠금 대상 확정이 제품/범위 결정이면 대상 Milestone의 `구현 잠금 > 결정 필요`로 분리한다.
- 후보가 없거나 둘 이상이면 locks.yaml을 만들거나 고치지 말고 사용자에게 대상 Milestone 선택을 요청한다.
- 외부 의존 잠금을 만들 때 대상 Milestone의 `구현 잠금`은 `잠금`으로 둔다.
- 새 `rely-on.status`는 선행 Milestone 상태에서 파생한다. `[검토중]` 또는 `[완료]`이면 `enable`, 그 외 상태거나 상태를 확인할 수 없으면 `disable`이다.
- 같은 `id` entry를 upsert할 때 기존 `rely-on` 항목을 삭제하지 않는다. 같은 `rely-on.target`만 status/note를 갱신하고, 없는 target은 추가하며, `locked` 경로가 바뀐 경우에만 `locked`를 갱신한다.
@ -130,27 +98,13 @@
- 잠금 해제 조건 충족 여부만 확인할 때는 `agent-ops/skills/common/check-roadmap-dependency/SKILL.md`를 읽는다. lock id가 없으면 해당 스킬은 `agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" "<direction>" "<locks-file>"`로 현재 Milestone이 `locked`인지 `rely-on.target`인지 양방향으로 찾은 뒤 `agent-ops/bin/roadmap-dependency-checker.sh "<lock-id>" "<locks-file>"`를 사용한다.
- checker exit code는 `0=true`, `1=false`, `2=설정/입력/파싱 오류`로 해석한다.
## SDD 게이트
- SDD는 큰 Milestone의 설계 계약을 로드맵에 녹이는 하위 문서다. 별도 작업 관리 체계로 쓰지 않는다.
- SDD 작성, 갱신, gate 확인, 사용자 리뷰 대기, 잠금 해제는 `agent-ops/skills/common/roadmap-sdd/SKILL.md`를 따른다.
- SDD는 cross-repo 계약, 외부 provider 쓰기, 상태 머신, idempotency/retry/identity map, API/proto/config/env/schema, field smoke, 사용자 승인 gate에 영향을 주는 Milestone에만 강제한다.
- 작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강, Milestone Task의 `검증:`만으로 닫히는 작업에는 SDD를 강제하지 않는다.
- 로드맵 갱신으로 새 Milestone을 만들거나 `[스케치]` Milestone을 `[계획]`으로 승격하면서 `SDD: 필요`로 판정하면 같은 흐름에서 SDD 파일도 만든다. 사용자가 명시적으로 SDD 생성을 뒤로 미루지 않았는데 `SDD: 필요`와 SDD 문서 링크만 있고 파일이 없는 상태로 종료하지 않는다.
- SDD 문서는 `agent-ops/skills/common/_templates/roadmap-sdd-template.md`의 표준 섹션, 순서, 필수 표 컬럼을 유지해야 한다.
- SDD의 `Acceptance Scenarios`는 Milestone 기능 Task id와 연결되어야 한다.
- SDD의 `Evidence Map`은 code-review/complete.log의 `Roadmap Completion`과 최종 검증 evidence로 검증 가능해야 한다.
- `SDD: 필요` Milestone의 구현 계획은 승인된 SDD를 입력으로 삼아 작성한다. 구현 계획은 Milestone 기능 Task만 보고 실행 항목을 만들지 않고, 연결된 Acceptance Scenario와 Evidence Map에서 구현 범위, 검증, 완료 evidence를 역산해야 한다.
- 외부 API 또는 프로젝트 간 호출 계약 원문은 `agent-contract/`에 두고 SDD에는 링크만 남긴다.
- SDD 전체 검토를 채팅 질문으로 처리하지 않는다. 에이전트가 확정할 수 없는 source of truth, 상태 전이, 책임 경계, 권한, 비용, 데이터 보존, 실패 처리만 `USER_REVIEW.md`로 분리한다.
## Epic과 Task id
- Milestone 문서의 실행 체크리스트는 `기능` 섹션 하나로 작성한다. 새 Milestone이나 갱신 범위에 포함된 Milestone에는 별도 `완료 기준` 섹션을 만들지 않는다.
- 기존 Milestone에 `필수 기능`과 `완료 기준`이 분리되어 있으면, 갱신 시 `완료 기준`을 관련 기능 Task 안의 선택적 `검증:` 문구로 흡수하고 섹션을 제거한다.
- 기능 Task는 기능 또는 산출물 단위다. 검증이 필요한 기능만 같은 Task 안에 `검증: <명령/확인 방법/기대 결과>`를 붙인다.
- 검증이 명시된 Task의 `[x]`는 기능/산출물과 해당 검증이 모두 충족되었다는 뜻이다. 검증이 명시되지 않은 Task의 `[x]`는 기능/산출물 완료 근거가 충분하다는 뜻이다.
- 에이전트가 확정할 수 없는 검토/선택/우선순위 항목은 기능 Task로 쓰지 않는다. 현재 구현에 직접 필요하면 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리하고, 그렇지 않으면 `작업 컨텍스트`에 표준선/가정/후속 후보로 남긴다.
- 사용자만 결정할 수 있는 검토/선택/우선순위 항목은 기능 Task로 쓰지 않는다. `구현 잠금`의 `결정 필요` 또는 `작업 컨텍스트`로 분리하고, 현재 구현에 직접 필요하면 plan 생성 전에 사용자 확인을 받는다.
- `기능` 섹션의 Task 체크리스트는 Epic 바로 아래의 flat list를 기본으로 한다. 구현 세부, 테스트만 따로 떼어낸 하위 체크박스는 roadmap에 만들지 말고 plan 내부 체크리스트나 같은 Task의 `검증:`으로 흡수한다.
- Epic heading은 `### Epic: [epic-id] <이름>` 형식을 사용한다.
- Task는 `- [ ] [item-id] 설명` 또는 `- [x] [item-id] 설명` 형식을 사용한다.
@ -167,21 +121,19 @@
- `m-<milestone-slug>`는 Milestone 기반 작업 전용 예약 prefix이며, 일반 작업 task group은 `m-`으로 시작하지 않는다.
- 런타임은 파일 내부가 아니라 task group 이름만으로 Milestone 기반 작업 여부를 판별한다.
- `code-review`에서 `m-<milestone-slug>` 작업이 PASS되면 roadmap을 직접 수정하거나 `update-roadmap`을 직접 호출하지 않는다.
- 런타임은 PASS 완료 이벤트의 task group에서 `m-<milestone-slug>`를 판별하고, 상태 체크 후 Core/MCP action으로 Milestone 업데이트를 호출한다. Core/MCP action이 없으면 `update-roadmap` file-based fallback 흐름을 호출한다. 단, Milestone 기능 Task 체크는 `complete.log`에 `Roadmap Completion` 섹션과 명시 Task id가 있을 때만 수행하고, 섹션이 없으면 no-op으로 둔다.
- SDD 대상 Milestone은 런타임 완료 이벤트의 `complete.log`에 있는 `Roadmap Completion`과 최종 검증 evidence가 SDD `Evidence Map`을 충족해야 roadmap Task 체크 후보가 된다. 단, 사용자가 명시적으로 evidence를 전달한 수동 `update-roadmap` 갱신에서는 Evidence Map 충족 근거를 보조 근거로 사용할 수 있다.
- 런타임은 PASS 완료 이벤트의 task group에서 `m-<milestone-slug>`를 판별하고, 상태 체크 후 Core/MCP action으로 Milestone 업데이트를 호출한다. Core/MCP action이 없으면 `update-roadmap` file-based fallback 흐름을 호출한다.
- 런타임 완료 이벤트가 최종 archive 경로만 갖고 있으면 `agent-task/archive/YYYY/MM/m-<milestone-slug>/...`를 `agent-task/m-<milestone-slug>/...` 형태의 `origin-task`로 정규화해 전달한다.
- 런타임 호출에서 매칭되는 활성 Milestone이 없거나 둘 이상이면 추정하지 말고 수동 target 선택이 필요하다고 보고한다.
- `WARN` 또는 `FAIL`은 Milestone 완료 업데이트를 하지 않는다. 일반적으로 같은 `m-<milestone-slug>` task group에서 후속 계획/리뷰를 이어가지만, code-review의 user-review gate가 트리거되면 연결된 Milestone 잠금 결정을 `USER_REVIEW.md`에 남긴다.
- `WARN` 또는 `FAIL`은 Milestone 완료 업데이트를 하지 않는다. 일반적으로 같은 `m-<milestone-slug>` task group에서 follow-up plan/review를 이어가지만, code-review의 user-review gate가 트리거되면 `USER_REVIEW.md`를 남기고 사용자 판단을 기다린다.
- `[스케치]` Milestone은 Milestone 기반 `agent-task` 생성 대상이 아니다. 런타임이나 plan 스킬은 이를 구현 작업으로 라우팅하지 않고 `[계획]` 승격 필요를 보고한다.
## 완료 리뷰
- Task 완료나 Milestone 갱신 시 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`가 되었는지 확인하고, `구현 잠금`이 `해제`이며 미완료 `결정 필요` 항목이 없는지 함께 확인한다.
- 기능 Task가 모두 충족되어도 `구현 잠금`이 남아 있으면 Milestone을 `[검토중]`으로 바꾸지 않는다. 완료 리뷰 또는 작업 컨텍스트에 잠금 차단 항목을 남기고, 잠금 해소 roadmap 갱신을 먼저 요구한다.
- 기능 Task와 구현 잠금이 모두 충족된 것으로 보이면 Milestone을 `[완료]`로 바로 바꾸거나 archive로 이동하지 말고 `[검토중]`으로 바꾼다.
- `[검토중]`으로 바꿀 때는 Milestone 문서에 `완료 리뷰` 섹션을 만들거나 갱신하고, 완료 근거 1~3줄과 남은 차단 항목을 남긴다. 에이전트가 확정할 수 없는 결정 항목은 완료 리뷰가 아니라 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
- 기능 Task, 검증, 구현 잠금이 모두 충족되면 `[완료]` 전환과 archive 이동을 수행할 수 있다.
- Phase도 모든 하위 Milestone이 `[완료]` 또는 `[폐기]`로 정리되고 Phase 목표가 충족되면 `[완료]` 또는 `[폐기]`로 전환한다.
- Task 완료나 Milestone 갱신 시 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`가 되었는지 확인한다.
- 모두 충족된 것으로 보이면 Milestone을 `[완료]`로 바로 바꾸거나 archive로 이동하지 말고 `[검토중]`으로 바꾼다.
- `[검토중]`으로 바꿀 때는 Milestone 문서에 `완료 리뷰` 섹션을 만들거나 갱신하고, 완료 근거 1~3줄과 사용자에게 필요한 최종 확인 항목을 남긴다.
- 사용자가 완료를 승인한 뒤에만 `[완료]`로 전환하고 archive 이동을 수행한다.
- Phase도 모든 하위 Milestone이 `[완료]` 또는 `[폐기]`로 정리되어 Phase 완료 후보가 되면 `[검토중]`으로 두고 사용자 최종 확인을 받은 뒤 `[완료]` 또는 `[폐기]`로 전환한다.
## 로드맵 현지점
@ -193,13 +145,10 @@
## 아카이브
- 완료 또는 폐기되어 현재 작업 후보에서 제외할 Phase/Milestone은 Core/MCP action으로 아카이빙한다. Core/MCP action이 없으면 `update-roadmap` file-based fallback으로 아카이빙한다.
- `[검토중]` Phase/Milestone은 archive 대상이 아니며, 완료 근거와 남은 차단 항목이 정리될 때까지 활성 경로에 남긴다.
- `[검토중]` Phase/Milestone은 archive 대상이 아니며, 사용자 승인 전까지 활성 경로에 남긴다.
- Phase 아카이브 대상은 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`와 같은 scaffold로 이동한다.
- Milestone 아카이브 대상은 `agent-roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md`로 이동한다.
- 활성 SDD가 있으면 `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/`로 함께 이동한다. SDD `USER_REVIEW.md`가 남아 있으면 먼저 해결한다.
- Milestone 아카이브 전에는 이동 전 활성 경로 identity로 `.agent-roadmap-sync/locks.yaml`을 확인한다. 해당 identity가 `rely-on.target`이면 `[완료]` 상태에서 `enable`로 동기화하고, 해당 identity가 `locked`이면 의존 조건 충족 여부를 보고하며, 어느 쪽에도 없으면 `관련 lock 없음`으로 보고한다.
- `구현 잠금`이 남아 있는 Milestone은 `[완료]` 전환이나 완료 archive 대상으로 삼지 않는다. 명시적인 폐기 근거가 있는 `[폐기]` archive는 허용한다.
- 아카이빙할 때는 활성 `ROADMAP.md` 또는 활성 `PHASE.md`에 archive 문서 링크와 짧은 요약만 남긴다.
- 아카이빙할 때 `priority-queue.md`가 있으면 이동 전 활성 Milestone 경로 항목을 제거한다. archive 경로로 바꿔 남기지 않는다.
- 아카이브된 Phase/Milestone은 로컬 `current.md`에 남기지 않고, 일반 Phase/Milestone 선택이나 위치 분석의 후보로 삼지 않는다.
- 아카이브된 Phase/Milestone은 `current.md`에 남기지 않고, 일반 Phase/Milestone 선택이나 위치 분석의 후보로 삼지 않는다.
- 아카이브 문서는 과거 기록 스냅샷으로 보고, 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.

14
agent-ops/rules/common/rules.md
View file

@ -3,19 +3,13 @@
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다.
- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`은 중앙 관리되는 공통 영역이므로 어떤 프로젝트 작업에서도 사용자가 직접 지시하지 않는 이상 절대 직접 수정하지 않는다. 프로젝트별 규칙과 스킬은 반드시 대응하는 `project/**` 영역에만 반영한다.
- 최종 답변은 한국어로 한다.
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
- 요청 범위를 넘는 변경을 하지 않는다.
- 불확실하면 단정하지 말고 후보를 제시한다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우, 또는 plan 스킬이 같은 task group의 새 index를 충돌 없이 할당하는 경우에만 필요한 범위를 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. index 할당은 같은 task group의 archived sibling directory basename만 열람하고 내부 파일은 읽지 않는다.
- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다.
- `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-spec/` 디렉터리가 있는 프로젝트에서 현재 구현 스펙 확인, 기존 기능 변경, 완료 검토, 구현 스펙 생성/갱신 요청은 세션 1회 `agent-ops/rules/common/rules-agent-spec.md`를 읽고, `agent-spec/index.md`와 매칭되는 spec 문서만 읽는다.
- `agent-spec/archive/**`는 일반 작업에서 읽지 않는다. 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-spec.md`의 archive 접근 규칙을 따른다.
- agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다.
- tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다.
- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다.
**세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다.
@ -33,16 +27,10 @@
- agent-ops 초기화
- domain rule 생성
- skill 생성
- agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW
- 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test
- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리
- agent-spec 생성/갱신, 현재 구현 스펙 문서화, 구현 스펙 업데이트, 스펙 동기화
- README 생성
- 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기
- 로드맵/마일스톤 생성·갱신
- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제
- 로드맵 현지점 / 현재 작업 지점 확인
- 마일스톤 완료 검토 / 종료 검토 / 현재 마일스톤 닫기 / 다음 마일스톤 지정
- 계획 작성 / plan 생성
- 코드 리뷰 / review 진행
- git commit / push

4
agent-ops/rules/project/domain/client-app/rules.md
View file

@ -1,7 +1,7 @@
---
domain: client-app
last_rule_review_commit: 8a7115d9c82e15b9f35bcfa019acb4b34962e81f
last_rule_updated_at: 2026-06-01
last_rule_review_commit: 4b0222479d9ab67093ab82ccdd31af146c73e1e4
last_rule_updated_at: 2026-05-28
---
# client-app

8
agent-ops/rules/project/domain/core-service/rules.md
View file

@ -1,7 +1,7 @@
---
domain: core-service
last_rule_review_commit: 8a7115d9c82e15b9f35bcfa019acb4b34962e81f
last_rule_updated_at: 2026-06-01
last_rule_review_commit: 4b0222479d9ab67093ab82ccdd31af146c73e1e4
last_rule_updated_at: 2026-05-28
---
# core-service
@ -32,7 +32,6 @@ Mattermost 서버 repository clone을 담당한다. `packages/messaging_flutter`
- `services/core/server/go.mod` — server Go module 기준
- `services/core/webapp/channels/` — Mattermost web client source 기준
- `services/core/webapp/platform/` — Mattermost webapp shared/client/types packages 기준
- `services/core/api/package.json` — API reference tooling 기준
- `services/core/compose/docker-compose.yml` — local core 서비스 구성
@ -40,8 +39,7 @@ Mattermost 서버 repository clone을 담당한다. `packages/messaging_flutter`
- upstream에서 온 구조와 명명은 필요한 경우에만 변경한다.
- 제품 특화 변경은 `packages/messaging_flutter` 검증에 필요한 범위로 좁게 유지하고, upstream 재동기화를 방해하지 않게 설명 가능한 단위로 남긴다.
- upstream 작업 clone은 이 저장소 안의 ignored `.upstream/mattermost/` staging 폴더에 둔다.
- `bin/sync-upstream`은 staging clone 갱신까지만 수행하고, `services/core` snapshot 반영은 별도 diff/smoke 확인 뒤 진행한다.
- upstream 작업 clone은 이 저장소 밖의 sibling/external `mattermost/` staging 폴더에 둔다.
- staging clone은 Mattermost server upstream `master`를 따라가며, `master` 변경 시점 또는 의도적으로 정한 refresh 시점에 snapshot을 떠서 이 저장소의 `services/core`로 merge 요청한다.
- `services/core` snapshot 반영 시 upstream commit SHA를 `services/core/UPSTREAM.md`에 기록한다.
- `services/core` snapshot merge 요청은 앱 또는 push-proxy snapshot과 섞지 않는다.

4
agent-ops/rules/project/domain/mattermost-app/rules.md
View file

@ -1,7 +1,7 @@
---
domain: mattermost-app
last_rule_review_commit: 8a7115d9c82e15b9f35bcfa019acb4b34962e81f
last_rule_updated_at: 2026-06-01
last_rule_review_commit: 4b0222479d9ab67093ab82ccdd31af146c73e1e4
last_rule_updated_at: 2026-05-28
---
# mattermost-app

19
agent-ops/rules/project/domain/messaging-flutter/rules.md
View file

@ -1,7 +1,7 @@
---
domain: messaging-flutter
last_rule_review_commit: 8a7115d9c82e15b9f35bcfa019acb4b34962e81f
last_rule_updated_at: 2026-06-01
last_rule_review_commit: 4b0222479d9ab67093ab82ccdd31af146c73e1e4
last_rule_updated_at: 2026-05-28
---
# messaging-flutter
@ -25,18 +25,15 @@ nexo의 메인 산출물인 메시징/알림 Flutter 플러그인 패키지를
- `apps/mattermost/` — 원래 Mattermost 앱 repository clone 책임
- `services/core/` — Mattermost 서버 repository clone 책임
- `services/push-proxy/` — Mattermost push-proxy repository clone 책임
- `docs/`, root `bin/` — workspace-level 문서와 command entrypoint 책임
- root `bin/` — workspace-level command entrypoint 책임
## 주요 구성 요소
- `NexoMessagingPlugin` — singleton access, event stream, token/key action channel, host routing callback API
- plugin public API — singleton access, event stream, token/key action channel
- `NotificationOpenedEvent` — notification open payload parsing
- `NexoFirebaseMessagingService` — Android FCM 수신, signature-before-ACK gate, foreground/background notification dispatch 진입점
- `PayloadGate` — signed payload verification과 ACK ordering을 testable하게 유지하는 acceptance gate
- Android FCM service — Android FCM 수신 진입점
- `NotificationReplyBroadcastReceiver`, `NotificationDismissService` — Android action handling
- `ReceiptDelivery` — ACK delivery와 transient failure queueing 책임
- `PendingNotificationActionStore`, `PendingNotificationActionDispatcher` — ACK/reply/dismiss retry queue와 permanent failure event 책임
- `NotificationHelper` — Android notification id, grouping, clear, dismiss behavior 책임
- `ReceiptDelivery` — ACK delivery 책임
## 유지할 패턴
@ -45,15 +42,11 @@ nexo의 메인 산출물인 메시징/알림 Flutter 플러그인 패키지를
- host app이 해야 할 Firebase 초기화, token 등록, navigation 연결은 README의 Host App Responsibilities와 맞춘다.
- 패키지를 이 저장소의 제품 중심으로 보고, 앱별 제품 UI나 business logic은 소비 앱 책임으로 둔다.
- native event type은 Dart API의 `PushNotificationType`과 호환되게 유지한다.
- signed push payload는 ACK 전에 검증하고, invalid signature payload는 ACK 없이 drop한다.
- ACK/reply/dismiss의 offline 또는 transient failure는 plugin-owned pending action queue로 처리하고 permanent failure는 `action_failure` event로 노출한다.
- Android native behavior는 `android/src/test/`의 payload gate, receipt delivery, notification display, pending action store 테스트와 함께 유지한다.
## 다른 도메인과의 경계
- **client-app**: `apps/flutter-test`는 plugin 검증용 테스트 앱이며 plugin 내부 push 처리 로직을 복제하지 않는다.
- **core-service**: Mattermost 기반 runtime과의 계약은 payload, signing key, auth token, ACK/reply endpoint 수준으로 다룬다.
- **push-proxy-service**: push proxy는 APNs/FCM delivery server이고, device token 저장과 native notification action 처리는 plugin 책임이다.
- **workspace-ops**: 공통 `bin/test`, `bin/lint`가 plugin 검증을 호출하지만 plugin 세부 검증 기준은 이 도메인이 소유한다.
## 금지 사항

5
agent-ops/rules/project/domain/push-proxy-service/rules.md
View file

@ -1,7 +1,7 @@
---
domain: push-proxy-service
last_rule_review_commit: 8a7115d9c82e15b9f35bcfa019acb4b34962e81f
last_rule_updated_at: 2026-06-01
last_rule_review_commit: 4b0222479d9ab67093ab82ccdd31af146c73e1e4
last_rule_updated_at: 2026-05-28
---
# push-proxy-service
@ -19,7 +19,6 @@ last_rule_updated_at: 2026-06-01
- `services/push-proxy/internal/` — internal version package
- `services/push-proxy/swagger/` — push-proxy API spec tooling
- `services/push-proxy/go.mod`, `services/push-proxy/Makefile` — Go module and release/build entrypoints
- `services/push-proxy/package.json` — swagger/npm tooling metadata
- `services/push-proxy/UPSTREAM.md` — upstream baseline 기록
## 제외 경로

16
agent-ops/rules/project/domain/workspace-ops/rules.md
View file

@ -1,7 +1,7 @@
---
domain: workspace-ops
last_rule_review_commit: 8a7115d9c82e15b9f35bcfa019acb4b34962e81f
last_rule_updated_at: 2026-06-01
last_rule_review_commit: 4b0222479d9ab67093ab82ccdd31af146c73e1e4
last_rule_updated_at: 2026-05-28
---
# workspace-ops
@ -16,9 +16,7 @@ last_rule_updated_at: 2026-06-01
- `docs/` — 여러 모듈에 걸친 제품, migration, 운영 문서
- `README.md` — workspace overview
- root `.gitignore`와 루트 수준 설정 파일
- `agent-roadmap/` — 프로젝트 로드맵의 활성 Phase/Milestone 문서
- `agent-test/local/` — local 검증 규칙과 도메인별 smoke 시나리오
- `agent-ops/rules/project/**` — 프로젝트 전용 agent-ops 규칙
- `agent-ops/rules/project/**`, `agent-ops/skills/project/**` — 프로젝트 전용 agent-ops 규칙과 skill
## 제외 경로
@ -28,7 +26,6 @@ last_rule_updated_at: 2026-06-01
- `apps/mattermost/` — 원래 Mattermost 앱 repository clone 책임
- `services/push-proxy/` — Mattermost push-proxy repository clone 책임
- `agent-ops/rules/common/**`, `agent-ops/skills/common/**` — 공통 framework 파일이며 프로젝트에서 직접 수정하지 않는다.
- `agent-roadmap/archive/**` — 일반 작업에서는 읽지 않는 과거 완료/폐기 기록
## 주요 구성 요소
@ -36,21 +33,16 @@ last_rule_updated_at: 2026-06-01
- `bin/lint` — Flutter analyze와 선택적 Go vet 실행
- `bin/build` — Flutter web build와 선택적 Go build 실행
- `bin/dev` — 개발 entrypoint 안내
- `bin/sync-upstream` — ignored `.upstream/mattermost/` 원본 clone 생성과 fast-forward 갱신
- `bin/publish-runtime-images` — nexo-owned runtime image build/publish wrapper
- `docs/runtime-image-validation.md` — runtime image registry, tag, digest evidence 문서
- `agent-roadmap/current.md` — 활성 Phase와 Milestone 후보 목록
- `agent-test/local/rules.md` — local 검증 환경의 공통 실행 규칙
## 유지할 패턴
- root helper script는 모듈별 command를 얇게 묶는 역할로 유지한다.
- upstream staging helper는 `.upstream/mattermost/` clone 갱신만 담당하고, tracked snapshot target으로 자동 복사하지 않는다.
- runtime image publish wrapper는 core/push-proxy build와 registry publish를 orchestration하되, 각 서비스의 내부 소스 책임을 가져오지 않는다.
- 로컬 도구가 없을 때 skip하는 기존 동작을 보존하고, skip된 검증은 작업 보고에 명시한다.
- 여러 모듈에 걸친 문서는 `docs/`에 두고, 모듈 내부만 해당하는 설명은 해당 모듈 README나 docs에 둔다.
- 프로젝트 전용 agent-ops 규칙만 수정하고 common 파일은 원본 framework에서 동기화한다.
- 로드맵과 테스트 규칙 갱신은 공통 skill/router 규칙을 따른다.
- 프로젝트 전용 agent-ops 파일만 수정하고 common 파일은 원본 framework에서 동기화한다.
## 다른 도메인과의 경계

4
agent-ops/rules/project/rules.md
View file

@ -35,8 +35,7 @@ Mattermost 원본은 앱, 서버, push 서버 repository clone 단위로 둔다.
- `packages/messaging_flutter/`를 제품 중심으로 본다. 앱별 제품 UI와 business logic은 이 저장소가 아니라 패키지를 소비하는 앱의 책임이다.
- `apps/flutter-test/`는 플러그인 integration 검증용 앱으로만 본다. 플러그인 integration 검증을 넘는 제품 기능을 키우지 않는다.
- `apps/mattermost`, `services/core`, `services/push-proxy`는 Mattermost 원본 repository clone으로 유지한다. nexo 제품 앱이나 독자 서버 제품으로 재정의하지 않는다.
- upstream 작업 clone은 이 저장소 안의 ignored `.upstream/mattermost/` staging 폴더에 원본 repository별로 둔다.
- `bin/sync-upstream`은 `.upstream/mattermost/` clone 생성과 fast-forward 갱신만 담당하며, snapshot target으로 자동 복사하지 않는다.
- upstream 작업 clone은 이 저장소 밖의 sibling/external `mattermost/` staging 폴더에 원본 repository별로 둔다.
- staging clone은 repository별 기록된 upstream branch를 따라간다. `mattermost-mobile`은 `main`, `mattermost`와 `mattermost-push-proxy`는 `master`를 기준으로 하며, 해당 branch 변경 시점 또는 의도적으로 정한 refresh 시점에 snapshot을 떠서 이 저장소로 merge 요청한다.
- 이 저장소에 들어오는 snapshot은 원본 repository별 commit SHA를 기록한다.
- merge 요청은 원칙적으로 upstream repository별로 분리한다. 앱, 서버, push-proxy snapshot을 한 요청에 섞지 않는다.
@ -75,7 +74,6 @@ Mattermost 원본은 앱, 서버, push 서버 repository clone 단위로 둔다.
| `apps/mattermost/**` | mattermost-app | `agent-ops/rules/project/domain/mattermost-app/rules.md` |
| `services/push-proxy/**` | push-proxy-service | `agent-ops/rules/project/domain/push-proxy-service/rules.md` |
| `docs/**`, `bin/**`, root docs/config | workspace-ops | `agent-ops/rules/project/domain/workspace-ops/rules.md` |
| `agent-roadmap/**`, `agent-test/local/**`, `agent-ops/rules/project/**` | workspace-ops | `agent-ops/rules/project/domain/workspace-ops/rules.md` |
## 스킬 라우팅

33
agent-ops/skills/common/_templates/agent-spec/index-template.md
View file

@ -1,33 +0,0 @@
---
spec_doc_type: index
status: 활성
---
# 구현 스펙 색인
## 목적
이 디렉터리는 사람과 agent가 함께 보는 현재 구현 기능 living spec을 관리한다.
로드맵 완료 이력, SDD, 계약 원문, 사람용 docs를 대체하지 않는다.
## 읽기 규칙
- 필요한 작업에서만 이 index를 읽고, 매칭되는 spec 문서만 읽는다.
- `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다.
- API, wire protocol, config/event schema, 프로세스 간 계약 원문은 `agent-contract/`를 따른다.
- 코드 배치, 구현 진입점, 도메인 간 상세 책임 경계는 domain rule을 따른다.
## Spec Map
| id | 상태 | 언제 읽나 | path | 주요 근거 |
|----|------|-----------|------|-----------|
| 없음 | 없음 | 없음 | 없음 | 없음 |
## 작성 규칙
- 현재 구현 기준으로 작성한다.
- 기능 목록과 주요 흐름을 먼저 파악할 수 있게 작성한다.
- 코드/계약/테스트 evidence를 우선한다.
- 계약 원문은 복제하지 않고 링크한다.
- 코드 진입점과 도메인룰 성격의 상세 경계는 반복하지 않는다.
- 불확실한 내용은 `불명확`으로 남긴다.

55
agent-ops/skills/common/_templates/agent-spec/spec-template.md
View file

@ -1,55 +0,0 @@
---
spec_doc_type: spec
spec_id: <area>/<spec-id>
status: 불명확
source_evidence:
- type: code
path: null
notes: <현재 구현 근거>
---
# 스펙: <title>
## 목적
<이 spec이 설명하는 현재 구현 기능과 이 문서를 읽어야 하는 이유>
## 기능 목록
| 기능 | 설명 |
|------|------|
| <기능명> | <현재 코드와 계약으로 확인된 동작> |
## 범위
- 포함: <현재 spec이 다루는 범위>
- 제외: <다른 spec, roadmap, SDD, contract, docs로 넘기는 범위>
## 주요 흐름
```mermaid
sequenceDiagram
participant A as <주체>
participant B as <주체>
A->>B: <주요 메시지 또는 동작>
```
## 계약
- <관련 agent-contract 문서 또는 코드 계약 포인터>
## 설정/데이터/이벤트
- <관련 config, 저장소, event, runtime state 요약. 원문 schema는 복제하지 않는다.>
## 검증
- `<command or profile>` - <기대 결과>
## 한계와 주의사항
- <현재 구현 한계 또는 조건부 동작>
## 변경 기록
- <YYYY-MM-DD>: <생성/갱신 근거>

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

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

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

@ -1,61 +0,0 @@
---
ui_doc_type: component
component_id: <component-id>
status: <구현됨|계획|가정|불명확>
source_evidence:
- type: code
path: null
notes: <구현 근거. 없으면 없음>
- type: docs
path: null
notes: <컨셉/계획 근거. 없으면 없음>
- type: user
path: null
notes: <사용자 명시 입력. 없으면 없음>
---
# <Component Name>
Component ID: `<component-id>`
Status: `<구현됨|계획|가정|불명확>`
## 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>: <현재 기준으로 남길 결정 요약>

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

@ -1,18 +0,0 @@
---
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는 이 목록에 있어야 한다.

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

@ -1,57 +0,0 @@
---
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을 대체하지 않는다.
- `구현됨`, `계획`, `가정`, `불명확` 상태를 섞어 쓰지 않는다.
- 기본 코드 동기화는 `.sync-state.json` 기준 이후 변경분만 대상으로 한다.
- 전체 동기화는 사용자가 명시한 경우에만 수행한다.
## Decision History
- <YYYY-MM-DD>: <초기 결정 또는 변경 요약>

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

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

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

@ -1,36 +0,0 @@
---
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에서도 제거 대상인지 확인한다.

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

@ -1,29 +0,0 @@
---
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 연결
- `.sync-state.json`: agent-ui -> code 동기화 기준점
- `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문
- `archive/user-review/`: 해결된 사용자 리뷰 로그
## 기본 규칙
- 현재 기준은 `definition/**`에 둔다.
- visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다.
- `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다.
- 초기 생성 이후 기본 흐름은 `agent-ui -> code` 방향이다.
- `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다.

11
agent-ops/skills/common/_templates/agent-ui/sync-state-template.json
View file

@ -1,11 +0,0 @@
{
"schema_version": 1,
"surface_type": "ops-dev",
"baseline_mode": "<code-first|concept-first|blank|migration>",
"last_sync_mode": "baseline",
"last_synced_head": "<git-commit-hash>",
"last_synced_at": "<ISO-8601>",
"agent_ui_paths": [],
"code_paths": [],
"notes": []
}

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

@ -1,25 +0,0 @@
---
ui_doc_type: user-review
status: open
---
# agent-ui 사용자 리뷰
이 문서는 agent가 확정할 수 없는 UI 결정을 사용자에게 넘기기 위한 활성 리뷰 문서다.
해결된 항목은 `agent-ui/archive/user-review/user_review_N.log`로 이동할 수 있다.
## Review Items
- [ ] [UIR-001] <결정이 필요한 질문>
- Source Skill: <update-agent-ui | validate-agent-ui | sync-agent-ui>
- Stage: <definition-edit | document-consistency | code-sync>
- Blocking Step: <validate-agent-ui | sync-agent-ui | none>
- Context: <관련 view/component/frame 경로>
- Options: <후보가 있으면 적는다>
- Needed For: <차단되는 작업>
- Resume From: <해결 후 재개할 스킬/명령>
- Pending Changes: <남은 작업트리 변경 파일 또는 없음>
## Notes
- 없음

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

@ -1,79 +0,0 @@
---
ui_doc_type: view
view_id: <view-id>
status: <구현됨|계획|가정|불명확>
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: `<구현됨|계획|가정|불명확>`
## 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>: <현재 기준으로 남길 결정 요약>

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

@ -1,31 +0,0 @@
---
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
- 없음

5
agent-ops/skills/common/_templates/implementation-user-review-request-section.md
View file

@ -1,12 +1,11 @@
## 사용자 리뷰 요청
_선택된 Milestone `구현 잠금 > 결정 필요`가 구현을 막을 때만 채운다. 이 섹션을 포함한 모든 구현 소유 섹션을 채운 뒤 `review-ready`를 보고하고 종료한다. code-review를 실행하거나 review model을 시작하지 않는다._
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
- 상태: 없음
- 사유 유형: 없음
- 연결 대상: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 후속으로 해결할 수 없는 이유: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

23
agent-ops/skills/common/_templates/roadmap-current-template.md
View file

@ -1,35 +1,28 @@
# 현재 로드맵 컨텍스트
## 고정 참조
- Phase를 가로지르는 다음 작업 후보는 [전역 마일스톤 실행 순서](priority-queue.md)를 먼저 확인한다.
- Phase는 도메인/책임 영역이며 순차 실행 게이트가 아니다.
## 활성 Phase
- [<스케치 | 계획 | 진행중 | 검토중 | 보류>] <phase-name>
- 경로: [PHASE.md](phase/<phase-slug>/PHASE.md)
- 경로: `agent-roadmap/phase/<phase-slug>/PHASE.md`
## 활성 Milestone
- [<스케치 | 계획 | 진행중 | 검토중 | 보류>] <milestone-name>
- Phase: [PHASE.md](phase/<phase-slug>/PHASE.md)
- 경로: [<milestone-name>](phase/<phase-slug>/milestones/<milestone-slug>.md)
- Phase: `agent-roadmap/phase/<phase-slug>/PHASE.md`
- 경로: `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`
## 선택 규칙
- 이 문서는 활성 Phase와 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
- 이 문서는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다.
- 활성 Phase는 [PHASE.md](phase/<phase-slug>/PHASE.md)를 가리킨다.
- 활성 Milestone은 [Milestone 문서](phase/<phase-slug>/milestones/<milestone-slug>.md)를 가리킨다.
- 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`를 가리킨다.
- 활성 Milestone은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`를 가리킨다.
- 활성 항목은 아카이브 경로를 포함하지 않는다.
- `[검토중]` 항목은 완료 근거와 archive 조건이 정리될 때까지 활성 항목으로 남길 수 있다.
- `[검토중]` 항목은 사용자 완료 확인 전까지 활성 항목으로 남길 수 있다.
- `[스케치]` 항목은 활성 후보로 남길 수 있지만 구현 계획 생성 대상은 아니며, `[계획]` 승격 조건을 정리하는 대상으로만 다룬다.
- `[완료]` 또는 `[폐기]` 항목은 archive 링크를 남긴 뒤 활성 항목에서 제거한다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Phase와 Milestone을 선택하고 같은 세션에서 1회 읽는다.
- 활성 Phase 또는 Milestone 둘 이상에 걸치면 필요한 문서를 모두 읽고 작업 범위를 좁힌다.
- 활성 범위 밖의 작업이면 [ROADMAP.md](ROADMAP.md)의 Phase 흐름을 확인하고 범위 충돌을 보고한다. 제품/범위 결정이 필요하면 대상 Milestone의 `구현 잠금 > 결정 필요` 또는 SDD [USER_REVIEW.md](sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)로 분리한다.
- 활성 범위 밖의 작업이면 `agent-roadmap/ROADMAP.md`의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- 완료된 과거 내용이 필요할 때만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 읽는다.
- 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금 해소용 roadmap-only 갱신으로 결정 항목을 정리한 뒤 진행하며, Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다.
- 선택된 Milestone에 `SDD: 필요`가 있으면 [SDD.md](sdd/<phase-slug>/<milestone-slug>/SDD.md)가 `[승인됨]`이고 SDD 잠금이 해제되었으며 SDD [USER_REVIEW.md](sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)가 없어야 구현이나 구현 계획을 시작한다.
- 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금을 유지한 채 진행할 수 있으며, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다.
- 선택된 Milestone 상태가 `[스케치]`이면 `구현 잠금` 상태와 관계없이 구현이나 구현 계획을 시작하지 않고 `[계획]` 승격 필요를 보고한다.

39
agent-ops/skills/common/_templates/roadmap-milestone-template.md
View file

@ -2,8 +2,8 @@
## 위치
- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
- Phase: [PHASE.md](../PHASE.md)
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/<phase-slug>/PHASE.md`
## 목표
@ -25,23 +25,15 @@
<!-- [스케치] 예시:
- [ ] 구현 가능한 목표와 범위를 확정한다.
- [ ] 에이전트가 확정할 수 없는 제품/우선순위/책임 경계를 `구현 잠금 > 결정 필요`로 분리한다.
- [ ] 사용자만 결정할 제품/우선순위/책임 경계를 정리한다.
- [ ] 기능 단위와 후속 구현 Milestone 후보를 나눈다.
-->
## 구현 잠금
- 상태: <잠금 | 해제>
- SDD: <필요 | 불필요>
- SDD 문서: <없음 | [SDD.md](../../../sdd/<phase-slug>/<milestone-slug>/SDD.md)>
- SDD 사유: <필요/불필요 판정 근거 한 줄>
- 잠금 해제 조건: <없음 | 아래 체크리스트>
- [ ] <SDD가 필요한 경우: SDD 잠금이 해제되어 있다>
- [ ] <SDD가 필요한 경우: SDD 사용자 리뷰가 없거나 승인/해결되었다>
- [ ] <SDD가 필요한 경우: Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다>
- [ ] <SDD가 필요한 경우: Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다>
- 결정 필요: <없음 | 아래 목록>
- <에이전트가 확정할 수 없는 제품/범위/우선순위/책임 경계 결정 항목>
- 결정 필요: <없음 | 아래 체크리스트>
- [ ] <사용자만 결정할 수 있는 제품/범위/우선순위/책임 경계 질문>
## 범위
@ -72,19 +64,14 @@ Task 체크리스트는 Epic 바로 아래의 flat list로 유지하고, 구현
## 완료 리뷰
- 상태: <없음 | 검토중 | 통과 | 보완 필요 | 보류 | 폐기>
- 상태: <없음 | 요청됨 | 승인됨 | 보완 필요 | 보류 | 폐기>
- 요청일: <YYYY-MM-DD | 없음>
- 완료 근거: <모든 기능 Task와 Task 안에 명시된 검증 충족 및 구현 잠금 해제 여부를 1~3줄로 요약>
- 검토 항목: <없음 | 에이전트/런타임이 확인할 완료 근거 또는 archive 조건>
- agent-ui 상태 반영: <해당 없음 | 대기 | 완료 | 차단: 사유>
- 완료 근거: <모든 기능 Task와 Task 안에 명시된 검증 충족 여부를 1~3줄로 요약>
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: <없음 | 보완/보류/폐기 방향성>
<!--
기본값은 `해당 없음`이다.
`sync-agent-ui`가 코드 작업을 `milestone-required`로 라우팅했거나 사용자가 Milestone 종료 검토에서 agent-ui 구현 상태 반영을 명시한 경우에만 `대기`로 둔다.
`대기`인 경우 Milestone 종료 검토에서 최종 검증과 code evidence가 확인된 agent-ui view/component/frame만 `구현됨`으로 반영한다.
-->
## 범위 제외
- <이 Milestone에서 의도적으로 하지 않는 일>
@ -93,6 +80,6 @@ Task 체크리스트는 Epic 바로 아래의 flat list로 유지하고, 구현
- 관련 경로: `<path>`
- 표준선(선택): <기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 진행할 기본 기준>
- 선행 작업: <없음 또는 파일 위치 기준 Markdown 링크(예: [Milestone 이름](../other-milestone.md))/태스크 이름>
- 후속 작업: <없음 또는 파일 위치 기준 Markdown 링크(예: [Milestone 이름](../next-milestone.md))/태스크 이름>
- 확인 필요: <없음 | `구현 잠금 > 결정 필요` 또는 [USER_REVIEW.md](../../../sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)로 분리할 항목>
- 선행 작업: <없음 또는 Milestone/태스크 이름>
- 후속 작업: <없음 또는 Milestone/태스크 이름>
- 확인 필요: <!-- TODO: 확인 필요 -->

6
agent-ops/skills/common/_templates/roadmap-phase-template.md
View file

@ -11,13 +11,11 @@
## Milestone 흐름
완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획, 스케치 또는 보류 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다.
이 흐름은 해당 Phase 안의 상태 정리이며, Phase를 가로지르는 실행 순서는 아니다.
Milestone은 완료, 검토중, 진행중, 계획, 스케치 또는 보류 상태 그룹으로 정리한다.
Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.
완료, 검토중, 진행중, 계획, 스케치 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
스케치 Milestone은 아직 구현 가능한 계획이 아니므로 계획 Milestone보다 아래에 둔다.
- [<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] <Milestone 이름>
- 경로: [<Milestone 이름>](milestones/<milestone-slug>.md) 또는 [archive <Milestone 이름>](../../archive/phase/<phase-slug>/milestones/<milestone-slug>.md)
- 경로: `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md` 또는 `agent-roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md`
- 요약: <목표 또는 결과 1문장>
## Phase 경계

49
agent-ops/skills/common/_templates/roadmap-position-report-template.md
View file

@ -1,46 +1,21 @@
# 로드맵 현지점
- local current: {없음 | [current.md](agent-roadmap/current.md)}
- [current.md](agent-roadmap/current.md)
<!--
작성 규칙:
- 아래 {...} placeholder는 실제 출력에 남기지 않는다.
- 링크는 반드시 [제목](repo-root-relative-path) 형식으로 쓴다.
- 문서 안에서 읽은 file-location-relative 링크는 원본 파일 위치 기준으로 해석한 뒤 repo root 기준 target으로 다시 쓴다.
- 경로를 확정할 수 없는 항목은 깨진 Markdown 링크 대신 `링크 없음: <사유>`로 쓴다.
- {PHASE_LINK}, {MILESTONE_LINK}, {SDD_LINK}, {USER_REVIEW_LINK}는 실제 Markdown 링크로 치환한다.
- 이 주석은 출력하지 않는다.
-->
## Breadcrumb
- [로드맵: {roadmap-name}](agent-roadmap/ROADMAP.md)
- Phase: {PHASE_LINK}
- Milestone: {MILESTONE_LINK}
- [{상태}] {목표 또는 역할 한 줄}
- SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)}
- 사용자 리뷰: {없음 | USER_REVIEW_LINK}
- Milestone: {MILESTONE_LINK}
- [{상태}] {목표 또는 역할 한 줄}
- SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)}
- 사용자 리뷰: {없음 | USER_REVIEW_LINK}
## 전역 마일스톤 실행 순서
- {없음 | [MILESTONE_TITLE](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md): 식별용 한 줄 설명}
- {[MILESTONE_TITLE](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md): 식별용 한 줄 설명 | 큐 정리 필요: 사유}
- [로드맵: <roadmap-name>](agent-roadmap/ROADMAP.md)
- [Phase: <phase-name>](agent-roadmap/phase/<phase-slug>/PHASE.md)
- [Milestone: <milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- [<상태>] <목표 또는 역할 한 줄>
- [Milestone: <milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- [<상태>] <목표 또는 역할 한 줄>
## 전체 Phase 흐름
- [{상태}] {PHASE_LINK}
- [{상태}] {PHASE_LINK} ← 현재
- [{상태}] {PHASE_LINK}
- [<상태>] [<Phase 이름>](<phase-path>)
- [<상태>] [<현재 Phase 이름>](<phase-path>) ← 현재
- [<상태>] [<Phase 이름>](<phase-path>)
## 현재 Phase의 Milestone 흐름
- [{상태}] {MILESTONE_LINK} ← 현재 후보, {역할 태그}
- SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)}
- 사용자 리뷰: {없음 | USER_REVIEW_LINK}
- [{상태}] {MILESTONE_LINK} ← 현재 후보, {역할 태그}
- SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)}
- 사용자 리뷰: {없음 | USER_REVIEW_LINK}
- [<상태>] [<Milestone 이름>](<milestone-path>) ← 현재 후보, <역할 태그>
- [<상태>] [<Milestone 이름>](<milestone-path>) ← 현재 후보, <역할 태그>

17
agent-ops/skills/common/_templates/roadmap-priority-queue-template.md
View file

@ -1,17 +0,0 @@
# 전역 마일스톤 실행 순서
이 문서는 Phase를 가로지르는 Milestone 실행 순서만 기록한다. 위에 있는 항목을 먼저 검토한다.
## 실행 순서
<!--
작성 규칙:
- 실행 후보가 없으면 이 섹션을 비워 둔다.
- 항목은 Milestone 제목 링크와 식별용 한 줄 설명만 둔다.
- 상태, 목표, 범위, 잠금, 기능, 완료 근거는 각 Milestone 문서를 원본으로 삼는다.
- 링크 target은 이 파일 위치 기준 상대 경로로 쓴다.
예:
1. [Milestone 제목](phase/<phase-slug>/milestones/<milestone-slug>.md)
이 Milestone에서 다루는 작업을 한 줄로 적는다.
-->

85
agent-ops/skills/common/_templates/roadmap-sdd-template.md
View file

@ -1,85 +0,0 @@
# SDD: <Milestone 이름>
## 위치
- Milestone: [Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md)
- Phase: [PHASE.md](../../../phase/<phase-slug>/PHASE.md)
## 상태
[<초안 | 검토중 | 승인됨 | 대체됨 | 폐기>]
## SDD 잠금
- 상태: <잠금 | 해제>
- 사용자 리뷰: <없음 | [USER_REVIEW.md](USER_REVIEW.md)>
- 잠금 항목:
- [ ] [D01] <사용자만 결정할 source of truth, 상태 전이, 책임 경계, 범위, 권한, 비용, 실패 처리 항목>
## 문제 / 비목표
- 문제: <이 SDD가 고정해야 하는 큰 작업의 모호함>
- 비목표:
- <이번 Milestone에서 의도적으로 다루지 않는 설계 범위>
## Source of Truth
| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | [Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md) | <장기 원장, 상태 반영 기준> |
| Code | `<path>` | <구현 source of truth> |
| External Provider | <없음 또는 provider> | <provider id/revision/status 기준> |
| User Decision | <없음 또는 D-id> | <사용자 결정이 필요한 기준> |
## State Machine
| 상태 | 진입 조건 | 다음 상태 | 근거 |
|------|-----------|-----------|------|
| <state> | <condition> | <state> | <event/file/provider> |
## Interface Contract
- 계약 원문: <없음 또는 [계약 문서](../../../../agent-contract/...)>
- 입력:
- <field>: <의미>
- 출력:
- <field>: <의미>
- 금지:
- <하면 안 되는 동작>
## Acceptance Scenarios
| ID | Milestone Task | Given | When | Then |
|----|----------------|-------|------|------|
| S01 | `<task-id>` | <상태/입력> | <행동> | <관찰 가능한 결과> |
## Evidence Map
| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
|----------|-------------------|------------------|---------------------------|
| S01 | <test/smoke/search/user-review evidence> | `agent-task/m-<milestone-slug>/...` | <complete.log의 Roadmap Completion/최종 검증으로 남길 근거> |
## Cross-repo Dependencies
- 없음
<!-- 필요한 경우:
- `<project>:agent-roadmap/phase/<phase>/milestones/<milestone>.md`
- `.agent-roadmap-sync/locks.yaml` entry: `<id>`
-->
## Drift Check
- [ ] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- [ ] Evidence Map이 code-review/complete.log에서 검증 가능하다.
- [ ] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
- [ ] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다.
## 사용자 리뷰 이력
- 없음
## 작업 컨텍스트
- 표준선: <기존 구조, 도메인 rule, 플랫폼 관례>
- 후속 SDD: <없음 또는 [SDD.md](../<other-milestone-slug>/SDD.md)>

37
agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md
View file

@ -1,37 +0,0 @@
# SDD User Review
## 상태
요청됨
## 검토 대상
- SDD: [SDD.md](SDD.md)
- Milestone: [Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md)
## 사용자 결정 항목
### [D01] <결정 제목>
- 결정 필요: <사용자만 결정할 질문>
- 추천안: <agent가 제안하는 기본안>
- 대안: <없음 또는 대안>
- 영향: <이 결정이 상태 전이, provider 쓰기, 권한, 비용, scope, 실패 처리에 미치는 영향>
- 적용 위치:
- SDD: `<section>`
- Milestone: `<item-id 또는 구현 잠금>`
## 승인 항목
- [ ] 위 결정 항목을 승인했다.
- [ ] SDD 잠금 해제를 승인했다.
## 답변 기록
- 없음
## 해결 조건
- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다.
- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다.
- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.

46
agent-ops/skills/common/_templates/roadmap-template.md
View file

@ -1,57 +1,41 @@
# 로드맵
## 고정 실행 순서
- 전역 Milestone 실행 순서는 [전역 마일스톤 실행 순서](priority-queue.md)를 먼저 확인한다.
- Phase는 도메인/책임 영역이며 순차 실행 게이트가 아니다.
- Phase 흐름과 상태는 로드맵 구조를 설명하고, 실제 다음 작업 선택은 `priority-queue.md`의 위아래 순서를 우선한다.
- `priority-queue.md`는 순서 전용 문서이며, 상태, 목표, 범위, 잠금, 기능, 완료 근거는 각 Milestone 문서를 원본으로 삼는다.
- `priority-queue.md` 항목은 Milestone 제목 링크와 식별용 한 줄 설명만 둔다.
- `priority-queue.md`는 로드맵 생성 시 함께 만들며, 실행 후보가 없을 때도 문서와 `실행 순서` 섹션은 유지한다.
- `priority-queue.md`는 사용자가 순서 조정을 요청한 경우, Milestone archive 시 완료 항목 제거가 필요한 경우, 큐에 있는 Milestone이 폐기, 경로 변경, split/merge, 또는 실행 의미가 바뀔 정도로 수정된 경우에만 재정렬한다.
- `priority-queue.md`의 링크가 깨졌으면 활성 Milestone 문서를 기준으로 큐를 재정렬하거나 재생성한다.
## 전체 목표
<프로젝트가 최종적으로 달성하려는 결과를 1~3문장으로 작성>
## Phase 흐름
Phase는 실행 순서가 아니라 도메인/책임 영역의 구조적 지도다.
위에서 아래로 진행된 순서와 예정 흐름을 나타낸다.
완료된 Phase도 로드맵에서 제거하지 않고, archive의 Phase 문서로 연결한다.
상태 그룹은 완료, 검토중, 진행중, 계획, 스케치 순서로 정리해 각 도메인 축의 성숙도와 정리 상태를 읽기 쉽게 한다.
실제 다음 작업 선택은 [전역 마일스톤 실행 순서](priority-queue.md)의 위아래 순서를 우선한다.
검토중 또는 진행중 Phase는 계획 Phase보다 위에 두어, 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
스케치 Phase는 아직 구현 가능한 계획이 아니므로 계획 Phase보다 아래에 둔다.
- [<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] <Phase 이름>
- 경로: [PHASE.md](phase/<phase-slug>/PHASE.md) 또는 [archive PHASE.md](archive/phase/<phase-slug>/PHASE.md)
- 경로: `agent-roadmap/phase/<phase-slug>/PHASE.md` 또는 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`
- 요약: <이 Phase의 목표와 역할 1문장>
## 로딩 정책
- 일반 작업에서는 [ROADMAP.md](ROADMAP.md)를 매번 읽지 않는다.
- Phase를 가로지르는 다음 작업 후보를 고를 때는 [전역 마일스톤 실행 순서](priority-queue.md)를 먼저 확인한다.
- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 [current.md](current.md)를 먼저 읽는다.
- 일반 작업에서는 `agent-roadmap/ROADMAP.md`를 매번 읽지 않는다.
- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-roadmap/current.md`를 먼저 읽는다.
- `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
- `current.md`는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다. 로드맵 기반 계획/갱신에서 없으면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 생성해 사용하고, 읽기 전용 현지점 확인에서는 생성하지 않는다.
- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
- `current.md`의 활성 Phase는 [PHASE.md](phase/<phase-slug>/PHASE.md)를 가리킨다.
- `current.md`의 활성 Milestone은 [Milestone 문서](phase/<phase-slug>/milestones/<milestone-slug>.md)를 가리킨다.
- `current.md`의 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`를 가리킨다.
- `current.md`의 활성 Milestone은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`를 가리킨다.
- `current.md`는 `agent-roadmap/archive/**` 경로를 활성 항목으로 포함하지 않는다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Phase와 Milestone 문서를 같은 세션에서 1회 읽는다.
- 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 범위 충돌을 보고한다. 제품/범위 결정이 필요하면 대상 Milestone의 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
- 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다.
- 상세 작업은 각 Milestone 문서의 `기능`으로 관리한다. 검증이 필요한 기능만 같은 Task 안에 `검증:`으로 통합한다.
- 큰 Milestone의 설계 게이트는 [SDD.md](sdd/<phase-slug>/<milestone-slug>/SDD.md)에 두고, Milestone `구현 잠금`의 SDD 조건과 연결한다.
- SDD 사용자 리뷰가 필요하면 [USER_REVIEW.md](sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)로 남기며, 해결 후 `user_review_N.log`로 보존한다.
- `[스케치]` Phase/Milestone은 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태이며 구현 계획 생성 대상이 아니다.
- `[스케치]` 항목은 `승격 조건`을 정리해 `[계획]`으로 전환한 뒤 구현 계획을 만든다.
- 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 `구현 잠금`이 해제된 Milestone은 먼저 `[검토중]`으로 두고, 완료 근거와 archive 조건이 정리되면 `[완료]`로 전환한다.
- 완료된 Phase는 [archive PHASE.md](archive/phase/<phase-slug>/PHASE.md)로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 [archive milestones](archive/phase/<phase-slug>/milestones/)로 이동한다.
- 모든 기능 Task와 Task 안에 명시된 검증이 충족된 Milestone은 먼저 `[검토중]`으로 두고, 사용자 완료 확인과 archive 승인을 받은 뒤 `[완료]`로 전환한다.
- 완료된 Phase는 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 `agent-roadmap/archive/phase/<phase-slug>/milestones/`로 이동한다.
- archive `PHASE.md`는 Phase 자체가 완료 또는 폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다.
- `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라가서 읽는다.
- 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.
- 선택된 Milestone의 `구현 잠금` 섹션이 없거나, 상태가 `잠금`이거나, 미완료 `결정 필요` 항목이 있으면 코드 구현, `agent-task` 구현 계획 생성, 세부 API/파일 구조 확정을 시작하지 않는다.
- 선택된 Milestone에 `SDD: 필요`가 있으면 SDD 상태가 `[승인됨]`이고 SDD 잠금이 해제되었으며 SDD 사용자 리뷰가 없어야 구현 계획을 만들 수 있다.
- 잠금 상태의 Milestone에서는 "현재 요청과 직접 관련 없음"을 이유로 실구현 계획이나 코드 구현을 진행하지 않는다. 먼저 roadmap-only 갱신으로 범위 제외, 후속 Milestone, 작업 컨텍스트 이동 또는 잠금 해제를 문서화한다.
- Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `구현 잠금` 상태를 `해제`로 둔다.
- 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획 생성, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다.
- 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조/도메인 rule/플랫폼 관례로 정할 수 있는 작업은 표준선으로 기록하고 진행할 수 있다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `구현 잠금` 상태를 `해제`로 둔다.

71
agent-ops/skills/common/analyze-roadmap-position/SKILL.md
View file

@ -1,7 +1,7 @@
---
name: analyze-roadmap-position
version: 1.13.0
description: "여러 레포를 전환할 때 코드/git 분석 없이 priority-queue 실행 순서와 ROADMAP > Phase > Milestone > current 현지점을 링크 달린 흐름 목록으로 빠르게 보여주는 읽기 전용 스킬"
version: 1.11.0
description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROADMAP > Phase > Milestone > current 현지점을 링크 달린 breadcrumb와 흐름 목록으로 빠르게 보여주는 읽기 전용 스킬"
---
# 로드맵 현지점
@ -9,8 +9,7 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 priority-q
## 목적
여러 레포를 병렬 운용하다가 돌아왔을 때, 현재 작업이 전체 로드맵의 어느 Phase와 Milestone에 있는지 빠르게 보여준다.
기본 출력은 전역 Milestone 실행 순서, `로드맵 > Phase > Milestone` breadcrumb, 전체 Phase 흐름, 현재 Phase의 Milestone 흐름이다.
Phase 흐름은 실행 순서가 아니라 도메인/책임 영역의 구조적 지도이며, 다음 작업 후보는 `priority-queue.md` 순서를 우선한다.
기본 출력은 `로드맵 > Phase > Milestone` breadcrumb와 전체 Phase 흐름, 현재 Phase의 Milestone 흐름이다.
코드 진행도 감사, git diff 분석, 테스트 근거 확인, 남은 작업 정밀 판정은 기본 책임이 아니다.
## 언제 호출할지
@ -18,74 +17,41 @@ Phase 흐름은 실행 순서가 아니라 도메인/책임 영역의 구조적
- 사용자가 "지금 작업이 뭐지?", "현재 작업이 뭐야?", "어디까지 했지?"라고 물을 때
- 사용자가 레포 전환 직후 로드맵상 현재 좌표를 빠르게 알고 싶어 할 때
- "로드맵상 현 위치", "현재 마일스톤 위치", "current 기준 breadcrumb"를 요청할 때
- Phase를 가로지르는 다음 작업 후보 순서를 함께 보고 싶어 할 때
- 구현 시작 전 전체 Roadmap > Phase > Milestone 관계만 확인하면 될 때
## 먼저 확인할 것
- [ ] `agent-ops/skills/common/_templates/roadmap-position-report-template.md`를 읽어 최신 답변 템플릿 확인
- [ ] `agent-roadmap/` 디렉터리 존재 여부 확인
- [ ] 로컬 `agent-roadmap/current.md` 존재 여부 확인
- [ ] `agent-roadmap/priority-queue.md`가 있으면 `실행 순서` 항목 확인
- [ ] `agent-roadmap/current.md` 존재 여부 확인
- [ ] 로드맵이 있으면 `ROADMAP.md`의 `Phase 흐름`을 확인
- [ ] 로컬 `current.md`의 활성 Phase와 활성 Milestone 이름, 상태, 경로 확인
- [ ] `current.md`의 활성 Phase와 활성 Milestone 이름, 상태, 경로 확인
- [ ] 활성 Phase 문서의 `Milestone 흐름` 확인
- [ ] 활성 Milestone 문서의 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 링크/경로만 확인
- [ ] 활성 Milestone 문서의 제목, `목표`, `상태`만 확인
## 실행 절차
1. `agent-roadmap/` 존재 여부를 확인한다.
- 없으면 로드맵 없음으로 짧게 보고하고 멈춘다.
2. `agent-ops/skills/common/_templates/roadmap-position-report-template.md`를 읽는다.
3. 로컬 `agent-roadmap/current.md`를 확인한다.
- 없으면 로컬 current 없음으로 보고하고, `priority-queue.md`가 있으면 전역 실행 순서와 `ROADMAP.md`의 `Phase 흐름`을 보여준다.
4. `agent-roadmap/priority-queue.md`가 있으면 `실행 순서` 항목을 읽어 전역 Milestone 실행 순서 목록을 만든다.
- 각 항목은 순번, Milestone 제목 링크, 식별용 한 줄 설명만 남긴다.
- 상태, 잠금, 목표, 기능 Task는 각 Milestone 문서 원본을 읽기 전에는 추정하지 않는다.
- archive 링크가 있거나 링크가 깨진 것으로 보이면 `큐 정리 필요`로 표시하고 archive 문서는 읽지 않는다.
- 파일이 없으면 `전역 실행 순서: 없음`으로 출력한다.
5. `ROADMAP.md`의 `Phase 흐름`을 읽어 전체 Phase 목록을 만든다.
3. `agent-roadmap/current.md`를 확인한다.
- 없으면 current 없음으로 보고하고, `ROADMAP.md`가 있으면 `Phase 흐름`만 보여준다.
4. `ROADMAP.md`의 `Phase 흐름`을 읽어 전체 Phase 목록을 만든다.
- 각 Phase는 상태, 이름, 링크만 남긴다.
- current의 활성 Phase와 일치하는 항목에 `← 현재` 표시를 붙인다.
- 완료된 Phase가 archive 경로를 가리켜도 링크만 표시하고 archive 문서는 읽지 않는다.
6. current의 활성 Phase 경로를 열고 `Milestone 흐름`을 읽는다.
5. current의 활성 Phase 경로를 열고 `Milestone 흐름`을 읽는다.
- 각 Milestone은 상태, 이름, 링크만 남긴다.
- current의 활성 Milestone과 일치하는 항목에 `← 현재 후보` 표시를 붙인다.
7. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 링크/경로만 읽는다.
- `SDD 문서` 링크/경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: SDD_LINK`로 출력한다.
- `SDD 문서` 링크/경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: SDD_LINK (파일 없음)` 형식으로 출력한다.
- `SDD 문서` 링크/경로가 없거나 `SDD: 불필요`이면 Milestone 아래에 `SDD: 없음`으로 출력한다.
- `SDD.md`와 같은 디렉터리에 `USER_REVIEW.md`가 있으면 Milestone 아래에 `사용자 리뷰: USER_REVIEW_LINK`로 출력하고, 없으면 `사용자 리뷰: 없음`으로 출력한다.
- SDD 상태, 잠금, 승인 여부를 역할 태그나 상태 요약으로 출력하지 않는다. 필요한 독자는 출력된 SDD 링크를 열어 확인하게 한다.
- SDD 본문은 읽지 않는다.
6. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`만 읽는다.
- `기능`, `완료 리뷰`, `범위 제외`, `작업 컨텍스트`는 사용자가 명시적으로 요청한 경우에만 읽는다.
8. 결과를 템플릿의 섹션 순서와 필드 의미에 맞춰 출력한다. 템플릿의 placeholder, 선택지 표기, HTML 주석은 출력하지 않는다.
## 링크 정규화
- 출력 링크는 채팅 결과이므로 항상 repo root 기준 상대경로를 target으로 쓴다. 예: `[PHASE.md](agent-roadmap/phase/example-phase/PHASE.md)`.
- `current.md`, `ROADMAP.md`, `PHASE.md`, Milestone 문서에서 읽은 Markdown 링크는 그대로 복사하지 않는다. 반드시 링크가 들어 있던 원본 파일 위치 기준으로 target을 해석한 뒤 repo root 기준 상대경로로 다시 쓴다.
- 예: `agent-roadmap/current.md`의 `[PHASE.md](phase/foo/PHASE.md)`는 출력에서 `[PHASE.md](agent-roadmap/phase/foo/PHASE.md)`로 쓴다.
- 예: `agent-roadmap/priority-queue.md`의 `[Milestone](phase/foo/milestones/bar.md)`는 출력에서 `[Milestone](agent-roadmap/phase/foo/milestones/bar.md)`로 쓴다.
- 예: `agent-roadmap/phase/foo/PHASE.md`의 `[Milestone](milestones/bar.md)`는 출력에서 `[Milestone](agent-roadmap/phase/foo/milestones/bar.md)`로 쓴다.
- 예: `agent-roadmap/phase/foo/PHASE.md`의 `[Archive](../../archive/phase/foo/milestones/bar.md)`는 출력에서 `[Archive](agent-roadmap/archive/phase/foo/milestones/bar.md)`로 쓴다. archive 문서는 읽지 않고 링크만 표시한다.
- 링크 label은 사람이 이해할 수 있는 이름을 쓰고, target에는 `<phase-path>`, `<milestone-path>`, `<sdd-path>`, `<user-review-path>`, `<phase-slug>`, `<milestone-slug>` 또는 `{PHASE_LINK}` 같은 placeholder를 남기지 않는다.
- 템플릿의 `{PHASE_LINK}`, `{MILESTONE_LINK}`, `{SDD_LINK}`, `{USER_REVIEW_LINK}`는 실제 `[제목](repo-root-relative-path)` Markdown 링크로 치환한다.
- 대상 경로를 확정할 수 없으면 Markdown 링크를 만들지 말고 `링크 없음: <사유>`로 표시한다. raw path만 단독으로 출력하거나 깨진 링크를 만들지 않는다.
- 출력 전 자체 점검으로 `](<`, `](...<...>)`, `{PHASE_LINK}` 같은 placeholder 링크가 남아 있지 않은지 확인한다.
7. 결과를 템플릿 형식 그대로 출력한다.
## 실행 결과 검증
- [ ] `roadmap-position-report-template.md`의 출력 구조를 유지했는가
- [ ] `priority-queue.md`가 있으면 `실행 순서` 항목을 표시했고, 없으면 `전역 실행 순서: 없음`으로 표시했는가
- [ ] 로컬 `current.md`, `priority-queue.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태/SDD 문서 링크/경로만 기본으로 읽었는가
- [ ] 현재 후보 Milestone 아래에 SDD와 사용자 리뷰를 링크 또는 `없음`으로 출력했는가
- [ ] Phase, Milestone, SDD, 사용자 리뷰 등 모든 문서 포인터가 raw path만 남지 않고 Markdown 링크로 출력되었는가
- [ ] 문서에서 읽은 file-location-relative 링크를 채팅 출력용 repo root 상대 링크로 정규화했는가
- [ ] 출력에 placeholder 링크 target이나 `(제목)[링크]`처럼 뒤집힌 Markdown 문법이 남지 않았는가
- [ ] SDD 상태, 잠금, 승인 여부를 역할 태그나 상태 요약으로 출력하지 않았는가
- [ ] `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태만 기본으로 읽었는가
- [ ] 완료 또는 archive Phase/Milestone은 링크만 표시하고 archive 문서를 읽지 않았는가
- [ ] Phase 흐름을 실행 순서로 설명하지 않고, 전역 실행 순서는 별도 섹션으로 출력했는가
- [ ] current가 여러 Milestone을 가리키면 모두 `현재 후보`로 표시했는가
- [ ] 코드 파일, 테스트 파일, `git status`, `git diff`를 기본 동작에서 읽지 않았는가
- [ ] 로드맵 파일을 수정하지 않았는가
@ -93,21 +59,16 @@ Phase 흐름은 실행 순서가 아니라 도메인/책임 영역의 구조적
## 출력 형식
- 템플릿 경로: `agent-ops/skills/common/_templates/roadmap-position-report-template.md`
- 템플릿의 섹션 순서와 필드 의미를 따른다. placeholder 줄을 그대로 복사하지 말고, 실제 항목 수에 맞춰 행을 생성한다.
- 출력에는 `<phase-path>`, `<milestone-path>`, `<sdd-path>`, `<user-review-path>`, `{PHASE_LINK}`, `{MILESTONE_LINK}`, `{SDD_LINK}`, `{USER_REVIEW_LINK}` placeholder를 그대로 남기지 않고 실제 repo root 기준 상대 링크 target으로 치환한다.
- 템플릿을 그대로 복사해 placeholder를 채운다.
- 섹션 제목과 필드명을 임의로 번역, 축약, 삭제하지 않는다.
- current가 여러 Milestone을 가리키면 breadcrumb와 Milestone 흐름에 모두 표시한다.
- 현재 후보의 역할 태그는 `선행 스케치`, `다음 구현 계획`, `검토 후보`, `보류 후보`처럼 짧게 쓰되 SDD 상태를 역할 태그에 넣지 않는다.
- 현재 후보에 `SDD 문서` 링크/경로가 있으면 Milestone 아래에 SDD 링크를 배치한다. `USER_REVIEW.md`가 있으면 그 링크도 SDD 아래에 배치한다.
- 문서 포인터는 항상 `[표시 제목](상대경로)` Markdown 링크로 출력한다. 파일이 없어도 raw path만 쓰지 말고 `SDD_LINK (파일 없음)`처럼 링크와 상태를 함께 쓴다.
- `전역 마일스톤 실행 순서`에는 `priority-queue.md`의 항목 순서를 그대로 출력한다. Milestone 상태나 잠금은 각 Milestone 문서를 읽지 않았다면 출력하지 않는다.
- 현재 후보의 역할 태그는 `선행 스케치`, `다음 구현 계획`, `검토 후보`, `보류 후보`처럼 짧게 쓴다.
- 로드맵이 없는 프로젝트에서는 로드맵 없음으로 짧게 보고하고 템플릿을 억지로 채우지 않는다.
- 로컬 `current.md`가 없으면 `local current: 없음`으로 출력하고, `[current.md](agent-roadmap/current.md)` 링크를 만들지 않는다.
## 금지 사항
- 기본 동작에서 코드 파일, 테스트 파일, `git status`, `git diff`를 읽지 않는다.
- 기본 동작에서 Milestone의 `기능` 체크리스트를 감사하지 않는다.
- 완료 여부, 남은 작업, 코드와 문서의 동기화 상태를 evidence 기반으로 판정하지 않는다.
- 사용자가 명시하지 않은 상태에서 `ROADMAP.md`, 로컬 `current.md`, Phase, Milestone 문서를 수정하지 않는다.
- 사용자가 명시하지 않은 상태에서 `ROADMAP.md`, `current.md`, Phase, Milestone 문서를 수정하지 않는다.
- 사용자가 과거 기록 확인을 명시하지 않으면 `agent-roadmap/archive/**`를 읽지 않는다.

13
agent-ops/skills/common/check-roadmap-dependency/SKILL.md
View file

@ -22,14 +22,14 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep
## 입력
- `lock-id`: 확인할 lock entry id. 예: `oto:oto-agent-registration`. 명시되면 이 id만 판별한다 (선택)
- `target-milestone`: 확인할 Milestone path 또는 `<project>:agent-roadmap/phase/.../milestones/<slug>.md`. 없으면 현재 프로젝트 로컬 `current.md`의 활성 Milestone 단일 후보를 사용한다 (선택)
- `target-milestone`: 확인할 Milestone path 또는 `<project>:agent-roadmap/phase/.../milestones/<slug>.md`. 없으면 현재 프로젝트 `current.md`의 활성 Milestone 단일 후보를 사용한다 (선택)
- `direction`: `locked` / `rely-on` / `both`. 기본값은 `both`다. `locked`는 대상 Milestone이 잠긴 entry만, `rely-on`은 대상 Milestone을 선행 조건으로 삼는 entry만 확인한다 (선택)
- `locks-file`: 기본값은 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`이며, 다른 파일을 검사할 때만 지정한다 (선택)
## 먼저 확인할 것
- [ ] `agent-ops/bin/roadmap-dependency-checker.sh`가 있는지 확인한다.
- [ ] `lock-id`가 명시되었거나 `target-milestone` 또는 현재 프로젝트 로컬 `current.md`의 활성 Milestone 하나로 Milestone identity를 추론 가능한지 확인한다.
- [ ] `lock-id`가 명시되었거나 `target-milestone` 또는 현재 프로젝트 `current.md`의 활성 Milestone 하나로 Milestone identity를 추론 가능한지 확인한다.
- [ ] 기본 경로 또는 지정된 `locks-file`을 읽을 수 있는지 확인한다.
## 실행 절차
@ -39,12 +39,12 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep
- `locks-file`이 명시되지 않았으면 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`을 사용한다.
- `locks-file`이 없거나 읽을 수 없으면 결과를 `error`로 보고한다. 이를 미충족 의존성으로 해석하지 않는다.
- `lock-id`가 있으면 그 id만 판별한다.
- `lock-id`가 없으면 `target-milestone` 또는 현재 프로젝트 로컬 `agent-roadmap/current.md`의 활성 Milestone 단일 후보로 Milestone identity를 만든다.
- `lock-id`가 없으면 `target-milestone` 또는 현재 프로젝트 `agent-roadmap/current.md`의 활성 Milestone 단일 후보로 Milestone identity를 만든다.
- Milestone identity는 `<project>:agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md` 형식이다.
- `target-milestone`이 `agent-roadmap/...` 상대 경로이면 현재 프로젝트명을 prefix로 붙인다.
- `target-milestone`이 workspace 하위 절대/상대 경로이면 workspace 바로 아래 디렉터리명을 project로 삼고, 그 뒤 `agent-roadmap/...` 경로를 붙인다.
- `target-milestone`이 archive 경로이면 일반 의존 판별 후보로 쓰지 말고 활성 Milestone 대상이 모호하다고 보고한다.
- 활성 Milestone 후보가 없거나 둘 이상이면 추정하지 말고 lock id 또는 Milestone 대상이 모호하다고 보고한다.
- `target-milestone`이 archive 경로이면 일반 의존 판별 후보로 쓰지 말고 사용자에게 활성 Milestone 선택을 요청한다.
- 활성 Milestone 후보가 없거나 둘 이상이면 추정하지 말고 사용자에게 lock id 또는 Milestone 선택을 요청한다.
- `lock-id`가 없으면 `agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" "<direction>" "<locks-file>"`로 Milestone identity와 일치하는 entry를 찾는다.
- find 출력의 `locked:<id>`는 locked entries로, `rely-on:<id>`는 rely-on entries로 분류한다.
- find 출력이 `none`이면 결과를 `error`가 아니라 `no-lock`으로 보고한다.
@ -59,7 +59,6 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep
- stdout `false`와 exit code `1`은 아직 충족되지 않은 의존 조건이 있음을 보고한다.
- exit code `2`는 설정 오류, 입력 오류, 필수 필드 누락, 파싱 오류로 보고한다.
- `rely-on` 방향에서 대상 Milestone이 `[검토중]` 또는 `[완료]`인데 status가 `disable`이면 `update-roadmap` 동기화가 필요한 stale lock으로 보고한다. 이 스킬은 status를 바꾸지 않는다.
- 사용자-facing 결과에 대상 Milestone 문서를 표시할 수 있으면 identity raw 값만 쓰지 말고 `[Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)` 링크를 함께 보고한다.
## 실행 결과 검증
@ -69,7 +68,6 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep
- [ ] lock id가 없을 때 대상 Milestone을 `locked`와 `rely-on.target` 양쪽에서 찾았는가
- [ ] `locks.yaml`이 없는 경우 `false`가 아니라 `error`로 보고했는가
- [ ] 이 스킬이 `locks.yaml`이나 roadmap 문서를 수정하지 않았는가
- [ ] 대상 Milestone 문서를 표시할 수 있으면 Markdown 링크로 함께 보고했는가
- 검증 실패 시: 오류 메시지와 사용한 `lock-id`, `locks-file` 경로를 보고하고 멈춘다.
## 출력 형식
@ -78,7 +76,6 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep
## 의존성 판별 결과
- target-milestone: `<identity | 해당 없음>`
- target-document: <[Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md) | 해당 없음>
- direction: `<locked | rely-on | both>`
- locks-file: `<locks-file>`
- 결과: `<true | false | error | no-lock>`

401
agent-ops/skills/common/code-review/SKILL.md
View file

@ -1,6 +1,6 @@
---
name: code-review
description: "Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, USER_REVIEW.md resolution, implementation-time 사용자 리뷰 요청, or 리뷰 루프. Review and archive one active pair, then leave exactly one next artifact: a follow-up PLAN/CODE_REVIEW pair, USER_REVIEW.md, or complete.log. Plan, implementation, and review use different models."
description: Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, USER_REVIEW.md resolution, implementation-time 사용자 리뷰 요청, or 리뷰 루프. Review the active PLAN/CODE_REVIEW pair, append PASS/WARN/FAIL, archive both active files, and create the required next state: PASS writes complete.log and moves the task to archive; WARN/FAIL writes follow-up PLAN/CODE_REVIEW files unless the user-review gate requires USER_REVIEW.md; user review resolution that closes the task writes complete.log before archive. Never stop after verdict append or user-review closure without writing the required next-state artifact.
---
# Code Review
@ -10,67 +10,45 @@ description: "Use for active task review requests such as 리뷰 진행해, 리
Review the implementation phase of the plan-code-review loop:
```text
plan model -> implementation model -> review model
^ |
+-- different plan model on WARN/FAIL -+
plan skill -> implementation -> code-review skill
^ |
+----- issues found: new routed plan/review files
```
Implementation may end its coding phase early by filling the active review stub's `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`. This path is valid only for a selected Milestone `구현 잠금 > 결정 필요` item. The implementation model must not ask the user directly, call a user-input tool, or execute code-review. It fills every implementation-owned section, reports `review-ready`, and stops for a later review model.
The review agent must select exactly one next-state artifact before ending:
- **Plan**: a different plan model writes one follow-up PLAN/CODE_REVIEW pair.
- **User review**: the review agent writes `USER_REVIEW.md`.
- **Complete**: the review agent writes `complete.log` and archives the task.
Archived findings or `plan-ready` alone are not a valid review result.
The three-output rule begins only after a `review-ready` pair or resolvable `USER_REVIEW.md` passes preflight. An unfilled stub remains in the implementation stage and is not a started review.
Finalization recovery uses the durable artifact combination itself: verdict-appended active review, partial pair archive, `complete.log`, `USER_REVIEW.md`, resolved `user_review_*.log`, or archived WARN/FAIL logs. No model-written transient state file is part of the protocol.
## Hard Actor Boundary
- Plan, implementation, and review use different model identities; separate agents or reasoning settings on the same model do not satisfy this rule.
- Runtime must preserve the exact selected task path and runtime-provided model identities through every handoff. A filled role identity is immutable for that pair; a retry uses the same model identity. Lane/G and agent names are not model identities.
- Resolving `USER_REVIEW.md` continues the archived Review role and must use the same Review model identity recorded in that archived review. If that identity is unavailable, leave `USER_REVIEW.md` unchanged and stop.
- The review model owns the verdict, archive, and USER_REVIEW/complete finalization. It must not edit product source/tests or author a follow-up plan.
- On WARN/FAIL, dispatch a plan model different from both the implementation and review models. End only after the follow-up pair exists; do not implement it.
Implementation may stop early by filling the active review stub's `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`. Code-review validates that request and, when justified, writes `USER_REVIEW.md` from `agent-ops/skills/common/code-review/templates/user-review-template.md`.
## Core Loop Rules
- Trigger: Korean or English active-task review requests, including `리뷰 진행해` and `리뷰해줘`, must use this skill when an active `CODE_REVIEW-*-G??.md` or `USER_REVIEW.md` exists under `agent-task/*/` or `agent-task/*/*/`, excluding `agent-task/archive/**`.
- Keep the selected `{task_name}` through review finalization.
- `PASS`: archive the pair, write `complete.log`, and move the task to monthly archive.
- `WARN`/`FAIL`: apply the user-review gate, then archive the pair. Write `USER_REVIEW.md` for a valid gate; otherwise dispatch a different plan model to write the follow-up pair.
- A filled `사용자 리뷰 요청` is valid only for a selected Milestone lock decision. Otherwise record the blocker as a WARN/FAIL finding for the next plan model.
- Do not replace `USER_REVIEW.md` with an inline user question. When the gate triggers, write the file-based stop state and include its path in the final report.
- Every unresolved `Required` forces `FAIL`; every `Suggested` forces `WARN`. Both require a follow-up pair unless the user-review gate writes `USER_REVIEW.md`.
- Recovery: finish missing review-owned finalization, then dispatch the different plan model when WARN/FAIL lacks a follow-up pair. Never plan or implement with the review model.
- Finalize every selected active state: for `CODE_REVIEW-*-G??.md`, append one verdict, archive the active review and plan files, then create exactly one next state; for `USER_REVIEW.md` completion, update the stop state, write `complete.log`, and archive the task. Do not report before finalization is complete.
- Next state: `PASS` writes `complete.log` and moves the task under `agent-task/archive/YYYY/MM/`; if the task group is `m-<milestone-slug>`, report completion metadata for the runtime event. `WARN` or `FAIL` normally writes the next active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md`; if the user-review gate triggers, write `USER_REVIEW.md` instead. A completed `USER_REVIEW.md` uses the same terminal `complete.log` and archive path as `PASS`.
- A filled implementation-owned `사용자 리뷰 요청` is a review input, not a next state by itself. If it is a genuine user-only decision, user-owned external environment prerequisite, or scope conflict, the user-review gate triggers and this skill writes `USER_REVIEW.md`; if it is vague, unsupported, repo-fixable, or only missing evidence that a follow-up agent can produce by rerunning commands or collecting artifacts, write a normal WARN/FAIL follow-up plan instead.
- Do not ask for confirmation before WARN/FAIL follow-up files unless the user-review gate triggers. If details are uncertain but the gate does not trigger, write the smallest concrete follow-up plan with file references and verification commands.
- Recovery: if a prior turn appended a verdict without archive or next-state files, or resolved `USER_REVIEW.md` without `complete.log`, resume at the matching finalization step and finish the missing artifacts first.
## User Review Gate
`USER_REVIEW.md` is a loop stop state only for selected Milestone lock decisions. The default WARN/FAIL branch creates a follow-up pair through a different plan model. The gate requires positive evidence that the blocker is already represented as a concrete selected Milestone `구현 잠금 > 결정 필요` item.
`USER_REVIEW.md` is a loop stop state for loop-limit exhaustion or user-owned blockers. Default to a normal WARN/FAIL follow-up; the gate requires positive evidence that another implementation/review agent cannot resolve the blocker without user action.
- Derive the pending review archive suffix as `0` when no `code_review_*.log` exists, otherwise `max(existing numeric suffix) + 1`; set `review-number` to that suffix plus one.
- Repeated `WARN`/`FAIL`, missing verification evidence, and environment blockers do not trigger `USER_REVIEW.md`; record them as findings for the next plan model.
- If the active review file has a filled `사용자 리뷰 요청` with `상태` other than `없음`, validate that `사유 유형` is `milestone-lock`, that `연결 대상` points to the selected Milestone, and that the requested decision matches a Milestone `구현 잠금 > 결정 필요` item.
- A valid Milestone-lock request is `Required`/`FAIL` and writes `USER_REVIEW.md` instead of a follow-up pair.
- If the request is not tied to the Milestone lock, do not write `USER_REVIEW.md`; record it as a WARN/FAIL finding.
- `USER_REVIEW.md` is created from `agent-ops/skills/common/code-review/templates/user-review-template.md`, filled with the archived loop history, current archived plan/review paths, verdict, loop count, blocking evidence, connection target, and the exact Milestone decision item.
- Compute `review-number` as `count(agent-task/{task_name}/code_review_*.log) + 1` before archiving the active review.
- If `review-number >= 5` and the verdict is `WARN` or `FAIL`, stop the automatic loop and write `USER_REVIEW.md`.
- If `review-number == 1`, the verdict is `FAIL`, and the blocking issue is a test environment problem that requires user action rather than repo-owned setup or evidence a follow-up agent can produce by rerunning commands or collecting artifacts, stop the automatic loop and write `USER_REVIEW.md`.
- If the active review file has a filled `사용자 리뷰 요청` with `상태` other than `없음`, and the blocker is a user-only decision, user-owned external environment prerequisite, or scope conflict that the repository and a capable next agent cannot safely resolve by code changes or verification reruns, stop the automatic loop and write `USER_REVIEW.md`.
- Treat a first-review failure as a test environment problem only with evidence from an attempted command: missing SDK/tool/runtime, unavailable external service, absent secret/credential, unsupported OS/device/interactive environment, or another prerequisite outside the repository. Record the exact command and stdout/stderr. Before claiming a tool is missing, require `command -v <tool>` or the project-equivalent check. Missing or non-verbatim verification evidence is a verification-trust failure, not a test environment problem.
- Treat an implementation-owned `사용자 리뷰 요청` as valid only with specific decision questions, evidence, attempted commands/output or a reason commands could not run, and clear resume conditions. The not-run reason must identify user-owned action or an external prerequisite; agent execution limits, missing handoff evidence, or incomplete verification records become normal WARN/FAIL follow-up plans when a capable follow-up lane can produce the evidence.
- Do not classify repo-owned setup bugs or verification evidence gaps as environment problems. If a manifest, bootstrap script, test fixture, documented project entrypoint, or follow-up agent can provide the dependency or evidence, write a normal follow-up plan instead.
- `USER_REVIEW.md` is created from `agent-ops/skills/common/code-review/templates/user-review-template.md`, filled with the archived loop history, current archived plan/review paths, verdict, loop count, blocking evidence, and user decision options.
## User Review Resolution
When an active `USER_REVIEW.md` exists, it remains terminal until the linked Milestone decision is resolved. After resolution, this skill either completes PASS finalization or dispatches a different plan model when more implementation is required.
When an active `USER_REVIEW.md` exists and the user decision closes the task as complete/PASS, finalization is still owned by this skill.
- Read `USER_REVIEW.md`, archived `plan_*.log`, and archived `code_review_*.log` in that task directory.
- Inspect `## 상태` before writing. `USER_REVIEW` means the linked decision still needs first-time resolution. `RESOLVED` means resolution was already durably recorded; never append another result or replace its timestamp.
- When status is `USER_REVIEW`, verify the linked decision. If it remains unresolved, leave `USER_REVIEW.md` unchanged; otherwise record its resolution exactly once using the matching branch below.
- If a first-time resolution requires implementation, replace the `## 상태` value with `RESOLVED` and append one `## 해소 결과` with the exact keys `결과: REPLAN`, `해소 일시`, `결정`, `Evidence`, `Archived plan`, `Archived review`, `Forbidden implementation model`, and `Forbidden review model`; then continue immediately with the `RESOLVED`/`REPLAN` branch below.
- If active `USER_REVIEW.md` is already `RESOLVED`/`REPLAN`, validate that single result, archive the file unchanged as `user_review_N.log` using `N=0` or `max(existing numeric suffix) + 1`, then dispatch a different plan model with that log and its referenced archived pair. Verify the pair. The highest numeric-suffix matching `RESOLVED`/`REPLAN` log is durable `plan-ready` evidence and takes precedence over the original user-review gate during recovery.
- If a first-time resolution closes the task, select one completion timestamp, replace the `## 상태` value with `RESOLVED`, and append one `## 해소 결과` with the exact keys `결과: COMPLETE`, `해소 일시`, `Final verdict`, `결정`, `Evidence`, `Archived plan`, and `Archived review`; then continue immediately with the `RESOLVED`/`COMPLETE` branch below.
- If active `USER_REVIEW.md` is already `RESOLVED`/`COMPLETE`, validate that single result and reuse its `해소 일시` without changing the file. The final archive path is selected and persisted later in `complete.log`.
- On that complete/PASS branch, write `complete.log` from `agent-ops/skills/common/code-review/templates/complete-log-template.md` before moving or archiving the task directory. Include both the original archived review verdict and the user-review resolution line in `루프 이력`.
- Verify the user decision and any follow-up evidence are sufficient to close the task. If a new implementation plan is needed instead, do not close; route back to the plan skill, which archives `USER_REVIEW.md` to `user_review_N.log` before writing a new plan.
- Update `USER_REVIEW.md` in place to show a resolved state, final verdict, loop history, fulfilled decision items, and the evidence that closed the stop state.
- Write `complete.log` from `agent-ops/skills/common/code-review/templates/complete-log-template.md` before moving or archiving the task directory. Include both the original archived review verdict and the user-review resolution line in `루프 이력`.
- Then apply the same task-directory archive move and `m-<milestone-slug>` PASS completion metadata rules as a normal `PASS`.
- Do not leave an active task directory that contains `USER_REVIEW.md` and `*.log` files but no `complete.log` after the linked Milestone decision resolves the task as complete/PASS.
- Do not leave an active task directory that contains `USER_REVIEW.md` and `*.log` files but no `complete.log` after the user has completed and approved the task.
## Workflow Contract
@ -92,7 +70,6 @@ Filename rules:
- Review file: `CODE_REVIEW-{review_lane}-GNN.md`
- `{lane}` is only `local` or `cloud`; never put model names in filenames.
- `GNN` is a two-digit capability grade from `G01` to `G10`; runtime maps lane+grade to current models externally.
- This skill reads the active routed names but does not choose follow-up lane/G. Follow-up basenames come only from `plan` executing `finalize-task-routing`.
Multi-plan runtime contract:
@ -108,32 +85,28 @@ Milestone task group contract:
- `agent-task/m-<milestone-slug>/` is reserved for Milestone-linked work created by the plan skill.
- Do not treat normal task groups that do not start with `m-` as runtime milestone completion targets.
- For a selected task path, parse only the first path segment as `{task_group}`. If it matches `^m-[a-z0-9][a-z0-9-]*$`, strip `m-` to get `<milestone-slug>`.
- Do not modify `agent-roadmap/**` for milestone routing during code-review finalization. Read only the Milestone path from `Roadmap Targets` and its SDD path when needed to verify SDD Evidence Map.
- Do not read or modify `agent-roadmap/**` for milestone routing during code-review finalization.
- Do not call `update-roadmap` from this skill. The runtime consumes the PASS completion event, checks current state, resolves the active Milestone, and calls `update-roadmap` if needed.
- For `m-<milestone-slug>` PASS tasks, report the original active task path, final archive path, complete log path, task group, and milestone slug so the runtime has deterministic event inputs.
Follow-up handoff:
Review routing rules:
- Record concrete findings, affected paths, verification evidence, and release conditions in the archived review log.
- The review model must not choose the next lane/G or write the follow-up pair.
- Dispatch a different plan model with the exact archived log paths. That model performs isolated routing, writes the pair, reports `implementation-ready` or `dependency-waiting`, and stops.
- The review agent is responsible for ensuring that the follow-up pair exists, even though the different plan model authors it.
- `local`: narrow, low-risk, or first-pass review where tests and scope are clear.
- `cloud`: multi-file, API/call-site impact, meaningful test judgment, plan deviation, weak verification, security/auth, storage/migration, concurrency, protocol/schema, cross-domain, or repeated Required issues.
- `cloud-G07` or higher is mandatory for terminal-agent follow-up work: shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, or terminal benchmark-style tasks. Merely running deterministic tests such as `go test` does not make a task terminal-agent work.
- `cloud-G07` or higher is mandatory for follow-up plans when a local implementation failed a real bin/smoke/integration command after unit tests passed, when the success condition depends on an interactive TUI/PTY/browser/external CLI or screen repaint/cursor stream, or when verification trust is Fail because recorded stdout/stderr does not match a rerun.
Directory states:
| State | Meaning |
|-------|---------|
| `PLAN-*-G??.md` + unfilled `CODE_REVIEW-*-G??.md` stub/placeholders | `implementation-ready`, `dependency-waiting`, or incomplete implementation; do not start review or append a verdict |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation claims a selected Milestone lock decision blocker; review validates the request and writes `USER_REVIEW.md` only if justified |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` without verdict, dependencies satisfied | `review-ready`; the review model may consume it |
| Active pair with encoded predecessors still unsatisfied | `dependency-waiting`; leave the pair unchanged and do not start review |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with appended verdict | Transitional; do not append another verdict and immediately resume Step 5 preparation/archive |
| Exactly one active pair member + its newly archived counterpart | Partial archive after a preflighted finalization; verify both identities, finish the remaining archive, then resume post-archive recovery |
| `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), with final archive/event metadata fixed before the final task-directory move |
| `USER_REVIEW.md` + `*.log` files | Linked Milestone decision is required |
| Highest numeric-suffix matching `user_review_*.log` has `## 상태` value `RESOLVED` and `해소 결과 > 결과` value `REPLAN`, with no active pair | Resolved user-review `plan-ready`; dispatch a different plan model using that log and its referenced archived pair |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub or placeholders | Implementation is pending/incomplete; review should fail completeness if invoked |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation claims a user-only blocker; review validates the request and writes `USER_REVIEW.md` only if justified |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill |
| `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), before final task-directory archive move |
| `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; user decision is required before creating another plan |
| `agent-task/archive/YYYY/MM/{task_name}/complete.log` + `*.log` files | Archived completed task path (PASS or user-review-resolved PASS); not active |
| Only matching `plan_*.log` / `code_review_*.log` with WARN/FAIL | Internal `plan-ready`; dispatch a different plan model to create the follow-up pair |
| Only `*.log` files (no `complete.log`) | Task terminated mid-loop or abandoned |
The implementing agent never archives or deletes active files; archiving is this skill's responsibility.
@ -153,31 +126,13 @@ Classify the combined set of active `CODE_REVIEW-*-G??.md` and `USER_REVIEW.md`
| Result | Action |
|--------|--------|
| Exactly one active path and it is `CODE_REVIEW-*-G??.md` | Review that task; exactly one `PLAN-*-G??.md` is normally expected beside it. If the review already has a verdict and its exact plan counterpart was just archived, use partial-archive recovery instead of reporting a missing plan. |
| Exactly one active path and it is `USER_REVIEW.md`, with a linked Milestone completion/resolution decision | Perform User Review Resolution for that task. |
| One or more active paths and every active path is `USER_REVIEW.md`, with no completion/resolution decision | Report that the linked Milestone decision is required and list the paths. |
| No active paths | Apply the finalization-recovery scan below; stop only when it finds no recoverable task. |
| Multiple active paths | If the user/runtime named a task group, task path, or subtask directory that identifies exactly one active path, use that directory. Otherwise list paths and stop with an ambiguity report; do not choose by agent judgment and do not create a user-review request for routing ambiguity. |
| Exactly one active path and it is `CODE_REVIEW-*-G??.md` | Review that task; exactly one `PLAN-*-G??.md` is expected beside it. |
| Exactly one active path and it is `USER_REVIEW.md`, with a user-supplied completion/resolution decision | Perform User Review Resolution for that task. |
| One or more active paths and every active path is `USER_REVIEW.md`, with no completion/resolution decision | Report that user decision is required and list the paths. |
| No active paths | Stop and report that no active review exists. |
| Multiple active paths | If the user/runtime named a task group, task path, or subtask directory that identifies exactly one active path, use that directory. Otherwise list paths and ask which task to review or resolve; do not choose by agent judgment. |
If a selected task directory contains both `USER_REVIEW.md` and an active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, do not overwrite either state or ask the user to choose between files. Validate provenance: a valid unresolved `USER_REVIEW.md` remains the terminal state; otherwise resume the provable active-pair or finalization recovery path and preserve the inconsistent path as review evidence.
Before review begins, runtime re-evaluates every encoded predecessor for both filled and unfilled pairs. If one is unsatisfied, leave the pair unchanged, report `dependency-waiting`, and do not record a Review identity or append a verdict.
An unfilled review stub with satisfied dependencies is not `review-ready`. Leave the pair unchanged and return it to the implementation stage.
Finalization-recovery scans active task paths and uses only the artifact identities already present:
- Find task directories with a verdict-appended active review, a partially archived pair, `complete.log` not yet moved, matching archived plan/review logs with no active pair, `USER_REVIEW.md`, or resolved `user_review_*.log`.
- Match plan/review artifacts by their `task` and `plan` headers, and match a resolved user-review log by the archived plan/review paths recorded in its `해소 결과`; do not choose by modification time alone.
- Recover the user/runtime-selected task path. Without one, recover only a single unambiguous candidate; list multiple candidates without mutating them.
- Apply recovery precedence in this order: active `complete.log`; active `USER_REVIEW.md`; an already-created follow-up pair; highest numeric-suffix matching `RESOLVED`/`REPLAN` user-review log; verdict-appended or partially archived pair; archived pair alone.
- Before returning an existing next artifact, verify its task/plan provenance and required fields.
- An active `complete.log` owns its completion timestamp and exact final archive path. Validate those fields, then resume the final move.
- An active `RESOLVED` `USER_REVIEW.md` resumes from its single `해소 결과`: archive an unchanged `REPLAN` result or continue `COMPLETE` using its fixed timestamp. Never resolve it again.
- A highest numeric-suffix matching `RESOLVED`/`REPLAN` user-review log dispatches the different plan model with that log and its referenced archived pair; never recreate `USER_REVIEW.md` from the older gate.
- Resume a verdict or partial archive at Step 5. For an archived WARN/FAIL pair without a next artifact, write `USER_REVIEW.md` when it proves a valid unresolved gate; otherwise dispatch the different plan model. For an archived PASS pair, finish the missing `complete.log`.
- A newly created unfilled follow-up pair already satisfies the prior review's Plan output. Return the pair to implementation; do not review it until implementation makes it `review-ready`.
- A PASS task move is the last review-owned filesystem mutation. After the move, the runtime may idempotently replay the completion event from the archived `complete.log` Finalization metadata; the review model does not reopen or mutate the moved task.
If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, report an inconsistent loop state instead of overwriting either state.
## Step 2 - Load Context
@ -188,24 +143,16 @@ Count `agent-task/{task_name}/code_review_*.log` in the selected active task dir
The diff is the starting point, not the boundary. Follow behavior and API connections far enough to judge correctness.
If the active plan or review file contains `Agent UI Completion`, also read `agent-ops/rules/common/rules-agent-ui.md` and the listed active agent-ui documents. Do not read `agent-ui/definition/archive/**` or `agent-ui/archive/user-review/**` unless the review explicitly cites those archive paths.
## Step 3 - Pre-Review Checklist
Before writing the verdict:
- Compare actual source files against every planned checklist item.
- For an indexed task directory, require its basename to match `NN_{subtask_name}` or `NN+PP[,QQ...]_{subtask_name}` and every encoded predecessor to be lower than `NN`. A malformed name is a Required orchestration finding and can never PASS.
- For an indexed task directory with `+PP[,QQ...]`, require one unambiguous matching predecessor `complete.log` for every encoded index before review can PASS. Missing dependency evidence is a Required orchestration finding; the implementation worker never supplies or repairs it.
- Compare the plan `구현 체크리스트` and review stub `구현 체크리스트`. Do not edit either checklist to repair drift; when correction is needed, record it as a WARN/FAIL finding.
- When the active artifacts have `Roadmap Targets`, check whether the referenced Milestone has `SDD: 필요`. When it does, read only that Milestone and its SDD, compare implementation evidence against the SDD Acceptance Scenarios/Evidence Map for the targeted task ids, and fail completeness or verification trust when evidence is insufficient. Do not require a separate SDD target section.
- Record obvious non-behavioral source nits such as typos, stale comments, docs, or formatting. Do not edit source/test files during review; Nit-only findings may follow the PASS rule below.
- Compare the plan `구현 체크리스트` and review stub `구현 체크리스트`; item text/order must match.
- If a checklist item contains integrated verification for a feature, treat that feature item as incomplete until both implementation evidence and the matching verification output are present. Do not accept a separate unchecked completion-criteria item as a substitute.
- Confirm the implementation marked the matching checklist items in the active review file, including the final mandatory `CODE_REVIEW-*-G??.md` completion item. Do not mark or rewrite implementation-owned items on its behalf; classify missing or inconsistent entries by their effect on completeness and verification trust.
- Verify that the PLAN `plan-model` metadata (or the legacy `역할 모델 > Plan` field) matches the review ledger and that the review stub records the Implementation identity. Require runtime to record the Review identity before verdict; filled identities are immutable. Reject review start unless all three are pairwise different, and do not infer identity from lane/G or agent name.
- If the active plan or review file contains `Agent UI Completion`, verify the implementation-owned fields are filled before PASS: listed agent-ui docs exist, actual code evidence paths exist, requested status updates are explicit, and implementation verification evidence is present. Missing or untrusted evidence is a completeness or verification-trust issue.
- Treat review artifact gaps as failures only when they prevent judging implementation correctness, tests, contracts, or verification trust.
- Read `사용자 리뷰 요청`. If filled, validate the exact linked Milestone decision and blocker evidence; reject non-lock requests.
- Confirm the implementation marked the matching checklist items in the active review file, including the final mandatory `CODE_REVIEW-*-G??.md` completion item.
- Treat blank placeholder sections, missing actual implementation notes, missing checklist completion, or missing actual stdout/stderr in the active review file as a completeness or verification-trust failure. This alone does not trigger `USER_REVIEW.md`; route it to a normal follow-up plan unless there is separate user-only blocker evidence.
- Read the `사용자 리뷰 요청` section. If `상태` is not `없음`, validate the exact decision needed, blocker evidence, command output or not-run reason, why automatic follow-up cannot resolve it, and resume condition before deciding whether the user-review gate triggers.
- Grep renamed/removed symbols for stale references.
- Confirm every required test exists, name matches, and assertions are meaningful.
- Cross-check claimed verification output in the active review file against actual code and project commands.
@ -215,30 +162,28 @@ Before writing the verdict:
Append `코드리뷰 결과` to the active `CODE_REVIEW-*-G??.md`.
Before appending `PASS`, if all other PASS conditions are met and the active review file contains `Agent UI Completion`, perform the review-pass status update first: update the listed agent-ui docs to `구현됨`, add actual code evidence, run `validate-agent-ui`, and mark the section's review-agent-owned finalization items. If this update or validation fails, do not append `PASS`; classify and record it as a normal WARN/FAIL finding.
Required fields:
- `종합 판정`: exactly `PASS`, `WARN`, or `FAIL`.
- `차원별 평가`: Pass/Warn/Fail for correctness, completeness, test coverage, API contract, code quality, implementation deviation, verification trust. If SDD Evidence Map applies through `Roadmap Targets`, also include spec conformance.
- `차원별 평가`: Pass/Warn/Fail for correctness, completeness, test coverage, API contract, code quality, plan deviation, verification trust.
- `발견된 문제`: `없음`, or bullets using `Required`, `Suggested`, or `Nit` with `file:line` and a concrete fix.
- `다음 단계`: keep only the matching PASS, WARN/FAIL follow-up, or USER_REVIEW line.
Do not perform archive or terminal-output mutations during Step 4. Step 5 onward owns finalization.
Do not check archive/next-state items in `코드리뷰 전용 체크리스트` during Step 4. Complete the applicable dedicated checklist items in the archived `code_review_*.log` during Step 7, after archive, next-state writes, and PASS task-directory moves are done.
Severity semantics:
| Verdict | Meaning | Follow-up plan |
|---------|---------|----------------|
| `PASS` | No Required/Suggested issues. Nit-only findings may still PASS. | No |
| `WARN` | One or more Suggested issues, zero Required. | Follow-up pair via a different plan model; a valid gate is normally `FAIL` |
| `FAIL` | One or more Required issues, including a valid Milestone-lock request. | Follow-up pair via a different plan model, except a valid `USER_REVIEW.md` gate |
| `WARN` | One or more Suggested issues, zero Required. | Yes, unless the user-review gate triggers |
| `FAIL` | One or more Required issues. | Yes, unless the user-review gate triggers |
Issue severity:
- `Required`: correctness, API contract, missing required test, missing integrated verification, plan-completeness issue, review artifact gaps that prevent judging implementation quality, or a valid selected Milestone-lock decision that blocks implementation.
- `Required`: correctness, API contract, missing required test, missing verification that was integrated into a feature item, plan-completeness issue, or incomplete/placeholder `CODE_REVIEW-*-G??.md` content required from the implementing agent.
- `Suggested`: useful improvement that should enter the loop but does not block correctness.
- `Nit`: tiny cleanup; record it without editing implementation-owned files or forcing WARN.
- `Nit`: tiny cleanup; may be recorded without forcing WARN.
Verdict consistency:
@ -248,65 +193,216 @@ Verdict consistency:
## Step 5 - Archive Active Files
- For a valid user-review gate, render `USER_REVIEW.md` in memory before renaming.
- Ensure `.gitignore` exposes `agent-task/**/*.md` and `agent-task/**/*.log`.
- Derive each archive suffix as `0` when no matching log exists, otherwise `max(existing numeric suffix) + 1`; combine it with that active file's own lane/grade.
- For an uninterrupted archive, compute and preflight both destinations before the first rename and require both to be absent.
- For partial recovery, identify the archived counterpart by matching `task` and `plan` headers. Treat its actual path as canonical, derive the missing member's destination from the remaining active member's own lane/grade and the current matching log suffixes, require that destination to be absent, and archive only the missing member. Do not invent or rename the existing counterpart.
- The verdict, user-review gate, task/plan identity, and forbidden Plan identities remain readable from the active or archived review. Derive the post-archive branch from those artifacts after each rename; do not depend on an in-memory value surviving restart.
- Rename the review, then the plan. Verify no active pair remains.
Archive is mandatory for `PASS`, `WARN`, and `FAIL`. Archive order is fixed:
1. Count existing `code_review_*.log` as `N`; rename `CODE_REVIEW-{review_lane}-GNN.md` to `code_review_{review_lane}_GNN_N.log`.
2. Count existing `plan_*.log` as `M`; rename `PLAN-{build_lane}-GNN.md` to `plan_{build_lane}_GNN_M.log`.
After archiving, neither active `.md` file remains unless Step 6 writes a follow-up plan/review or `USER_REVIEW.md`.
## Step 6 - Post-Review Actions
For `PASS`, after both pair logs exist, select one completion timestamp and collision-safe final task archive path, then write `agent-task/{task_name}/complete.log`. If a `USER_REVIEW.md` stop is resolved as complete/PASS, reuse its fixed resolution timestamp and select the collision-safe path when writing `complete.log`. Write and verify `complete.log` before moving that task. On recovery, an existing `complete.log` is canonical; do not select a new timestamp or path.
For `PASS`, write `agent-task/{task_name}/complete.log` before reporting. If a `USER_REVIEW.md` stop is resolved as complete/PASS, write the same `complete.log` before archiving that task.
Complete log template:
- Template path: `agent-ops/skills/common/code-review/templates/complete-log-template.md`
- Copy the template's section order and fill every placeholder from the archived plan/review logs and final verdict.
- Do not leave placeholders in `complete.log`.
- Fill the required `Finalization` section with the exact template keys: original `origin-task`, collision-safe `final-archive-path`, `task-group`, Milestone slug or `none`, final archived plan/review paths, and roadmap-completion Task ids or `none`. These fields are the runtime's idempotent completion-event input and the final-move recovery source.
- If the task did not close through `USER_REVIEW.md`, remove the optional user-review row from the `루프 이력` table.
- If the archived plan or review log contains `Roadmap Targets`, copy it into `complete.log` as `Roadmap Completion`. Include the Milestone path, completed Task ids, archived plan/review log paths, and verification evidence. If there is no `Roadmap Targets` section, remove the optional `Roadmap Completion` template section entirely and do not invent roadmap targets.
- If the archived review log contains `Agent UI Completion`, copy the completed evidence into `complete.log`. If there is no `Agent UI Completion` section, remove the optional complete-log section entirely.
- Use `없음` for empty `잔여 Nit` or `후속 작업`.
- A PASS `complete.log` must not contain unresolved Required or Suggested issues. Nit-only leftovers may be recorded under `잔여 Nit`.
For `WARN` or `FAIL` after archive:
For `WARN` or `FAIL`, apply the user-review gate before writing follow-up files.
- If the user-review gate triggered, write and verify `USER_REVIEW.md`.
- Otherwise dispatch a different plan model with the archived plan/review paths and wait for its readiness result. Require one new routed PLAN/CODE_REVIEW pair at the same task path and verify `implementation-ready` or `dependency-waiting`. The review model must not write that pair or edit product source/tests.
- Stop before implementation.
If the user-review gate triggers:
If the task group is `m-<milestone-slug>` and the user-review gate triggered, prepare a blocked-on-user-review report; do not emit PASS completion metadata and do not call `update-roadmap`.
- Write `agent-task/{task_name}/USER_REVIEW.md` from `agent-ops/skills/common/code-review/templates/user-review-template.md`.
- Fill every placeholder. Use `loop-limit`, `environment-blocked`, or `implementation-blocked` as the reason type.
- Include all available archived loop history in chronological order, the current archived plan/review log paths, the final verdict, review number, issue summary, blocking evidence, and the exact user decision needed.
- Do not write a new active `PLAN-{build_lane}-GNN.md` or `CODE_REVIEW-{review_lane}-GNN.md`.
- Do not write `complete.log`.
- If the task group is `m-<milestone-slug>`, report that the milestone task is blocked on user review; do not emit PASS completion metadata and do not call `update-roadmap`.
## Step 7 - Finalize, Move PASS Task, And Report
If the user-review gate does not trigger, write new routed plan/review files using the plan skill format:
- New plan number is the count of `plan_*.log` after archive.
- Header tag is `REVIEW_<PARENT_TAG>`.
- If the selected task group is `m-<milestone-slug>`, write the follow-up plan/review under the same `m-<milestone-slug>` task group.
- Base the follow-up scope directly on the archived review findings. Keep it narrow and actionable.
- Choose lane/grade again; preserve the prior route only when it was adequate, otherwise raise `GNN` and/or move `local -> cloud`.
- If the finding is only missing or untrusted verification evidence that an appropriate follow-up lane can produce by rerunning commands or collecting artifacts, do not write `USER_REVIEW.md` solely for that reason. Write a follow-up plan that reruns the exact commands in an appropriate lane and records actual stdout/stderr.
- Before choosing the follow-up route, apply this escalation gate:
- If the archived plan was `local-*` and the verdict is `FAIL` for correctness, completeness, test coverage, or verification trust, move the follow-up build lane to `cloud` unless the issue is trivially deterministic and review-detectable without live environment behavior.
- If the follow-up work is terminal-agent work (shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, or terminal benchmark-style tasks), use `cloud-G07` or higher.
- If unit tests passed but a real bin/smoke/integration command failed, use `cloud-G07` or higher.
- If the task depends on interactive TUI/PTY/browser/external CLI behavior, screen repaint/cursor stream parsing, or live command-palette state, use `cloud-G07` or higher.
- If verification evidence is missing, reconstructed, stale, untrusted, or mismatched on rerun, use `cloud-G07` or higher and make verification trust recovery a plan item.
- `FAIL`: one plan item per Required issue.
- `WARN`: one grouped plan item for Suggested issues, plus related Nit issues if useful.
- Each plan item needs problem, solution with before/after when non-trivial, checklist, test decision, intermediate verification.
- The follow-up plan and review stub must contain matching `구현 체크리스트` item text/order, including the final mandatory `CODE_REVIEW-*-G??.md` completion item.
- The follow-up plan's implementer instructions and review stub must include the implementation-time `사용자 리뷰 요청` stop path so the next implementer can act without reading the plan skill.
- Copy `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` into the follow-up review stub's `사용자 리뷰 요청` section.
Routed review stub template (fill `{…}` placeholders; everything else is fixed and must not be changed by the implementing agent):
```markdown
<!-- task={task_name} plan={N} tag={TAG} -->
# Code Review Reference - {TAG}
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date={YYYY-MM-DD}
task={task_name}, plan={N}, tag={TAG}
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-{review_lane}-GNN.md` → `code_review_{review_lane}_GNN_N.log`, `PLAN-{build_lane}-GNN.md` → `plan_{build_lane}_GNN_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [{TAG}-1] {item description} | [ ] |
| [{TAG}-2] {item description} | [ ] |
## 구현 체크리스트
{copy the follow-up plan's 구현 체크리스트 items exactly, preserving order and checkbox text}
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다.
- [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
## 주요 설계 결정
_구현 에이전트가 주요 설계 결정 사항을 기록한다._
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
{pre-filled from plan — one bullet per review focus area}
## 검증 결과
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
### {TAG}-1 중간 검증
```
$ {verification command from plan}
(output)
```
### 최종 검증
```
$ {final verification command from plan}
(output)
```
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.
```
Sections and their ownership:
| 섹션 | 소유자 | 설명 |
|------|--------|------|
| 헤더 주석, 개요(date/task/plan/tag), 리뷰 에이전트 지시 | 스텁 생성 시 고정 | 구현 에이전트가 수정하거나 실행하지 않음 |
| 구현 항목별 완료 여부 (항목명) | 스텁 생성 시 고정 | `[ ]` → `[x]` 체크만 구현 에이전트가 수행 |
| 구현 체크리스트 (항목 텍스트/순서) | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 `[ ]` → `[x]` 체크만 수행; 마지막 체크박스는 저장 전 필수 |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
| 계획 대비 변경 사항, 주요 설계 결정 | 구현 에이전트가 채움 | placeholder 텍스트를 실제 내용으로 교체 |
| 사용자 리뷰 요청 | 구현 에이전트가 채움 | 진행에 사용자 입력이 필요하지 않으면 `상태: 없음` 유지; 필요하면 결정 항목, 근거, 명령 출력, 자동 후속 불가 이유, 재개 조건을 기록 |
| 리뷰어를 위한 체크포인트 | 스텁 생성 시 고정 | 계획에서 추출한 리뷰 포인트 |
| 검증 결과 (섹션 제목 + 명령) | 스텁 생성 시 고정 | 실행 출력만 구현 에이전트가 채움; 명령 변경은 `계획 대비 변경 사항`에 기록 |
| 코드리뷰 결과 | 리뷰 에이전트가 append | 스텁에 포함하지 않음 |
## Step 7 - Complete Review-Only Checklist, Move PASS Task, And Report
After Step 6:
- For `PASS`, read the exact task archive path and completion-event fields back from `complete.log`; do not rely on in-memory copies.
- Before a PASS move, run the ignore check and prepare the branch report from the same `complete.log` metadata. The move must be the only remaining review-owned filesystem mutation.
- Create the parent of the exact task archive path and preflight the destination again. If it is newly occupied by non-matching evidence while the active task still exists, select the next collision-free suffix, replace every affected old final-archive prefix in `complete.log` including `Finalization` and `Roadmap Completion` evidence paths, re-read and revalidate the whole file, then preflight that new exact path.
- Move the selected active task directory to that exact path as the final review-owned filesystem mutation. Do not open or update the moved review log, `complete.log`, or any other file after the move.
- If verdict is `PASS` and `{task_group}` matches `m-<milestone-slug>`, do not resolve the roadmap target and do not call `update-roadmap`. Before the task archive move, verify the `complete.log` Finalization metadata contains `origin-task=agent-task/{task_name}`, `task-group={task_group}`, `milestone-slug=<milestone-slug>`, final archive path, archived plan/review log paths, and `roadmap-completion=<Task ids from complete.log or none>`.
- The runtime consumes that completion event, checks current state, and calls `update-roadmap` if needed. `update-roadmap` only checks Milestone Task ids when `complete.log` contains `Roadmap Completion`; if the section is absent, roadmap Task completion is a no-op even for `m-*` task groups.
- If verdict is `PASS` and the archived review log contains `Agent UI Completion`, ensure the listed agent-ui status/evidence update and `validate-agent-ui` check are complete before writing or finalizing `complete.log`. Do not defer this to runtime or Milestone completion.
- `WARN` and `FAIL` do not update the roadmap Milestone. The dispatched plan model keeps the same task path.
- `USER_REVIEW` does not update the roadmap Milestone and does not produce PASS completion metadata. Keep the active task directory in place with `USER_REVIEW.md` and archived plan/review logs until the linked Milestone lock decision is resolved.
- If `USER_REVIEW.md` is later resolved as complete/PASS by linked Milestone decision and evidence, write `complete.log`, move the task directory to archive, and report `m-*` PASS completion metadata just like a normal `PASS`.
- For `WARN` or `FAIL`, run `git check-ignore -q --` on generated logs and terminal files after the follow-up pair or `USER_REVIEW.md` exists.
- For `PASS`, perform the same ignore check before the final move. For user-review-resolved PASS, also verify the active task contains the resolved `USER_REVIEW.md`, `complete.log`, and existing archived pair before moving.
- If any required artifact is missing, finish the archive, follow-up pair handoff, `complete.log`, final-path metadata, or `USER_REVIEW.md` write first.
- Report only after the selected artifact and final paths are verified. A PASS report is read-only after the final move.
- If verdict is `PASS`, determine archive month from the current completion date as `YYYY/MM`, create the needed archive parent directories, then move the selected active task directory `agent-task/{task_name}/` to `agent-task/archive/YYYY/MM/{task_name}/`. For split work, the selected active task directory is the subtask directory, and the archive must preserve the task group path, e.g. `agent-task/refactoring/01_core/` moves to `agent-task/archive/YYYY/MM/refactoring/01_core/`.
- Do not overwrite an existing archive directory. If `agent-task/archive/YYYY/MM/{task_name}/` already exists, append the next numeric suffix to the final path segment: single-plan `agent-task/archive/YYYY/MM/{task_group}_1/`, split-plan `agent-task/archive/YYYY/MM/{task_group}/{subtask_dir}_1/`, and so on.
- After moving a split subtask, remove the active parent `agent-task/{task_group}/` only if it is empty. If sibling subtask directories or other files remain, leave the parent task group in place.
- If verdict is `PASS` and `{task_group}` matches `m-<milestone-slug>`, do not resolve the roadmap target and do not call `update-roadmap`. Report completion event metadata after the task archive move: `origin-task=agent-task/{task_name}` from the original active task path, `task-group={task_group}`, `milestone-slug=<milestone-slug>`, final archive path, `complete.log` path, and archived plan/review log paths.
- The runtime consumes that completion event, checks current state, resolves `agent-roadmap/phase/*/milestones/<milestone-slug>.md`, and calls `update-roadmap` if needed.
- `WARN` and `FAIL` do not update the roadmap Milestone; the follow-up plan remains under the same `m-<milestone-slug>` task group when the original task was Milestone-linked.
- `USER_REVIEW` does not update the roadmap Milestone and does not produce PASS completion metadata. Keep the active task directory in place with `USER_REVIEW.md` and archived plan/review logs until the user decides how to resume, replan, defer, or abandon the task.
- If `USER_REVIEW.md` is later resolved as complete/PASS by user decision and evidence, write `complete.log`, move the task directory to archive, and report `m-*` PASS completion metadata just like a normal `PASS`.
- For `PASS`, open the moved `agent-task/archive/YYYY/MM/{final_task_name}/code_review_{review_lane}_GNN_N.log`, where `{final_task_name}` is the archived task path, including `{task_group}/` for split work.
- For user-review-resolved PASS, confirm the moved archive contains the resolved `USER_REVIEW.md`, `complete.log`, and the existing archived `plan_*.log` / `code_review_*.log`; do not recreate an active review file only to add a new checklist item.
- For `WARN` or `FAIL`, open `agent-task/{task_name}/code_review_{review_lane}_GNN_N.log`.
- Check every applicable item in `코드리뷰 전용 체크리스트`; leave mutually exclusive verdict items unchecked.
- If any applicable item cannot be checked, finish the missing archive, `complete.log`, task-directory move, follow-up plan/review write, or `USER_REVIEW.md` write first.
- Do not recreate an active review file just to update this checklist; update the archived `code_review_*.log`.
- Only report after the archived review log has the verdict, applicable checked review-only checklist, required next-state files, for `PASS` or user-review-resolved PASS the final task archive move, for `m-*` PASS tasks the completion event metadata, and for unresolved `USER_REVIEW` the filled `USER_REVIEW.md`.
Report exactly one output: follow-up plan pair, `USER_REVIEW.md`, or `complete.log`. Include the relevant paths.
Report Required/Suggested counts, archive names, the final task archive path for `PASS`, the new plan path for normal `WARN`/`FAIL`, the `USER_REVIEW.md` path for user review stops, and any `m-*` runtime completion event metadata.
## Review Dimensions
| Dimension | Check |
|-----------|-------|
| Correctness | Logic, edge cases, concurrency, errors |
| Completeness | Planned implementation/verification items are done; implementation-owned artifact drift is classified and routed without reviewer edits |
| Completeness | All planned checklist items done, including integrated implementation+verification feature items and matching plan/review `구현 체크리스트` completion |
| Test coverage | Required tests present and meaningful |
| API contract | Call sites, compatibility, docs |
| Code quality | No debug prints, dead code, leftover TODOs |
@ -320,24 +416,19 @@ Report exactly one output: follow-up plan pair, `USER_REVIEW.md`, or `complete.l
- Name exact stale symbols or missing tests.
- Do not write vague praise or style opinions without a rule.
- Every dimension gets Pass/Warn/Fail.
- For verification-trust findings, specify deterministic commands, for example `rg --sort path`, and forbid repo-local tool artifacts.
- For follow-up plans about verification trust, specify deterministic commands, for example `rg --sort path`, and forbid repo-local tool artifacts.
## Final Checklist
- Exactly one next-state outcome was selected: a follow-up PLAN/CODE_REVIEW pair, `USER_REVIEW.md`, or `complete.log`.
- `{current_review_archive_name}` exists with the verdict appended and was derived from the archived active review's own route.
- `{current_plan_archive_name}` exists and was derived from the archived active plan's own route.
- `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores local `agent-roadmap/current.md`; generated task artifacts are not ignored by `git check-ignore`.
- `code_review_{review_lane}_GNN_N.log` exists with verdict appended.
- `plan_{build_lane}_GNN_M.log` exists.
- No active `.md` files remain after PASS or user-review-resolved PASS.
- PASS or user-review-resolved PASS: `complete.log` contains the required Finalization metadata, then task directory moved under `agent-task/archive/YYYY/MM/` as the final filesystem mutation with task-group path preserved for split work.
- PASS milestone task group: `m-<milestone-slug>` completion event metadata is prepared for runtime; roadmap was not modified by code-review.
- PASS with `Roadmap Targets`: `complete.log` contains `Roadmap Completion` with Milestone path, Task ids, archived plan/review evidence, and verification evidence.
- PASS without `Roadmap Targets`: `complete.log` omits `Roadmap Completion` and prepared metadata says `roadmap-completion=none`.
- PASS with `Agent UI Completion`: listed agent-ui docs were updated to `구현됨` with code evidence, `validate-agent-ui` passed, and `complete.log` contains `Agent UI Completion`.
- PASS without `Agent UI Completion`: complete.log omits `Agent UI Completion`.
- WARN/FAIL without user-review gate: a different plan model wrote one follow-up pair, the reviewer did not plan or implement, and the pair has an `implementation-ready` or `dependency-waiting` result.
- Follow-up review stubs include the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` and forbid direct user prompts during implementation.
- PASS or user-review-resolved PASS: `complete.log` written from `agent-ops/skills/common/code-review/templates/complete-log-template.md`, then task directory moved under `agent-task/archive/YYYY/MM/` with task-group path preserved for split work.
- PASS milestone task group: `m-<milestone-slug>` completion event metadata was reported for runtime; roadmap was not modified by code-review.
- PASS split: empty active parent `agent-task/{task_group}/` removed after the subtask move; non-empty parent left in place.
- WARN/FAIL without user-review gate: new active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` created with matching headers and matching `구현 체크리스트`; no `complete.log`.
- Follow-up review stubs include the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`.
- USER_REVIEW: `USER_REVIEW.md` exists from template, no active `PLAN-*.md` or `CODE_REVIEW-*.md` remains, and no `complete.log` was written.
- Implementation-requested USER_REVIEW: archived review log preserves the filled `사용자 리뷰 요청` evidence and the generated `USER_REVIEW.md` records the exact linked Milestone decision needed.
- Implementation-requested USER_REVIEW: archived review log preserves the filled `사용자 리뷰 요청` evidence and the generated `USER_REVIEW.md` records the exact user decision needed.
- USER_REVIEW resolved as PASS: archived task contains both resolved `USER_REVIEW.md` and `complete.log`.
- USER_REVIEW resolved to more implementation: `USER_REVIEW.md` was archived to a `RESOLVED`/`REPLAN` `user_review_N.log` that references its archived pair and forbidden identities, a different plan model wrote one follow-up pair from that evidence, and the pair has an `implementation-ready` or `dependency-waiting` result.
- The applicable review-agent-only finalization checklist was completed before reporting.

4
agent-ops/skills/common/code-review/agents/openai.yaml
View file

@ -1,4 +1,4 @@
interface:
display_name: "Code Review"
short_description: "Review and leave the required next artifact"
default_prompt: "Use $code-review to leave exactly one result: a follow-up pair authored by a different Plan model, USER_REVIEW.md, or complete.log."
short_description: "Review and route task loops"
default_prompt: "Use $code-review to review or resolve the active repository task, archive active files, and create complete.log, follow-up plan/review files, or USER_REVIEW.md."

31
agent-ops/skills/common/code-review/templates/complete-log-template.md
View file

@ -4,16 +4,6 @@
{YYYY-MM-DD or ISO-8601}
## Finalization
- origin-task: `agent-task/{task_name}`
- final-archive-path: `agent-task/archive/{YYYY}/{MM}/{final_task_name}`
- task-group: `{task_group}`
- milestone-slug: `{milestone-slug or none}`
- archived-plan: `{final archived plan log path}`
- archived-review: `{final archived review log path}`
- roadmap-completion: `{Task ids or none}`
## 요약
{one-line task summary, loop count, and final verdict; include user-review resolution if applicable}
@ -23,7 +13,7 @@
| Plan | Review | Verdict | 메모 |
|------|--------|---------|------|
| `plan_{build_lane}_GNN_N.log` | `code_review_{review_lane}_GNN_N.log` | PASS/WARN/FAIL | {main outcome or follow-up reason} |
| `USER_REVIEW.md` | linked Milestone decision | PASS/RESOLVED | {only when a user-review stop was resolved as the terminal completion path; remove this row otherwise} |
| `USER_REVIEW.md` | user decision | PASS/RESOLVED | {only when a user-review stop was resolved as the terminal completion path; remove this row otherwise} |
## 구현/정리 내용
@ -33,25 +23,6 @@
- `{command}` - {PASS/FAIL/BLOCKED}; {actual output summary or saved output path}
## Roadmap Completion
{optional; include only when archived plan/review had Roadmap Targets. Remove this entire section when there are no Roadmap Targets.}
- Milestone: `{agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md}`
- Milestone link: [Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- Completed task ids:
- `{task-id}`: PASS; evidence=`{archived-plan-log}`, `{archived-review-log}`; verification=`{command or saved output path}`
- Not completed task ids: 없음
## Agent UI Completion
{optional; include only when archived review had Agent UI Completion. Remove this entire section when there is no Agent UI Completion.}
- Agent UI docs:
- `{agent-ui/definition/views/<view-id>/index.md}`: `구현됨`; code evidence=`{code path}`; implementation verification=`{command or output path}`; validation=`{validate-agent-ui result or output path}`
- Status updates: 완료
- Remaining agent-ui issues: 없음
## 잔여 Nit
- 없음

24
agent-ops/skills/common/code-review/templates/user-review-template.md
View file

@ -10,11 +10,10 @@ USER_REVIEW
## 사유
- 유형: milestone-lock
- 연결 대상: {agent-roadmap/phase/<phase>/milestones/<milestone>.md}
- 유형: {loop-limit, environment-blocked, or implementation-blocked}
- 현재 리뷰 회차: {review-number}
- 최종 판정: {WARN or FAIL}
- 요약: {Milestone 구현 잠금 항목이 실구현을 차단한 이유}
- 요약: {why automatic follow-up stopped}
## 루프 이력
@ -30,23 +29,24 @@ USER_REVIEW
- 현재 archive review: `{current-archived-review-log}`
- 검증 명령: `{command or 없음}`
- 실제 출력: {stdout/stderr excerpt or saved output path}
- 차단 판단 근거: {연결 대상의 Milestone 결정 필요 항목과 일치하는 근거}
- 차단 판단 근거: {why this needs user decision or is outside repo-fixable scope, or 없음}
## 연결 결정 필요
## 사용자 결정 필요
- [ ] {Milestone `구현 잠금 > 결정 필요`에 기록된 결정 항목}
- [ ] 자동 follow-up plan/review를 계속 진행한다.
- [ ] 계획을 재작성한다.
- [ ] 테스트 환경, secret, 외부 서비스, SDK, 장비 조건을 준비한 뒤 재시도한다.
- [ ] 작업 범위를 줄이거나 보류/폐기한다.
## 재개 조건
- {위 결정이 Milestone 구현 잠금에 반영되고, 필요한 경우 해당 USER_REVIEW.md가 user_review_N.log로 해결되어야 한다}
- {what must be true before the next plan/review loop should start}
## 다음 실행 힌트
- {resolve-review 또는 update-roadmap으로 반영할 대상 경로와 후속 plan/review 재개 조건}
- {suggested command, task path, or user decision needed to resume}
## 종료 규칙
- 이 해소는 archived review에 기록된 같은 Review model identity의 재시도만 수행한다.
- 연결 결정과 evidence가 이 stop state를 완료/PASS로 해소하면 `USER_REVIEW.md`를 해소 상태로 갱신하고, `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
- 새 구현이 필요하면 `## 상태` 값을 `RESOLVED`로 바꾸고 단일 `## 해소 결과`에 `결과: REPLAN`, `해소 일시`, `결정`, `Evidence`, `Archived plan`, `Archived review`, `Forbidden implementation model`, `Forbidden review model`을 기록한 뒤 `user_review_N.log`로 아카이브한다. 이미 `RESOLVED`이면 결과나 timestamp를 다시 쓰지 않고 그대로 재개한다.
- 완료/PASS 해소이면 `## 상태` 값을 `RESOLVED`로 바꾸고 단일 `## 해소 결과`에 `결과: COMPLETE`, `해소 일시`, `Final verdict`, `결정`, `Evidence`, `Archived plan`, `Archived review`를 기록한다. 이미 `RESOLVED`이면 기존 `해소 일시`를 재사용한다. 이 파일은 rename하지 않고 `complete.log`와 함께 최종 task archive에 보존한다.
- 사용자가 이 stop state를 완료/PASS로 해소하면 `USER_REVIEW.md`를 해소 상태로 갱신하고, `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
- 새 구현이 필요하면 `plan` 스킬이 `USER_REVIEW.md`를 `user_review_N.log`로 아카이브한 뒤 새 `PLAN-*-G??.md` / `CODE_REVIEW-*-G??.md`를 작성한다.

134
agent-ops/skills/common/complete-milestone/SKILL.md
View file

@ -1,134 +0,0 @@
---
name: complete-milestone
version: 1.1.0
description: "마일스톤 완료해도 될지 검토, 현 마일스톤 종료 검토, 현재 마일스톤 닫고 다음 마일스톤 지정, 검토중 Milestone 코드레벨 종료 감사 요청에 사용한다. 코드/테스트/계약/evidence를 점검하고 작은 보완은 처리하거나 큰 보완은 plan으로 넘기며, agent-spec이 있으면 update-spec을 필수 gate로 수행한 뒤 update-roadmap으로 완료/archive와 다음 Milestone 지정을 처리한다."
---
# complete-milestone
## 목적
`[검토중]` 또는 완료 후보 Milestone을 코드레벨에서 종료해도 되는지 감사하고, 종료 가능할 때 spec sync와 roadmap 완료/archive까지 이어지는 오케스트레이션을 수행한다.
`update-spec`과 `update-roadmap`의 책임을 합치지 않고, 이 스킬이 완료 workflow의 순서와 gate를 관리한다.
## 언제 호출할지
- 사용자가 "마일스톤 완료해도 될지 검토해봐"라고 요청할 때
- 사용자가 "현 마일스톤 종료 검토해", "현재 마일스톤 닫고 다음 마일스톤 지정해"라고 요청할 때
- `[검토중]` Milestone의 완료 리뷰 통과, archive, 다음 Milestone current 지정 여부를 코드레벨 evidence로 확인해야 할 때
- Milestone 종료 시점에 `agent-spec` 갱신이 함께 필요할 때
## 입력
- `target-milestone`: 종료 검토할 Milestone 경로, 이름, slug. 없으면 `agent-roadmap/current.md`의 활성 Milestone 단일 후보를 사용한다. (선택)
- `next-milestone`: 종료 후 `current.md`에 둘 다음 Milestone 후보. 없으면 Phase 흐름에서 자동 후보를 찾되 모호하면 보고한다. (선택)
- `mode`: `check-only` 또는 `close`. 기본값은 `close`다. (선택)
- `evidence`: 완료 판단에 사용할 complete.log, 테스트 결과, 사용자 설명, PR/커밋 등. (선택)
## 먼저 확인할 것
- [ ] `agent-roadmap/current.md`와 대상 활성 Milestone, 대상 Phase `PHASE.md`를 읽는다.
- [ ] `agent-roadmap/priority-queue.md`가 있으면 종료 후 다음 후보와 archive 제거 대상 확인을 위해 읽는다.
- [ ] 대상 Milestone의 `상태`, `기능`, `구현 잠금`, `완료 리뷰`, `작업 컨텍스트`, SDD gate를 확인한다.
- [ ] 완료 근거 동기화가 필요하면 `sync-milestone-workstate` 절차를 확인한다.
- [ ] 종료/archive가 가능하면 `update-roadmap` 절차를 확인한다.
- [ ] `agent-spec/`가 있으면 `agent-ops/rules/common/rules-agent-spec.md`와 `update-spec` 절차를 확인한다.
- [ ] 코드, 계약, 테스트에 닿는 범위는 project/domain/test/contract 규칙을 따른다.
## 실행 절차
1. **대상 Milestone 확정**
- `target-milestone`이 있으면 활성 Milestone에서 정확히 하나를 찾는다.
- 없으면 `agent-roadmap/current.md`의 활성 Milestone 단일 후보를 사용한다.
- 대상이 archive 경로이거나 둘 이상이면 수정하지 않고 target 불명확으로 보고한다.
2. **완료 후보 상태 확인**
- 대상 Milestone이 `[검토중]`이면 종료 감사로 진행한다.
- `[진행중]` 또는 `[계획]`이면 `sync-milestone-workstate` 기준으로 기능 Task/evidence를 동기화할 수 있는지 먼저 확인한다. 동기화 후 `[검토중]` 조건을 충족하지 못하면 종료 감사로 진행하지 않는다.
- `[스케치]`, `[보류]`, `[폐기]`, `[완료]`이면 일반 종료 감사를 진행하지 않고 상태 불일치를 보고한다.
- `구현 잠금`이 남아 있거나 미완료 `결정 필요`가 있으면 archive하지 않는다.
3. **코드레벨 종료 감사**
- Milestone `기능` Task와 검증 문구, `완료 리뷰`, complete.log, SDD Evidence Map, 관련 코드/계약/테스트를 비교한다.
- `agent-task/archive/**`는 같은 `m-<milestone-slug>` complete.log 후보처럼 규칙상 허용된 범위만 좁게 읽는다.
- 코드/계약 변경에 닿으면 관련 domain rule과 `agent-contract/index.md` 라우팅을 따른다.
- 필요한 검증 명령은 `agent-test/<env>/rules.md`와 관련 profile을 따른다. 환경 미지정은 local로 본다.
4. **보완 분기**
- 작은 문서/코드/테스트 보완으로 바로 해결 가능한 이슈는 직접 수정하고 검증한다.
- Milestone 범위 안의 큰 구현 보완이 필요하면 `plan`을 작성하고 종료를 중단한다.
- 제품/범위/우선순위/책임 경계 결정이 필요하면 Milestone `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리하고 종료를 중단한다.
- 보완이 발생하면 Milestone 완료 리뷰를 `보완 필요`로 남기고 `[완료]` 전환이나 archive를 하지 않는다.
5. **Spec Sync Gate**
- `mode=check-only`이고 `agent-spec/`가 있으면 `update-spec mode=check-only`로 갱신 필요 여부만 확인한다.
- `agent-spec/`가 없으면 `Spec sync: skipped-no-agent-spec`으로 기록하고 종료 흐름을 계속할 수 있다.
- `agent-spec/`가 있고 `mode=close`이면 `update-spec`을 필수로 수행한다.
- 관련 spec이 없고 Milestone 결과가 현재 구현 지도에 영향을 주면 `create-spec` 필요로 보고하고 종료를 중단한다.
- 결과는 반드시 `Spec updated`, `Spec update not needed`, `create-spec needed`, `Spec blocked`, `skipped-no-agent-spec` 중 하나로 정리한다.
- `Spec blocked` 또는 `create-spec needed`이면 Milestone을 `[완료]`로 전환하거나 archive하지 않는다.
- `Spec updated` 또는 `Spec update not needed`이면 Milestone 완료 리뷰에 `Spec sync` 결과와 spec 문서 링크 또는 사유를 남긴다.
6. **Milestone 완료와 archive**
- `mode=check-only`이면 여기서 쓰지 않고 종료 가능 여부만 보고한다.
- 모든 기능 Task, 검증, 구현 잠금, SDD gate, code audit, spec sync gate가 충족되면 `update-roadmap` archive 흐름으로 Milestone을 `[완료]`로 전환하고 archive한다.
- `.agent-roadmap-sync/locks.yaml`이 있으면 `update-roadmap`의 workspace lock 검사/동기화 규칙을 따른다.
- Phase `PHASE.md`에는 archive 링크와 짧은 요약을 남긴다.
- `priority-queue.md`가 있으면 완료/archive된 Milestone 항목을 제거하도록 `update-roadmap` archive 흐름에 포함한다.
- `agent-roadmap/current.md`에서 완료 Milestone을 제거한다.
7. **다음 Milestone 지정**
- `next-milestone`이 있으면 활성 Milestone에서 정확히 하나인지 확인하고 `current.md`에 반영한다.
- 없고 `priority-queue.md`가 있으면 큐의 위에서 아래 순서 중 완료/archive 대상이 아니고 `[폐기]`가 아닌 첫 활성 Milestone을 다음 후보로 찾는다.
- `priority-queue.md`가 없으면 같은 Phase의 Milestone 흐름에서 완료/폐기/archive가 아닌 다음 후보를 찾는다.
- 후보가 없거나 둘 이상이면 자동 지정하지 않고 후보와 이유를 보고한다.
- 다음 후보가 `[스케치]`이면 구현 대상이 아니라 구체화 대상임을 보고한다.
8. **결과 보고**
- 종료 가능 여부, 수정/생성한 파일, 실행 검증, spec sync 결과, roadmap archive 결과, 다음 Milestone을 보고한다.
## 실행 결과 검증
- [ ] 대상 Milestone이 활성 경로에서 정확히 하나로 확정되었는가
- [ ] Milestone 상태, 기능 Task, 구현 잠금, 완료 리뷰, SDD gate를 확인했는가
- [ ] 코드/계약/테스트 evidence를 확인했거나 범위 불명확 사유를 보고했는가
- [ ] 작은 보완은 검증까지 수행하고, 큰 보완은 plan으로 넘겼는가
- [ ] `agent-spec/`가 있으면 `update-spec` 결과를 확인하고 완료 진행 가능 상태가 `Spec updated` 또는 `Spec update not needed`인지 판단했는가
- [ ] `Spec blocked` 또는 `create-spec needed` 상태에서 Milestone 완료/archive를 하지 않았는가
- [ ] `update-roadmap` 완료/archive 규칙과 workspace lock 규칙을 따랐는가
- [ ] `priority-queue.md`가 있으면 완료/archive된 Milestone이 제거되었고 다음 후보 판단에 큐 순서가 반영되었는가
- [ ] 완료 Milestone이 `current.md`에 남아 있지 않은가
- [ ] 다음 Milestone 지정이 모호하면 자동 선택하지 않았는가
- [ ] `git diff --check`를 실행했는가
- 검증 실패 시: archive 이동을 하지 않고 실패 사유와 필요한 후속 작업을 보고한다.
## 출력 형식
```markdown
## Milestone 종료 검토 결과
- 대상 Milestone: [<title>](agent-roadmap/phase/<phase>/milestones/<milestone>.md)
- 판정: <종료 완료 | 종료 가능-check-only | 보완 필요 | plan 작성 | 차단>
- 코드레벨 감사: <통과 | 보완 내용 | 차단 사유>
- 검증:
- `<command>` - <PASS | FAIL | BLOCKED>; <요약>
- Spec sync: <updated | not-needed | create-spec needed | blocked | skipped-no-agent-spec>
- <[spec](agent-spec/<area>/<spec-id>.md) | 사유>
- Roadmap: <archive 완료 | 변경 없음 | 차단>
- 다음 Milestone: <[title](agent-roadmap/phase/<phase>/milestones/<next>.md) | 미지정: 사유>
- 수정 파일:
- <없음 | [path](path)>
## TODO 항목
- <남은 차단 항목 또는 없음>
```
## 금지 사항
- `update-spec`과 `update-roadmap`의 책임을 이 스킬 본문에 합쳐서 재정의하지 않는다.
- `Spec blocked` 또는 `create-spec needed`인데 Milestone을 `[완료]`로 전환하거나 archive하지 않는다.
- 큰 구현 보완을 종료 검토 중 임의로 처리하지 않는다. `plan`으로 넘긴다.
- archive 전체를 일반 탐색하지 않는다.
- 구현 잠금이나 미해결 SDD 사용자 리뷰가 남은 Milestone을 완료 처리하지 않는다.
- 다음 Milestone 후보가 모호한데 자동으로 선택하지 않는다.

180
agent-ops/skills/common/create-agent-ui/SKILL.md
View file

@ -1,180 +0,0 @@
---
name: create-agent-ui
version: 1.1.0
description: 프로젝트 코드 또는 문서 근거를 분석해 agent-ui 기본 스캐폴드와 최초 코드 동기화 기준선을 생성하는 스킬
---
# create-agent-ui
## 목적
프로젝트의 기존 UI 코드나 컨셉 문서를 근거로 `agent-ui/` 기본 구조와 UI 정의 초안을 생성한다.
ops/dev UI를 1차 대상으로 하며, 생성 결과를 최초 agent-ui 기준선으로 보고 `.sync-state.json`을 만든다.
## 언제 호출할지
- 사용자가 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 코드 후보와 컨셉 문서 후보를 모두 가볍게 확인한다.
- [ ] baseline commit/push를 위해 현재 git status와 HEAD를 확인한다.
- [ ] unrelated dirty worktree가 있으면 baseline commit 전에 범위를 보고하고, agent-ui 생성 파일만 stage한다.
## 실행 절차
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: 구현됨`
- 문서 근거만 있으면 `status: 계획`
- 명시 입력만 있고 근거가 부족하면 `status: 가정`
- 판단 불가하면 `status: 불명확`과 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. **정합성 검증과 baseline 기록**
- 생성 직후 `validate-agent-ui`를 실행해 scaffold와 문서 간 정합성을 확인하고 자동 보정한다.
- `agent-ui/.sync-state.json`에 기록할 baseline 내용을 준비한다.
- `baseline_mode`는 선택된 `source-mode`로 둔다.
- `code-first`, `concept-first`, `blank` 모두 생성된 agent-ui를 최초 기준선으로 본다.
- baseline commit은 두 단계로 남긴다.
- 먼저 `.sync-state.json`을 제외한 agent-ui 생성/보정 파일을 commit한다.
- 그 commit hash를 새 `agent-ui/.sync-state.json`의 `last_synced_head`에 기록한 뒤 별도 commit한다.
- commit message는 예를 들어 `docs(agent-ui): create baseline`과 `sync: record agent-ui baseline`처럼 목적이 분리되게 쓴다.
- 두 commit을 push한다.
- USER_REVIEW가 생성되어도 생성 baseline은 남길 수 있다. 단, 이후 `sync-agent-ui`는 관련 USER_REVIEW가 해결될 때까지 실행하지 않는다.
9. **결과 보고**
- 선택된 `source-mode`
- 읽은 근거 파일과 생성에 사용한 evidence
- 생성한 파일
- 적용한 frontmatter schema
- 생성한 view/component의 status
- USER_REVIEW 생성 여부
- `.sync-state.json` 생성 여부와 baseline commit hash
- baseline commit/push 결과
- 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`가 있는가
- [ ] 구현 근거 없는 항목을 `구현됨`으로 표시하지 않았는가
- [ ] visual source가 없는 view에 빈 `frame/views/<view-id>/index.md`를 만들지 않았는가
- [ ] 코드/문서 충돌이나 UI 의도 판단이 필요한 항목이 USER_REVIEW에 남았는가
- [ ] 같은 레벨에 `<name>.md`와 `<name>/`가 함께 생기지 않았는가
- [ ] archive 본문 파일을 불필요하게 생성하지 않았는가
- [ ] `validate-agent-ui` 결과가 PASS 또는 자동 보정 완료 WARN으로 보고되었는가
- [ ] `.sync-state.json`이 생성되었고 `last_synced_head`가 baseline commit을 가리키는가
- [ ] baseline commit/push가 완료되었는가
- [ ] unrelated dirty file이 baseline commit에 포함되지 않았는가
- 검증 실패 시: 누락된 scaffold만 보완하고 기존 문서를 덮어쓰지 않는다.
## 출력 형식
```md
## 생성 완료
- 루트: agent-ui/
- source-mode: <code-first|concept-first|blank>
- evidence: <주요 근거 파일 목록>
- 생성 파일: <목록>
- frontmatter schema: <적용/부분 적용/없음>
- views: <view-id=status 목록 또는 없음>
- components: <component-id=status 목록 또는 없음>
- USER_REVIEW: <생성/없음>
- sync state: <생성/없음, last_synced_head>
- baseline commit/push: <완료/실패/생략 사유>
- 확인 필요: <항목 또는 없음>
- 후속 권장: <필요 시 sync-agent-ui 또는 없음>
```
## 금지 사항
- 기존 `agent-ui/` 문서를 덮어쓰지 않는다.
- `.excalidraw` 파일을 현재 UI source of truth로 만들지 않는다.
- 코드나 문서 근거 없이 화면 의도를 확정하지 않는다.
- 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
- product UI 전용 레이어를 요청 없이 추가하지 않는다.
- `definition/archive/**`나 `archive/user-review/**`에 현재 기준 문서를 만들지 않는다.
- baseline commit 없이 `.sync-state.json`의 `last_synced_head`를 추정하지 않는다.

121
agent-ops/skills/common/create-contract/SKILL.md
View file

@ -1,121 +0,0 @@
---
name: create-contract
version: 1.0.0
description: agent-contract 구조와 inner/outer 계약 문서를 생성한다. 계약 생성해, 프로젝트 계약 생성해, contract 생성, agent-contract 생성, inner/outer 계약 생성 요청에서 사용한다.
---
# create-contract
## 목적
프로젝트에 계약 관리가 필요해진 시점에 `agent-contract/` 구조를 생성하고, 흩어진 문서와 코드에서 확인한 계약을 `inner/outer` 기준으로 정리한다.
계약 문서는 schema 원본을 복제하지 않고, agent가 읽을 수 있는 라우팅, 원본 경로, 필드 의미, 변경 규칙, 검증 포인터를 한 곳에 모은다.
## 언제 호출할지
- 사용자가 계약 생성, 프로젝트 계약 생성, contract 생성, agent-contract 생성을 요청할 때
- API, runtime 호출, wire protocol, event/config schema 같은 계약을 처음 문서화할 때
- 프로젝트에 `agent-contract/`가 없고, 둘 이상의 프로젝트/프로세스/앱/도메인이 맞춰야 하는 요청/응답 경계가 확인될 때
- 기존 README/docs/rules/code에 흩어진 계약 설명을 새 계약 구조로 모아야 할 때
## 입력
- `contract-id`: 계약 식별자, kebab-case 또는 dotted id (선택, 없으면 분석으로 후보 산출)
- `boundary`: `inner` 또는 `outer` (선택, 없으면 실제 소비자와 경계로 판정)
- `scope`: 계약 범위 요약. 예: public HTTP API, worker-runtime protocol, app-server wire (선택, 없으면 코드/문서에서 산출)
- `canonical-path`: proto/OpenAPI/config/code 등 schema 원본 경로 (선택, 없으면 분석으로 찾음)
- `trigger-conditions`: 계약 문서를 읽어야 하는 조건 목록 (선택)
## 분류 기준
- `outer`: 프로젝트 바깥 caller나 다른 프로젝트가 직접 맞춰야 하는 계약이다. 예: 공개 HTTP API, webhook, 외부 SDK, 외부 agent handoff.
- `inner`: 같은 프로젝트 안이어도 프로세스, 앱, 도메인, runtime 경계를 넘는 계약이다. 예: controller-worker proto, service-service wire, app-server WebSocket, runtime request/event/config schema.
- 제외: 한 패키지 내부 private interface, 코드만 보면 충분한 DTO, 안정화되지 않은 실험 구조, 단일 구현 내부 helper.
## 먼저 확인할 것
- [ ] `agent-contract/` 존재 여부를 확인한다.
- [ ] `agent-contract/index.md`가 있으면 읽고 기존 구조와 중복 id를 확인한다.
- [ ] 요청 범위와 관련된 코드, proto, config, README/docs/rules를 읽어 원본 경로와 흩어진 계약 설명을 찾는다.
- [ ] 계약 원문을 이미 docs/README/rules에 길게 복제하고 있는지 확인한다.
## 실행 절차
1. **필요성 판정**
- 둘 이상의 프로젝트/프로세스/앱/도메인이 맞춰야 하는 안정 경계인지 확인한다.
- 단일 패키지 내부 구현이면 계약 문서를 만들지 않고 이유를 보고한다.
- 단건 `contract-id`가 없으면 코드와 문서에서 계약 후보를 수집하고, 안정 경계가 확인된 후보만 생성한다.
- 후보는 있지만 boundary나 원본 경로가 불명확하면 문서를 억지로 만들지 않고 `확인 필요`로 보고한다.
2. **구조 생성**
- `agent-contract/index.md`가 없으면 생성한다.
- `agent-contract/inner/`와 `agent-contract/outer/`가 없으면 생성한다.
- legacy `provided/consumed/`가 있으면 덮어쓰지 않고, 이번 생성 결과와 충돌하는지 보고한다.
3. **코드와 문서 분석**
- 관련 schema 원본을 먼저 찾는다. 우선순위는 proto/OpenAPI/schema 파일, config struct, public DTO/interface, handler/parser, 테스트 fixture 순서다.
- README/docs/rules에 흩어진 계약 설명을 찾고, 계약 문서에 필요한 내용만 추린다.
- 필드 의미는 코드와 테스트에서 확인한 것만 쓴다. 추측은 `확인 필요`로 남긴다.
4. **계약 문서 작성**
- 경로는 `agent-contract/<inner|outer>/<contract-name>.md`로 둔다.
- 여러 계약을 생성해야 하면 각 문서는 독립된 경계 단위로 나누고, 공통 설명은 index가 아니라 각 계약의 원본 경로 포인터로 해결한다.
- 문서는 짧게 유지하고 다음 항목을 포함한다.
- 계약 메타: id, boundary, 원본 경로, status(필요한 경우)
- 읽는 조건
- 범위와 비범위
- 최소 요청/응답 또는 message/event 형태
- 필드 의미와 금지 사항
- 변경 시 확인할 코드/테스트
- 원본 schema 전체를 복제하지 않는다. 긴 schema는 원본 경로와 핵심 필드 의미만 둔다.
5. **index 갱신**
- `Outer Contracts`와 `Inner Contracts` 섹션을 둔다.
- outer/inner 표는 `id`, `읽는 조건`, `원본 경로`, `path`를 둔다.
- 매칭 조건은 agent가 검색/판단할 수 있는 API 이름, message 이름, field 이름, runtime 이름, protocol 이름을 포함한다.
- 프로젝트 전용 path trigger는 공통 rule이 아니라 `agent-contract/index.md`의 `읽는 조건`/`원본 경로` 또는 project/domain rule 포인터로 둔다.
6. **흩어진 문서 정리**
- README/docs/rules에 계약 본문이 중복되어 있으면 원문 경로 포인터로 줄인다.
- domain rule에는 소유권, 경계, 금지 사항만 남기고 상세 schema는 계약 문서 또는 원본 경로를 가리킨다.
- common rule에는 특정 프로젝트 경로, 계약 id, API 이름을 추가하지 않는다. common rule은 `agent-contract/index.md` 조건부 진입까지만 담당한다.
- 사람용 최신 가이드가 필요한 README 문구는 유지하되 계약 원문과 충돌하지 않게 축소한다.
7. **결과 보고**
- 생성한 index와 계약 문서
- boundary 판정 근거
- 원본 경로
- 중복 제거 또는 포인터화한 문서
- 확인 필요 항목
## 실행 결과 검증
- [ ] `agent-contract/index.md`가 생성되고 inner/outer 라우팅 표를 포함하는가
- [ ] 계약 문서가 `agent-contract/inner/` 또는 `agent-contract/outer/` 아래에 있는가
- [ ] 계약 id가 index와 문서 메타에서 일치하는가
- [ ] 원본 경로가 실제 존재하거나 외부 원본으로 명확히 적혀 있는가
- [ ] README/docs/rules에 계약 본문이 중복 복제되지 않고 포인터만 남았는가
- [ ] 코드/proto/config/test 분석 없이 계약을 추정하지 않았는가
- 검증 실패 시: 누락된 index, 문서 메타, 포인터, 원본 경로만 보완한다.
## 출력 형식
```md
## 계약 생성 완료
- index: agent-contract/index.md
- contracts: agent-contract/<inner|outer>/<contract-name>.md
- boundary: <inner|outer> (<근거>)
- 원본 경로: <path 또는 외부 원본>
- pointers: <갱신한 README/docs/rules 경로 또는 없음>
- 확인 필요: <항목 또는 없음>
```
## 금지 사항
- 모든 내부 interface를 계약 문서로 만들지 않는다.
- 원본 schema 전체를 계약 문서에 장황하게 복제하지 않는다.
- 코드/proto/config/test 확인 없이 필드 의미를 단정하지 않는다.
- README/docs/rules에 계약 본문을 계속 중복 유지하지 않는다.
- 프로젝트 전용 path trigger를 common rule에 넣지 않는다.
- legacy `provided/consumed/` 구조가 있어도 사용자 요청 없이 대량 이동하지 않는다.

93
agent-ops/skills/common/create-handoff/SKILL.md
View file

@ -1,93 +0,0 @@
---
name: create-handoff
version: 1.0.0
description: 작업을 다른 세션이나 다른 에이전트가 이어받을 수 있도록 핸즈오프 기록을 남기는 공통 스킬. "핸즈오프 남겨", "인수인계 작성", "다른 세션에서 이어가게 정리", "작업을 이어받도록 기록" 같은 요청에 사용한다.
---
# Create Handoff
## 목적
현재 작업 상태를 중단 없이 이어받을 수 있도록 짧고 검증 가능한 핸즈오프 기록을 남긴다.
핸즈오프는 새 구현 계획이나 코드 변경을 시작하는 절차가 아니라, 현재 상태와 다음 진입점을 보존하는 절차다.
## 언제 호출할지
- 사용자가 작업을 다른 세션, 다른 에이전트, 또는 이후 자기 자신이 이어가게 정리해 달라고 할 때
- 긴 작업 중 현재 판단, 변경 파일, 남은 검증, 차단 사항을 지속 가능한 문서에 남겨야 할 때
- 구현을 계속하지 않고 현재 위치만 안전하게 넘겨야 할 때
- 실패한 검증이나 외부 환경 상태를 다음 세션이 오해하지 않도록 남겨야 할 때
## 입력
- `handoff-request`: 사용자가 남기라고 한 핸즈오프 요청 문장 (필수)
- `target`: 현재 작업 대상 Phase, Milestone, plan, review, task group, issue, PR, 파일 경로 등 (선택)
- `evidence`: 이번 세션에서 확인한 명령, 테스트, 로그, 외부 상태, 사용자 결정 (선택)
## 먼저 확인할 것
- [ ] 현재 작업 대상이 명시되어 있으면 해당 활성 문서나 파일을 확인한다.
- [ ] 대상이 없으면 로컬 current, 활성 PLAN/CODE_REVIEW/USER_REVIEW, git diff, 최근 대화 맥락 중 가장 좁은 충분한 대상으로 정한다.
- [ ] 기존 핸즈오프 섹션이나 `HANDOFF.md`가 있으면 새 위치를 만들기 전에 갱신 후보로 본다.
- [ ] archive 경로는 일반 작업에서 읽지 않는다. 사용자가 archive 확인을 명시했거나 활성 문서가 특정 archive evidence를 가리킬 때만 필요한 파일을 좁게 읽는다.
- [ ] secret, token, private endpoint 원문, 서명값, 개인 credential은 핸즈오프에 기록하지 않는다.
## 실행 절차
1. **상태 수집**
- `git status --short`로 변경 파일과 untracked 파일을 확인한다.
- 필요한 경우 대상 파일의 diff 또는 관련 문서를 읽어 이번 세션에서 실제로 바뀐 내용과 바뀌지 않은 내용을 분리한다.
- 실행 중인 서버, 원격 runner, 외부 provider 같은 live 상태가 handoff에 영향을 주면 secret 없이 요약한다.
2. **기록 위치 선택**
- 활성 Milestone이 작업의 장기 기준이면 해당 Milestone의 `작업 컨텍스트` 아래에 `핸즈오프(<YYYY-MM-DD>)` 항목을 추가하거나 갱신한다.
- 활성 plan/review/task group이 작업의 실행 기준이면 그 디렉터리의 기존 `PLAN-*.md`, `CODE_REVIEW-*.md`, `USER_REVIEW.md`, 또는 `HANDOFF.md` 중 가장 직접적인 파일에 남긴다.
- 적절한 활성 문서가 없으면 새 파일을 만들기보다 최종 답변에만 남길지 판단하고, 지속 기록이 필요하면 가장 좁은 활성 작업 디렉터리 아래 `HANDOFF.md`를 만든다.
- 같은 내용을 여러 곳에 중복 기록하지 않는다. 필요하면 한 곳에 기록하고 다른 문서에는 짧은 링크만 남긴다.
3. **핸즈오프 작성**
- 현재 타겟과 다음 세션의 첫 진입 파일을 적는다.
- 이번 세션에서 실제로 한 일과 하지 않은 일을 분리한다.
- 남은 작업을 실행 순서로 적되, 구현 세부 계획으로 과하게 확장하지 않는다.
- 검증한 명령과 결과, 생략한 검증과 사유를 남긴다.
- dirty worktree, untracked 파일, 원격 환경, 외부 provider 상태처럼 다음 세션이 오해하기 쉬운 조건을 남긴다.
- 사용자 결정이나 명시 금지 사항을 그대로 보존한다.
4. **검증**
- 수정한 Markdown이나 text 파일에 대해 `git diff --check`를 실행한다.
- 새 `HANDOFF.md`를 만들었다면 경로가 active 작업 범위 안인지 확인한다.
- 핸즈오프가 완료/검토중/통과 같은 상태 전환을 암시하지 않는지 확인한다.
5. **결과 보고**
- 핸즈오프를 남긴 경로를 보고한다.
- 다음 세션이 바로 열어야 할 파일 1~3개를 보고한다.
- 검증 명령과 결과를 보고한다.
## 실행 결과 검증
- [ ] 핸즈오프가 지속 가능한 활성 문서나 가장 좁은 작업 디렉터리에 남아 있다.
- [ ] 현재 타겟, 실제 변경, 남은 작업, 검증 상태, 주의사항이 구분되어 있다.
- [ ] secret 또는 credential 원문이 기록되지 않았다.
- [ ] archive 문서를 불필요하게 읽거나 최신 형식으로 재작성하지 않았다.
- [ ] `git diff --check`가 통과했다.
- 검증 실패 시: 핸즈오프 문서만 보완하고, 본 작업 구현이나 상태 전환은 진행하지 않는다.
## 출력 형식
```markdown
## 핸즈오프 완료
- 위치: `<handoff-path>`
- 현재 타겟: `<target>`
- 다음 진입점: `<file-or-command>`
- 검증: `<command>` PASS
- 남은 주의: `<요약 또는 없음>`
```
## 금지 사항
- 핸즈오프 요청만 받았는데 새 구현, 테스트 보강, 리팩터링, 원격 배포를 시작하지 않는다.
- evidence 없이 완료, 검토중, PASS, archive 같은 상태 전환을 하지 않는다.
- secret, token, private signing key, password, 원문 credential을 기록하지 않는다.
- 여러 문서에 같은 핸즈오프 전문을 중복 작성하지 않는다.
- 사용자 또는 다른 에이전트가 만든 unrelated 변경을 되돌리지 않는다.

4
agent-ops/skills/common/create-readme/SKILL.md
View file

@ -76,7 +76,7 @@ README는 프로젝트 특성에 맞게 필요한 섹션만 사용하되, 기본
- README 상단에는 프로젝트가 무엇을 해결하는지와 현재 사용할 수 있는 범위를 먼저 쓴다.
- AI가 작업을 이어받을 때 필요한 경로, 명령, 검증 방법, 주요 문서를 명확한 제목과 표로 정리한다.
- `agent-ops/`가 있으면 규칙, 로드맵, 스킬 문서를 참고 문서나 작업 맥락에 연결한다.
- 로컬 `agent-roadmap/current.md`가 있으면 README에 현재 작업 위치를 복사하지 말고, 로드맵을 확인할 문서 경로만 적는다.
- `agent-roadmap/current.md`가 있으면 README에 현재 작업 위치를 복사하지 말고, 로드맵을 확인할 문서 경로만 적는다.
- README는 제품 소개 문서이면서 작업 진입점이다. 마케팅 문구보다 실행 가능한 정보와 프로젝트 경계를 우선한다.
- README의 자연어 설명은 한국어 중심으로 작성한다.
- 단, README, API, CLI, SDK, runtime, build, test, lint, deploy, workflow, migration, integration처럼 개발자가 흔히 쓰는 영어 표현과 제품명, 기술명, 패키지명, 명령, 경로, 코드 식별자는 자연스럽게 영어로 유지한다.
@ -88,7 +88,7 @@ README는 프로젝트 특성에 맞게 필요한 섹션만 사용하되, 기본
- [ ] 루트 `README.md` 존재 여부와 기존 내용 확인
- [ ] `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, `docker-compose.yml` 등 실행/검증 명령 근거 확인
- [ ] `agent-ops/rules/project/rules.md`가 있으면 프로젝트 개요, 기술 스택, 도메인 매핑 확인
- [ ] `agent-roadmap/ROADMAP.md` 또는 로컬 `agent-roadmap/current.md`가 있으면 제품 방향과 활성 Milestone 문서 경로만 확인
- [ ] `agent-roadmap/ROADMAP.md` 또는 `agent-roadmap/current.md`가 있으면 제품 방향과 활성 Milestone 문서 경로만 확인
- [ ] 주요 소스 디렉터리와 테스트 디렉터리를 `rg --files`로 가볍게 확인
## 실행 절차

108
agent-ops/skills/common/create-roadmap/SKILL.md
View file

@ -1,16 +1,15 @@
---
name: create-roadmap
version: 1.19.0
description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, 전역 priority-queue.md 실행 순서 문서, 로컬 current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하고, agent-ui 코드 동기화 Milestone의 완료 리뷰 상태 반영 항목을 포함하는 공통 스킬
version: 1.15.0
description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하는 공통 스킬
---
# 로드맵 생성
## 목적
`agent-roadmap/` 하위에 `Roadmap -> priority-queue -> Phase -> Milestone` 기반 한국어 로드맵 구조를 처음 생성한다.
전체 로드맵은 전체 방향과 Phase index만 담당하고, 일반 작업에서는 브랜치별 로컬 `current.md`의 활성 Phase/Milestone 링크와 관련 문서만 읽도록 만든다.
`priority-queue.md`는 Phase를 가로지르는 실행 순서만 담당한다.
`agent-roadmap/` 하위에 `Roadmap -> Phase -> Milestone` 기반 한국어 로드맵 구조를 처음 생성한다.
전체 로드맵은 전체 방향과 Phase index만 담당하고, 일반 작업에서는 `current.md`의 활성 Phase/Milestone 링크와 관련 문서만 읽도록 만든다.
Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서다.
Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능` 안에서 관리한다. 별도 `완료 기준` 섹션은 만들지 않고, 검증이 필요한 기능에만 같은 Task 안의 `검증:` 문구로 통합한다.
@ -33,54 +32,35 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능
```text
agent-roadmap/
ROADMAP.md
priority-queue.md
current.md # local, git ignored
current.md
phase/
<phase-slug>/
PHASE.md
milestones/
<milestone-slug>.md
sdd/
<phase-slug>/
<milestone-slug>/
SDD.md
USER_REVIEW.md
archive/
phase/
<phase-slug>/
PHASE.md
milestones/
<milestone-slug>.md
sdd/
<phase-slug>/
<milestone-slug>/
SDD.md
```
| 파일 | 역할 |
|------|------|
| `agent-roadmap/ROADMAP.md` | 전체 목표와 Phase 흐름만 담는 최상위 지도. 로드맵 생성/갱신/Phase 전환 때만 읽는다 |
| `agent-roadmap/priority-queue.md` | Phase를 가로지르는 Milestone 실행 순서만 담는 순서 전용 문서 |
| `agent-roadmap/current.md` | 활성 Phase와 활성 Milestone 후보, 선택 규칙을 담는 브랜치별 로컬 포인터 |
| `agent-roadmap/current.md` | 활성 Phase와 활성 Milestone 후보, 선택 규칙을 담는 얇은 포인터 |
| `agent-roadmap/phase/<phase-slug>/PHASE.md` | Phase 목표, 상태, Milestone 흐름, Phase 경계를 담는 문서 |
| `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md` | 일반 작업 시 읽는 Milestone 단위 목표, 스케치 승격 조건, 구현 잠금, 범위, 기능 Epic/Task 체크리스트, 범위 제외 항목 |
| `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md` | 큰 Milestone의 source of truth, 상태 전이, interface, acceptance scenario, evidence map을 담는 설계 게이트 |
| `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md` | SDD에서 에이전트가 확정할 수 없는 결정 항목이 있을 때 열리는 파일 기반 리뷰 gate |
| `agent-roadmap/archive/phase/<phase-slug>/...` | 완료 또는 폐기되어 현재 후보에서 제외한 과거 Phase/Milestone. 일반 작업에서는 읽지 않는다 |
| `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/...` | 완료 또는 폐기된 Milestone의 SDD 스냅샷과 해결된 사용자 리뷰 로그 |
## 템플릿
- `ROADMAP.md`는 `agent-ops/skills/common/_templates/roadmap-template.md` 형식을 따른다.
- `priority-queue.md`는 `agent-ops/skills/common/_templates/roadmap-priority-queue-template.md` 형식을 따른다.
- `current.md`는 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식을 따른다.
- `PHASE.md`는 `agent-ops/skills/common/_templates/roadmap-phase-template.md` 형식을 따른다.
- Milestone 문서는 `agent-ops/skills/common/_templates/roadmap-milestone-template.md` 형식을 따른다.
- SDD 본문은 `agent-ops/skills/common/_templates/roadmap-sdd-template.md` 형식을 따른다.
- SDD 사용자 리뷰는 `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md` 형식을 따른다.
- `ROADMAP.md`에는 Milestone 상세 체크리스트를 넣지 않는다.
- `priority-queue.md`는 순서 전용 문서이며, Milestone 제목 링크와 식별용 한 줄 설명만 둔다.
- `current.md`는 git 추적 대상이 아니며, 예시 파일을 `agent-roadmap/`에 따로 만들지 않는다.
- `current.md`는 활성 Phase/Milestone 후보만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다.
- archive 경로는 `current.md`의 활성 항목에 넣지 않는다.
@ -89,55 +69,39 @@ agent-roadmap/
- 기본 작성 언어는 한국어다.
- 상태 표기는 `[스케치]`, `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- `[스케치]`는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 구현 계획 생성 대상이 아니다.
- `[계획]`은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 문서화되어 잠금 해제 후 구현 계획을 만들 수 있는 상태다.
- `[계획]`은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 정리되어 구현 계획을 만들 수 있는 상태다.
- Phase와 Milestone 이름, 파일명에는 `1`, `2`, `M01`, `P1` 같은 순번을 붙이지 않는다.
- Phase 흐름은 실행 순서가 아니라 도메인/책임 영역의 구조적 지도다.
- Phase를 가로지르는 실제 실행 순서는 `priority-queue.md`의 위에서 아래 순서로 표현한다.
- `priority-queue.md`에는 상태, 목표, 범위, 잠금, 기능, 완료 근거, 의존성 필드를 복제하지 않는다.
- 실행 후보가 없더라도 `priority-queue.md` 파일과 `실행 순서` 섹션은 생성한다.
- 진행 순서는 `ROADMAP.md`와 각 `PHASE.md`의 위에서 아래 순서로 표현한다.
- Phase 파일명은 `agent-roadmap/phase/<phase-slug>/PHASE.md`로 만든다.
- Milestone 파일명은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`로 만든다.
- `<phase-slug>`와 `<milestone-slug>`는 소문자 영문, 숫자, 하이픈만 사용하고, 공백/언더스코어/순번 prefix를 넣지 않는다.
- 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.
- 로드맵 문서 안에서 다른 로드맵 문서, SDD, `USER_REVIEW.md`, archive 문서를 가리킬 때는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
- 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`와 `current.md`에서는 `[PHASE.md](phase/<phase-slug>/PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/<milestone-slug>.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다.
- `경로:`, `Phase:`, `Milestone:`, `SDD 문서:` 같은 필드명을 유지해야 해도 값은 `경로: [PHASE.md](phase/<phase-slug>/PHASE.md)`처럼 링크로 작성한다.
- 실제 생성한 로드맵 문서에는 `<phase-slug>`, `<milestone-slug>`, `<relative-...>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
- 코드 경로, 명령 입력, `.agent-roadmap-sync/locks.yaml`의 machine-readable identity는 raw 값이 필요하면 유지할 수 있지만, 사용자에게 보여주는 문서 포인터에는 Markdown 링크를 함께 둔다.
## Milestone 작성 규칙
- Milestone 기본 섹션은 `위치`, `목표`, `상태`, `구현 잠금`, `범위`, `기능`, `완료 리뷰`, `범위 제외`, `작업 컨텍스트`다.
- `승격 조건`은 `[스케치]` Milestone에서 필수다. `[계획]` 이상 상태에서는 섹션을 생략하거나 `- 없음`으로 둘 수 있다.
- `[스케치]` Milestone은 `승격 조건`을 체크리스트로 작성하고, `[계획]`으로 전환하기 위해 필요한 정의, 결정, 경계, 후속 구현 Milestone 후보를 적는다.
- 새 Milestone은 에이전트가 확정할 수 없는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 `구현 잠금`을 `잠금`으로 둔다.
- 새 Milestone은 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 `구현 잠금`을 `잠금`으로 둔다.
- 새 `[스케치]` Milestone은 `구현 잠금`을 `잠금`으로 둔다.
- Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다.
- `구현 잠금`에는 상태, SDD 필요 여부, 잠금 해제 조건, `결정 필요` 체크리스트를 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적는다.
- SDD가 필요한 기준: cross-repo 계약, 외부 provider 쓰기, 상태 머신/lifecycle, idempotency/retry/identity map, API/proto/config/env/schema 변경, field smoke, 사용자 승인 gate 영향.
- SDD가 불필요한 기준: 단일 repo 내부의 작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강, Milestone Task `검증:`만으로 닫히는 작업.
- SDD가 필요한 Milestone은 `SDD 문서` 값을 해당 Milestone 파일 위치 기준 `[SDD.md](../../../sdd/<phase-slug>/<milestone-slug>/SDD.md)` Markdown 링크로 적고, SDD 잠금이 해제될 때까지 `구현 잠금`을 `잠금`으로 둔다.
- 로드맵 생성 흐름에서 SDD가 필요한 신규 Milestone은 SDD 문서 링크만 남기지 않고 해당 파일에 SDD 초안을 만든다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다.
- `구현 잠금`에는 상태와 `결정 필요` 체크리스트만 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적는다.
- 새 Milestone이 다른 프로젝트 Milestone 완료 전까지 잠겨야 하면 `구현 잠금`을 `잠금`으로 두고 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`에 entry를 만든다. 의존 대상 확정과 entry 형식은 `update-roadmap`의 프로젝트 간 잠금 규칙을 따른다.
- `기능`은 Epic heading과 Task 체크리스트로 작성한다.
- Epic heading은 `### Epic: [epic-id] <이름>` 형식으로 작성한다.
- Task는 `- [ ] [item-id] 설명` 형식으로 작성한다.
- epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 해당 Milestone 안에서만 유일하면 된다.
- 검증이 필요한 Task에만 같은 항목 안에 `검증: <명령/확인 방법/기대 결과>`를 붙인다. 검증이 필요 없는 기능에는 억지 검증을 붙이지 않는다.
- `완료 리뷰`는 새 Milestone에서는 `상태: 없음`, `요청일: 없음`으로 두고, 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 `구현 잠금`이 해제된 뒤 에이전트/런타임 완료 근거를 기록할 때 갱신한다. 에이전트가 확정할 수 없는 결정 항목은 완료 리뷰가 아니라 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
- `agent-ui 상태 반영` 항목은 모든 신규 Milestone의 `완료 리뷰`에 두고 기본값은 `해당 없음`으로 적는다.
- `sync-agent-ui`의 `milestone-required` 코드 작업 라우팅으로 생성/갱신하는 Milestone, 또는 사용자가 Milestone 종료 검토에서 agent-ui 구현 상태 반영을 명시한 Milestone만 `agent-ui 상태 반영: 대기`로 둔다.
- `대기` Milestone은 종료 검토에서 최종 검증과 code evidence가 확인된 agent-ui view/component/frame만 `구현됨`으로 반영한다.
- `완료 리뷰`는 새 Milestone에서는 `상태: 없음`, `요청일: 없음`으로 두고, 모든 기능 Task와 Task 안에 명시된 검증이 충족된 뒤 사용자 최종 확인을 요청할 때 갱신한다.
- `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 작성하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.
## 먼저 확인할 것
- [ ] `agent-roadmap/ROADMAP.md` 또는 로컬 `agent-roadmap/current.md`가 이미 존재하는지 확인
- [ ] `agent-roadmap/ROADMAP.md` 또는 `agent-roadmap/current.md`가 이미 존재하는지 확인
- [ ] 이미 존재하면 덮어쓰지 말고 `update-roadmap` 스킬 사용을 안내
- [ ] `README.md`, `agent-ops/GUIDE.md`, `agent-ops/rules/project/rules.md` 등 프로젝트 방향을 설명하는 문서를 확인
- [ ] `rg --files`로 현재 프로젝트의 주요 구조를 가볍게 확인
- [ ] `roadmap-template.md`, `roadmap-priority-queue-template.md`, `roadmap-current-template.md`, `roadmap-phase-template.md`, `roadmap-milestone-template.md`를 읽어 최신 형식 확인
- [ ] SDD가 필요한 Milestone 후보가 있으면 `agent-ops/skills/common/roadmap-sdd/SKILL.md`, `roadmap-sdd-template.md`, `roadmap-sdd-user-review-template.md`를 읽어 최신 절차와 형식 확인
- [ ] `roadmap-template.md`, `roadmap-current-template.md`, `roadmap-phase-template.md`, `roadmap-milestone-template.md`를 읽어 최신 형식 확인
- [ ] `agent-ops/rules/common/rules.md`가 로드맵 디렉터리 존재 시 `agent-ops/rules/common/rules-roadmap.md`를 읽도록 라우팅하는지 확인
## 실행 절차
@ -158,60 +122,41 @@ agent-roadmap/
- Milestone 내부에서 여러 기능 묶음이 필요하면 Epic으로 선언하고, Epic 아래 flat Task 체크리스트를 둔다.
4. **파일 생성**
- `ROADMAP.md`, `priority-queue.md`, 로컬 `current.md`, 각 Phase의 `PHASE.md`, 각 Milestone 문서를 템플릿 순서대로 생성한다.
- `ROADMAP.md` 최상단에는 `priority-queue.md`를 먼저 확인하도록 `고정 실행 순서` 섹션을 둔다.
- `priority-queue.md`에는 Phase를 가로지르는 실행 후보 Milestone을 위에서 아래 순서로 둔다. 후보가 없으면 `실행 순서` 섹션만 비워 둔다.
- `ROADMAP.md`, `current.md`, 각 Phase의 `PHASE.md`, 각 Milestone 문서를 템플릿 순서대로 생성한다.
- 활성 Phase와 활성 Milestone은 `current.md`에 모두 기록한다.
- `.gitignore`의 Agent-Ops 관리 block에 `agent-roadmap/current.md`가 있는지 확인하고 없으면 추가한다.
- `ROADMAP.md`의 Phase 흐름에는 완료/검토중/진행중/계획/스케치 Phase 모두를 상태 그룹별로 정리한다. 이 순서는 실행 우선순위가 아니며, 실제 다음 작업 선택은 `priority-queue.md`를 따른다.
- `ROADMAP.md`의 Phase 흐름에는 완료/검토중/진행중/계획/스케치 Phase 모두를 위에서 아래 순서로 두고, 계획 Phase는 진행중 Phase보다 아래에, 스케치 Phase는 계획 Phase보다 아래에 둔다.
- 완료된 Phase가 초기 구조에 포함되어야 하는 경우 `archive/phase/<phase-slug>/PHASE.md`로 만들고 `ROADMAP.md`에서 archive 경로를 가리킨다.
- 완료된 Milestone이 진행중 Phase에 포함되어야 하는 경우 `archive/phase/<phase-slug>/milestones/<milestone-slug>.md`로 만들고 해당 활성 `PHASE.md`에서 archive 경로를 가리킨다.
- archive `PHASE.md`는 Phase 자체가 완료/폐기된 경우에만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 둘 수 있다.
- SDD가 필요한 Milestone은 `구현 잠금`에 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크와 잠금 해제 조건을 적고, 같은 흐름에서 `roadmap-sdd`의 `create` 절차를 적용해 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md` 초안을 만든다.
- `roadmap-sdd create` 결과 SDD 결정 항목이 있으면 `roadmap-sdd`의 `review-ready` 절차에 따라 같은 디렉터리에 `USER_REVIEW.md`를 만들고, SDD와 Milestone 구현 잠금을 `잠금`으로 둔다.
- 외부 의존 잠금이 있으면 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`을 생성하거나 기존 entry를 upsert한다. 의존 대상이 명시 경로, slug, 제목, 문서 힌트, 로컬 current 단일 후보 중 하나로 확정되지 않으면 lock entry를 만들지 않고 TODO로 남긴다.
- 외부 의존 잠금이 있으면 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`을 생성하거나 기존 entry를 upsert한다. 의존 대상이 명시 경로, slug, 제목, 문서 힌트, current 단일 후보 중 하나로 확정되지 않으면 lock entry를 만들지 않고 TODO로 남긴다.
5. **검증**
- 생성한 링크가 실제 파일을 가리키는지 확인한다.
- `priority-queue.md`가 존재하고 `실행 순서` 섹션이 있는지 확인한다.
- `priority-queue.md`의 모든 링크가 활성 Milestone 파일을 가리키는지 확인한다. 실행 후보가 없어서 빈 큐이면 정상으로 보고하되, 활성 실행 후보가 있는데 비어 있으면 큐 동기화 필요로 본다.
- 생성한 로드맵 문서의 문서/산출물 포인터가 raw path만 남지 않고 Markdown 링크로 작성되었는지 확인한다.
- 생성한 로드맵 문서의 Markdown 링크 target에 템플릿 placeholder가 남지 않았는지 확인한다.
- 로컬 `current.md` 활성 항목에 `agent-roadmap/archive/**` 경로가 없는지 확인한다.
- `current.md` 활성 항목에 `agent-roadmap/archive/**` 경로가 없는지 확인한다.
- Epic heading과 Task 체크리스트 id가 형식을 따르는지 확인한다.
- 상태 표기가 `[진행중]`처럼 공백 없는 표준값인지 확인한다.
- `[스케치]` Milestone에 `승격 조건` 섹션이 있고 `구현 잠금`이 `잠금`인지 확인한다.
- 각 Milestone의 `구현 잠금`에 `SDD: 필요|불필요`와 판정 사유가 있는지 확인한다.
- `SDD: 필요` Milestone은 SDD 문서 링크와 잠금 해제 조건이 있고, 해당 `SDD.md` 파일이 실제 존재하는지 확인한다.
- 생성된 각 `SDD.md`는 `roadmap-sdd`의 `check-gate` 절차로 표준 top-level 섹션, 필수 표 컬럼, SDD 상태, SDD 잠금, `USER_REVIEW.md` 존재 여부, Acceptance Scenario와 Milestone 기능 Task 연결, Evidence Map 연결성을 최종 확인한다.
- `check-gate` 결과는 `SDD gate` 항목에 `pass`, `review-required`, `blocked`, `invalid` 중 하나로 분리해 남긴다. `review-ready`로 만든 `USER_REVIEW.md` 때문에 막힌 경우는 `review-required`로 보고하고 형식 보완 실패로 보지 않는다.
- `[검토중]` Milestone이 있다면 `구현 잠금`이 해제되어 있고 미완료 `결정 필요` 항목이 없는지 확인한다.
- Milestone 문서에 `완료 리뷰` 섹션이 있는지 확인한다.
- `sync-agent-ui`의 `milestone-required` 코드 작업 라우팅으로 생성/갱신한 Milestone이면 `완료 리뷰`에 `agent-ui 상태 반영: 대기`가 있고, 그 외 Milestone은 `agent-ui 상태 반영: 해당 없음`인지 확인한다.
## 출력 형식
```markdown
## 생성 결과
## 생성 완료
- 로드맵: [ROADMAP.md](agent-roadmap/ROADMAP.md)
- 전역 실행 순서: [priority-queue.md](agent-roadmap/priority-queue.md)
- 로컬 현재 컨텍스트: [current.md](agent-roadmap/current.md)
- 로드맵: agent-roadmap/ROADMAP.md
- 현재 컨텍스트: agent-roadmap/current.md
- Phase 문서: <N개>
- Milestone 문서: <N개>
- 활성 Phase: <N개>
- 활성 Milestone: <N개>
- 구현 잠금: <잠금 Milestone N개 | 해제 Milestone N개>
- SDD gate: <필요 N개 | 불필요 N개 | 작성 N개 | pass N개 | review-required N개 | blocked/invalid N개>
- 전역 실행 순서: <항목 N개 | 빈 큐 | 동기화 필요>
- 최종 확인: <통과 | 사용자 리뷰 필요 | 보완 필요: SDD gate/링크/상태/형식>
- Workspace 잠금: <생성/갱신 N개 | 없음>
- 공통 로드맵 룰: <확인함 | 설치 필요 | 해당 없음>
## 활성 항목
- Phase: <phase-name>: [PHASE.md](agent-roadmap/phase/<phase-slug>/PHASE.md)
- Milestone: <milestone-name>: [<milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- Phase: <phase-name>: agent-roadmap/phase/<phase-slug>/PHASE.md
- Milestone: <milestone-name>: agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md
## TODO 항목
@ -222,13 +167,10 @@ agent-roadmap/
- 기존 `agent-roadmap/` 파일을 덮어쓰지 않는다.
- 일반 작업마다 전체 `ROADMAP.md`를 읽도록 규칙을 만들지 않는다.
- `priority-queue.md`를 두 번째 로드맵처럼 사용하지 않는다. 상태, 목표, 범위, 잠금, 기능, 완료 근거를 복제하지 않는다.
- `priority-queue.md`에 archive Milestone 링크를 넣지 않는다.
- 로컬 `current.md`에 `agent-roadmap/archive/**` 경로를 넣지 않는다.
- `agent-roadmap/current.md`를 git 추적 대상으로 만들지 않는다.
- `current.md`에 `agent-roadmap/archive/**` 경로를 넣지 않는다.
- Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
- `ROADMAP.md`에 Milestone 상세 작업 체크리스트를 넣지 않는다.
- Epic과 Task를 별도 파일로 분리하지 않는다.
- Milestone 문서에서 `구현 잠금` 섹션을 생략하지 않는다.
- 에이전트가 확정할 수 없는 결정 항목이 남아 있는데 새 Milestone을 `해제` 상태로 만들지 않는다.
- 사용자만 결정할 수 있는 항목이 남아 있는데 새 Milestone을 `해제` 상태로 만들지 않는다.
- 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다.

117
agent-ops/skills/common/create-spec/SKILL.md
View file

@ -1,117 +0,0 @@
---
name: create-spec
version: 1.0.0
description: agent-spec 최초 생성, 현재 구현 스펙 작성, living spec bootstrap, 완료된 기능의 구현 스펙 신규 문서화 요청에 사용한다. 코드/계약/테스트/로드맵 근거를 바탕으로 agent-spec/index.md와 매칭 spec 문서를 생성한다.
---
# create-spec
## 목적
현재 구현된 기능의 living spec을 새로 만든다.
스펙은 로드맵 완료 이력이나 계약 원문을 복제하지 않고, 사람과 agent가 구현된 기능, 동작 흐름, 계약/검증 포인터를 함께 확인하는 문서로 유지한다.
## 언제 호출할지
- 사용자가 "스펙 생성", "구현 스펙 작성", "현재 구현 문서화", "agent-spec 생성"을 요청할 때
- agent-spec을 처음 도입해 `agent-spec/index.md`와 초기 spec 문서를 만들 때
- 완료된 기능이나 활성 기능에 대응되는 현재 구현 spec 문서가 없고, 새 spec 작성이 필요한 때
- `complete-milestone` 또는 `update-spec`에서 관련 spec이 없지만 evidence가 충분해 신규 작성이 필요하다고 판단한 때
## 입력
- `mode`: `bootstrap` 또는 `targeted`. 기본값은 요청에서 추론한다. (선택)
- `spec-id`: 만들 spec id. `<area>/<spec-id>` 형식을 권장한다. (선택)
- `target-milestone`: spec 근거로 삼을 활성 또는 명시 Milestone 경로, 이름, slug. (선택)
- `source-paths`: 우선 확인할 코드, 계약, 테스트, docs 경로 목록. (선택)
- `evidence`: complete.log, SDD, 사용자 설명, 검증 결과 등 보조 근거. (선택)
## 먼저 확인할 것
- [ ] `agent-ops/rules/common/rules-agent-spec.md`를 읽는다.
- [ ] `agent-spec/` 존재 여부와 `agent-spec/index.md` 존재 여부를 확인한다.
- [ ] `agent-ops/skills/common/_templates/agent-spec/index-template.md`와 `spec-template.md`를 확인한다.
- [ ] 계약에 닿는 spec이면 `agent-contract/index.md`를 읽고 매칭 계약 문서만 읽는다.
- [ ] 로드맵 근거가 필요하면 활성 Milestone/SDD만 우선 읽고, archive는 사용자가 명시했거나 현재 스펙 배경 확인에 꼭 필요한 링크만 좁게 읽는다.
## 실행 절차
1. **범위 결정**
- 요청을 `bootstrap` 또는 `targeted`로 분류한다.
- `targeted`이면 spec 하나의 기능 범위와 `spec-id`를 정한다.
- `bootstrap`이면 프로젝트 전체를 완성하려 하지 말고, 코드/계약으로 확인 가능한 핵심 축과 spec 후보 목록을 먼저 만든다.
- `spec-id`는 소문자 영문, 숫자, 하이픈, `/`만 사용한다.
2. **근거 수집**
- 코드, 계약, 테스트, 설정 예시, README/docs, 활성 roadmap/SDD, complete.log 순서로 현재 동작 근거를 확인한다.
- 현재 동작은 코드와 계약으로 재확인한다.
- 로드맵 archive 또는 agent-task archive는 일반 탐색하지 않는다.
- 확인할 수 없는 내용은 `불명확` 또는 `확인 필요`로 둔다.
3. **agent-spec 구조 생성**
- `agent-spec/`가 없으면 만든다.
- `agent-spec/index.md`가 없으면 index template으로 만든다.
- 필요한 `<area>/` 디렉터리를 만든다.
- 기존 같은 `spec-id` 문서가 있으면 새로 만들지 말고 `update-spec` 대상이라고 보고한다.
4. **spec 문서 작성**
- spec template의 기본 섹션 구조를 따른다.
- frontmatter의 `spec_doc_type`, `spec_id`, `status`, `source_evidence`를 채운다.
- `status`는 evidence 수준에 따라 `구현됨`, `부분`, `가정`, `불명확` 중 하나로 둔다.
- `기능 목록`을 `목적` 다음에 바로 둔다.
- 기능 목록은 `기능`과 `설명` 중심으로 작성한다. 기능별 `상태` 칼럼은 기본 생성하지 않는다.
- `주요 흐름`은 Mermaid `sequenceDiagram` 또는 `flowchart`를 우선 고려한다. 단순 기능은 짧은 목록으로 둔다.
- 책임 경계는 기능 이해에 필요한 최소 수준만 적고, 도메인별 코드 배치나 금지 사항은 domain rule로 넘긴다.
- 계약 원문, proto field 전체 목록, config schema 원문은 복제하지 않고 링크한다.
- `코드 진입점` 섹션은 만들지 않는다. 코드 근거는 `source_evidence`에 남긴다.
- 검증 방법은 실행 가능한 명령 또는 확인 기준으로 남긴다.
5. **index 갱신**
- `Spec Map`에 새 spec id, 상태, 읽는 조건, path, 주요 근거를 추가하거나 보정한다.
- 매칭 조건은 agent가 좁게 읽을 수 있도록 기능명, 코드 경로, 계약 id, 운영 표면 중심으로 쓴다.
- 기존 행을 삭제하거나 재정렬하지 않는다. 명백히 placeholder인 `없음` 행은 첫 실제 spec 추가 시 제거할 수 있다.
6. **결과 보고**
- 만든 spec 문서와 index 변경 내용을 보고한다.
- 불명확하거나 후속 `update-spec`이 필요한 항목을 보고한다.
## 실행 결과 검증
- [ ] `agent-spec/index.md`가 존재하고 Spec Map에 생성한 spec이 들어 있는가
- [ ] 생성한 spec 문서가 `rules-agent-spec.md`의 기본 섹션 기준을 따르는가
- [ ] 기능 목록이 기능/설명 중심이며 불필요한 상태 칼럼이나 과한 상세 설명을 만들지 않았는가
- [ ] 코드 진입점, 패키지 배치, 도메인별 금지 사항을 spec 본문에 반복하지 않았는가
- [ ] frontmatter의 `spec_doc_type`, `spec_id`, `status`, `source_evidence`가 채워졌는가
- [ ] source evidence path가 실제 파일이거나 `path: null`인 사용자 근거인가
- [ ] 계약 원문을 복제하지 않고 `agent-contract/` 또는 코드 링크로 연결했는가
- [ ] archive를 무차별로 읽거나 과거 완료 기록을 현재 truth처럼 쓰지 않았는가
- [ ] `git diff --check`를 실행했는가
- 검증 실패 시: spec 문서와 index만 보완하고 코드 파일은 수정하지 않는다.
## 출력 형식
```markdown
## Spec 생성 완료
- 모드: <bootstrap | targeted>
- 생성/갱신 파일:
- [index.md](agent-spec/index.md)
- [<spec-id>.md](agent-spec/<area>/<spec-id>.md)
- 상태: <구현됨 | 부분 | 가정 | 불명확>
- 주요 근거:
- <path 또는 사용자 근거> - <요약>
## TODO 항목
- <확인 필요 또는 없음>
```
## 금지 사항
- agent-spec에 계약 원문, proto 전체 필드, config schema 원문을 복제하지 않는다.
- 현재 코드/계약으로 확인하지 않은 내용을 구현 사실처럼 쓰지 않는다.
- archive 전체를 훑지 않는다.
- 기존 spec이 있으면 중복 spec을 만들지 않는다.
- 코드 진입점, 구현 배치, 도메인 간 상세 책임 경계, 유지할 패턴, 금지 사항을 domain rule 대신 agent-spec에 길게 쓰지 않는다.
- 사람용 공개 가이드를 agent-spec에 장황하게 작성하지 않는다.
- spec 생성과 무관한 코드 파일을 수정하지 않는다.

34
agent-ops/skills/common/create-test/SKILL.md
View file

@ -1,14 +1,14 @@
---
name: create-test
version: 1.1.4
description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테스트 rule 문서를 생성하거나 구조적 blank/skeleton baseline을 보완하는 스킬
version: 1.1.1
description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테스트 rule 문서를 생성하는 스킬
---
# create-test
## 목적
`agent-test/<env>/rules.md`와 `agent-test/<env>/<test-profile>.md`를 템플릿 기준으로 생성하거나 구조적 blank/skeleton 상태에서 baseline으로 보완한다.
`agent-test/<env>/rules.md`와 `agent-test/<env>/<test-profile>.md`를 템플릿 기준으로 생성한다.
공통 진입점은 얇게 유지하고, 실제 테스트 기준은 환경/도메인/검증 시나리오별 문서에 둔다.
`test-case`는 기존 호출과의 호환을 위한 alias이며, 새 문서 기준 이름은 `test-profile`이다.
@ -17,7 +17,6 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
- 새 테스트 환경을 추가할 때
- 특정 환경의 `rules.md`가 없을 때
- 특정 환경의 `rules.md`가 비어 있거나 템플릿 뼈대만 있어 baseline 보완이 필요할 때
- 새 도메인/검증 시나리오별 테스트 문서와 라우팅을 추가할 때
- `init-agent-ops` 후 local 테스트 환경 보완이 필요할 때
@ -35,10 +34,6 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
- 도메인 매핑이나 domain rule에서 도메인이 하나 이상 확인되면, 누락된 `agent-test/<env>/<domain>-smoke.md`를 도메인별로 항상 생성한다.
- 명시 `test-profile`은 추가 생성 대상이다. 명시 대상만 만들고 도메인 baseline을 생략하지 않는다.
- 도메인이 하나도 확인되지 않을 때만 `agent-test/<env>/project-smoke.md`를 fallback baseline으로 만든다.
- env rules는 빈 파일, 제목/frontmatter만 있는 파일, 필수 섹션 누락, 또는 `## 라우팅`에 실제 profile 경로가 없으면 구조적 blank/skeleton으로 본다.
- test-profile 문서는 빈 파일, 제목/frontmatter만 있는 파일, 필수 섹션 누락, 또는 적용 범위/분류/명령/필수 검증/판정 기준 섹션 자체가 없으면 구조적 blank/skeleton으로 본다.
- 필수 섹션은 있고 일부 값이 비어 있거나 `<확인 필요>`인 상태는 구조적 blank/skeleton이 아니다. 이 경우 structured-incomplete로 보고 확인된 구체 값과 미확인 항목을 결과에 남긴다.
- 구조적 blank/skeleton env rules나 profile은 기존 완성 문서가 아니라 baseline 보완 대상으로 본다. 확인된 구체 값은 보존하고, 빠진 필수 섹션과 baseline 라우팅만 채운다.
## 먼저 확인할 것
@ -49,20 +44,16 @@ 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 중 하나로 분류한다.
- [ ] 도메인 baseline과 추가 생성 대상 `agent-test/<env>/*.md`의 존재 여부를 확인한다.
## 실행 절차
1. **환경 rules 생성**
- `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는 덮어쓰지 않고 라우팅 추가가 필요한 경우에만 최소 수정한다.
- `agent-test/<env>/rules.md`가 없으면 `test-env-rules-template.md` 형식으로 만든다.
- 제목은 `# <env> 테스트 규칙`으로 쓴다.
- 제목 바로 아래 정독 필수 문구를 유지한다.
- `last_rule_updated_at`은 생성/보완일 `YYYY-MM-DD`로 쓴다.
- `last_rule_updated_at`은 생성일 `YYYY-MM-DD`로 쓴다.
2. **생성 대상 확정**
- `test-case`가 있고 `test-profile`이 없으면 `test-profile`로 취급한다.
@ -75,9 +66,7 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
- 도메인은 새로 발명하지 않는다. 도메인 매핑이나 domain rule에서 확인되지 않은 이름은 `project-wide`로 기록한다.
3. **도메인/검증 시나리오별 문서 생성**
- 생성 대상 문서가 없으면 프로젝트 `agent-test/_templates/test-profile-template.md`가 있을 때는 그 형식으로 만들고, 없으면 공통 `test-case-rule-template.md` 형식으로 만든다.
- 대상 문서가 이미 있고 usable하면 덮어쓰지 않는다.
- 대상 문서가 구조적 blank/skeleton이면 기존 구체 값을 보존한 채 빠진 frontmatter와 필수 섹션을 보완한다.
- 생성 대상마다 `agent-test/<env>/<test-profile>.md`를 `test-case-rule-template.md` 형식으로 만든다.
- frontmatter에는 `test_profile`, `domain`, `verification_type`, `last_rule_updated_at`을 채운다.
- 파일명은 kebab-case로 쓴다.
- 실제 확인된 환경, 명령, 판정 기준만 채운다.
@ -86,8 +75,7 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
4. **라우팅 갱신**
- 새 환경을 만들었고 `agent-ops/rules/common/rules.md`에 해당 env 라인이 없으면 `# 테스트 규칙`에 한 줄을 추가한다.
- 생성하거나 보완한 `test-profile` 문서는 `agent-test/<env>/rules.md`의 `## 라우팅`에 한 줄씩 추가한다.
- 이미 같은 profile로 향하는 라우팅이 있으면 중복 추가하지 않고 설명만 필요할 때 최소 보정한다.
- 생성한 `test-profile` 문서는 `agent-test/<env>/rules.md`의 `## 라우팅`에 한 줄씩 추가한다.
- 라우팅 설명은 `<domain 또는 project-wide> / <verification-type> / <scope 요약>` 형식으로 쓴다.
- 도메인/검증 시나리오별 문서에서 다른 테스트 문서로 라우팅하지 않는다.
- 공통룰에서 스킬 최종 진입까지의 경로는 `rules.md` -> `router.md` -> `create-test/SKILL.md`로 유지한다.
@ -99,7 +87,6 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
- 생성한 파일
- 추가한 라우팅
- 자동 생성 기준: 도메인 baseline / 명시 입력 / scope 매칭 / project-smoke fallback
- 구조적 blank/skeleton 보완 대상
- 비워 둔 확인 필요 항목
## 실행 결과 검증
@ -110,7 +97,6 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
- [ ] 새 도메인/검증 시나리오별 문서가 env rules의 라우팅에 연결되었는가
- [ ] 확인된 모든 도메인에 `<domain>-smoke` 문서가 생성되었는가
- [ ] 도메인이 없을 때 `project-smoke` fallback 문서가 생성되었는가
- [ ] 생성/보완 대상에 섹션 누락이나 라우팅 없는 구조적 blank/skeleton 파일이 남아 있지 않고, 불확실한 값은 `<확인 필요>`로 보고되었는가
- [ ] local 생성 시 `.gitignore`에 local 경로가 반영되었는가
- 검증 실패 시: 누락된 파일/섹션/라우팅만 보완한다.
@ -124,14 +110,12 @@ description: agent-test 환경 rules.md와 도메인/검증 시나리오별 테
- 테스트 profiles: <agent-test/<env>/<test-profile>.md 목록>
- 라우팅 추가: <내용>
- 자동 생성 기준: <도메인 baseline | 명시 입력 | scope 매칭 | project-smoke fallback>
- 구조적 blank/skeleton 보완: <파일 목록 또는 없음>
- 확인 필요: <항목 또는 없음>
```
## 금지 사항
- usable한 기존 테스트 문서를 덮어쓰지 않는다.
- 구조적 blank/skeleton 보완 시에도 확인된 구체 환경값, 명령, 판정 기준을 추측으로 교체하지 않는다.
- 기존 테스트 문서를 덮어쓰지 않는다.
- 도메인/검증 시나리오별 문서에서 추가 테스트 문서로 라우팅하지 않는다.
- 도메인 매핑이나 domain rule에 없는 도메인을 확정값처럼 만들지 않는다.
- 확인되지 않은 host, port, token, endpoint를 추측해 쓰지 않는다.

196
agent-ops/skills/common/finalize-task-routing/SKILL.md
View file

@ -1,196 +0,0 @@
---
name: finalize-task-routing
description: PLAN/CODE_REVIEW 작성 직전 현재 작업 증거만으로 cloud/local lane과 G01-G10 등급을 독립 평가하고 canonical 파일명을 확정한다. 최초 plan, review 실패 후 follow-up plan, 라우팅 재평가, lane/G 판단, routed filename 결정에 사용한다.
---
# Finalize Task Routing
## 목적
계획 분석이 끝난 뒤 구현과 리뷰 target의 lane과 G 등급을 처음부터 평가하고 canonical 파일명을 반환한다.
이 스킬은 라우팅 판단의 단일 원본이며 plan/review 내용을 작성하거나 task 파일을 직접 생성하지 않는다.
Lane/G는 capability 요구사항이다. Runtime은 plan, build, review를 서로 다른 모델 identity에 배정해야 하며, 같은 lane/G여도 같은 모델을 재사용하면 안 된다.
## 언제 호출할지
- `plan`이 최초 PLAN/CODE_REVIEW pair를 쓰기 직전
- `code-review`의 WARN/FAIL 후 `plan`이 follow-up PLAN/CODE_REVIEW pair를 다시 쓰기 직전
- 기존 lane/G 판정이 검증 실패, 증거 충돌, 범위 변화, 소유권 변화로 무효화된 뒤 재평가할 때
- 사용자가 현재 작업의 cloud/local, G 등급, canonical task 파일명만 요청할 때
## 입력
- `targets`: `build`, `review`, 또는 둘 다. `plan`은 항상 둘 다 전달한다 (필수)
- `evaluation_mode`: 이전 라우팅이 없는 최초 평가는 `first-pass`, 무효화된 기존 라우팅의 lane/grade/score/rationale를 입력에서 격리하고 현재 미해결 작업을 처음부터 평가하는 모드는 `isolated-reassessment` (필수)
- `task_snapshot`: 사용자 요구, 현재 scope, 수정/영향 경로, 불변조건, 상태 전이, 검증 계획, 이미 존재하는 증거 또는 `none` (필수)
- `context_snapshot`: 함께 유지해야 하는 source/test/diff/log/contract 범위와 분할 가능성 (필수)
- `ownership_snapshot`: 공유 상태, 병행 작업, sibling task, 외부 책임 경계 (필수)
- `decision_snapshot`: 미해결 의미 판단, 사용자 권한이 필요한 결정, 외부 환경 의존성 (필수)
- `invalidation_evidence`: 검증 실패, 실제 로그, review finding, 변경된 범위 등 현재 판정을 바꾸는 원시 증거 (선택)
이전 `lane`, `grade`, 점수, 라우팅 사유, routed filename은 입력에서 제외한다.
이전 PLAN/CODE_REVIEW 문서의 코드 경로, 기존 로그, finding은 경로와 revision 관련성을 정적으로 확인한 뒤 원시 증거로만 사용할 수 있다. 확인을 위해 검증 명령을 다시 실행하지 않는다.
## 먼저 확인할 것
- [ ] `agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh`가 실행 가능한가
- [ ] 호출자가 plan 분석, scope, split, 검증 계획을 모두 확정했는가
- [ ] `targets`마다 필요한 구현 또는 리뷰 작업이 구분되어 있는가
- [ ] 이전 lane/G와 그 평가 문구가 입력에서 격리되었는가
- [ ] `isolated-reassessment`이면 이전 lane/grade/score/rationale/preferred route를 제외한 중립 snapshot만 평가 입력으로 사용했는가
- [ ] 현재 파일, diff, 확정된 제약, 이미 기록된 명령 출력을 우선 증거로 사용했는가
## 검증 책임
- Routing은 계획된 검증의 결정성과 관찰 가능성만 평가한다. 실행 전 출력 부재는 `unknown` 또는 `needs_evidence` 사유가 아니다.
- Plan과 routing은 구현 검증을 실행하지 않는다. 이 스킬은 canonical filename 계산 script만 실행한다.
- Build가 검증과 출력 기록을 맡고, review가 evidence를 확인하며 review scope에 필요한 명령을 재실행한다.
## 실행 절차
1. **평가 상태 초기화**
- 호출할 때마다 각 target을 `unrouted`로 시작한다.
- `isolated-reassessment`는 이전 lane/grade/score/rationale/preferred route를 입력에서 제외하고, 현재 미해결 Required/Suggested, 영향 경로, 검증, 소유권, 결정 상태로 재구성한 중립 snapshot만 평가한다.
- `isolated-reassessment`는 plan 역할 안의 라우팅 재평가다. 별도 routing model은 필요 없으며 plan/build/review의 서로 다른 모델 조건은 그대로 유지한다.
- 이전 lane/G를 승계하거나 하한으로 사용하지 않는다.
- 실패 횟수, Required 개수, 이전 G 등급만으로 cloud 또는 상위 G를 선택하지 않는다.
- 실패는 자동 승격 조건이 아니라 현재 증거에 추가되는 판정 무효화 사건으로만 취급한다.
- 새 결과가 확정되기 전에는 이전 평가와 비교하지 않는다. 감사용 비교가 요청된 경우에만 호출자가 routed 출력 이후 delta를 기록한다.
2. **폐쇄성 평가**
- 각 target을 bounded local execution으로 완료·판정할 수 있는지를 기준으로 아래 값을 `true`, `false`, `unknown` 중 하나로 독립 판정하고 근거를 한 줄로 기록한다.
- `scope_closed`: 정확성 조건과 영향 경로가 확정된 범위 안에서 설명되는가
- `context_closed`: 중요한 증거를 생략하지 않고 필요한 컨텍스트를 함께 다룰 수 있는가
- 계획 분석 결과, 해당 target을 수행하는 동안 긴 컨텍스트를 유지해야 한다고 판단되면 `context_closed=false`로 판정한다.
- `verification_closed`: 계획된 명령과 관찰로 build/review가 성공 여부를 결정적으로 증명할 수 있는가
- `evidence_trusted`: 검증 경로와 evidence 출처가 구체적이고 재현 가능한가. 최초 plan에서는 실행 전 검증 설계의 신뢰성을 평가하며 PASS 출력은 요구하지 않는다.
- `ownership_closed`: 공유 상태, 병행 작업, 외부 소유권이 판단을 모호하게 만들지 않는가
- `decision_closed`: 사용자 권한이나 미해결 외부 의미 결정 없이 작업을 완료할 수 있는가
- active review follow-up에서는 유효한 Milestone-lock 결정만 `false`의 terminal gate가 될 수 있다. 환경, permission, secret, service, evidence 한계는 해결 완료 여부가 아니라 blocker 확인·해제 조건·재검증이 계획 가능한지를 평가한다.
- 동시성, dirty worktree, 외부 명령, 많은 finding은 그 자체로 lane을 결정하지 않는다. 위 폐쇄성에 미치는 영향만 평가한다.
3. **판정 가능성 확인**
- 하나라도 `unknown`이면 `status: needs_evidence`와 필요한 정적 planning evidence를 반환한다. 실행 전 PASS 출력 부재는 `unknown` 사유가 아니다. lane, grade, filename은 반환하지 않는다.
- first-pass에서 하나 이상의 값이 `false`이고 cloud의 더 넓은 컨텍스트나 진단도 그 폐쇄 실패를 해소할 수 없으면 `status: blocked`, 폐쇄 실패별 `blocked_reason`, 해제 조건을 반환한다. 이 상태는 routed pair가 생성되기 전의 loop-entry 거절이며, active loop의 terminal state가 아니다.
- active code-review의 `isolated-reassessment`에서는 유효한 Milestone-lock 결정이 이미 code-review의 `USER_REVIEW.md` gate로 분기되어야 한다. 그 외 환경, permission, secret, service, ownership, verification 제한은 blocker 증거·결정적 해제 조건·재검증을 포함하는 follow-up으로 평가하고 `blocked`를 반환하지 않는다.
- 호출자는 `needs_evidence`를 cloud로 해석하지 말고 정적 planning evidence를 보강한 뒤 이 스킬을 처음부터 다시 실행한다. routing을 위해 구현 검증을 실행하지 않는다.
4. **Lane 결정**
- 모든 폐쇄성이 `true`인 target만 `local`로 정한다.
- `unknown`이 없고 하나 이상의 폐쇄성이 `false`이며 cloud의 더 넓은 컨텍스트나 진단이 그 실패를 실제로 해소할 수 있을 때 `cloud`로 정한다.
- `false`를 cloud가 해소할 수 있는지 근거를 기록한다. 해소 가능성을 설명할 수 없는 first-pass target만 Step 3의 `blocked`를 반환한다. Active code-review의 `isolated-reassessment`에서는 `blocked`를 반환하지 말고, 유효한 Milestone-lock 결정은 code-review의 `USER_REVIEW.md` gate로 돌려보내며 그 외 제한은 blocker 증거·결정적 해제 조건·재검증을 수행하는 bounded follow-up scope로 재구성한 뒤 폐쇄성을 다시 평가한다.
- 실패 후에도 현재 폐쇄성이 모두 `true`이면 다시 `local`을 선택할 수 있다.
- lane은 capability fit이며 작업량이나 모델 사용량 균형을 위한 값이 아니다.
5. **G 등급 재산정**
- lane을 정한 뒤에만 각 target을 아래 다섯 차원에서 `0`, `1`, `2`로 처음부터 채점한다.
- `scope_coupling`: `0` 단일 국소 변경 / `1` 여러 연결 지점 / `2` 다중 모듈·계약
- `state_concurrency`: `0` 무상태 / `1` 상태 전이 / `2` 공유 상태·순서·동시성
- `blast_irreversibility`: `0` 내부 가역 / `1` 다중 호출자·설정·지속 상태 / `2` 외부 계약·권한·비가역 영향
- `evidence_diagnosis`: `0` 직접 증거 / `1` 복수 증거 조합 / `2` 충돌·불신 증거 진단
- `verification_complexity`: `0` 단일 결정 명령 / `1` 복수 단계·통합 검증 / `2` 외부·상호작용·장시간 검증
- grade는 `max(1, 다섯 점수의 합)`이며 유효 범위는 `G01`부터 `G10`이다.
- 이전 grade, 실패 횟수, lane 변경은 점수에 더하지 않는다.
6. **파일명 확정**
- 각 target에 대해 다음 명령을 실행하고 stdout의 grade와 filename을 그대로 사용한다.
```bash
agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh \
<build|review> <local|cloud> \
<scope_coupling> <state_concurrency> <blast_irreversibility> \
<evidence_diagnosis> <verification_complexity>
```
- 모델이 점수 합산, zero-padding, prefix 조합을 직접 계산하지 않는다.
- 두 target은 같은 lane/G를 복사하지 말고 각자의 실행 범위로 독립 평가한다.
- 모든 요청 target이 `routed`일 때만 filename을 반환한다.
- 결과 확정 뒤 scope, 검증, 증거, 소유권, 결정 조건이 달라지면 결과를 무효화하고 Step 1부터 다시 실행한다.
## 라우팅 결과 확인
- [ ] 모든 요청 target에 여섯 폐쇄성 값과 현재 증거 근거가 있는가
- [ ] 재평가가 `isolated-reassessment`로 실행되었고 새 결과를 확정하기 전에 이전 lane/grade/score/rationale를 입력·하한·비교 기준으로 사용하지 않았는가
- [ ] `unknown` 또는 `blocked` 상태에서 lane/G/filename을 만들지 않았는가
- [ ] 이전 lane/G, 실패 횟수, finding 개수를 승계하거나 자동 승격 근거로 사용하지 않았는가
- [ ] lane을 먼저 정하고 G 등급을 별도 차원 점수로 산정했는가
- [ ] 각 target에 formatter script를 실행했고 grade와 filename을 stdout 그대로 사용했는가
- [ ] build/review filename이 target별 formatter 결과와 정확히 일치하는가
- [ ] plan/build/review model identity 분리 조건을 runtime handoff에 남겼는가
- 확인 실패 시 결과를 `unrouted`로 폐기하고 누락된 정적 planning evidence부터 보강한 뒤 전체 평가를 다시 수행한다.
## 출력 형식
```yaml
status: routed | needs_evidence | blocked
evaluation_mode: first-pass | isolated-reassessment
targets:
build:
closures:
scope_closed: true
context_closed: true
verification_closed: true
evidence_trusted: true
ownership_closed: true
decision_closed: true
closure_basis:
scope_closed: "<current evidence>"
context_closed: "<current evidence>"
verification_closed: "<current evidence>"
evidence_trusted: "<current evidence>"
ownership_closed: "<current evidence>"
decision_closed: "<current evidence>"
lane: local
grade_scores:
scope_coupling: 1
state_concurrency: 1
blast_irreversibility: 1
evidence_diagnosis: 0
verification_complexity: 1
grade: G04
filename: PLAN-local-G04.md
review:
closures:
scope_closed: true
context_closed: false
verification_closed: true
evidence_trusted: false
ownership_closed: true
decision_closed: true
closure_basis:
scope_closed: "<current evidence>"
context_closed: "<current evidence>"
verification_closed: "<current evidence>"
evidence_trusted: "<current evidence>"
ownership_closed: "<current evidence>"
decision_closed: "<current evidence>"
lane: cloud
grade_scores:
scope_coupling: 1
state_concurrency: 1
blast_irreversibility: 1
evidence_diagnosis: 2
verification_complexity: 1
grade: G06
filename: CODE_REVIEW-cloud-G06.md
missing_evidence: []
blocked_reason: null
```
`needs_evidence` 또는 `blocked`에서는 해당 target의 `lane`, `grade_scores`, `grade`, `filename`을 `null`로 둔다.
## 금지 사항
- 이전 lane/G를 기본값, 최소값, 비교 기준으로 사용하지 않는다.
- `isolated-reassessment`에 별도 routing model을 요구하거나, 이를 근거로 한 모델이 plan/build/review 중 둘 이상을 맡게 하지 않는다.
- active review follow-up에서 `USER_REVIEW.md` gate가 아닌 blocker를 사용자 질문이나 `blocked` terminal로 바꾸지 않는다.
- 기존 평가가 있다는 이유로 같은 호출에서 재평가하는 것을 금지하지 않는다. 다만 이전 lane/grade/score/rationale/preferred route를 재평가 입력이나 하한으로 사용하지 않는다.
- local 실패를 이유로 cloud로 자동 승격하지 않는다.
- 높은 local G로 cloud에 필요한 컨텍스트나 판단을 보상하지 않는다.
- 파일 수, 동시성, dirty 상태, Required 개수 같은 단일 휴리스틱으로 lane을 정하지 않는다.
- grade나 filename을 formatter script 출력과 다르게 수작업으로 만들지 않는다.
- `needs_evidence`를 `cloud`로 치환하거나 미완성 상태에서 routed filename을 만들지 않는다.
- 실행 전 PASS evidence를 요구하거나 routing 중 구현 검증 명령을 실행하지 않는다.
- PLAN, CODE_REVIEW, archive, complete.log 파일을 직접 생성·수정·이동하지 않는다.
- 이 routing 스킬은 다음 역할을 시작하지 않는다. 호출 runtime은 handoff 후 반드시 다른 model identity를 배정한다.

4
agent-ops/skills/common/finalize-task-routing/agents/openai.yaml
View file

@ -1,4 +0,0 @@
interface:
display_name: "Finalize Task Routing"
short_description: "Finalize task lane, grade, and filenames"
default_prompt: "Use $finalize-task-routing to determine build/review capability routes while requiring distinct plan, build, and review model identities."

58
agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh
View file

@ -1,58 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
usage() {
printf '%s\n' \
'usage: finalize-task-route.sh <build|review> <local|cloud> <scope> <state> <blast> <evidence> <verification>' >&2
exit 2
}
if [[ $# -ne 7 ]]; then
usage
fi
target=$1
lane=$2
shift 2
scores=("$@")
case "$target" in
build)
prefix=PLAN
;;
review)
prefix=CODE_REVIEW
;;
*)
usage
;;
esac
case "$lane" in
local|cloud)
;;
*)
usage
;;
esac
sum=0
for score in "${scores[@]}"; do
case "$score" in
0|1|2)
sum=$((sum + score))
;;
*)
usage
;;
esac
done
if [[ $sum -lt 1 ]]; then
sum=1
fi
printf 'target=%s\n' "$target"
printf 'lane=%s\n' "$lane"
printf 'grade=G%02d\n' "$sum"
printf 'filename=%s-%s-G%02d.md\n' "$prefix" "$lane" "$sum"

25
agent-ops/skills/common/init-agent-ops/SKILL.md
View file

@ -1,6 +1,6 @@
---
name: init-agent-ops
version: 1.1.9
version: 1.1.8
description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드를 생성하기 위한 초기 규칙
---
@ -73,13 +73,12 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드
| `agent-ops/rules/project/domain/<domain>/rules.md` | 도메인 분석 후 생성 |
| `agent-ops/rules/private/` | 폴더만 생성 (내용은 개인이 작성) |
| `.gitignore`에 `agent-ops/rules/private/` 추가 | git 추적 제외 |
| `.gitignore`의 Agent-Ops 관리 block | `*.log` 같은 전역 ignore가 있어도 `agent-task/**/*.md`, `agent-task/**/*.log` task 산출물이 추적되도록 unignore하고 `agent-roadmap/current.md`는 로컬 포인터로 ignore |
| `agent-test/local/rules.md` | `init-agent-ops.sh`가 최소 내용으로 생성 |
| `agent-test/local/project-smoke.md` | 도메인이 아직 없으면 `init-agent-ops.sh`가 fallback baseline으로 생성 |
| `agent-test/local/<domain>-smoke.md` | domain rule 생성 후 각 도메인별 기본 smoke 테스트 뼈대로 생성 |
| `.gitignore`에 `agent-test/local/`, `agent-test/runs/` 추가 | `init-agent-ops.sh`가 local 테스트 환경/로그를 git 추적 제외 |
| `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore` | 사용자 항목은 보존하고 Agent-Ops 관리 block에 `agent-task/archive/**`, `agent-roadmap/archive/**` 추가 |
| `.claude/settings.json`, `opencode.json` | archive hard read/glob deny를 제거하고, 필요 시 명시 경로로 읽을 수 있게 둔다. `opencode.json`은 watcher ignore에 `agent-task/archive/**`, `agent-roadmap/archive/**`를 둘 수 있다 |
| `.claude/settings.json`, `opencode.json` | `agent-task/archive/**` 읽기/검색 제외 설정을 생성 또는 병합한다. `agent-roadmap/archive/**`는 필요 시 링크로 읽을 수 있어야 하므로 hard read/glob deny에서 제거한다 |
에이전트별 파일명:
@ -187,12 +186,11 @@ common/rules.md와 내용이 중복되지 않도록 한다.
3. **AI ignore / permission 기본 설정**
- `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에는 사용자 항목을 건드리지 않고 Agent-Ops 관리 block만 추가하거나 교체한다
- Agent-Ops 관리 block에는 `agent-task/archive/**`와 `agent-roadmap/archive/**`를 넣는다
- `.claude/settings.json`, `opencode.json`이 없으면 archive hard read/glob deny 없이 생성하고, 있으면 가능한 경우 기존 설정을 보존하며 archive hard read/glob deny를 제거한다
- archive는 일반 작업에서 읽지 않도록 AI ignore, watcher ignore, 공통 규칙으로 제한하되, `.claude/settings.json`이나 `opencode.json`의 hard read/glob deny에는 두지 않는다
- 기존 `.claude/settings.json`이나 `opencode.json`에 archive hard read/glob deny가 있으면 init-agent-ops 표준에 맞게 제거한다
- `.claude/settings.json`, `opencode.json`이 없으면 `agent-task/archive/**` 읽기/검색 제외 설정을 생성하고, 있으면 가능한 경우 기존 설정을 보존하며 필요한 제외 설정만 병합한다
- `agent-roadmap/archive/**`는 일반 작업에서 읽지 않도록 AI ignore와 로드맵 규칙으로 제한하되, `.claude/settings.json`이나 `opencode.json`의 hard read/glob deny에는 두지 않는다
- 기존 `.claude/settings.json`이나 `opencode.json`에 `agent-roadmap/archive/**` hard read/glob deny가 있으면 init-agent-ops 표준에 맞게 제거한다
- 대상 루트에 `.agent-ops-source`가 있으면 AI ignore / permission 파일은 보강하지 않는다
- `agent-task/archive/**`와 `agent-roadmap/archive/**` ignore 항목은 `.gitignore`에 추가하지 않는다
- `.gitignore`에는 Agent-Ops 관리 block으로 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`만 추가하거나 갱신한다
- `agent-task/archive/**`와 `agent-roadmap/archive/**` 제외는 `.gitignore`에 추가하지 않는다
4. **agent-ops 폴더 구조 복사**
- 공통 관리 레포의 `agent-ops/` 공통 폴더(bin, rules/common, skills/common)를 복사한다
@ -255,23 +253,22 @@ common/rules.md와 내용이 중복되지 않도록 한다.
- [ ] 생성된 domain rules.md가 `domain-rule-template.md` 형식을 따르는가
- [ ] `rules/project/rules.md`의 도메인 매핑 테이블에 생성된 도메인이 모두 등록되어 있는가
- [ ] `.gitignore`에 `agent-ops/rules/private/` 항목이 추가되어 있는가
- [ ] `.gitignore`에 Agent-Ops 관리 block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`가 포함되어 있는가
- [ ] `agent-test/local/rules.md`가 생성되었는가
- [ ] 생성되었거나 기존에 있던 모든 domain rule에 대응하는 `agent-test/local/<domain>-smoke.md`가 있는가
- [ ] domain rule이 아직 없으면 `agent-test/local/project-smoke.md` fallback이 있는가
- [ ] `agent-test/local/rules.md`에 생성된 테스트 profile 라우팅이 연결되었는가
- [ ] `.gitignore`에 `agent-test/local/`과 `agent-test/runs/`가 추가되어 있는가
- [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-roadmap/archive/**`가 포함되어 있는가
- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` 또는 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가
- [ ] 기존 archive hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가
- [ ] `.gitignore`에 `agent-task/archive/**` 또는 `agent-roadmap/archive/**` ignore 항목을 추가하지 않았는가
- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` 제외 설정이 있거나, 병합 불가 시 수동 병합 안내를 출력했는가
- [ ] `.claude/settings.json`, `opencode.json`에 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가
- [ ] 기존 `agent-roadmap/archive/**` hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가
- [ ] `.gitignore`에 `agent-task/archive/**` 또는 `agent-roadmap/archive/**`를 추가하지 않았는가
- 검증 실패 시: 누락된 파일/항목을 사용자에게 알리고 해당 부분만 보완한다
## 금지 사항
- 진입 파일에 rules/common/rules.md 외 내용을 추가하지 않는다.
- `agent-task/archive/**`와 `agent-roadmap/archive/**` ignore 항목을 `.gitignore`에 추가하지 않는다.
- `.gitignore`의 Agent-Ops 관리 task 산출물 unignore 예외를 제거하지 않는다.
- `agent-task/archive/**`와 `agent-roadmap/archive/**` 제외를 `.gitignore`에 추가하지 않는다.
- local 테스트 환경 파일을 git 추적 대상으로 만들지 않는다.
- domain rule이 확인된 경우 도메인별 기본 smoke 테스트 문서를 생략하지 않는다.
- 실제 구조보다 앞선 추상 구조를 강요하지 않는다.

471
agent-ops/skills/common/plan/SKILL.md
View file

@ -1,6 +1,6 @@
---
name: plan
description: "Analyze the repository and write routed PLAN/CODE_REVIEW pairs for initial work or archived WARN/FAIL findings. The plan model only plans, runtime gates dependencies, and a separate implementation model consumes only ready pairs. Plan, implementation, and review must use different model identities."
description: Analyze the current repository and write a detailed PLAN-{build_lane}-GNN.md for implementation work. Also writes the CODE_REVIEW-{review_lane}-GNN.md stub that the implementing agent will fill in after coding. Use for any feature, refactor, bug fix, or follow-up fix that should enter the plan-code-review loop. Milestone-linked work uses a reserved m-prefixed task group so runtime can route PASS completion events to update-roadmap. A separate implementing agent, or the same agent in an implementation pass, reads the plan file and does the coding.
---
# Plan
@ -10,41 +10,29 @@ description: "Analyze the repository and write routed PLAN/CODE_REVIEW pairs for
Create the planning artifacts for the implementation loop:
```text
plan model -> routed pair -> runtime dependency gate -> implementation model -> review-ready -> review model
^ |
+-------------------------------- plan-ready -------------------------------------+
plan skill -> PLAN-{build_lane}-GNN.md + CODE_REVIEW-{review_lane}-GNN.md stub
implementation -> code changes + filled CODE_REVIEW-{review_lane}-GNN.md, or blocked-state user-review request recorded in the review stub
code-review skill -> verdict + archive, complete.log, and PASS/user-review-resolved task-directory archive move, new follow-up plan/review files, or USER_REVIEW.md
runtime -> for m-prefixed PASS completion events, state check and optional update-roadmap call
```
After writing the pair, report `implementation-ready` only for a task whose encoded predecessors are satisfied; report `dependency-waiting` for an unsatisfied dependent task. Then stop.
`code-review` may stop the automatic loop with `USER_REVIEW.md` when repeated non-PASS reviews or first-review test environment blockers require a user decision. Verification evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are not user decisions by themselves; they should become normal follow-up plans that record the required evidence. Plan creation after `USER_REVIEW.md` requires an explicit user decision. If the user decision closes the task as complete/PASS, code-review resolves `USER_REVIEW.md`, writes `complete.log`, and archives the task instead of creating a new plan.
Role completion means leaving the routed PLAN/CODE_REVIEW pair and its readiness result; it does not include implementation or worker scheduling.
`code-review` writes `USER_REVIEW.md` only when a selected Milestone `구현 잠금 > 결정 필요` item blocks implementation. Other blockers become `plan-ready` findings.
Plan, implementation, and review use different model identities; separate agents using the same model do not satisfy this rule.
The plan file and review stub must be self-sufficient for implementation agents that do not read this skill. If implementation discovers a user-only decision, user-owned external environment prerequisite, or scope conflict that blocks safe progress, the implementing agent records a `사용자 리뷰 요청` in the active `CODE_REVIEW-*-G??.md`, leaves active files in place, and reports ready for review. The code-review skill validates that request and writes `USER_REVIEW.md` when the stop is justified. Use `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` as the shared section template.
## Workflow Contract
This skill intentionally uses routed active files under an active task directory as the state protocol. Do not change this directory or filename contract unless the paired code-review skill is updated together.
Role boundary:
- The plan model may inspect source/tests but must not edit them or run implementation verification.
- Write only PLAN/CODE_REVIEW files and required planning metadata.
- Do not implement, review, invoke `code-review`, or start another agent.
- Record the runtime-provided Plan model identity in both files. It is immutable for that pair; do not infer it from lane/G or agent name.
- Runtime, not the implementation worker, resolves encoded predecessor `complete.log` evidence and starts only `implementation-ready` tasks. The worker never searches task archives, interprets dependency state, or schedules siblings.
Task path terms:
- `{task_group}` is the top-level work category under `agent-task/`. Normal task groups use a short snake_case name such as `refactoring`.
- Milestone-linked work uses the reserved task group form `m-<milestone-slug>`, where `<milestone-slug>` is the active Milestone filename without `.md`.
- `{subtask_dir}` is an indexed executable sibling inside grouped work and follows the naming rules below, such as `01_core` or `02+01_db`.
- `{subtask_dir}` is used only for split work and follows the existing indexed directory naming rules below, such as `01_core` or `02+01_db`.
- `{subtask_name}` is the short snake_case name after the index or dependency prefix inside `{subtask_dir}`.
- `{task_name}` in headers and templates means the active task path relative to `agent-task/`: either `{task_group}` for a one-off task or `{task_group}/{subtask_dir}` for a grouped task.
- `{task_name}` in headers and templates means the active task path relative to `agent-task/`: either `{task_group}` for a single-plan task or `{task_group}/{subtask_dir}` for a split subtask.
- A single-plan task stores active files directly under `agent-task/{task_group}/`.
- Grouped work stores one active pair under each `agent-task/{task_group}/{subtask_dir}/`; the parent `agent-task/{task_group}/` must not contain active plan/review files.
- Initial planning may create immediate sibling pairs. A `plan-ready` follow-up keeps the exact existing task path and writes one replacement pair.
- Split work stores active files under `agent-task/{task_group}/{subtask_dir}/`; the parent `agent-task/{task_group}/` is only the grouping folder and must not contain active plan/review files.
Filename rules:
@ -52,32 +40,28 @@ Filename rules:
- Review stub: `CODE_REVIEW-{review_lane}-GNN.md`
- `{lane}` is only `local` or `cloud`; never put model names in filenames.
- `GNN` is a two-digit capability grade from `G01` to `G10`; the runtime maps lane+grade to current models externally.
- Lane, grade, and both canonical basenames come only from `agent-ops/skills/common/finalize-task-routing/SKILL.md`.
Generated pair boundary:
Role boundary rules:
- Runtime records the Implementation identity and verifies every encoded predecessor before dispatch. An unsatisfied dependent pair remains `dependency-waiting`.
- The implementation model receives only a ready pair, edits source/tests, fills implementation-owned review sections, then reports `review-ready` and stops. It does not inspect task/archive state.
- The review model judges and archives the pair. On WARN/FAIL, orchestration dispatches a different plan model; no model performs another role itself.
- Implementing agents fill implementation-owned `CODE_REVIEW-*-G??.md` sections, keep active files in place, and report ready for review.
- If implementation cannot continue without user input, implementing agents fill the review stub's `사용자 리뷰 요청` section with the exact decision needed, evidence, commands/output, and resume condition, then stop with active files in place. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts should be recorded in `검증 결과` or `계획 대비 변경 사항`, not escalated to user review.
- Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, review-only checklist) is code-review-skill only.
Planning-time verification boundary:
Split decision policy:
- This skill designs verification; build executes it and records actual output, and review validates the evidence and reruns commands required by its review scope.
- During planning, use repository files, manifests, scripts, workflows, rules, and already-recorded evidence only. Do not refresh existing evidence.
- Do not run compile, build, test, lint, source formatter, smoke/E2E, live/remote checks, package installation, dependency download, or cache warming while planning.
- Missing implementation-time output is not a planning evidence gap. Record the command, expected result, assumptions, and responsible build/review stage instead.
- Default to multiple subtask directories under one task group. Before writing any plan, decide whether the work has smaller independently reviewable implementation units.
- If there is any natural dependency boundary, ownership boundary, subsystem boundary, API-vs-call-site phase, test strategy split, or independently reviewable risk, write multiple subtask directories under one task group.
- A single plan is an exception. Use one only when all of these are true: the work is one coherent implementation unit, it has one primary ownership boundary, it has no prerequisite subtask, splitting would create artificial coordination overhead, and the whole change remains easy to review at once.
- When uncertain, split. Do not choose a single plan merely because it is shorter to write.
- Record the split decision in the plan. For a single plan, explicitly state why each applicable split boundary does not require a separate task. For multi-plan output, list the shared `{task_group}`, each sibling `{subtask_dir}`, and its dependency relationship.
Shallow sibling extraction policy:
Split gates:
- Treat a Milestone Epic or other broad request as a selection boundary. Select exactly one next executable Milestone Task or non-roadmap candidate; do not batch every Task in the Epic.
- Before loading implementation files in depth, use the selected Task, roadmap/SDD, repository structure, and targeted symbol/test inventory to make one shallow splitability check.
- If the selected Task has at least two clearly separable implementation or verification chunks and keeping them together would make local context unnecessarily broad, materialize the minimum complete set of immediate sibling tasks. Otherwise keep one task.
- Create one routed PLAN/CODE_REVIEW pair for every materialized sibling. Do not create empty directories, placeholder files, index-only reservations, decomposition caches, or manifests.
- Split only one level. Do not recursively subdivide siblings or expand into other Milestone Tasks. Reuse the shallow inventory and load only each sibling's required source/test regions.
- Account for the selected Task's required scope across the sibling set. Do not hide a known required chunk as deferred prose. Irreducible scope that has no coherent boundary remains one task and is handled by final cloud routing.
- Declare each sibling's intended write set and shared mutable state. Siblings may run in parallel only when their write sets are disjoint and they have no state, ordering, or contract-handoff dependency; read-only overlap is allowed.
- If write sets overlap or one sibling consumes another's state or contract, merge them or encode the producer as a `+` predecessor. Unknown overlap is not parallel-safe.
- Record the full immediate sibling set and real dependencies in every sibling plan. Approximate but bounded fan-out is preferred over exhaustive decomposition.
- Split when the work combines shared API/foundation changes with broad call-site rollout. Put the API/foundation in an earlier task and the rollout in dependent task(s).
- Split when the work touches multiple domains or ownership boundaries, unless the change is purely mechanical and trivially reviewable.
- Split when different parts can be verified with different focused tests or have different risk profiles.
- Split when a likely failure in one part would force rewriting unrelated parts of the plan.
- Split when one part can produce a useful `complete.log` before another part starts.
Task directory naming rules:
@ -85,71 +69,55 @@ Task directory naming rules:
- If the plan is based on a selected active Milestone, use `agent-task/m-<milestone-slug>/` as the task group. Do not include the Phase slug, Epic id, Task id, or a separate task slug in the task group.
- `m-<milestone-slug>` is a reserved top-level task group namespace for Milestone-linked work. Non-roadmap tasks must not use `m-`.
- Runtime completion-event routing for `m-*` reads only the top-level `{task_group}` name. It resolves `<milestone-slug>` by matching exactly one active file at `agent-roadmap/phase/*/milestones/<milestone-slug>.md`; archive paths are not target candidates.
- New Milestone/Epic task extraction creates either one indexed `{subtask_dir}` or the immediate sibling set selected by the shallow split.
- Choose the next two-digit index after all active sibling indices and archived sibling directory basenames for the same task group. Read archive basenames only; do not read archived file contents. Allocate consecutive indices only to siblings that will receive routed pairs in this invocation.
- Each indexed directory owns exactly one normal active plan file and one normal active review stub. The index increases for sorting but is not a serial execution dependency.
- When split gates require decomposition, create one shared category folder and multiple subtask directories under it. Each subtask directory owns exactly one normal active plan file and one normal active review stub.
- Multi-plan output is a set of independent `PLAN-{build_lane}-GNN.md` + `CODE_REVIEW-{review_lane}-GNN.md` pairs across `agent-task/{task_group}/{subtask_dir}/` folders, not multiple plan files inside one folder.
- Multi-plan subtask directory names must start with a stable two-digit task index. The index must increase across sibling subtask directories for sorting, but it is not a serial execution dependency.
- Use `NN_{subtask_name}` for a task with no runtime dependencies, e.g. `01_core`, `04_docs`, `05_ui`.
- Use `NN+PP[,QQ...]_{subtask_name}` for a task that depends on earlier task indices, e.g. `02+01_db`, `03+01,02_api`, `06+05_integration`.
- Valid independent pattern: `^[0-9]{2}_[a-z0-9_]+$`.
- Valid dependent pattern: `^[0-9]{2}\+[0-9]{2}(,[0-9]{2})*_[a-z0-9_]+$`.
- `NN`, `PP`, and `QQ` are two-digit indices. Every predecessor index after `+` must be lower than `NN` and must refer to a sibling indexed task directory under the same `{task_group}`.
- `NN`, `PP`, and `QQ` are two-digit indices. Every predecessor index after `+` must be lower than `NN` and must refer to a sibling multi-plan subtask directory under the same `{task_group}`.
- The first `_` after the index or dependency list starts `{subtask_name}`. `{subtask_name}` stays short snake_case and may contain additional underscores.
- Scheduling contract: a runtime that consumes task directories reads only `{subtask_dir}`; `_` means `depends_on=[]`, and `+` means `depends_on` is the comma-separated index list between `+` and the first `_`. Before worker dispatch, runtime requires one unambiguous matching predecessor `complete.log` for every encoded index. This skill records dependencies and readiness but does not start or schedule workers.
- An independent `NN_...` name asserts that its write set and shared mutable state do not conflict with concurrently runnable siblings. Any write/state/ordering/contract conflict must appear as `NN+PP[,QQ...]_...` or be merged into one sibling.
- Runtime scheduling reads only the `{subtask_dir}` name: `_` means `depends_on=[]`; `+` means `depends_on` is the comma-separated index list between `+` and the first `_`.
- Subtask directory names are the source of truth for runtime dependencies. Do not hide extra dependencies only in the plan body, and do not create a bare `NN+{subtask_name}` without predecessor indices.
- A predecessor index is satisfied by a `complete.log` for the matching predecessor subtask under the same `{task_group}`. Check active siblings first, then matching archived subtasks across all archive month folders. This is a narrow exception to the normal archive skip rule: read only candidate predecessor `complete.log` files needed to prove split dependency completion.
- For predecessor index `PP`, the only valid active lookup candidates are `agent-task/{task_group}/PP_*/complete.log` and `agent-task/{task_group}/PP+*/complete.log`.
- For predecessor index `PP`, the only valid archive lookup candidates are `agent-task/archive/*/*/{task_group}/PP_*/complete.log` and `agent-task/archive/*/*/{task_group}/PP+*/complete.log`.
- Archive lookup matches the predecessor index at the start of the archived subtask directory name, such as `01_...` or `01+...`, under the same `{task_group}`. If multiple candidates match one predecessor index, do not choose by guess; record the ambiguity and require a concrete task path or runtime selection.
- Do not treat an archived predecessor as the active task to edit. Archive lookup is only for dependency satisfaction before writing or implementing a dependent split plan.
- `01_core`, `02+01_edge_integration`, and `03+01_node_integration` express two integrations that may run in parallel after `01_core` completes. A shallow split may create all three routed sibling pairs in one invocation.
- Example: split a refactoring common core plus two app integrations under `agent-task/refactoring/` as `01_core`, `02+01_edge_integration`, `03+01_node_integration`. Both integrations depend only on `01_core` and may run in parallel after `01_core` has `complete.log`.
- Example: split three sequential tasks under one task group as `01_schema`, `02+01_migration`, `03+02_api`.
- Example: split independent docs/UI plus an integration under one task group as `01_core`, `02+01_db`, `03+02_api`, `04_docs`, `05_ui`, `06+05_integration`; `01_core`, `04_docs`, and `05_ui` can start together, and `06+05_integration` waits only for `05_ui`.
- Preserve task group and subtask directory names verbatim; do not normalize, reinterpret, or choose execution order by agent judgment.
Final routing boundary:
Routing rules:
- Do not estimate, inherit, or write lane/G while analyzing. Keep the task `unrouted` until plan scope, split, verification design, ownership, decision facts, and available existing evidence are complete.
- Execute `agent-ops/skills/common/finalize-task-routing/SKILL.md` for both `build` and `review` after analysis. Its routed outputs are the only source for active PLAN/CODE_REVIEW filenames.
- Apply this boundary independently to every first-pass sibling and to each review WARN/FAIL or USER_REVIEW replan.
- A previous loop's lane, grade, score, rationale, and filename are quarantined. Prior code paths, recorded command output, and review findings may be carried as raw evidence after confirming their path and revision relevance without rerunning commands.
- `needs_evidence` requires missing static planning facts and a fresh full routing run. It must not trigger implementation verification. A first-pass `blocked` may prevent loop entry; once a selected review loop is active, a valid Milestone-lock decision routes to `USER_REVIEW.md`, while every other limitation becomes a routed follow-up with its blocker evidence and deterministic release condition.
- If plan facts change after routing, invalidate both target results and run final routing again before writing files.
- Treat non-behavioral review artifact drift and obvious non-behavioral source nits as current-scope evidence; they do not bypass final routing.
- Build defaults to `local` when the plan is explicit, tests are runnable, and failure is review-detectable.
- Use `cloud` for weak tests, broad API/call-site impact, ambiguity, storage/concurrency/protocol/auth risk, or prior local failure.
- Use `cloud-G07` or higher for terminal-agent work: shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, or terminal benchmark-style tasks. Merely running deterministic tests such as `go test` does not make a task terminal-agent work.
- Use `cloud-G07` or higher when acceptance depends on a real interactive external tool, TUI, PTY, browser, screen repaint/cursor stream, or bin-level smoke output. This is mandatory when unit tests pass but the real smoke/integration command fails.
- Use `cloud-G07` or higher when a prior review found missing, untrusted, reconstructed, or rerun-mismatched verification evidence.
- Keep high-risk design judgment on `cloud` with a higher grade; the runtime may map `cloud-GNN` to frontier-class models.
- Review may be `local` for narrow/low-risk checks and `cloud` for multi-file/API/test-meaning reviews, security/auth, storage/migration, concurrency, protocol/schema, cross-domain, or repeated Required issues.
- Raise `GNN` with scope, ambiguity, missing tests, irreversible behavior, and blast radius; keep grade model-independent.
Directory states:
| State | Meaning |
|-------|---------|
| `PLAN-*-G??.md` only | Invalid; plan skill always writes both active files |
| `STAGED_BATCH.md` | Multi-sibling write transaction; finish every listed sibling before reporting |
| `STAGED_PLAN.md` only | Pair write interrupted; render the matching staged review from this fixed plan without rerouting |
| `STAGED_PLAN.md` + `STAGED_CODE_REVIEW.md` | Pair is fully staged; verify and promote both without rerouting |
| unstarted active pair + staged replacement | Explicit replan transaction; archive only the old pair, then promote the staged pair |
| one old active member + its archived counterpart + staged replacement | Interrupted replan archive; finish the old archive, then promote the staged pair |
| routed PLAN plus matching `STAGED_CODE_REVIEW.md` | Partial promotion; promote the staged review and do not rewrite the PLAN |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub, dependencies satisfied | `implementation-ready`; a different implementation model consumes the pair |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub, dependencies unsatisfied | `dependency-waiting`; runtime does not dispatch the implementation model |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md`, dependencies satisfied | `review-ready`; a different review model consumes the pair |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md`, dependencies unsatisfied | `dependency-waiting`; runtime does not dispatch the review model |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with appended verdict | Review finalization pending; the plan model must not modify it |
| `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), with exact final archive/event metadata fixed before the final task-directory archive move |
| `USER_REVIEW.md` + `*.log` files | Linked Milestone decision is required before planning |
| Highest numeric-suffix matching `user_review_*.log` has `## 상태` value `RESOLVED` and `해소 결과 > 결과` value `REPLAN`, with no active pair | Resolved user-review `plan-ready`; create one follow-up pair from that log and its referenced archived pair |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub | Implementation is pending/in progress |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation claims a user-only blocker; ready for code-review to validate and create `USER_REVIEW.md` only if justified |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill |
| `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), before final task-directory archive move |
| `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; user decision is required before creating another plan |
| `agent-task/archive/YYYY/MM/{task_name}/complete.log` + `*.log` files | Archived completed task path (PASS or user-review-resolved PASS); not active |
| Matching archived plan/review logs with WARN/FAIL | `plan-ready`; create one follow-up pair from those exact logs |
| Only `*.log` files (no `complete.log`) | Task terminated mid-loop or abandoned |
## Step 1 - Determine Task
If the user names an exact existing task path for continuation or replan, use it. Do not treat a Milestone/Epic id or title as an exact task path.
Any plan-creation request scoped to a Milestone, Epic, or other broad roadmap item enters new-task extraction mode unless it selects an existing indexed task. Select one Milestone Task inside the requested Epic before applying sibling extraction.
If the user names the task explicitly, use that task group or task path.
Otherwise, find active plan files with both globs, excluding `agent-task/archive/**`:
- `agent-task/*/PLAN-*-G??.md`
- `agent-task/*/*/PLAN-*-G??.md`
Find `agent-task/*/STAGED_BATCH.md`, then `STAGED_PLAN.md` and `STAGED_CODE_REVIEW.md` with the task-depth globs before classifying active plans or selecting a new task. A staged state wins selection and resumes every listed sibling at Steps 5-6 with the recorded Plan model identity, without rerouting or a new task path. Do not apply active-pair stop rules until that transaction finishes.
Also note active user-review stops, excluding `agent-task/archive/**`:
- `agent-task/*/USER_REVIEW.md`
@ -157,165 +125,117 @@ Also note active user-review stops, excluding `agent-task/archive/**`:
| Result | Action |
|--------|--------|
| Exactly one | Select it, then apply the active-state guards below |
| Exactly one | Continue that task |
| None | Create a new task only for a feature/refactor/fix/follow-up that belongs in this workflow |
| Multiple | If the user/runtime named a task group, task path, or subtask directory that identifies exactly one active plan, use it. Otherwise list paths and stop with an ambiguity report; do not choose by agent judgment and do not create a user-review request for routing ambiguity. |
| Multiple | If the user/runtime named a task group, task path, or subtask directory that identifies exactly one active plan, use it. Otherwise list paths and ask which task to use; do not choose by agent judgment. |
For an exact task path with no active pair, inspect durable evidence in this order:
The routed plan file is the loop entry point. A missing active plan normally means only that no plan has been started for a new task; do not create task files for casual analysis, status, or review requests unless the user explicitly asks for a plan.
1. If the highest numeric-suffix matching `user_review_*.log` has `## 상태` value `RESOLVED` and `해소 결과 > 결과` value `REPLAN`, require its referenced archived plan/review pair, treat all three files as `plan-ready` evidence, use the next monotonic plan number, and refuse the handoff if the current Plan model identity matches either forbidden identity recorded in the resolution log.
2. Otherwise accept follow-up planning only when the highest numeric-suffix matching archived review log is WARN/FAIL, its plan log is identifiable, and the archived review does not contain a valid unresolved Milestone-lock user-review gate. Treat that pair as `plan-ready` evidence, use the next monotonic plan number, and refuse the handoff if the current Plan model identity matches the archived Implementation or Review identity.
3. If the archived review contains a valid unresolved user-review gate and no matching resolved log exists, return the task to code-review recovery so it writes or restores `USER_REVIEW.md`; do not plan.
If no active plan exists but one or more `USER_REVIEW.md` files exist, report that user decision is required and list the paths unless the user explicitly asked to resume one of them. If a selected active task directory contains `USER_REVIEW.md`, read it before planning. Do not write a new follow-up plan unless the user explicitly decides to continue, replan, retry after preparing the environment, or change the task scope. When planning resumes from `USER_REVIEW.md`, archive it to `user_review_N.log` in the same task directory before writing the new active plan/review pair, and record the user decision in the new plan `배경` or `분석 결과`.
If `USER_REVIEW.md` exists, do not plan until a review model resolves and archives it.
If a selected task directory contains both `USER_REVIEW.md` and an active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, do not overwrite either state or ask the user to choose between files. Treat a valid unresolved `USER_REVIEW.md` as the terminal state; otherwise return the exact paths and provenance to code-review finalization/recovery so it can continue from evidence rather than waiting for another instruction.
If an active review already has a verdict, leave it unchanged and report that review finalization is required.
Before reporting readiness for an indexed active pair, validate its basename against `NN_{subtask_name}` or `NN+PP[,QQ...]_{subtask_name}` and require every predecessor to be lower than `NN`. Return a malformed pair for Plan path migration; never dispatch it or report it as ready.
If the selected active pair is an unfilled stub, resolve its encoded predecessor evidence. Report `implementation-ready` only when all predecessors are satisfied; otherwise report `dependency-waiting`. Replan it only when the user explicitly requests replan before implementation starts. If its implementation-owned sections are filled and it has no verdict, report `review-ready` and stop.
If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, report an inconsistent loop state and do not overwrite either state until the user decides whether to resume from user review or continue the active plan/review.
로드맵 확인:
- `agent-roadmap/current.md`는 브랜치별 로컬 포인터다. 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다.
- `agent-roadmap/priority-queue.md`가 있으면 명시 target이 없는 구현 계획에서 Phase를 가로지르는 후보 순서를 확인하기 위해 읽는다. 큐 순서는 우선순위 참고이며, 상태/잠금/기능 원본은 각 Milestone 문서다.
- 사용자가 target Milestone을 명시하지 않았고 요청이 "다음 작업" 또는 일반 구현 계획이면 `priority-queue.md`의 위에서 아래 순서 중 요청과 맞고 활성 경로에 존재하는 첫 Milestone을 우선 후보로 둔다.
- `priority-queue.md` 링크가 깨졌으면 Milestone을 추측해 계획하지 말고 `update-roadmap`으로 큐 재정렬/재생성이 필요하다고 보고한다.
- `agent-roadmap/`이 있는데 `current.md`가 없으면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 로컬 파일을 만들거나, `ROADMAP.md`의 Phase 흐름과 관련 `PHASE.md`에서 후보를 고른 뒤 로컬 current를 채운다. current 없음만으로 일반 task routing으로 빠지지 않는다.
- `agent-roadmap/current.md`가 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다.
- `current.md`가 `agent-roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 활성 Phase/Milestone이 아니라고 보고한다.
- 선택한 Phase를 한 번 읽어 Phase 목표, Milestone 흐름, Phase 경계를 확인한다.
- 선택한 Milestone을 한 번 읽어 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. `승격 조건`은 `[스케치]`에서만 필수이며, `[계획]` 이상에서 섹션이 없으면 `없음`으로 본다. `구현 잠금` 섹션이 없거나, 상태가 `잠금`이거나, 미완료 `결정 필요` 항목이 하나라도 있으면 실구현 계획을 만들지 않는다.
- 구현 잠금에 걸린 Milestone에서는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, task directory, file/API/package 수준 구현 단계를 확정하지 말고 `구현 잠금 차단`으로 보고한다. 보고에는 Milestone 경로, 잠금 상태, 남은 `결정 필요` 항목, 다음에 필요한 `update-roadmap` 조치를 적는다.
- 남은 `결정 필요` 항목이 현재 실구현 범위가 아니라고 판단되더라도 같은 plan 요청 안에서 구현 계획을 계속 쓰지 않는다. 먼저 roadmap-only 갱신으로 해당 항목을 `범위 제외`, 후속 Milestone, 또는 `작업 컨텍스트`로 옮기고 `구현 잠금`을 `해제`한 뒤 새 plan 요청에서 진행한다.
- 선택한 Milestone에 `SDD: 필요`가 있으면 승인된 SDD를 구현 계획 작성의 입력으로 읽는다. SDD 문서가 없거나, 상태가 `[승인됨]`이 아니거나, `SDD 잠금`이 `잠금`이거나, 같은 디렉터리에 `USER_REVIEW.md`가 있으면 plan 파일을 만들지 말고 `roadmap-sdd` 또는 `update-roadmap` 조치가 필요하다고 보고한다.
- `SDD: 필요` Milestone의 구현 계획은 Milestone 기능 Task만 보고 작성하지 않는다. 요청 대상 Task id에 연결된 SDD Acceptance Scenario와 Evidence Map을 먼저 매핑하고, 그 결과에서 구현 범위, checklist, 검증 명령, 완료 evidence를 역산한다. 매핑이 없거나 SDD와 Milestone Task가 어긋나면 plan 생성을 멈추고 SDD와 Milestone의 정합성 갱신이 필요하다고 보고한다.
- 선택한 Milestone에 legacy `필수 기능`/`완료 기준`이 분리되어 있으면 plan 파일을 만들지 말고 `update-roadmap` 정규화가 필요하다고 보고한다.
- 선택한 Milestone을 한 번 읽어 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. `승격 조건`은 `[스케치]`에서만 필수이며, `[계획]` 이상에서 섹션이 없으면 `없음`으로 본다. `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인하고, 그 결정 없이는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, file/API/package 수준 구현 단계를 확정하지 않는다.
- 선택한 Milestone에 legacy `필수 기능`/`완료 기준`이 분리되어 있으면 plan 작성 전에 roadmap preflight로 정규화한다. 흡수 가능한 기준은 관련 기능 Task 안의 선택적 `검증:` 또는 Task 설명으로 즉시 흡수하고, 어느 기능에도 붙지 않는 기준이 남으면 plan 파일을 만들지 말고 남은 기준과 필요한 사용자 판단을 구체적으로 보고한다.
- 선택한 Phase 또는 Milestone 상태가 `[스케치]`이면 구현 계획 파일을 만들지 않는다. `[스케치]`는 컨셉 상태이므로 `update-roadmap`의 concretize 흐름으로 승격 조건, 결정 필요, 범위, 기능 Task를 정리해 `[계획]`으로 전환해야 한다고 보고한다.
- Phase 또는 Milestone 후보가 여럿이면 요청 문장, 변경 경로 직접성, Milestone 상태, 구현 잠금, 선후 의존성, Phase/Milestone 흐름상 위치를 기준으로 1순위와 2순위를 추천하고 필요한 후보 문서만 읽어 범위를 좁힌다.
- 로드맵 current가 있고 활성 Phase/Milestone 밖 작업이면 `ROADMAP.md`의 Phase 흐름을 확인하고 전환, 신규 Phase/Milestone, 또는 기존 활성 범위 내 배치 필요성을 보고한다.
- 사용자가 선택한 Milestone의 작업, 구현, 계획 작성을 명시했더라도 `구현 잠금`이 완전히 해제되어 있지 않으면 계획 작성을 이어가지 않는다. Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없을 때만 roadmap update 흐름으로 `구현 잠금` 상태를 `해제`로 갱신할 수 있다.
- 제품 선택, 우선순위 결정처럼 에이전트가 확정할 수 없는 항목은 구현 계획의 실행 checklist로 쓰지 않는다. 그런 항목이 남아 있으면 plan 생성을 멈추고 `구현 잠금 > 결정 필요`로 분리한다.
- 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조, 도메인 rule, 플랫폼 관례로 정할 수 있는 세부는 표준선/가정으로 계획에 기록하고 진행할 수 있다.
- 사용자가 선택한 Milestone의 작업, 구현, 계획 작성을 명시했고 현재 계획에 필요한 결정이 모두 정해져 있다면 계획 작성을 이어간다. Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 roadmap update 흐름으로 `구현 잠금` 상태를 `해제`로 갱신한다. 현재 요청에 직접 걸리는 결정이 필요하면 그 항목만 체크리스트로 남기고 사용자에게 확인한다.
- 사용자 검토, 제품 선택, 우선순위 결정처럼 사용자가 해야 하는 항목은 구현 계획의 실행 checklist로 쓰지 않는다. 현재 구현에 직접 필요하면 plan 생성을 멈추고 `결정 필요`로 남기며, 직접 필요하지 않으면 `작업 컨텍스트`나 `범위 결정 근거`에만 기록한다.
- 기능 Task에 `검증:`이 있으면 구현 계획의 같은 plan item 안에 해당 검증을 포함한다. 검증이 명시되지 않은 기능 Task에는 억지 검증 항목을 만들지 말고, 필요한 일반 빌드/회귀 확인만 최종 검증에 둔다.
- 선택한 활성 Milestone 범위에 속하는 구현 계획이면 `{task_group}`을 `m-<milestone-slug>`로 정한다. `<milestone-slug>`는 선택한 Milestone 경로의 파일명에서 `.md`를 제거한 값이다.
- Milestone 또는 Epic 범위의 plan 생성은 먼저 Milestone Task 하나를 선택하고, 그 Task가 크면 immediate sibling pair들을 `agent-task/m-<milestone-slug>/<subtask_dir>/` 아래에 함께 만든다. Epic은 선택 범위일 뿐 완료 대상으로 쓰지 않는다.
- Milestone 기능 Task 완료를 목표로 하는 계획이면 `Roadmap Targets` 섹션에 활성 Milestone 경로와 완료 대상 Task id를 고정한다. Sibling split에서는 모든 필수 sibling을 선행 조건으로 가진 closure sibling 하나에만 이 섹션을 둔다. 자연스러운 마지막 sibling이 없으면 작은 integration/verification closure sibling을 만든다. 이 섹션은 `complete.log`의 `Roadmap Completion` 근거로 복사되어 `update-roadmap`이 해당 Task만 체크하는 anchor가 된다. `{task_group}`이 해당 Milestone slug의 `m-<milestone-slug>`일 때만 쓴다.
- Milestone 작업이 아니거나, Milestone 안의 조사/부분 구현처럼 이번 작업만으로 특정 기능 Task 완료를 주장할 수 없으면 `Roadmap Targets` 섹션을 쓰지 않는다. 해당 기능 Task의 남은 acceptance를 실제로 닫는 마지막 작업에만 넣는다. 섹션이 없으면 PASS 후에도 roadmap Task 체크를 하지 않는다.
- `agent-roadmap/` 디렉터리가 없으면 기존 task routing 규칙대로 진행한다.
- 같은 Milestone에서 split work가 필요하면 기존 split 규칙 그대로 `agent-task/m-<milestone-slug>/<subtask_dir>/` 아래에 계획 파일을 만든다.
- roadmap/current 파일이 없으면 기존 task routing 규칙대로 진행한다.
Use short snake_case task group names for non-roadmap work, e.g. `api_refactor`.
Before choosing plan files or task directory names, apply the shallow sibling extraction policy once. Choose one task directory or a complete immediate sibling set. Do not put multiple active plan files in one task directory or mix indexed task directories with active plan/review files directly in the parent task group.
Before choosing plan files or task directory names, apply the split decision policy above. When the policy allows a single plan, write active files directly under `agent-task/{task_group}/` and record the exception rationale. When the policy requires multiple plans, choose one shared `{task_group}` and `{subtask_dir}` names using the task directory naming rules above. Do not put multiple active plan files in one active task directory, and do not mix split subtask directories with active plan/review files directly in the parent task group.
## Step 2 - Analyze Before Writing
Complete these four items before creating active plan/review files. The only allowed pre-plan edits are local `agent-roadmap/current.md` creation or `.gitignore` repair needed for routing. Report test-rule gaps separately; do not create or update test rules while planning.
Complete all items below before creating any files. Work through them in order; do not proceed to the next step until every checkbox is done.
- [ ] **Fix scope and split once** — select one executable candidate from the request and required roadmap/SDD context. Keep it whole or freeze one immediate sibling set; do not recurse.
- [ ] **Fix directories and dependencies** — allocate indices, encode real predecessors, and confirm concurrent siblings have disjoint writes and no shared state or ordering conflict. Resolve only the predecessor `complete.log` paths required by dependent siblings.
- [ ] **Inspect the implementation surface** — read targeted source/test regions, affected contracts, renamed or removed symbol references, and relevant manifests. Identify obvious dependency, import, type, or implementation risks statically; do not load unrelated files or compile.
- [ ] **Write the verification contract** — use the user-selected `test_env` or `local` by default. Read applicable rules/profiles or a static fallback, then record test additions or gaps, exact commands, workdir, expected results, cache policy when stale results could hide failure, and any non-local preflight assumptions. Do not execute commands, probe environments, or mutate test rules.
- [ ] **Read all source files in full** — read every source file the change will touch, whole file. No partial reads.
- [ ] **Read all test files in full** — read every test file that exercises the changed behavior.
- [ ] **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.
- [ ] **Grep all symbol references** — for any renamed or removed symbol, find every call site and import chain.
- [ ] **Check dependency manifests** — before adding any new package, verify its presence in go.mod / package manifest.
- [ ] **Pre-check compile issues** — identify missing interface implementations, type mismatches, and broken imports.
- [ ] **Verify verification commands** — confirm that the final verification commands actually run in this repository layout.
- [ ] **Stabilize fragile verification** — for search or generated-output checks, choose deterministic commands up front, such as `rg --sort path`, and decide whether cached test output is acceptable or `-count=1` is required.
## Step 3 - Finalize Task Routing
## Step 3 - Determine GXX Grade
This step is mandatory and must be the last semantic decision before routed filenames are fixed. Complete Step 2 and prepare the full plan structure in memory before starting it.
GXX is an output of analysis, not an input. Determine lane and grade only after Step 2 is fully complete.
- [ ] **Build neutral input** — for each sibling, prepare its scope, affected paths, invariants, context size, sibling-set position, verification plan, available existing evidence, ownership, unresolved decisions, and existing failure evidence for `build` and `review`. Exclude every previous lane, grade, routing score, rationale, filename, and archive basename that exposes them.
- [ ] **Select evaluation mode** — use `first-pass` for new work and `isolated-reassessment` for `plan-ready` findings. Exclude the previous lane, grade, score, rationale, and preferred route.
- [ ] **Run the routing skill** — read and fully execute `agent-ops/skills/common/finalize-task-routing/SKILL.md` with both targets independently for each sibling. Do not reproduce or replace its decision logic inside this skill. Do not return `blocked` merely because a separate evaluation context or explicit follow-up instruction is unavailable.
- [ ] **Resolve non-final states** — for `needs_evidence`, collect only static planning facts and rerun. Never execute implementation verification.
- [ ] **Accept only a fully routed set** — require independent `build` and `review` closure records, lane, grade scores, GNN, and canonical filename for every sibling. If any new sibling is not routed, write none of the new sibling batch.
- [ ] **Freeze the result** — use each sibling's exact basenames in Steps 4-6. If any routing input or sibling boundary changes before files are written, discard the affected set and repeat this step.
- [ ] **Assess change scope** — count affected files, interface impact, and call-site count.
- [ ] **Check risk factors** — mark any that apply: concurrency, storage/migration, protocol/schema, auth, irreversible behavior.
- [ ] **Evaluate test confidence** — judge whether existing tests sufficiently verify the changed behavior.
- [ ] **Decide lane** — use `local` if the plan is explicit and tests are sufficient; use `cloud` if any of the following apply:
- Tests are weak or do not cover the changed behavior
- Broad API/call-site impact
- Concurrency, storage, protocol, or auth risk
- Prior local build failure on this task
- Terminal-agent work: shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, or terminal benchmark-style tasks
- Real bin/smoke/integration verification failed after unit tests passed
- Interactive TUI/PTY/browser/external CLI automation or screen-rendered output is part of the success condition
- A prior review marked verification trust Fail/Warn because recorded command output did not match a rerun
- [ ] **Decide GNN** — assign a higher grade as scope, ambiguity, irreversibility, and blast radius increase. Grade is complexity-based, not model-name-based.
## Step 4 - Prepare Task Files
## Step 4 - Archive Existing Active Files
Apply this step independently to every routed sibling directory. Do not archive or overwrite unrelated active siblings.
Before writing new active files for the chosen active task directory:
- Validate that the task directory contains at most one active routed pair, at most one staged pair, and at most one `USER_REVIEW.md`. Reject ambiguous, malformed, or identity-mismatched files.
- For multi-sibling work, require at most one `STAGED_BATCH.md` in the task-group parent.
- Ensure `.gitignore` exposes task Markdown and log files.
- Do not archive review artifacts. A `plan-ready` pair is already archived by the review model.
- For an explicit replan with an unstarted active pair, calculate its archive destinations but defer renames until the replacement pair is fully staged.
- Use monotonic suffixes for the new pair's future archive names.
- Count existing `agent-task/{task_name}/plan_*.log`; call it `N`. If `PLAN-*-G??.md` exists in that same directory, rename `PLAN-{build_lane}-GNN.md` to `plan_{build_lane}_GNN_N.log`.
- Count existing `agent-task/{task_name}/code_review_*.log`; call it `M`. If `CODE_REVIEW-*-G??.md` exists in that same directory, rename `CODE_REVIEW-{review_lane}-GNN.md` to `code_review_{review_lane}_GNN_M.log`.
- Count existing `agent-task/{task_name}/user_review_*.log`; call it `U`. If `USER_REVIEW.md` exists in that same directory and the user explicitly decided to resume planning, rename `USER_REVIEW.md` to `user_review_U.log`.
Set each `next_log_suffix` to `0` when no matching log exists, otherwise `max(existing numeric suffix) + 1`. A normal new pair uses those suffixes. An explicit replacement archives the old pair at those suffixes and uses suffix plus one for the staged pair. Set `plan_number=plan_log_number`.
The new plan number is the count of `plan_*.log` after archiving.
## Step 5 - Render Plan File
Render each complete plan in memory. Do not write the routed PLAN basename yet.
## Step 5 - Write Plan File
Header line must be exactly:
```markdown
<!-- task={task_name} plan={plan_number} tag={TAG} -->
```
Write the immutable Plan identity in a second metadata comment:
```markdown
<!-- plan-model={plan_model_identity} -->
<!-- task={task_name} plan={N} tag={TAG} -->
```
Required sections:
- Title.
- `구현 에이전트 규칙`: keep this to four short bullets:
- runtime has already verified encoded predecessor dependencies before dispatch; do not search `agent-task/**` or `agent-task/archive/**`;
- change only the listed implementation files and follow the checklist/verification contract;
- fill only implementation-owned fields in the review stub;
- report `review-ready` and stop without reviewing, archiving, writing terminal files, or starting another agent.
- `배경`: 1-3 sentences explaining why the work is needed.
- `Archive Evidence Snapshot`: include this section only when the plan resumes from a resolved `user_review_*.log`, a prior archived review, or any archive evidence. Omit it for first-pass plans with no archive evidence. For resolved user review, include the resolution log path, decision, evidence, and its referenced archived pair. The section must otherwise contain only the archive facts needed to implement without rereading archive by default: prior task/archive paths, verdict, Required/Suggested/Nit summary, affected files, verification evidence, and any roadmap carryover. If exact prior context is still required, cite the specific archive file paths allowed to read; do not ask the implementer to search `agent-task/archive/**` broadly.
- `Roadmap Targets`: include this section only when the plan is intended to complete one or more existing Milestone 기능 Task ids. In a sibling set, include it only in the closure sibling whose directory dependencies cover every required predecessor. Omit the section entirely for non-roadmap work or partial siblings that should not check a Task on PASS. Format exactly:
```markdown
## Roadmap Targets
- Milestone: `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- Task ids:
- `<task-id>`: <Task text or concise label>
- Completion mode: check-on-pass
```
- `Agent UI Completion`: include this section only when the plan implements agent-ui definition/frame/component changes in code and code-review PASS should move specific agent-ui documents to `status: 구현됨`. Omit it for non-agent-ui work, `direct-sync` work handled entirely by `sync-agent-ui`, and `milestone-required` work whose status update is intentionally deferred to Milestone 종료 검토. Format exactly:
```markdown
## Agent UI Completion
- Mode: review-pass-status-update
- Agent UI docs:
- `agent-ui/definition/views/<view-id>/index.md`
- Required code evidence:
- `<code path>`: <what proves the UI definition is implemented>
- Required implementation verification:
- `<test or analysis command>`: PASS expected before review
- Review finalization validation:
- `validate-agent-ui scope=<scope>`: PASS expected after status/evidence update
- Status updates on PASS:
- `agent-ui/definition/views/<view-id>/index.md`: `계획` -> `구현됨`
```
- `구현 범위`: give the worker only execution-relevant facts:
- exact write set;
- required behavior, invariants, and public/inner contract constraints;
- only the source/spec/test-rule paths needed while implementing;
- tests to add or update;
- explicit exclusions.
Keep routing scores, lane rationale, full read inventories, split deliberation, and dependency-resolution history out of the generated plan. The routed filenames and task directory already preserve those decisions. For SDD work, include only the applicable SDD path, Acceptance Scenario ids, Milestone Task ids, and required evidence behavior.
- `구현 체크리스트`: a top-level checklist the implementing agent must follow while coding. Include one item per implementation/verification unit; if the roadmap feature Task has `검증:`, keep that verification in the same checklist item. Make the final item exactly: `- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 채우고 review-ready를 보고한 뒤 현재 실행을 종료한다. code-review를 실행하거나 다음 에이전트를 시작하지 않는다.` Copy it into the review stub unchanged.
- `이 파일을 읽는 구현 에이전트에게`: warn that filling implementation-owned `CODE_REVIEW-*-G??.md` sections is mandatory. Tell the implementer to run verification, fill actual notes/output, keep active files in place, and report ready for review; finalization is code-review-skill only. Also state that if implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, the implementer must fill the review stub's `사용자 리뷰 요청` section with exact evidence and stop for code-review; the implementer does not create `USER_REVIEW.md`, archive logs, or write `complete.log`. State that evidence gaps a follow-up agent can close by rerunning commands or collecting artifacts are not user-review requests by themselves.
- `배경`: 2-4 sentences explaining why the work is needed.
- `사용자 리뷰 요청 흐름`: state that implementation-time blockers are recorded in the active review stub's `사용자 리뷰 요청` section, copied from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`; code-review owns validation and the actual `USER_REVIEW.md` file write.
- `분석 결과`: 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 and test file read during analysis, with path.
- `테스트 커버리지 공백`: 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.
- `범위 결정 근거`: state which files or areas were explicitly excluded from this change and why. This is the boundary justification — the implementing agent must not silently expand scope beyond what is recorded here.
- `빌드 등급`: state the decided lane and GNN grade with a one-line rationale.
- `구현 체크리스트`: a top-level checklist the implementing agent must follow while coding. Include one item per implementation/verification unit; if the roadmap feature Task has `검증:`, keep that verification in the same checklist item instead of making a separate completion-criteria item. Include one item for whole-plan intermediate/final verification only when it is not already covered by the feature items, and make the final item exactly: `- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.` Copy this checklist into the review stub's `구현 체크리스트` section with the same item text and order.
- One item per change: `### [TAG-1] Title`, `TAG-2`, etc.
- `수정 파일 요약`: table mapping files to item ids.
- `최종 검증`: runnable commands and expected outcome. Prefer commands from the matched agent-test env/profile rules. The final line must read exactly — **"검증 결과를 review stub에 기록하고 review-ready를 보고한 뒤 현재 실행을 종료한다. code-review를 실행하거나 다음 에이전트를 시작하지 않는다."**
- `최종 검증`: runnable commands and expected outcome. Commands must be exact and deterministic enough for the reviewer to rerun; use stable ordering for searches and state whether cached test output is acceptable. The final line of this section must read exactly — **"모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다."**
Each plan item must include the applicable fields below:
Each plan item must include:
- `문제`: concrete problem with file:line references.
- `해결 방법`: exact approach and before/after code block for non-trivial changes.
- `수정 파일 및 체크리스트`: exhaustive file-level checklist.
- `테스트 작성`: explicit write/skip decision. If writing tests, include path, test name, assertion goal, and fixtures. If skipping, justify.
- `중간 검증` (optional): include it only when a later plan item depends on that result; otherwise rely on final verification.
- `중간 검증`: runnable commands and expected result.
Describe within-task implementation order only when one plan item depends on another. Do not copy sibling dependency status into the generated plan or instruct the implementation worker to inspect `complete.log`; `{subtask_dir}` and runtime remain the dependency source of truth.
Include `의존 관계 및 구현 순서` only when order matters.
For split multi-plan work, the `{subtask_dir}` directory name is the runtime source of truth. If a plan has a `NN+PP[,QQ...]_...` subtask directory name, `의존 관계 및 구현 순서` must echo the decoded predecessor subtask directories under the same task group that must produce `complete.log` before implementation starts, and it must not add dependencies that are absent from the directory name.
Quality rules:
@ -339,43 +259,147 @@ Test policy:
Verification fidelity rules:
These are execution rules for build and review, not commands for the plan author to run.
- 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.
- If mobile/UI verification has no progress for 2 minutes or times out, stop blind retries; collect focused stdout plus screenshot/window/UI-tree evidence when available, or record why capture is impossible.
- If the plan's pass condition says all leftovers must be intentional exceptions, any `변경 필요` item forces FAIL until resolved or explicitly reclassified with evidence.
- Decide in the plan whether Go test cache output is acceptable. If fresh execution matters, use `go test -count=1 ...`.
## Step 6 - Write Review Stub
Read `agent-ops/skills/common/plan/templates/review-stub-template.md` in full only after Step 3 returns `status: routed` for the complete new sibling set.
Replace every occurrence of each token below:
Use the template below exactly. Fill `{…}` placeholders from the plan; everything else is fixed and must not be changed by the implementing agent.
Copy `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` into the review stub's `사용자 리뷰 요청` section.
- Scalar tokens: `{date}`, `{task_name}`, `{plan_number}`, `{TAG}`, `{plan_model_identity}`.
- Plan-copy tokens: `{roadmap_targets_or_omit}`, `{archive_evidence_snapshot_or_omit}`, `{agent_ui_completion_or_omit}`, `{implementation_checklist}`, `{review_checkpoints}`.
- Generated row/section tokens: `{implementation_completion_rows}` contains one row for every plan item, and `{verification_result_sections}` contains the fixed verification instructions plus every intermediate/final command from the plan.
- `{implementation_user_review_request_section}` is replaced by the full contents of `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`; do not prepend another `사용자 리뷰 요청` heading.
```markdown
<!-- task={task_name} plan={N} tag={TAG} -->
`{review_checkpoints}` contains only product behavior, scope, contract, and verification focuses useful while implementing. Do not include model identity, dependency/`complete.log`, archive, terminal-output, or finalization checks; the Review skill owns those controls.
# Code Review Reference - {TAG}
Use the routed build/review grades independently. Remove optional plan-copy content by replacing its token with an empty string, not by leaving template instructions.
Do not write any pair when a sibling's routing target is not `routed`. After rendering, scan every stub for the exact template-token inventory above and reject the output if any known token remains; do not reject unrelated braces in copied commands or code.
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
For a multi-sibling set, first write `STAGED_BATCH.md` with the task group, Plan identity, complete sibling paths, frozen scopes, routed basenames, and source-evidence fingerprints. Recovery must finish every listed pair without changing scope/routing; reject fingerprint drift. Remove the batch marker only after all listed pairs are verified.
## 개요
For each sibling, write the complete plan to `STAGED_PLAN.md`, then the complete stub to `STAGED_CODE_REVIEW.md`. An existing staged plan is immutable: use it as the render source, create only a missing staged review, and reject conflicts. Verify both headers, identities, routed basenames, and bodies before promotion.
date={YYYY-MM-DD}
task={task_name}, plan={N}, tag={TAG}
For an explicit replacement, preflight the old pair's calculated log destinations after both staged files exist, then rename the old review and old plan. On interruption, match the remaining old member, archived counterpart, and staged pair by task/plan headers; finish only the missing old archive and never overwrite a log.
## 이 파일을 읽는 리뷰 에이전트에게
Preflight both routed destinations, then rename `STAGED_PLAN.md` to the routed PLAN basename and `STAGED_CODE_REVIEW.md` to the routed CODE_REVIEW basename. If only the PLAN was promoted, verify it against the staged identity and promote only the remaining review. Never reroute or create a second PLAN during staged recovery.
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
After every pair is promoted, resolve only its encoded predecessor `complete.log` evidence and report the pair path with exactly one readiness value: `implementation-ready` or `dependency-waiting`. Do not start an implementation agent. Runtime re-evaluates a waiting task before later dispatch.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-{review_lane}-GNN.md` → `code_review_{review_lane}_GNN_N.log`, `PLAN-{build_lane}-GNN.md` → `plan_{build_lane}_GNN_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [{TAG}-1] {item description} | [ ] |
| [{TAG}-2] {item description} | [ ] |
## 구현 체크리스트
{copy the plan's 구현 체크리스트 items exactly, preserving order and checkbox text}
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다.
- [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
## 주요 설계 결정
_구현 에이전트가 주요 설계 결정 사항을 기록한다._
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
{pre-filled from plan — one bullet per review focus area}
## 검증 결과
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
### {TAG}-1 중간 검증
```
$ {verification command from plan}
(output)
```
### 최종 검증
```
$ {final verification command from plan}
(output)
```
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.
```
Sections and their ownership:
| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) |
| 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
| 구현 체크리스트 (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only; final checkbox is mandatory before saving |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required to proceed; when filled, include exact decision, evidence, commands/output, why automatic follow-up cannot resolve it, and resume condition |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
| 검증 결과 (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `계획 대비 변경 사항` entry |
| 코드리뷰 결과 | Review agent appends | Not included in stub |
## Naming
@ -388,13 +412,16 @@ After every pair is promoted, resolve only its encoded predecessor `complete.log
## Final Checklist
- Every planned sibling has one fully routed PLAN/CODE_REVIEW output pair for the correct task path, with matching headers, checklist, conditional sections, and no template tokens.
- No `STAGED_BATCH.md`, `STAGED_PLAN.md`, or `STAGED_CODE_REVIEW.md` remains after every routed pair is verified.
- Directory names encode every real dependency; parallel siblings have no write, state, ordering, or contract conflict. Unsatisfied dependent siblings are reported as `dependency-waiting`, not dispatched.
- `Roadmap Targets`, Agent UI, archive evidence, and user-review sections appear only when their stated conditions apply and match between PLAN and CODE_REVIEW; concise SDD targets remain in the PLAN implementation scope.
- Verification records the selected environment, static sources, test decision, commands, and expected results without plan-time execution output. Intermediate verification appears only when it adds an early failure signal.
- The plan model wrote the routed pair, reported `implementation-ready` or `dependency-waiting` from dependency evidence, and stopped without implementing, reviewing, or starting another agent.
- An explicitly replaced unstarted pair was archived only after its replacement pair was fully staged, with distinct monotonic log suffixes.
- Follow-up routing does not inherit prior lane/G, and implementation/user-review ownership remains unchanged.
- Every generated review ledger states the three-model separation, and the PLAN worker rules state the one-role-per-invocation boundary.
- The PLAN metadata comment and review ledger contain the same runtime-provided Plan model identity; Implementation and Review identities remain pending until runtime starts those roles.
- `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` both exist under the active task directory `agent-task/{task_name}/`.
- Single-plan work stores active files directly under `agent-task/{task_group}/`.
- Split work, if any, uses one shared `agent-task/{task_group}/` parent and one subtask directory per plan/review pair with names like `01_core`, `02+01_edge_integration`, `03+01_node_integration`; dependency details live in the subtask directory name as `NN+PP[,QQ...]_subtask_name`.
- Milestone-linked work uses `agent-task/m-<milestone-slug>/` as the task group; non-roadmap task groups do not start with `m-`.
- Both first lines match `<!-- task={task_name} plan={N} tag={TAG} -->`.
- Previous active files, if any, were archived with correct numeric suffixes.
- If resuming from `USER_REVIEW.md`, it was archived to `user_review_N.log` and the user decision was recorded in the new plan.
- 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.
- The plan's implementer instructions and review stub both explain the implementation-time `사용자 리뷰 요청` stop path.
- The review stub includes the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`.
- The review stub has a clearly marked `코드리뷰 전용 체크리스트` owned only by the review agent.
- Routed review file completion table lists every plan item.

4
agent-ops/skills/common/plan/agents/openai.yaml Normal file
View file

@ -0,0 +1,4 @@
interface:
display_name: "Plan"
short_description: "Write implementation plans"
default_prompt: "Use $plan to create grouped PLAN/CODE_REVIEW task files for this repository change."

59
agent-ops/skills/common/plan/templates/review-stub-template.md
View file

@ -1,59 +0,0 @@
<!-- task={task_name} plan={plan_number} tag={TAG} -->
# Code Review Reference - {TAG}
> **[IMPLEMENTATION WORKER]**
> Complete the implementation checklist, fill the implementation evidence below, report `review-ready`, and stop.
> Edit only completion checkboxes, `계획 대비 변경 사항`, `주요 설계 결정`, `사용자 리뷰 요청`, Agent UI implementation evidence when present, and command output blocks.
> Do not edit role identities, review, archive, create terminal files, or start another agent. Runtime and the later Review model own those actions.
> Do not ask the user directly. Use `사용자 리뷰 요청` only for a selected Milestone `구현 잠금 > 결정 필요`; record other blockers in the implementation evidence.
## 개요
date={date}
task={task_name}, plan={plan_number}, tag={TAG}
## 역할 모델
- Plan: `{plan_model_identity}`
- Implementation: `pending`
- Review: `pending`
> Runtime-only ledger. Runtime requires three distinct model identities; the implementation worker does not edit it.
{roadmap_targets_or_omit}
{archive_evidence_snapshot_or_omit}
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
{implementation_completion_rows}
## 구현 체크리스트
{implementation_checklist}
{agent_ui_completion_or_omit}
## 계획 대비 변경 사항
_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
## 주요 설계 결정
_구현 에이전트가 주요 설계 결정 사항을 기록한다._
{implementation_user_review_request_section}
## 리뷰어를 위한 체크포인트
{review_checkpoints}
## 검증 결과
{verification_result_sections}
---
> Before saving, fill every implementation-owned field and command output. Then report `review-ready` and stop.

79
agent-ops/skills/common/refine-local-plans/SKILL.md
View file

@ -1,79 +0,0 @@
---
name: refine-local-plans
description: 현재 plan들 세분화해, 현재 plan 세분화, 기존 plan 더 나눠, local plan 분리해 같은 요청에서 이미 생성된 미착수 local plan을 유지하거나 최대 3개의 local sibling plan으로 한 단계 분리할 때 사용한다. 현재 Worker용 PLAN/CODE_REVIEW 형식, 유효한 runtime dependency 이름, readiness를 함께 갱신한다.
---
# refine-local-plans
## 목표
기존 미착수 local pair를 더 작은 실행 단위로 한 번만 나눈다. 문서와 runtime dependency를 갱신하되 구현 조사, 실행 검증, Worker/Review 시작은 하지 않는다.
## 대상
- 사용자가 지정한 `agent-task/{task_group}` 또는 `PLAN-local-G??.md`를 대상으로 삼는다.
- 대상을 생략하면 미착수 local pair가 있는 active task group이 정확히 하나일 때만 사용한다. 여러 개면 후보만 보고한다.
- 대상은 active PLAN/CODE_REVIEW pair가 있고 Implementation/Review identity와 구현 소유 필드가 아직 채워지지 않았으며 verdict가 없는 작업이다.
- `complete.log` 또는 `USER_REVIEW.md`가 있는 작업과 이미 구현이 시작된 pair는 제외한다. 이전 loop의 `*.log`만 있다는 이유로 미착수 follow-up pair를 제외하지 않는다.
- 대상 또는 dependency가 바뀌는 direct dependent가 이미 구현 중이면 분리하지 않는다.
- 대상 pair와 실제 dependency가 바뀌는 미착수 sibling pair만 읽는다.
- index 할당에는 같은 task group의 active directory name과 archived sibling directory basename만 사용한다. Readiness 판정에 필요한 direct predecessor `complete.log`만 active/archive에서 좁게 읽고 Worker 문서에는 그 경로나 상태를 쓰지 않는다.
- Roadmap, source, test 또는 다른 `SKILL.md`를 추가로 읽거나 호출하지 않는다. PLAN만으로 독립 경계가 명확하지 않으면 유지한다.
## 절차
1. **범위를 고정한다**
- 각 PLAN의 목적, write set, checklist, verification, encoded dependency만 정리한다.
- CODE_REVIEW는 미착수 여부, Plan identity, checklist, 명령만 확인한다.
- Active directory name으로 direct dependent를 찾고 실제 dependency가 바뀌는 미착수 pair만 대상에 추가한다.
2. **유지 또는 분리를 결정한다**
- 의미 있는 독립 경계가 두 개면 2개, 세 개면 최대 3개로 한 단계만 분리한다.
- 각 child는 단독 구현 가능한 결과와 겹치지 않는 write set을 가져야 한다. 공유 상태나 dependency가 더 복잡해지면 유지한다.
- 원본 checklist와 verification을 담당 child에 빠짐없이 배분하되 실행하지 않는다.
3. **경로와 dependency를 확정한다**
- 이름은 `NN_{subtask_name}` 또는 `NN+PP[,QQ...]_{subtask_name}`만 사용한다. 모든 predecessor는 `NN`보다 작고 같은 task group의 sibling이어야 한다.
- 첫 child는 가능한 경우 원본 index와 기존 predecessor를 유지한다. 추가 child는 active/archive basename에 없는 다음 index를 사용한다.
- 직렬 child에만 실제 predecessor를 comma-separated로 표시하고 병렬 child에는 dependency를 만들지 않는다.
- 기존 direct dependent가 새 child를 의존해야 하는데 predecessor index가 그 dependent의 index 이상이면, 해당 미착수 dependent를 다음 collision-free index로 옮긴다. `02+01+03`처럼 더 큰 index를 참조하는 이름은 만들지 않는다.
- 변경 대상 directory, PLAN header, review header와 `개요 > task`는 같은 최종 task path를 사용한다. Historical `*.log`의 header는 수정하지 않는다.
- 원본에 `Roadmap Targets`가 있으면 모든 필수 child를 거친 closure child 하나에만 둔다. 그런 closure를 만들 수 없으면 분리하지 않는다.
4. **현재 Worker 형식으로 pair를 만든다**
- Build/review lane과 G는 원본을 유지하고 재라우팅하지 않는다.
- 현재 runtime-provided Plan model identity를 PLAN metadata와 review ledger에 동일하게 기록한다. Implementation/Review는 `pending`으로 둔다.
- PLAN은 `구현 에이전트 규칙` 네 bullet, 짧은 `배경`, 실행에 필요한 `구현 범위`, checklist, 항목, 수정 파일, 검증만 둔다. 원본에 `Archive Evidence Snapshot`이 있으면 구현에 필요한 finding과 affected path만 담당 child에 보존한다.
- 분석 파일 목록, routing 점수, 분할 과정, dependency 상태/경로와 전체 archive history를 Worker PLAN에 쓰지 않는다.
- CODE_REVIEW는 `agent-ops/skills/common/plan/templates/review-stub-template.md`의 compact Worker 구조를 사용한다. Product behavior/scope/contract/verification checkpoint만 넣고 dependency, `complete.log`, archive, finalization, review 전용 checklist는 넣지 않는다.
- PLAN과 CODE_REVIEW의 checklist 문구·순서와 검증 명령을 정확히 맞춘다.
5. **한 transaction으로 교체한다**
- 모든 최종 pair를 먼저 메모리에서 완성한다. Task-group parent에 `STAGED_BATCH.md`를 쓰고, 각 영향받는 directory에는 `STAGED_PLAN.md`와 `STAGED_CODE_REVIEW.md`를 모두 쓴 뒤 교체를 시작한다.
- Marker에는 task group, Plan identity, old-to-new directory mapping, 최종 pair basenames를 기록한다. 중단 시 이 mapping만 재개하고 scope/index를 다시 결정하지 않는다.
- 교체되는 미착수 active pair는 기존 lane/G와 monotonic suffix로 archive한 뒤 directory를 필요한 최종 이름으로 옮긴다. 교체 pair의 `plan_number`는 그 archive 다음 suffix를 사용하고, 새 child는 기존 log가 없으면 `0`을 사용한다. 기존 log를 덮어쓰거나 수정하지 않는다.
- 모든 staged pair의 header, identity, checklist, 명령을 검증한 뒤 최종 basename으로 promote한다. 모든 pair가 확인된 뒤에만 `STAGED_BATCH.md`를 제거한다.
6. **Readiness를 보고한다**
- 각 최종 directory의 encoded predecessor만 확인한다.
- 모두 충족되면 `implementation-ready`, 하나라도 미충족이면 `dependency-waiting`을 보고한다.
- Worker 또는 Review를 시작하지 않는다.
## 출력
```text
Local plan refinement
- targets: <원본 PLAN 경로>
- decisions: <유지 | 원본 -> child 목록>
- dependency updates: <변경 내용 또는 없음>
- readiness: <pair path = implementation-ready | dependency-waiting>
- document check: passed
```
## 금지
- Inventory/validator script, compile, build, test, lint, formatter, smoke/E2E, live/remote 검증을 실행하지 않는다.
- Source/test 재분석, verification 실행, package 설치, dependency 다운로드, cache warming을 하지 않는다.
- `plan` 또는 `finalize-task-routing`으로 child를 재라우팅하지 않는다.
- 관련 없는 active sibling 재인덱싱, repository 밖 staging, 전체 task group 복원을 하지 않는다.
- Plan 밖 구현 범위를 추가하거나 child를 재귀 분리하지 않는다.

213
agent-ops/skills/common/roadmap-sdd/SKILL.md
View file

@ -1,213 +0,0 @@
---
name: roadmap-sdd
version: 1.0.0
description: 로드맵 Milestone에 녹아 있는 SDD 설계 게이트를 판정, 생성, 갱신, 사용자 리뷰 대기, 잠금 해제, archive 처리할 때 사용한다. 사용자가 SDD, spec gate, 설계 게이트, SDD 필요 여부, SDD 승인 준비, SDD 사용자 리뷰, SDD 잠금 해제, SDD archive를 요청하거나, 큰 Milestone의 구현 잠금이 SDD 필요 상태일 때 사용한다.
---
# Roadmap SDD
## 목적
큰 Milestone에서 로드맵만으로 부족한 계약, 상태 전이, 수용 시나리오, 검증 근거를 `agent-roadmap/sdd/` 아래에 기록한다.
SDD는 로드맵과 분리된 별도 운영물이 아니라 Milestone `구현 잠금`을 해제하고, 이후 Milestone 구현 계획이 따라야 할 설계 입력을 고정하는 하위 설계 게이트다.
`SDD: 필요` Milestone의 구현 계획은 승인된 SDD의 Acceptance Scenario와 Evidence Map에서 구현 범위, 검증, 완료 evidence를 역산해야 한다.
## 모드
- `classify`: Milestone 또는 신규 작업 설명이 SDD 대상인지 판정한다.
- `create`: SDD 초안을 만든다.
- `update`: 기존 SDD를 갱신한다.
- `check-gate`: SDD 잠금, 사용자 리뷰, Acceptance Scenario, Evidence Map 연결성을 확인한다.
- `review-ready`: 사용자 결정이 필요한 항목을 `USER_REVIEW.md`로 만든다.
- `resolve-review`: 사용자의 답변을 SDD에 반영하고 `USER_REVIEW.md`를 `user_review_N.log`로 보낸다.
- `archive`: Milestone archive와 함께 SDD를 archive 경로로 이동할 준비 상태인지 확인한다.
## 구조
```text
agent-roadmap/
sdd/
<phase-slug>/
<milestone-slug>/
SDD.md
USER_REVIEW.md
user_review_0.log
archive/
sdd/
<phase-slug>/
<milestone-slug>/
SDD.md
user_review_*.log
```
- `USER_REVIEW.md`는 필요한 경우에만 존재한다.
- `user_review_N.log`는 해결된 사용자 리뷰 기록이다.
- 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/`로 이동한다.
- SDD 경로는 같은 Milestone의 slug를 그대로 사용한다. 별도 SDD slug를 만들지 않는다.
## 표준 형식
- `SDD.md`는 반드시 `agent-ops/skills/common/_templates/roadmap-sdd-template.md`의 top-level 섹션을 같은 순서로 사용한다.
- `Source of Truth`, `State Machine`, `Acceptance Scenarios`, `Evidence Map` 표는 템플릿의 컬럼을 유지한다.
- 값이 아직 없으면 섹션을 삭제하지 말고 `없음`, `확인 필요`, 또는 잠금 항목으로 남긴다.
- `update`는 기존 SDD의 내용을 갱신하더라도 표준 섹션과 순서를 유지한다. 누락된 표준 섹션이 있으면 먼저 복원한 뒤 변경을 반영한다.
- `check-gate`는 표준 섹션이나 필수 표 컬럼이 누락된 SDD를 `invalid`로 보고하고, Milestone 구현 잠금 해제 대상으로 보지 않는다.
- SDD별 추가 설명은 `작업 컨텍스트` 또는 해당 표준 섹션 안에 넣고 임의 top-level 섹션을 늘리지 않는다.
- SDD 안에서 Milestone, Phase, 계약 문서, `USER_REVIEW.md`, 후속 SDD 같은 문서 포인터를 남길 때는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
- SDD 링크 target은 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/` 디렉터리 기준 상대경로로 쓴다. 예: `[Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md)`, `[PHASE.md](../../../phase/<phase-slug>/PHASE.md)`, `[USER_REVIEW.md](USER_REVIEW.md)`.
- 실제 생성/갱신한 SDD에는 `<phase-slug>`, `<milestone-slug>`, `<path>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
- 코드 source path나 machine-readable identity는 raw 값이 필요하면 유지할 수 있다.
## SDD 대상 판정
아래 중 하나라도 해당하면 `SDD: 필요`로 판정한다.
- cross-repo 계약 또는 프로젝트 간 source of truth가 있다.
- Plane, Jira, Mattermost 같은 외부 provider 상태를 변경한다.
- lifecycle, state machine, 사용자 승인 gate, archive 자동화, work item sync에 영향을 준다.
- idempotency, retry, identity map, revision 보존이 필요하다.
- API, proto, config, env, DB/schema, 이벤트 계약을 바꾼다.
- field smoke, 원격 runner, 사용자 소유 환경이 완료 근거의 일부다.
- 실패 처리 방식이 제품 판단, 보안, 비용, 권한, 데이터 보존에 영향을 준다.
아래에만 해당하면 `SDD: 불필요`로 판정한다.
- 단일 repo 내부의 작고 국소적인 리팩터링이다.
- 문서 정리, 테스트 보강, 작은 UI 보강이다.
- Milestone Task의 `검증:`과 일반 plan/code-review 루프만으로 완료 판단이 충분하다.
- 기존 SDD 또는 agent-contract를 그대로 소비하고 새 설계 결정이 없다.
## Milestone 연결
SDD가 필요한 Milestone은 `구현 잠금`에 아래 필드를 둔다.
```md
- 상태: 잠금
- SDD: 필요
- SDD 문서: [SDD.md](../../../sdd/<phase-slug>/<milestone-slug>/SDD.md)
- 잠금 해제 조건:
- [ ] SDD 잠금이 해제되어 있다
- [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다
- [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
- [ ] Evidence Map이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증 가능하게 연결되어 있다
- 결정 필요: 없음
```
SDD가 불필요한 Milestone은 사유를 남긴다.
```md
- SDD: 불필요
- SDD 사유: 단일 repo 내부 변경이며 외부 계약, 상태 머신, provider mutation이 없다.
```
## SDD 잠금
SDD 문서는 자체 잠금을 가진다.
- `SDD 잠금: 잠금`이면 Milestone `구현 잠금` 해제 대상이 아니다.
- `USER_REVIEW.md`가 존재하면 사용자 답변 전까지 SDD 잠금을 해제하지 않는다.
- 사용자 결정이 필요 없는 기술 세부는 agent가 코드, 규칙, 기존 계약을 근거로 채우고 잠금 항목으로 만들지 않는다.
- 모든 잠금 항목이 해결되고 사용자 리뷰가 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 둔다.
- SDD 잠금이 해제되어야 Milestone `구현 잠금`도 해제 후보가 된다.
사용자 리뷰가 필요한 항목:
- source of truth 선택
- 상태 전이 의미 변경
- 사용자 승인, 검토, 폐기 흐름 변경
- 외부 provider 쓰기 동작 추가
- cross-repo 책임 경계 변경
- scope 확대/축소
- 보안, 비용, 데이터 보존, 권한 영향
- 실패 시 처리 정책이 제품 판단인 경우
사용자 리뷰가 필요 없는 항목:
- 기존 코드/문서/rule에서 답이 명확한 세부
- 기존 agent-contract를 그대로 따르는 인터페이스
- 일반 파일 구조, 테스트 명령, Evidence Map 작성
- 구현자가 plan/code-review 루프에서 검증할 수 있는 기술 선택
## 실행 절차
### classify
1. 관련 Milestone 또는 신규 작업 설명을 읽는다.
2. SDD 대상 판정 기준을 적용한다.
3. 결과를 `필요`, `불필요`, `불명확` 중 하나로 보고한다.
4. `필요`이면 Milestone `구현 잠금`에 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크와 잠금 해제 조건을 갱신한다.
5. 신규 Milestone 생성 또는 `[스케치] -> [계획]` 승격 흐름에서 호출된 경우, `classify`에서 멈추지 않고 같은 턴에 `create`까지 이어간다. 사용자만 결정할 항목이 없으면 승인 가능한 SDD로 만들고, 사용자 결정이 있으면 SDD 초안과 `USER_REVIEW.md`를 함께 만든다.
### create
1. `agent-ops/skills/common/_templates/roadmap-sdd-template.md`를 읽는다.
2. 대상 Milestone의 목표, 범위, 기능 Task, 범위 제외, 구현 잠금을 읽는다.
3. 필요하면 `agent-contract/index.md`를 읽고 매칭 계약 원문을 링크한다. 계약 본문을 SDD에 복제하지 않는다.
4. 표준 템플릿의 top-level 섹션, 섹션 순서, 필수 표 컬럼을 유지해 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`를 만든다.
5. 사용자 결정이 필요한 항목이 있으면 `review-ready`를 수행한다. 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 둘 수 있다.
6. SDD가 `[승인됨]`이고 SDD 잠금이 `해제`이며 `USER_REVIEW.md`가 없으면 같은 흐름의 `update-roadmap` 갱신에서 Milestone `구현 잠금` 해제 후보로 반영한다.
### update
1. 기존 SDD와 Milestone을 읽는다.
2. 변경 요청이 문제, source of truth, 상태 전이, interface, scenario, evidence 중 어디에 해당하는지 판정한다.
3. 표준 섹션 또는 필수 표 컬럼이 누락되어 있으면 먼저 복원한다.
4. 사용자 결정이 필요한 변경이면 SDD 잠금을 `잠금`으로 두고 `USER_REVIEW.md`를 갱신한다.
5. 기술 세부 보강이면 SDD 본문과 Evidence Map만 갱신한다.
### check-gate
1. Milestone `구현 잠금`의 `SDD` 필드를 확인한다.
2. `SDD: 불필요`이면 `not-required`로 보고한다.
3. `SDD: 필요`인데 SDD 문서가 없으면 `blocked`로 보고한다.
4. SDD가 표준 top-level 섹션 또는 필수 표 컬럼을 갖추지 못했으면 `invalid`로 보고한다.
5. SDD 상태가 `[승인됨]`이 아니거나 `SDD 잠금`이 `잠금`이면 `blocked`로 보고한다.
6. `USER_REVIEW.md`가 있으면 `blocked`로 보고한다.
7. Acceptance Scenario가 Milestone 기능 Task id와 연결되어 있는지 확인한다.
8. Evidence Map이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증될 수 있도록 scenario, task, evidence가 매핑되어 있는지 확인한다.
9. 모두 충족하면 `pass`로 보고한다.
### review-ready
1. `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md`를 읽는다.
2. 사용자만 결정할 항목만 추린다.
3. `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md`를 만든다.
4. SDD의 `SDD 잠금`을 `잠금`으로 둔다.
5. 채팅으로 즉시 선택지를 묻지 않고 파일 경로와 필요한 결정만 보고한다.
### resolve-review
1. `USER_REVIEW.md`와 SDD를 읽는다.
2. 사용자의 답변을 관련 SDD 섹션과 `사용자 리뷰 이력`에 반영한다.
3. `USER_REVIEW.md`를 `user_review_N.log`로 이동한다.
4. 남은 잠금 항목이 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 바꾼다.
5. SDD gate가 pass이면 Milestone `구현 잠금`을 해제할 수 있다고 보고한다. 직접 해제는 요청 또는 runtime/update-roadmap 흐름에 따른다.
### archive
1. Milestone이 `[완료]` 또는 `[폐기]`인지 확인한다.
2. 활성 SDD 디렉터리가 있으면 `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/`로 이동한다.
3. 활성 `PHASE.md` 또는 Milestone archive 링크와 SDD archive 경로가 어긋나지 않는지 확인한다.
4. `USER_REVIEW.md`가 남아 있으면 archive하지 말고 해결 필요로 보고한다.
## 출력 형식
```markdown
## SDD 결과
- mode: `<classify|create|update|check-gate|review-ready|resolve-review|archive>`
- milestone: <[Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md) | 해당 없음>
- sdd: <[SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) | 없음>
- 결과: `<pass | blocked | not-required | created | updated | review-required | archived | invalid>`
- 잠금: `<해제 | 잠금 | 해당 없음>`
- 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md) | [user_review_N.log](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/user_review_N.log)>
- 다음 단계: `<없음 | 사용자 리뷰 필요 | Milestone 구현 잠금 해제 가능 | SDD 작성 필요>`
```
## 금지 사항
- SDD 본문에 agent-contract 계약 원문을 복제하지 않는다.
- 사용자 결정이 필요한 항목을 chat 질문으로 바로 던지지 않는다. `USER_REVIEW.md`로 남긴다.
- 작은 작업에 SDD를 강제하지 않는다.
- `USER_REVIEW.md`가 남아 있는데 SDD 상태를 `[승인됨]`으로 두지 않는다.
- SDD gate가 막힌 Milestone의 구현 잠금을 해제하지 않는다.

38
agent-ops/skills/common/router.md
View file

@ -1,59 +1,21 @@
# 공통 스킬 라우터
라우팅 우선순위:
- SDD/spec gate 자체의 작성, 갱신, gate 확인, 사용자 리뷰, 잠금 해제는 `roadmap-sdd`로 보낸다.
- 로드맵/마일스톤 생성 또는 갱신 요청 안에 SDD 필요 여부와 gate 연결이 포함되면 `create-roadmap` 또는 `update-roadmap`을 진입점으로 삼고, 해당 흐름에서 `roadmap-sdd` create/check를 처리한다.
- agent-spec은 구현 후 현재 상태를 설명하는 living spec이다. SDD/spec gate와 구분하며, 현재 구현 스펙 생성은 `create-spec`, 갱신은 `update-spec`으로 보낸다.
- "마일스톤 완료해도 될지 검토", "현 마일스톤 종료 검토", "현재 마일스톤 닫고 다음 마일스톤 지정"처럼 종료 판단, spec sync, roadmap archive, 다음 Milestone 지정을 함께 요구하는 요청은 `complete-milestone`으로 보낸다. 이 흐름 안에서 `update-spec`을 필수 gate로 수행한다.
- 구현 계획 요청에서 선택 Milestone의 구현 잠금이 남아 있으면 `plan`은 구현 계획을 만들지 않고 잠금 차단을 보고한다.
- SDD 생성/갱신/잠금 해제는 `roadmap-sdd` 또는 `update-roadmap` 요청으로 처리한다.
- 런타임이 `origin-task`/`complete-log` 단건 완료 이벤트를 전달한 경우는 `update-roadmap`으로 처리한다. PASS task 이동 뒤에는 archived `complete.log`의 `Finalization` 메타데이터를 idempotent event source로 사용해 중단된 전달을 재생할 수 있다.
- active/archive `complete.log`, 관련 파일, git history를 종합해 Milestone 작업 상태를 복구하거나 확인하는 요청은 `sync-milestone-workstate`로 처리한다.
| 요청 키워드 | SKILL.md |
|------------|----------|
| 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 추가, 화면 정의 갱신, 화면 정의서 갱신, 화면정의서 수정, 화면 정의서에 추가, 화면 정의서에서 제거, 와이어프레임 수정, 와이어프레임에 추가, wireframe 수정, wireframe에 추가, agent-ui USER_REVIEW 해결, UIR 결정 반영 | `agent-ops/skills/common/update-agent-ui/SKILL.md` |
| agent-ui 검증, agent-ui validate, UI 정의 정합성 확인, wireframe 정합성 확인, 화면정의서와 wireframe 맞춰, 화면 정의서와 와이어프레임 정합성 확인, 화면정의서와 코드가 안 맞아, UI 스캐폴드 검사 | `agent-ops/skills/common/validate-agent-ui/SKILL.md` |
| agent-ui와 코드 동기화, agent-ui와 코드 전체 동기화, 화면정의서대로 코드 반영, 화면 정의서 변경사항 구현, wireframe 변경사항 구현 | `agent-ops/skills/common/sync-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` |
| 계약 생성해, 프로젝트 계약 생성해, 프로젝트 계약 생성, contract 생성, agent-contract 생성, 계약 문서 생성, inner 계약 생성, outer 계약 생성 | `agent-ops/skills/common/create-contract/SKILL.md` |
| 계약 업데이트해, 프로젝트 계약 업데이트해, 프로젝트 계약 업데이트, 계약 갱신해, 계약 갱신, 계약 수정, 계약 정리, contract update, agent-contract 갱신, inner 계약 갱신, outer 계약 갱신 | `agent-ops/skills/common/update-contract/SKILL.md` |
| 스펙 생성, 구현 스펙 생성, 현재 구현 문서화, agent-spec 생성, living spec 생성, 완료된 기능 스펙 작성 | `agent-ops/skills/common/create-spec/SKILL.md` |
| 스펙 업데이트, 스펙 갱신, 구현 스펙 갱신, 구현 스펙 업데이트, 완료 기능 스펙 반영, agent-spec 갱신, 스펙 동기화 | `agent-ops/skills/common/update-spec/SKILL.md` |
| README 작성해줘, README 만들어줘, 프로젝트 설명 문서 만들어줘 | `agent-ops/skills/common/create-readme/SKILL.md` |
| 핸즈오프 남겨, handoff 작성, 인수인계 작성, 다른 세션에서 이어가게 정리, 작업을 이어받도록 기록 | `agent-ops/skills/common/create-handoff/SKILL.md` |
| 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` |
| 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, complete.log 후보 스캔, 누락된 Roadmap Completion 복구, 파일/git 기준 작업 상태 확인, 작은 작업 완료 반영, 마일스톤 체크박스 재동기화, 로드맵 작업 완료 상태 동기화 | `agent-ops/skills/common/sync-milestone-workstate/SKILL.md` |
| 마일스톤 완료해도 될지 검토해봐, 현 마일스톤 종료 검토, 현재 마일스톤 닫고 다음 마일스톤 지정, 마일스톤 종료해, 마일스톤 완료 검토, 종료 검토 | `agent-ops/skills/common/complete-milestone/SKILL.md` |
| 로드맵 업데이트, roadmap 갱신, 로드맵에 추가, 로드맵 작업 추가, 로드맵 기능 추가, 로드맵 Epic 추가, 로드맵 에픽 추가, 로드맵 Task 추가, 로드맵 태스크 추가, 로드맵 테스크 추가, 로드맵 TODO 추가, 마일스톤에 추가, 마일스톤 추가, 마일스톤 갱신, 마일스톤 아카이브, phase 추가, phase 변경, 페이즈 추가, 페이즈 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` |
| SDD 작성, SDD 생성, SDD 갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제, SDD 승인 준비, SDD archive, spec gate, 설계 게이트 | `agent-ops/skills/common/roadmap-sdd/SKILL.md` |
| 이 마일스톤은 X가 끝나야 가능해, A 전까지 B 잠가둬, 잠금 해제 조건은 X야, X 프로젝트 작업 뒤에 현재 마일스톤 진행, 의존성 설정해, 외부 의존 잠금 | `agent-ops/skills/common/update-roadmap/SKILL.md` |
| roadmap dependency 확인, locks.yaml 판별, 외부 의존 잠금 확인, unlock-ready 판별, 잠금 해제 조건 충족 여부 확인, roadmap-dependency-checker.sh | `agent-ops/skills/common/check-roadmap-dependency/SKILL.md` |
| 지금 작업이 뭐지?, 현재 작업 분석, 어디까지 했지?, 로드맵상 현 위치, 현재 마일스톤 위치, current 기준 breadcrumb | `agent-ops/skills/common/analyze-roadmap-position/SKILL.md` |
| 현재 plan들 세분화해, 현재 plan 세분화, 기존 plan 더 나눠, local plan 분리해 | `agent-ops/skills/common/refine-local-plans/SKILL.md` |
| 계획 세워줘, 계획 작성해, 계획 만들어줘, 구현 계획, PLAN.md, plan, plan 작성해, plan 만들어줘 | `agent-ops/skills/common/plan/SKILL.md` |
| 최종 라우팅, task routing, cloud/local 재평가, lane/G 판단, G 등급 재평가, routed filename 결정 | `agent-ops/skills/common/finalize-task-routing/SKILL.md` |
| 코드 리뷰해줘, 리뷰 진행해, 리뷰해줘, code review, CODE_REVIEW.md, 리뷰 루프 | `agent-ops/skills/common/code-review/SKILL.md` |
| 커밋해줘, 푸시해줘, commit, push, 반영해줘 | `agent-ops/skills/common/commit-push/SKILL.md` |
| agent-ops 싱크해, agent-ops 동기화해, agentic-framework에 올려줘, agent-ops를 [프로젝트]로 싱크해 | `agent-ops/skills/common/sync-push/SKILL.md` |
| agent-ops pull해, agent-ops 가져와, agentic-framework에서 가져와, agent-ops 내려받아 | `agent-ops/skills/common/sync-pull/SKILL.md` |
| 도메인 업데이트, domain rule 갱신, 도메인 검토, domain 스캔 | `agent-ops/skills/common/update-domain-rule/SKILL.md` |
Plan/review 역할 경계:
- 선택한 task group에 `STAGED_BATCH.md`, `STAGED_PLAN.md`, 또는 `STAGED_CODE_REVIEW.md`가 있으면 `plan` 복구를 먼저 수행하며, marker가 남아 있는 동안 implementation/review를 시작하지 않는다.
- PLAN/CODE_REVIEW 작성 또는 재작성이 요청 범위에 포함되면 `plan`을 선택한다. `plan`이 최종 단계에서 `finalize-task-routing`을 필수 호출한다.
- lane/G/canonical filename 판단만 요청되고 plan 문서 작성은 요청되지 않았을 때만 `finalize-task-routing`을 직접 선택한다.
- plan, implementation, review는 서로 다른 모델이 한 역할씩 수행한다. 현재/root 모델은 다음 역할을 다른 모델에 맡길 수 있지만 직접 그 역할을 수행하지 않는다.
- Runtime은 선택 task path와 역할별 model identity를 pair/handoff에 기록한다. 다음 역할 시작 전에 identity 중복을 거부하고 encoded predecessor를 다시 확인한다. 구현 소유 리뷰 섹션이 모두 채워지고 dependency가 충족된 `review-ready` 상태에서만 Review 모델을 시작한다.
- Indexed task의 basename은 `NN_{subtask_name}` 또는 `NN+PP[,QQ...]_{subtask_name}`이어야 하고 모든 predecessor는 `NN`보다 작아야 한다. Runtime은 malformed 이름을 implementation에 전달하지 않고 Plan 이관 대상으로 돌린다. 유효한 `_`/`+PP[,QQ...]` dependency는 runtime이 해석하며, 모든 predecessor의 matching `complete.log`가 확인된 pair만 implementation에 전달한다. Worker에게 archive 검색이나 dependency 판정을 맡기지 않는다.
- Plan은 PLAN/CODE_REVIEW pair 작성과 `implementation-ready`/`dependency-waiting` 판정, implementation은 리뷰 문서 완성, review는 후속 plan pair·`USER_REVIEW.md`·`complete.log` 중 하나를 남긴 뒤 끝난다.
- WARN/FAIL 리뷰는 다른 Plan 모델이 후속 pair를 작성한 뒤 끝나며, 같은 리뷰 흐름에서 구현하지 않는다.
- Review finalization 복구는 verdict가 append된 active review, partial archive, `complete.log`, resolved `user_review_*.log`, archived WARN/FAIL pair 같은 실제 산출물 조합으로 판별한다. 별도 transient review state 파일을 만들지 않으며, PASS 이동은 self-contained `complete.log`를 쓴 뒤 review 모델의 마지막 filesystem mutation으로 수행한다.
- 정상 역할 종료 상태에는 `STAGED_BATCH.md`, `STAGED_PLAN.md`, `STAGED_CODE_REVIEW.md`가 없다. `USER_REVIEW.md`는 결정 대기 terminal/evidence이며, 해소 후 replan이면 `user_review_N.log`, 완료면 task archive로 수렴한다.

155
agent-ops/skills/common/sync-agent-ui/SKILL.md
View file

@ -1,155 +0,0 @@
---
name: sync-agent-ui
version: 1.1.0
description: 정합화된 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`에 남기고 중단한다.
## 출력 형식
```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의 작업트리 변경을 사용자 결정 없이 되돌리지 않는다.

182
agent-ops/skills/common/sync-milestone-workstate/SKILL.md
View file

@ -1,182 +0,0 @@
---
name: sync-milestone-workstate
version: 1.1.0
description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, active/archive complete.log 후보 스캔, 누락된 Roadmap Completion 복구, 작은 작업처럼 agent-task 기록이 없는 완료 내역을 관련 파일과 git 기록까지 종합 확인, 마일스톤 체크박스 재동기화 요청에서 Milestone Task, 상태, Phase/current 라벨을 실제 evidence와 맞추는 절차
---
# sync-milestone-workstate
## 목적
현재 또는 지정 Milestone의 기능 Task 상태를 실제 작업 evidence와 동기화한다.
새 작업을 배치하거나 구현 계획을 수정하지 않는다.
`complete.log`의 `Roadmap Completion`은 가장 강한 직접 근거로 사용하되, 그 파일이 있더라도 관련 파일과 git history로 최소 sanity pass를 수행한다.
`complete.log`가 없거나 불완전해도 완료가 없다고 단정하지 않는다.
작은 작업이나 수동 수정처럼 `agent-task` 기록이 없을 수 있으므로 Milestone의 관련 경로, 실제 파일 내용, git history, 테스트/검증 흔적을 함께 확인한다.
런타임이 `origin-task`와 `complete-log`를 단건 완료 이벤트로 전달한 일반 반영은 `update-roadmap`을 사용한다.
## 언제 호출할지
- 사용자가 "현 마일스톤과 작업현황 동기화", "현재 마일스톤 작업현황 동기화", "마일스톤 작업현황 동기화"라고 요청할 때
- 사용자가 "마일스톤 완료내역 동기화", "agent-task 완료를 마일스톤에 반영", "complete.log 후보 스캔"이라고 요청할 때
- 사용자가 "누락된 Roadmap Completion 복구", "마일스톤 체크박스 재동기화", "로드맵 작업 완료 상태 동기화"라고 요청할 때
- 사용자가 agent-task에는 없지만 실제 파일/git 기준으로는 완료된 것 같다고 지적할 때
- code-review PASS/archive 이후 runtime completion event 반영이 누락되었는지 확인하고 file-based fallback으로 복구해야 할 때
## 입력
- `target-milestone`: 동기화할 Milestone 이름, slug, 또는 경로. 없으면 `agent-roadmap/current.md`의 활성 Milestone 단일 후보를 사용한다. (선택)
- `complete-log`: 특정 `complete.log` 경로. 지정되면 이 파일을 우선 검증하되, 같은 Milestone slug의 active/archive 후보도 함께 확인한다. (선택)
- `mode`: `sync` 또는 `check-only`. 기본값은 `sync`다. (선택)
- `check-only`: 어떤 파일도 수정하지 않는다. Milestone, Phase, `current.md`, `.agent-roadmap-sync/locks.yaml` 모두 쓰기 금지이며 반영 후보만 보고한다.
## 먼저 확인할 것
- [ ] `agent-roadmap/current.md`를 읽어 활성 Milestone 후보를 확인한다.
- [ ] 대상 Milestone 문서의 `상태`, `구현 잠금`, `기능`, `완료 리뷰`, `작업 컨텍스트`를 확인한다.
- [ ] 대상 Phase `PHASE.md`의 `Milestone 흐름`에 대상 Milestone 항목이 있는지 확인한다.
- [ ] 대상 Milestone의 `SDD: 필요` 여부와 `SDD 문서`, `USER_REVIEW.md` 존재 여부를 확인한다.
- [ ] 같은 slug의 active task와 archive task `complete.log` 후보를 모두 탐색한다. active만 보고 no-op으로 끝내지 않는다.
- [ ] 관련 파일과 git history를 최소 확인한다. `complete.log`가 없거나 일부 Task만 설명하면 더 깊게 감사한다.
## 실행 절차
1. **대상 Milestone 확정**
- `target-milestone`이 있으면 활성 `agent-roadmap/phase/*/milestones/*.md`에서 정확히 하나를 찾는다.
- `target-milestone`이 없으면 `agent-roadmap/current.md`의 활성 Milestone이 정확히 하나인지 확인한다.
- 대상이 없거나 둘 이상이면 Milestone을 수정하지 않고 target 불명확으로 보고한다.
- 대상 경로가 `agent-roadmap/archive/**`이면 수정하지 않고 archive target 불가로 보고한다.
2. **Milestone Task와 evidence scope 읽기**
- Milestone `기능` 섹션의 Task id만 완료 후보로 본다.
- Task id는 `- [ ] [item-id]` 또는 `- [x] [item-id]` 형식에서 추출한다.
- 각 Task의 설명과 `검증:` 문구를 기록한다.
- `구현 잠금`의 상태, `결정 필요`, `SDD: 필요|불필요`, SDD 문서 링크/경로를 확인한다.
- `작업 컨텍스트`의 관련 경로, Milestone 범위, Task 설명의 코드/문서 키워드를 evidence scope로 삼는다.
- 관련 경로가 전혀 없으면 Task 설명에서 검색어를 만들되, 후보가 넓거나 모호하면 Task를 자동 완료하지 않고 scope 불명확으로 보고한다.
3. **complete.log 후보 수집**
- 대상 Milestone slug를 `<milestone-slug>`로 두고 task group은 `m-<milestone-slug>`로 고정한다.
- active 후보를 찾는다: `agent-task/m-<milestone-slug>/complete.log`, `agent-task/m-<milestone-slug>/**/complete.log`
- archive 후보를 찾는다: `agent-task/archive/*/*/m-<milestone-slug>/complete.log`, `agent-task/archive/*/*/m-<milestone-slug>/**/complete.log`
- `complete-log` 입력이 있으면 그 파일도 후보에 포함하되, `Roadmap Completion`의 Milestone 경로가 대상과 일치해야 직접 반영한다.
- 일반 `agent-task/archive/**` 전체를 훑지 말고 위 패턴에 맞는 같은 milestone task group만 읽는다.
4. **Roadmap Completion 직접 근거 검증**
- 각 `complete.log`에 `Roadmap Completion` 섹션이 없으면 직접 Task 체크 근거로 쓰지 않는다. 파일/git evidence를 찾기 위한 힌트로만 사용하고 no-op 사유에 남긴다.
- `Milestone:` 경로가 대상 Milestone 경로와 정확히 일치하지 않으면 해당 파일을 직접 반영하지 않고 mismatch로 보고한다.
- `Completed task ids`의 id가 대상 Milestone의 기존 Task id와 정확히 일치하지 않으면 직접 반영하지 않고 unknown task id로 보고한다.
- 완료 근거는 `PASS` 또는 동등한 완료 판정과 검증 evidence가 있는 항목만 직접 인정한다.
- 같은 Task id에 여러 `complete.log`가 있으면 PASS 근거가 있는 항목을 모으고, 서로 충돌하는 `Not completed task ids`가 있으면 충돌을 보고한다.
5. **파일/git evidence 감사**
- 항상 대상 Milestone의 관련 파일과 git history를 최소 확인한다.
- `Roadmap Completion`으로 확인되지 않은 Task가 있거나 사용자가 실제 구현 완료를 지적하면 Task별 상세 감사를 수행한다.
- 관련 파일을 `rg --files <관련 경로>`와 Task 키워드 `rg`로 찾고, 필요한 파일 본문을 읽어 Task 설명과 직접 대응되는 구현/문서/테스트 변경을 확인한다.
- `git log --oneline -- <관련 경로>`와 필요한 경우 `git show --stat --name-only <commit>`로 Milestone 관련 커밋을 확인한다.
- 커밋 메시지만으로 Task를 완료 처리하지 않는다. 커밋이 변경한 파일과 현재 파일 내용이 Task 설명을 충족해야 한다.
- Task 완료 인정 기준:
- 구현/산출물 evidence가 Task 설명과 직접 대응한다.
- Task에 `검증:`이 있으면 해당 검증 명령의 기록, 현재 테스트 실행 결과, 또는 같은 범위를 검증하는 명시 evidence가 있다.
- `validation-tests` 같은 테스트 Task는 테스트 코드와 검증 실행 evidence가 모두 있어야 한다.
- evidence가 의미상 유사하지만 Task id와 연결이 불분명하면 `[x]` 처리하지 않고 `검토 필요`로 보고한다.
6. **SDD Evidence Map 확인**
- `SDD: 필요`인 Milestone은 direct evidence와 file/git evidence 모두 SDD gate를 통과해야 한다.
- SDD `Acceptance Scenarios`와 `Evidence Map`에서 각 완료 후보 Task id와 연결된 scenario가 있는지 확인한다.
- 연결된 scenario의 evidence가 확인한 complete log, 파일 변경, git commit, verification 중 하나로 설명 가능해야 한다.
- SDD 파일이 없거나 `USER_REVIEW.md`가 남아 있거나 Evidence Map 연결이 비어 있으면 Task 체크 또는 `[검토중]` 전환을 하지 않고 차단 사유로 보고한다.
7. **Milestone 문서 반영**
- `mode=check-only`이면 어떤 파일도 수정하지 않고 반영 후보만 보고한다.
- 검증된 완료 Task id만 `[x]`로 바꾼다. 이미 `[x]`인 항목은 유지한다.
- 일부 Task만 완료되었고 미완료 Task가 남으면 Milestone 상태는 `[진행중]`으로 둔다. 단, 기존 상태가 `[검토중]`, `[보류]`, `[폐기]`이면 자동으로 낮추지 않고 차이만 보고한다.
- 모든 기능 Task가 `[x]`이고 `구현 잠금`이 `해제`, `결정 필요: 없음`, SDD 사용자 리뷰 없음, SDD evidence 충족이면 Milestone 상태를 `[검토중]`으로 바꾼다.
- `[검토중]`으로 바꾸면 `완료 리뷰` 섹션을 만들거나 갱신하고, 사용한 `complete.log`, 파일/git evidence 요약, 완료 Task id, 남은 차단 항목 없음 또는 요약을 1~3줄로 남긴다.
- 모든 Task가 `[x]`여도 구현 잠금이나 SDD gate가 남으면 `[검토중]`으로 바꾸지 않고 `완료 리뷰` 또는 `작업 컨텍스트`에 차단 항목을 남긴다.
- 이 스킬은 Milestone을 `[완료]`로 바꾸거나 archive로 이동하지 않는다.
8. **Phase와 current 라벨 동기화**
- `mode=check-only`이면 이 단계를 쓰기 없이 확인만 한다.
- 대상 Phase `PHASE.md`의 `Milestone 흐름`에서 대상 Milestone 상태 라벨을 Milestone 본문 상태와 맞춘다.
- `agent-roadmap/current.md`에 대상 Milestone이 있으면 상태 라벨을 Milestone 본문 상태와 맞춘다.
- `current.md`에는 `[완료]` 또는 `[폐기]`를 남기지 않는다. 이 스킬은 `[검토중]`까지 유지할 수 있다.
9. **workspace lock 확인**
- `mode=check-only`이면 관련 lock 여부와 필요한 동기화 후보만 보고하고 `locks.yaml`을 수정하지 않는다.
- `.agent-roadmap-sync/locks.yaml`이 있으면 대상 Milestone identity로 `agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<project>:<milestone-path>" both "<locks-file>"`를 실행한다.
- 관련 lock이 없으면 결과에 `Workspace 잠금: 관련 lock 없음`을 남긴다.
- 대상 Milestone identity가 어느 entry의 `rely-on.target`과 일치하면 대상 Milestone 상태 기준으로 해당 `rely-on.status`를 동기화한다. `[검토중]` 또는 `[완료]`이면 `enable`, 그 외 상태면 `disable`이다.
- 대상 Milestone identity가 어느 entry의 `locked`와 일치하면 모든 `rely-on.status`가 `enable`인지 결과에 남긴다.
- 이 스킬에서 새 lock을 만들거나 다른 Milestone의 구현 잠금을 직접 해제하지 않는다.
10. **결과 보고**
- 수정 파일과 변경 전/후 상태를 보고한다.
- 읽은 active/archive `complete.log` 후보 수, 확인한 관련 파일/git 범위, 반영한 Task id를 보고한다.
- 반영하지 않은 `complete.log`나 Task가 있으면 이유를 보고한다.
- SDD gate, 완료 리뷰, Workspace lock, 남은 미완료 Task, 검토 필요 Task를 보고한다.
- 대상 Milestone, 수정 파일, `complete.log`, SDD, 사용자 리뷰 같은 문서/산출물 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 보고한다.
## 실행 결과 검증
- [ ] 대상 Milestone이 활성 경로에서 정확히 하나로 확정되었는가
- [ ] 같은 `m-<milestone-slug>`의 active/root/nested `complete.log`와 archive/root/nested `complete.log` 후보를 모두 확인했는가
- [ ] archive 확인을 생략하고 active task만 근거로 no-op 처리하지 않았는가
- [ ] `complete.log` 부재만으로 완료 Task 없음이라고 단정하지 않았는가
- [ ] 관련 파일과 git history를 확인했거나, scope 불명확 사유를 보고했는가
- [ ] `Roadmap Completion`의 Milestone 경로와 Task id가 대상 Milestone과 exact match였는가
- [ ] `SDD: 필요`인 경우 SDD 파일, `USER_REVIEW.md` 부재, Acceptance Scenario, Evidence Map 연결을 확인했는가
- [ ] 완료 근거가 있는 Task만 `[x]`로 바꾸었는가
- [ ] 모든 Task 완료와 구현 잠금 해제 조건이 충족된 경우에만 `[검토중]`으로 전환했는가
- [ ] `[검토중]`으로 전환했다면 `완료 리뷰`에 complete.log, 파일/git evidence, 남은 차단 항목이 남았는가
- [ ] Phase `PHASE.md`와 `agent-roadmap/current.md`의 상태 라벨이 Milestone 본문과 일치하는가
- [ ] `[검토중]` 전환만 수행하고 `[완료]` 전환 또는 archive 이동을 하지 않았는가
- [ ] `.agent-roadmap-sync/locks.yaml`이 있으면 관련 lock 여부와 필요한 `rely-on.status` 동기화를 결과에 반영했는가
- [ ] 결과 보고의 문서/산출물 포인터가 raw path만 남지 않고 Markdown 링크로 작성되었는가
- [ ] `git diff --check`를 실행했는가
- 검증 실패 시: 파일을 추가로 추정 수정하지 말고 실패한 항목, 차단 사유, 필요한 evidence 경로를 보고한다.
## 출력 형식
```markdown
## 동기화 완료
- 대상 Milestone: [<milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- 모드: <sync | check-only>
- 수정 파일:
- <없음 | [문서명](path)>
## 반영 내용
- 상태: <변경 없음 | 이전 -> 이후>
- 완료 Task: <id 목록 또는 없음>
- 미완료 Task: <id 목록 또는 없음>
- 검토 필요 Task: <id 목록 또는 없음>
- complete.log 후보: active <N>개, archive <N>개
- 반영한 complete.log:
- <[complete.log](path)>
- 반영 제외 complete.log:
- <[complete.log](path)> - <사유>
- 파일/git evidence:
- <task-id 또는 범위> - <파일/커밋/검증 요약>
- SDD gate: <불필요 | 충족 | 차단: 사유>
- 완료 리뷰: <변경 없음 | 검토중 갱신 | 잠금 차단 기록>
- Workspace 잠금: <관련 lock 없음 | 상태 요약 | 미확인 사유>
## TODO 항목
- <남은 차단 항목 또는 없음>
```
## 금지 사항
- active `agent-task/m-<milestone-slug>`만 확인하고 archive `complete.log` 확인 없이 no-op 처리하지 않는다.
- `complete.log` 부재만으로 Task 미완료를 단정하지 않는다.
- 대상 slug와 다른 `agent-task/archive/**` 문서를 일반 탐색하지 않는다.
- 커밋 메시지, 파일명, plan/review log만으로 Task를 `[x]` 처리하지 않는다.
- `complete.log`의 Task id를 의미 유사도, 순서, 파일명으로 보정하지 않는다.
- 파일/git evidence가 있어도 Task 설명과 직접 대응되지 않으면 완료 처리하지 않는다.
- SDD gate가 필요한데 Evidence Map 연결을 확인하지 않고 `[검토중]`으로 전환하지 않는다.
- 구현 잠금이 남아 있거나 `결정 필요`가 있으면 `[검토중]`, `[완료]`, archive를 수행하지 않는다.
- 이 스킬에서 새 Milestone/Epic/Task를 만들거나 기존 id를 바꾸지 않는다.
- 이 스킬에서 Milestone을 `[완료]`로 전환하거나 archive 이동하지 않는다.

9
agent-ops/skills/common/sync-pull/SKILL.md
View file

@ -8,7 +8,6 @@ description: agentic-framework에서 현재 프로젝트로 agent-ops를 내려
## 목적
`agent-ops/bin/sync.sh --pull`을 호출해 agentic-framework → 현재 프로젝트 방향으로 agent-ops를 내려받는다.
내려받기 과정에서 현재 프로젝트의 `.gitignore` Agent-Ops 관리 block과 AI ignore / permission 설정도 보강한다.
## 언제 호출할지
@ -31,12 +30,10 @@ agent-ops/bin/sync.sh --pull <target>
- [ ] sync.sh 가 오류 없이 완료됐는가
- [ ] 현재 프로젝트 버전이 framework 버전과 일치하는가
- [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 갱신됐고, 내용이 framework의 `agent-ops/rules/common/rules.md`와 일치하는가
- [ ] `.gitignore`에 Agent-Ops 관리 gitignore block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`가 포함되어 있는가
- [ ] `agent-roadmap/current.md`가 있으면 파일은 보존되고 git 추적 대상에서는 제거됐는가
- [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-roadmap/archive/**`가 포함되어 있는가
- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` 또는 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가
- [ ] 현재 프로젝트에 기존 archive hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가
- [ ] agentic-framework의 `.gitignore`와 AI ignore / permission 파일은 수정되거나 stage되지 않았는가
- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` hard deny가 있고 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가
- [ ] 현재 프로젝트에 기존 `agent-roadmap/archive/**` hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가
- [ ] agentic-framework의 AI ignore / permission 파일은 수정되거나 stage되지 않았는가
## 금지 사항

55
agent-ops/skills/common/sync-push/SKILL.md
View file

@ -33,25 +33,21 @@ description: 현재 프로젝트의 agent-ops를 공통 원본 repo로 올리거
2. **있으면**: `agent-ops/bin/sync.sh` 실행 또는 `agent-ops/bin/sync.sh agentic-framework` 실행
3. **없으면**: 사용자에게 agentic-framework 경로 입력을 안내하고, 입력받은 경로로 실행
4. 공통 관리 파일 변경 없이 `agent-ops/.version`만 다른 경우 `sync.sh`는 버전 갱신과 commit/push를 건너뛴다
5. 공통 관리 파일 변경이 없어도 현재 프로젝트 또는 공통 원본 repo의 진입 파일이 `agent-ops/rules/common/rules.md`와 다르면 진입 파일만 재적용하고 commit/push 한다
6. 공통 관리 파일 변경이 있으면 `sync.sh`가 버전을 한 단계 올리고 현재 프로젝트와 공통 원본 repo에 같은 버전을 반영한다
7. 이때 현재 프로젝트와 공통 원본 repo의 진입 파일은 각각 자기 `agent-ops/rules/common/rules.md` 내용으로 재적용한다
8. 일반 프로젝트에서 공통 원본 repo로 올릴 때는 AI ignore / permission 파일을 보강하거나 stage하지 않는다
5. 공통 관리 파일 변경이 있으면 `sync.sh`가 버전을 한 단계 올리고 현재 프로젝트와 공통 원본 repo에 같은 버전을 반영한다
6. 일반 프로젝트에서 공통 원본 repo로 올릴 때는 AI ignore / permission 파일을 보강하거나 stage하지 않는다
### 현 프로젝트가 공통 원본 repo인 경우 (`.agent-ops-source` 있음)
1. 사용자 요청에서 target 프로젝트명 또는 경로를 추출한다
2. 공통 원본 repo 자신의 진입 파일이 `agent-ops/rules/common/rules.md`와 다르면 먼저 재적용하고 commit/push 한다
3. **명시된 경우**: `agent-ops/bin/sync.sh <target>` 실행
4. **명시되지 않은 경우**: `agent-ops/bin/sync.sh` 실행
5. target이 없으면 `sync.sh`가 현재 프로젝트 기준 상위 폴더(`../`)의 하위 디렉터리 중 `agent-ops/` 폴더가 있는 프로젝트를 모두 대상으로 삼는다
6. `sync.sh`는 현재 공통 원본 repo의 `agent-ops/rules/common/rules.md` 내용을 대상 프로젝트 루트의 진입 파일에 덮어쓴다
7. 적용 후 각 대상 repo에서 agent-ops 공통 관리 경로(`rules/common/rules.md` 포함), 진입 파일, `.gitignore`, AI ignore / permission 파일을 stage 하여 commit/push 한다
8. `.gitignore`와 AI ignore / permission 파일은 대상 프로젝트의 기존 내용을 덮어쓰지 않고, Agent-Ops 관리 block 또는 Agent-Ops 전용 permission key만 보강한다
9. 이 과정에서는 버전을 새로 올리지 않고 현재 공통 원본 repo의 `agent-ops/.version` 값을 그대로 대상 프로젝트에 반영한다
2. **명시된 경우**: `agent-ops/bin/sync.sh <target>` 실행
3. **명시되지 않은 경우**: `agent-ops/bin/sync.sh` 실행
4. target이 없으면 `sync.sh`가 현재 프로젝트 기준 상위 폴더(`../`)의 하위 디렉터리 중 `agent-ops/` 폴더가 있는 프로젝트를 모두 대상으로 삼는다
5. `sync.sh`는 현재 공통 원본 repo의 `agent-ops/rules/common/rules.md` 내용을 대상 프로젝트 루트의 진입 파일에 덮어쓴다
6. 적용 후 각 대상 repo에서 agent-ops 공통 관리 경로(`rules/common/rules.md` 포함), 진입 파일, AI ignore / permission 파일을 stage 하여 commit/push 한다
7. AI ignore / permission 파일은 대상 프로젝트의 기존 내용을 덮어쓰지 않고, Agent-Ops 관리 block 또는 Agent-Ops 전용 permission key만 보강한다
8. 이 과정에서는 버전을 새로 올리지 않고 현재 공통 원본 repo의 `agent-ops/.version` 값을 그대로 대상 프로젝트에 반영한다
덮어쓰기 대상은 `init-agent-ops` 초기 세팅과 동일하며, 실제 목록은 `agent-ops/bin/entry-files.sh`의 `AGENT_OPS_ENTRY_FILES`를 단일 기준으로 사용한다.
모든 repo에서 진입 파일 내용은 해당 repo의 `agent-ops/rules/common/rules.md`와 같아야 한다.
| 에이전트 | 파일명 |
|---------|--------|
@ -63,22 +59,10 @@ description: 현재 프로젝트의 agent-ops를 공통 원본 repo로 올리거
대상 프로젝트에 기존 진입 파일이 있어도 보존하거나 병합하지 않고 `agent-ops/rules/common/rules.md` 내용으로 교체한다.
## Gitignore / AI Ignore / Permission 재적용
## AI Ignore / Permission 재적용
- 이 절차는 `.agent-ops-source`가 있는 공통 원본 repo에서 대상 프로젝트로 push할 때와 `--pull`로 공통 원본 repo에서 현재 프로젝트로 내려받을 때만 적용한다.
- 일반 프로젝트에서 공통 원본 repo로 올리는 push에서는 `.gitignore`와 AI ignore / permission 파일을 수정하거나 stage하지 않는다.
- `.gitignore`는 사용자 영역을 수정하지 않고 아래 관리 block만 추가하거나 교체한다. 이 예외는 `*.log` 같은 전역 ignore가 있어도 plan/review/archive task 산출물이 git에 잡히도록 하고, `agent-roadmap/current.md`는 브랜치별 로컬 포인터로 남긴다.
```text
# BEGIN Agent-Ops managed gitignore
!agent-task/
!agent-task/**/
!agent-task/**/*.md
!agent-task/**/*.log
agent-roadmap/current.md
# END Agent-Ops managed gitignore
```
- 일반 프로젝트에서 공통 원본 repo로 올리는 push에서는 AI ignore / permission 파일을 수정하거나 stage하지 않는다.
- `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`는 사용자 영역을 수정하지 않고 아래 관리 block만 추가하거나 교체한다.
```text
@ -89,30 +73,27 @@ agent-roadmap/archive/**
```
- 관리 block 밖의 기존 ignore 항목은 사용자 소유로 보고 삭제, 정렬, 중복 제거하지 않는다.
- `.claude/settings.json`과 `opencode.json`은 기존 사용자 설정을 보존하고 `agent-task/archive/**`와 `agent-roadmap/archive/**` hard read/glob deny를 제거한다.
- archive는 기본 컨텍스트에서 제외하되 필요한 경우 명시 경로로 읽을 수 있어야 하므로 `.claude/settings.json`이나 `opencode.json`의 hard read/glob deny로 두지 않는다.
- 대상 프로젝트에 기존 archive hard read/glob deny가 있으면 init-agent-ops 표준에 맞게 제거한다.
- `.claude/settings.json`과 `opencode.json`은 기존 사용자 설정을 보존하고 `agent-task/archive/**` hard read/glob deny만 보강한다.
- `agent-roadmap/archive/**`는 필요한 경우 링크로 읽을 수 있어야 하므로 `.claude/settings.json`이나 `opencode.json`의 hard read/glob deny로 두지 않는다.
- 대상 프로젝트에 기존 `agent-roadmap/archive/**` hard read/glob deny가 있으면 init-agent-ops 표준에 맞게 제거한다.
- `opencode.json`의 watcher ignore에는 `agent-task/archive/**`와 `agent-roadmap/archive/**`를 둘 수 있다.
```bash
agent-ops/bin/sync.sh [target]
```
푸시 대상 path는 항상 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, `AGENT_OPS_ENTRY_FILES`의 진입 파일로 제한한다. 예외적으로 `agent-roadmap/current.md`가 이미 추적 중이고 `.gitignore`에 로컬 current ignore가 있으면 파일을 보존한 채 git 추적에서 제거하는 삭제만 함께 commit할 수 있다. `.gitignore`와 AI ignore / permission 파일은 `.agent-ops-source`가 있는 공통 원본 repo에서 일반 프로젝트로 내려보내는 경우에만 대상 repo에서 추가 stage한다.
푸시 대상 path는 항상 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, `AGENT_OPS_ENTRY_FILES`의 진입 파일로 제한한다. AI ignore / permission 파일은 `.agent-ops-source`가 있는 공통 원본 repo에서 일반 프로젝트로 내려보내는 경우에만 대상 repo에서 추가 stage한다.
## 실행 결과 검증
- [ ] sync.sh 가 오류 없이 완료됐는가
- [ ] 버전 충돌 경고가 없었는가 — 있었다면 사용자에게 수동 머지 필요함을 알린다
- [ ] 대상 repo의 `agent-ops/rules/common/rules.md`가 현재 공통 원본 repo의 `agent-ops/rules/common/rules.md`와 일치하는가
- [ ] 현재 repo와 대상 repo의 `AGENT_OPS_ENTRY_FILES` 진입 파일이 각각 자기 repo의 `agent-ops/rules/common/rules.md`와 일치하는가
- [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `agent-ops/bin/entry-files.sh`의 모든 진입 파일 내용이 현재 공통 원본 repo의 `agent-ops/rules/common/rules.md`와 일치하는가
- [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `.gitignore`에 Agent-Ops 관리 gitignore block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`가 포함되어 있는가
- [ ] 대상 프로젝트에서 `agent-roadmap/current.md`가 있으면 파일은 보존되고 git 추적 대상에서는 제거됐는가
- [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-roadmap/archive/**`가 포함되어 있는가
- [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `.claude/settings.json`과 `opencode.json`에 `agent-task/archive/**` 또는 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가
- [ ] 대상 프로젝트에 기존 archive hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가
- [ ] 일반 프로젝트에서 공통 원본 repo로 push한 경우, `.gitignore`와 AI ignore / permission 파일이 공통 원본 repo에 유입되지 않았는가
- [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `.claude/settings.json`과 `opencode.json`에 `agent-task/archive/**` hard deny가 있고 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가
- [ ] 대상 프로젝트에 기존 `agent-roadmap/archive/**` hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가
- [ ] 일반 프로젝트에서 공통 원본 repo로 push한 경우, AI ignore / permission 파일이 공통 원본 repo에 유입되지 않았는가
- [ ] 대상 repo에 commit/push 된 path가 방향별 허용 범위로 제한되었는가
## 금지 사항

156
agent-ops/skills/common/update-agent-ui/SKILL.md
View file

@ -1,156 +0,0 @@
---
name: update-agent-ui
version: 1.1.1
description: 화면정의서, view, component, frame, wireframe 내용을 agent로 수정하고 후속 validate 필요성과 sync intent 전달 여부를 판단하는 스킬
---
# update-agent-ui
## 목적
기존 `agent-ui/`의 화면정의서와 wireframe 관련 문서를 갱신한다.
사용자가 "화면정의서에 X 추가", "wireframe에 사이드바 추가"처럼 agent-ui 명사를 쓰지 않아도 UI 정의 문서 수정 요청이면 이 스킬을 사용한다.
오래된 결정이 현재 기준을 흐리면 archive log로 분리하고, 변경 후 `validate-agent-ui` 필요성과 code sync intent 전달 여부를 판단한다.
코드 구현 규모 판정, plan 라우팅, roadmap/milestone 라우팅은 `sync-agent-ui` 책임이며 이 스킬에서 수행하지 않는다.
## 언제 호출할지
- 화면 정의서, view 정의, component 정의를 추가하거나 수정할 때
- wireframe 또는 Excalidraw visual source 연결을 추가하거나 수정할 때
- 기존 구현 코드 또는 컨셉 문서 변화에 맞춰 Source Evidence와 Status를 갱신할 때
- agent-ui 문서의 decision history, open question, user review를 갱신할 때
- ops/dev UI 정의를 제품 진행 상황에 맞춰 동기화할 때
- 사용자가 "화면정의서에 ... 추가/수정/삭제", "와이어프레임에 ... 추가/수정/삭제", "wireframe에 ... 반영"처럼 요청할 때
- 사용자가 `UIR-NNN` 결정, agent-ui USER_REVIEW 해결, 화면정의서와 코드 불일치 보정을 요청할 때
## 입력
- `change`: 갱신할 내용 요약 (필수)
- `view-id`: 대상 view id (선택)
- `component-id`: 대상 component id 또는 path id (선택)
- `frame-source`: 예: `wire.excalidraw`, `overview.png` (선택)
- `evidence`: 코드, 문서, 사용자 입력 근거 경로 또는 요약 (선택)
- `status`: `구현됨`, `계획`, `가정`, `불명확` 중 하나 (선택)
- `mode`: `definition`, `frame`, `component`, `mixed` 중 하나. 기본값은 `mixed` (선택)
- `post-validate`: `auto`, `true`, `false` 중 하나. 기본값은 `auto` (선택)
- `post-sync`: `auto`, `true`, `false` 중 하나. 기본값은 `auto` (선택)
- `review-resolution`: 해결할 `UIR-NNN`과 결정 내용 (선택)
## 먼저 확인할 것
- [ ] `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를 유지한다.
- 구현 코드 반영 완료 항목은 `구현됨`, 문서 기준으로 정합화됐지만 코드 반영 전이거나 재작업 대상인 항목은 `계획`, 사용자 입력/추정만 있는 항목은 `가정`, 판단 불가 항목은 `불명확`으로 둔다.
- 실제 근거 파일이 없으면 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`로 이동하거나 추가한다. 단순 변경 이벤트를 모두 archive로 남기지 않는다.
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 항목에는 `Source Skill: update-agent-ui`, `Stage: definition-edit`, `Blocking Step`을 남긴다.
- 기존 USER_REVIEW 항목을 해결하는 변경이면 항목 상태를 갱신하고, 필요하면 `agent-ui/archive/user-review/user_review_N.log`로 이동한다.
- 해결 로그를 만들 때는 현재 변경과 직접 관련된 항목만 이동한다.
- `review-resolution`이 있으면 결정 내용을 관련 활성 definition/frame/component 문서에 먼저 반영한다.
- 해결된 항목은 `agent-ui/archive/user-review/user_review_N.log`로 이동하고, 활성 `USER_REVIEW.md`에는 미해결 항목만 남긴다. 남은 항목이 없으면 활성 `USER_REVIEW.md`를 제거할 수 있다.
- sync 실패 후 남은 작업트리 변경이 있고 사용자 결정과 충돌하지 않으면 보존한 채 후속 validate/sync에서 이어간다.
5. **후속 validate와 sync intent 판단**
- `post-validate=false`가 아니고 view/component/frame/wireframe/source evidence/status 중 하나라도 바뀌었으면 `validate-agent-ui`를 실행한다.
- `post-validate=true`이면 변경 크기와 무관하게 `validate-agent-ui`를 실행한다.
- `post-sync=true` 또는 코드 반영이 필요한 `계획` 상태 변경이 있으면 sync intent를 `validate-agent-ui`에 전달한다.
- `post-sync=false`이면 sync intent를 전달하지 않는다.
- 후속 단계가 실행되면 순서는 항상 `validate-agent-ui` 다음 `sync-agent-ui`다.
- 현재 변경 범위에 미해결 USER_REVIEW가 있으면 `sync-agent-ui`를 실행하지 않고 차단 항목을 보고한다.
- 사용자가 "화면정의서와 코드가 안 맞아"처럼 불일치를 보고하면 관련 항목을 `계획`으로 되돌릴지 확인하고 validate/sync intent를 만든다.
- sync intent를 만들더라도 코드 반영 방식이 direct-sync, plan-required, milestone-required 중 무엇인지는 판단하지 않는다.
6. **결과 보고**
- 수정한 활성 정의 문서
- 수정한 frame 문서와 visual source
- frontmatter schema 변경 여부
- archive log 변경 여부
- USER_REVIEW 생성/갱신 여부
- validate-agent-ui 실행 여부와 결과
- sync-agent-ui 필요 여부와 실행/보류 사유
- 남은 정합성 확인 항목
## 실행 결과 검증
- [ ] view/component는 folder-first + `index.md` 구조를 유지하는가
- [ ] 새로 만들거나 수정한 활성 Markdown 문서가 `ui_doc_type` frontmatter를 포함하는가
- [ ] 새로 만들거나 수정한 view/component에 `Source Evidence`와 `Status`가 있는가
- [ ] 구현 근거 또는 sync 완료 없이 항목을 `구현됨`으로 표시하지 않았는가
- [ ] frame-view가 있으면 view region id와 frame region id가 충돌하지 않는가
- [ ] view에서 참조한 component id가 존재하거나 USER_REVIEW에 남았는가
- [ ] visual source가 있으면 대응 frame index에 기록되었는가
- [ ] visual source가 없는데 빈 frame-view 문서만 남아 있지 않은가
- [ ] 현재 기준이 archive에만 남지 않았는가
- [ ] 확정할 수 없는 UI 결정이 임의로 확정되지 않았는가
- [ ] 후속 단계가 필요할 때 `validate-agent-ui`가 `sync-agent-ui`보다 먼저 실행되었는가
- [ ] USER_REVIEW 해결 요청이면 결정이 활성 문서에 반영되고 해결 로그가 archive 되었는가
- [ ] sync 실패 후 남은 작업트리를 임의로 버리지 않았는가
- 검증 실패 시: 자동 보정 가능한 것은 보완하고, 판단이 필요한 것은 `agent-ui/USER_REVIEW.md`에 남긴다.
## 출력 형식
```md
## 갱신 완료
- 수정 파일: <목록>
- view: <view-id 또는 없음>
- component: <component-id 또는 없음>
- frame source: <파일 또는 없음>
- evidence/status: <요약 또는 없음>
- frontmatter schema: <변경/유지/없음>
- archive 변경: <내용 또는 없음>
- USER_REVIEW: <생성/갱신/없음>
- USER_REVIEW resolution: <해결/부분 해결/없음>
- validate-agent-ui: <실행/PASS/WARN/FAIL/생략 사유>
- sync-agent-ui: <실행/보류/생략 사유>
- 확인 필요: <항목 또는 없음>
```
## 금지 사항
- `definition/archive/**`를 현재 기준으로 사용하지 않는다.
- 코드나 문서 근거 없이 status를 확정하지 않는다.
- 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
- 사용자 판단이 필요한 UI 의도를 임의로 확정하지 않는다.
- view/component id를 명시적 요청 없이 바꾸지 않는다.
- `.excalidraw` 파일만 만들고 frame index를 생략하지 않는다.
- visual source 없이 빈 frame-view 문서를 만들지 않는다.
- agent-ui 갱신과 무관한 앱 구현 파일을 수정하지 않는다.
- 코드 구현 규모에 따라 plan 또는 roadmap/milestone 라우팅을 확정하지 않는다.
- `validate-agent-ui`를 거치지 않고 `sync-agent-ui`를 실행하지 않는다.
- sync 실패 후 남은 코드 변경을 사용자 결정 없이 되돌리지 않는다.

111
agent-ops/skills/common/update-contract/SKILL.md
View file

@ -1,111 +0,0 @@
---
name: update-contract
version: 1.0.0
description: agent-contract inner/outer 계약 문서를 갱신하고 흩어진 계약 설명을 정리한다. 계약 업데이트해, 프로젝트 계약 업데이트해, 계약 갱신/수정/정리, contract update 요청에서 사용한다.
---
# update-contract
## 목적
기존 `agent-contract/`의 inner/outer 계약 문서를 최신 코드와 문서 기준으로 갱신한다.
계약 원문은 한 곳에 모으고, README/docs/rules에는 포인터와 경계 규칙만 남긴다.
## 언제 호출할지
- 사용자가 계약 업데이트, 프로젝트 계약 업데이트, 계약 갱신, 계약 수정, 계약 정리를 요청할 때
- API, runtime 호출, wire protocol, event/config schema 변경이 기존 계약에 영향을 줄 때
- 계약 설명이 README/docs/rules/code review 과정에서 다시 흩어진 것을 정리할 때
- legacy `provided/consumed` 계약을 `inner/outer` 모델로 점진 정리할 때
## 입력
- `contract-id`: 갱신할 계약 식별자 (선택, 없으면 index와 변경 diff에서 탐색)
- `change`: 바뀐 내용 또는 정리할 문제 요약 (선택, 없으면 최근 변경/요청 맥락에서 산출)
- `boundary`: `inner` 또는 `outer` (선택, 기존 문서 우선)
- `canonical-path`: 갱신 기준이 되는 proto/OpenAPI/config/code 원본 경로 (선택)
## 먼저 확인할 것
- [ ] `agent-contract/index.md` 존재 여부를 확인한다. 없으면 create-contract 흐름으로 전환할지 판단한다.
- [ ] index에서 대상 계약 문서를 찾는다. 없으면 새 계약 생성 대상인지 판단한다.
- [ ] 대상 계약 문서와 원본 경로를 읽는다.
- [ ] 변경 범위와 관련된 코드, proto, config, 테스트를 읽어 실제 동작을 확인한다.
- [ ] README/docs/rules에 계약 본문이 새로 중복 작성되었는지 검색한다.
- [ ] legacy `provided/consumed/` 구조가 남아 있으면 현재 요청이 구조 migration인지 단순 계약 갱신인지 구분한다.
## 실행 절차
1. **대상 확정**
- index의 `Outer Contracts`/`Inner Contracts`에서 계약을 찾는다.
- `contract-id`가 없으면 요청 키워드, 변경 파일, 코드 diff, README/docs/rules의 계약 설명을 기준으로 영향을 받는 계약을 좁힌다.
- legacy index만 있으면 `provided`는 outer 후보, 프로젝트 내부 runtime/wire 계약은 inner 후보로 분류하되 즉시 이동하지 말고 변경 범위와 함께 판단한다.
- 대상이 없고 요청이 계약 생성/정리까지 허용하면 create-contract 흐름으로 전환한다.
- 대상이 없고 사용자가 특정 기존 계약 갱신만 요청했다면 대상 부재를 보고한다.
2. **코드 우선 분석**
- 원본 경로를 먼저 확인한다.
- 실제 parser/handler/DTO/interface/test에서 필드 의미와 허용/거부 동작을 확인한다.
- 문서와 코드가 다르면 코드를 근거로 계약 문서를 갱신하고, 코드가 틀렸을 가능성이 있으면 사용자에게 후보를 제시한다.
3. **계약 문서 갱신**
- 필드 의미, 금지 사항, 읽는 조건, 변경 시 테스트를 최신 상태로 맞춘다.
- schema 원본 전체를 복제하지 않고 핵심 의미와 원본 경로를 유지한다.
- 불확실한 값은 단정하지 않고 `확인 필요`로 남긴다.
- `last updated` 같은 날짜 메타가 이미 있는 문서에서만 갱신한다. 없는 문서에 날짜 관례를 새로 만들지 않는다.
4. **index 갱신**
- 읽는 조건이 새 API/field/message/protocol 이름을 포함하는지 확인한다.
- path, 원본 경로, boundary가 실제 문서와 일치하는지 확인한다.
- 중복 id, dead path, 존재하지 않는 원본 경로를 제거하거나 수정한다.
- 프로젝트 전용 path trigger가 필요하면 `agent-contract/index.md` 또는 project/domain rule 포인터에 둔다. common rule에는 넣지 않는다.
5. **흩어진 문서 정리**
- README/docs/rules에 계약 본문이 들어간 경우 계약 문서 포인터로 축소한다.
- domain rule에는 책임 경계와 금지 사항만 남기고 상세 요청/응답 schema를 반복하지 않는다.
- 테스트 문서에는 검증 기준만 남기고 계약 본문을 복제하지 않는다.
- common rule에 특정 프로젝트 경로, 계약 id, API 이름이 새로 들어갔으면 제거하고 프로젝트 문서로 옮긴다.
6. **검증 판단**
- 계약 문서만 바꿨으면 링크/path/index 정합성을 확인한다.
- 원본 schema 또는 runtime 코드를 함께 바꿨으면 해당 domain/test rule의 검증 기준을 따른다.
- proto/config schema를 바꿨으면 생성물 갱신 명령과 관련 테스트를 실행한다.
7. **결과 보고**
- 수정한 계약 문서와 index
- 코드 분석 근거
- 중복 제거한 문서
- 실행한 검증
- 남은 확인 필요 항목
## 실행 결과 검증
- [ ] index가 대상 계약의 최신 path와 읽는 조건을 가리키는가
- [ ] 계약 문서의 원본 경로가 실제 코드/proto/config와 맞는가
- [ ] README/docs/rules에 같은 계약 본문이 중복 남아 있지 않은가
- [ ] inner/outer boundary가 계약의 실제 소비자와 맞는가
- [ ] 코드 분석 없이 문서만 추측해 갱신하지 않았는가
- [ ] 변경 범위에 필요한 테스트 또는 링크 검증을 실행했는가
- 검증 실패 시: index/path/원본 경로/중복 문서/테스트 누락을 보완한다.
## 출력 형식
```md
## 계약 업데이트 완료
- contract: agent-contract/<inner|outer>/<contract-name>.md
- index: agent-contract/index.md
- code evidence: <확인한 코드/proto/config/test>
- pointers: <갱신한 README/docs/rules 경로 또는 없음>
- verification: <실행한 명령 또는 생략 사유>
- 확인 필요: <항목 또는 없음>
```
## 금지 사항
- 코드와 원본 경로를 확인하지 않고 계약 문서만 고치지 않는다.
- README/docs/rules에 계약 본문을 새로 복제하지 않는다.
- 프로젝트 전용 path trigger를 common rule에 넣지 않는다.
- 사용자 요청 없이 전체 계약 구조를 대량 migration하지 않는다.
- 한 패키지 내부 구현 세부를 inner 계약으로 승격하지 않는다.
- 계약 갱신과 무관한 리팩터링을 함께 수행하지 않는다.

266
agent-ops/skills/common/update-roadmap/SKILL.md
View file

@ -1,7 +1,7 @@
---
name: update-roadmap
version: 1.24.0
description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경, 전역 Milestone 실행 순서 갱신 요청에 사용한다. Roadmap-priority-queue-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 priority-queue.md 순서 동기화, 로컬 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, agent-ui 코드 동기화 Milestone의 종료 검토 시 구현됨 상태 반영, 완료 근거 충족 archive 이동, workspace 외부 의존 잠금 양방향 동기화를 처리한다.
version: 1.21.0
description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, 승인된 archive 이동, workspace 외부 의존 잠금 양방향 동기화를 처리한다.
---
# 로드맵 업데이트
@ -9,10 +9,9 @@ description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/
## 목적
기존 `agent-roadmap/` 구조를 현재 프로젝트 방향과 진행 상태에 맞게 갱신한다.
표준 구조는 `ROADMAP.md -> priority-queue.md -> phase/<phase-slug>/PHASE.md -> phase/<phase-slug>/milestones/<milestone-slug>.md`다.
표준 구조는 `ROADMAP.md -> phase/<phase-slug>/PHASE.md -> phase/<phase-slug>/milestones/<milestone-slug>.md`다.
archive도 같은 Phase scaffold를 유지하며 `archive/phase/<phase-slug>/...` 아래에 둔다.
로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, 브랜치별 로컬 `current.md`의 활성 Phase와 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다.
`priority-queue.md`는 Phase를 가로지르는 실행 순서만 담당하며, Milestone 상세 정보는 복제하지 않는다.
로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, `current.md`의 활성 Phase와 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다.
Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서로 유지한다.
Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능` 안에서 관리한다. 별도 `완료 기준` 섹션은 만들지 않고, 검증이 필요한 기능에만 같은 Task 안의 `검증:` 문구로 통합한다.
@ -28,9 +27,6 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능
- 특정 기능이나 작업을 새 Milestone, 기존 Milestone의 Epic, 기존 Epic의 Task 중 적절한 위치에 추가해야 할 때
- 활성 Phase/Milestone 창에 포함할 목록이 달라졌을 때
- 기존 로드맵을 `phase/<phase-slug>/PHASE.md` scaffold로 마이그레이션하거나 표준화해야 할 때
- 사용자가 "순서 바꿔", "이거 먼저", "이거 뒤로", "우선순위 재정렬"처럼 전역 Milestone 실행 순서 변경을 요청할 때
- `priority-queue.md`에 있는 Milestone이 archive, 폐기, 경로 변경, split/merge, 또는 실행 의미가 바뀔 정도로 수정되어 큐 정리가 필요할 때
- `priority-queue.md` 링크가 깨져 활성 Milestone 문서 기준으로 큐를 재정렬하거나 재생성해야 할 때
- 사용자가 "이 Milestone은 X가 끝나야 가능하다", "A 전까지 B를 잠근다", "잠금 해제 조건은 X다", "현재 마일스톤은 X 프로젝트 작업 뒤에 진행되어야 한다", "의존성 설정해"처럼 외부 의존 잠금을 말할 때
## 입력
@ -45,79 +41,57 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능
- `placement-unit`: 삽입 단위. `phase` / `milestone` / `epic` / `task` / `subtask` / `auto` 중 하나 (선택)
- `target-status`: 전환할 Phase/Milestone 상태. `[스케치]` / `[계획]` / `[진행중]` / `[검토중]` / `[완료]` / `[보류]` / `[폐기]` 중 하나 (선택)
- `lock-state`: Milestone 구현 잠금 상태. `잠금` / `해제` 중 하나 (선택)
- `decision-needed`: `구현 잠금`에 남길 에이전트가 확정할 수 없는 제품/범위/우선순위/책임 경계 결정 목록 (선택)
- `sdd-state`: Milestone SDD gate. `필요` / `불필요` / `확인 필요` 중 하나 (선택)
- `sdd-path`: SDD 문서 경로. 기본값은 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md` (선택)
- `sdd-review`: SDD 사용자 리뷰 상태. `없음` / `요청됨` / `해결됨` 중 하나 (선택)
- `decision-needed`: `구현 잠금`에 남길 사용자만 결정할 수 있는 질문 목록 (선택)
- `evidence`: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택)
- `complete-log`: 런타임 완료 이벤트가 전달한 `complete.log` 경로. `Roadmap Completion` 섹션이 있을 때만 Milestone 기능 Task 체크에 사용한다 (선택)
- `review-state`: 완료 리뷰 상태. `검토중` / `통과` / `보완 필요` / `보류` / `폐기` 중 하나 (선택)
- `review-comment`: 완료 리뷰에 남길 보완, 보류, 폐기 방향성 또는 근거 메모 (선택)
- `review-state`: 완료 리뷰 상태. `요청됨` / `승인됨` / `보완 필요` / `보류` / `폐기` 중 하나 (선택)
- `review-comment`: 완료 리뷰에 남길 사용자 확인, 보완, 보류, 폐기 방향성 (선택)
- `origin-task`: 런타임 완료 이벤트가 전달한 `agent-task/m-<milestone-slug>` 또는 `agent-task/m-<milestone-slug>/<subtask_dir>` 형식의 원래 active task 경로. 이벤트가 최종 archive 경로만 갖고 있으면 런타임이 이 형식으로 정규화해 전달한다 (선택)
- `archive-date`: Phase/Milestone 아카이브 날짜. 없으면 현재 날짜를 사용한다 (선택)
- `workspace-lock`: 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`에 기록하거나 동기화할 외부 의존 잠금 설명 (선택)
- `priority-queue-order`: `agent-roadmap/priority-queue.md`에 반영할 Milestone 경로/제목 순서 목록. 사용자가 순서 조정을 명시한 경우에만 사용한다 (선택)
## 표준 구조
```text
agent-roadmap/
ROADMAP.md
priority-queue.md
current.md # local, git ignored
current.md
phase/
<phase-slug>/
PHASE.md
milestones/
<milestone-slug>.md
sdd/
<phase-slug>/
<milestone-slug>/
SDD.md
USER_REVIEW.md
archive/
phase/
<phase-slug>/
PHASE.md
milestones/
<milestone-slug>.md
sdd/
<phase-slug>/
<milestone-slug>/
SDD.md
```
- `ROADMAP.md`는 전체 목표와 Phase 흐름, `priority-queue.md` 고정 라우팅만 담는다.
- `priority-queue.md`는 Phase를 가로지르는 Milestone 실행 순서만 담는다. 항목은 Milestone 제목 링크와 식별용 한 줄 설명만 둔다.
- `ROADMAP.md`는 전체 목표와 Phase 흐름만 담는다.
- `PHASE.md`는 해당 Phase의 목표, 상태, Milestone 흐름, Phase 경계를 담는다.
- Milestone 문서는 해당 Phase 하위 `milestones/`에 둔다.
- 완료된 Phase는 `archive/phase/<phase-slug>/PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
- 진행중 Phase 안에서 완료된 Milestone은 `archive/phase/<phase-slug>/milestones/<milestone-slug>.md`로 이동하고, 활성 `PHASE.md`에는 짧은 archive 링크를 남긴다.
- archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우에는 archive Phase 디렉터리에 `milestones/`만 있을 수 있다.
- 큰 Milestone의 SDD는 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`에 둔다.
- SDD 사용자 리뷰는 같은 디렉터리의 `USER_REVIEW.md`로 두고, 해결 후 `user_review_N.log`로 남긴다.
- 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/`로 이동한다.
- `<phase-slug>`와 `<milestone-slug>`는 소문자 영문, 숫자, 하이픈만 사용한다.
- `current.md`는 브랜치별 로컬 포인터이며 활성 Phase와 활성 Milestone을 모두 가리킨다.
- `current.md`는 git 추적 대상이 아니며, 공유 진행 상태는 `ROADMAP.md`, `PHASE.md`, Milestone 문서, `.agent-roadmap-sync/locks.yaml`에 기록한다.
- `current.md`는 활성 Phase와 활성 Milestone을 모두 가리킨다.
- `current.md`에는 archive 경로를 넣지 않는다.
- `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 완료 근거와 archive 전환이 정리될 때까지 `[검토중]`으로 둔다.
- `priority-queue.md`에는 archive 경로를 넣지 않는다. 완료 Milestone은 archive 시 제거하고, 폐기 Milestone은 큐에서 제거한다.
- `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 사용자 승인 전까지 `[검토중]`으로 둔다.
## 상태와 id
- 상태 표기는 `[스케치]`, `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- 기존 비표준 상태 표기는 갱신 범위에 포함될 때 표준 상태 표기로 정리한다.
- `[스케치]`는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 `agent-task` 구현 계획 생성과 코드 구현 대상으로 삼지 않는다.
- `[스케치]` 항목은 `[계획]`으로 승격하기 위한 `승격 조건`, 에이전트가 확정할 수 없는 결정, 범위 경계, 후속 Milestone 후보를 정리한다.
- `[스케치]` 항목은 `[계획]`으로 승격하기 위한 `승격 조건`, 사용자 결정, 범위 경계, 후속 Milestone 후보를 정리한다.
- `[계획]` 이상 Milestone에서 `승격 조건` 섹션은 선택 사항이다. 섹션이 없거나 `- 없음`이면 템플릿 오류로 보지 않는다.
- `[스케치]`를 `[계획]`으로 전환할 때는 `승격 조건`의 미정 항목이 해소되고, 목표, 범위, 기능 Task, 직접 필요한 결정 항목, 후속 구현 단위가 구현 계획을 만들 수 있을 만큼 정리되었는지 확인한다.
- `[계획]`은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 문서화되어 잠금 해제 후 구현 계획을 만들 수 있는 상태다.
- `[검토중]`은 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 `구현 잠금`이 해제되었으나, 완료 근거 정리와 archive 전환이 남은 완료 후보 상태다.
- `[스케치]`를 `[계획]`으로 전환할 때는 `승격 조건`의 미정 항목이 해소되고, 목표, 범위, 기능 Task, 직접적인 사용자 결정 항목, 후속 구현 단위가 구현 계획을 만들 수 있을 만큼 정리되었는지 확인한다.
- `[계획]`은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 정리되어 구현 계획을 만들 수 있는 상태다.
- `[검토중]`은 모든 기능 Task와 Task 안에 명시된 검증이 충족된 것으로 보이나, 사용자 최종 확인과 archive 승인이 남은 완료 후보 상태다.
- 검토 결과 보완이 필요하면 별도 reopen 상태를 만들지 않고 `[진행중]`으로 되돌린 뒤 `완료 리뷰` 또는 `작업 컨텍스트`에 보완 방향을 남긴다.
- 검토 결과 보류 또는 폐기 결정이 나면 `[보류]` 또는 `[폐기]`로 전환한다.
- `ROADMAP.md`의 Phase 흐름은 실행 순서가 아니라 도메인/책임 영역의 구조적 지도다. 상태 그룹은 완료, 검토중, 진행중, 계획, 스케치 순서를 기본으로 하되 실제 다음 작업 선택은 `priority-queue.md`를 우선한다.
- `PHASE.md`의 Milestone 흐름은 해당 Phase 안의 상태 정리 흐름이다. Phase를 가로지르는 실행 순서로 해석하지 않는다.
- `ROADMAP.md`의 Phase 흐름과 `PHASE.md`의 Milestone 흐름은 완료, 검토중, 진행중, 계획, 스케치 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
- Epic heading은 `### Epic: [epic-id] <이름>` 형식으로 작성한다.
- Task는 `- [ ] [item-id] 설명` 또는 `- [x] [item-id] 설명` 형식으로 작성한다.
- epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 해당 Milestone 안에서만 유일하면 된다.
@ -125,10 +99,8 @@ agent-roadmap/
## 로딩 원칙
- 일반 갱신은 로컬 `current.md`, 관련 활성 Phase, 관련 활성 Milestone을 우선 읽는다.
- `current.md`가 없고 활성 창 갱신이 필요하면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 로컬 파일을 만든다.
- 일반 갱신은 `current.md`, 관련 활성 Phase, 관련 활성 Milestone을 우선 읽는다.
- `ROADMAP.md`는 Phase 흐름, 전체 구조, 활성 범위 밖 작업, 전체 재계획, archive 링크 갱신이 필요할 때 읽는다.
- `priority-queue.md`는 Phase를 가로지르는 다음 작업 후보 선택, 사용자가 요청한 순서 조정, archive/폐기/경로 변경/split/merge 후 큐 정리, 깨진 링크 복구가 필요할 때 읽고 갱신한다.
- `agent-roadmap/archive/**`는 일반 작업이나 sync에서 읽지 않는다.
- archive 모드에서 이동 대상이 아직 활성 경로에 있으면 그 대상 문서는 읽을 수 있다.
- 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 요청이면 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라 필요한 archive 문서만 읽는다.
@ -136,40 +108,16 @@ agent-roadmap/
## 템플릿
- `ROADMAP.md`: `agent-ops/skills/common/_templates/roadmap-template.md`
- `priority-queue.md`: `agent-ops/skills/common/_templates/roadmap-priority-queue-template.md`
- `current.md`: `agent-ops/skills/common/_templates/roadmap-current-template.md`
- `PHASE.md`: `agent-ops/skills/common/_templates/roadmap-phase-template.md`
- Milestone: `agent-ops/skills/common/_templates/roadmap-milestone-template.md`
- SDD: `agent-ops/skills/common/_templates/roadmap-sdd-template.md`
- SDD 사용자 리뷰: `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md`
## 링크 표기
- 사용자에게 보여주는 결과 보고와 새로 생성/갱신하는 로드맵 문서에서 `ROADMAP.md`, `priority-queue.md`, `current.md`, `PHASE.md`, Milestone 문서, SDD, `USER_REVIEW.md`, archive 문서, `complete.log` 같은 문서/산출물 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
- 로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`와 `current.md`에서는 `[PHASE.md](phase/<phase-slug>/PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/<milestone-slug>.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다.
- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase/<phase-slug>/PHASE.md)`.
- `경로:`, `Phase:`, `Milestone:`, `SDD 문서:`, `수정 파일:` 같은 필드명을 유지해야 해도 값은 Markdown 링크로 작성한다.
- 실제 갱신한 활성 로드맵 문서에는 `<phase-slug>`, `<milestone-slug>`, `<relative-...>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
- 기존 문서에 남아 있는 raw path나 backtick path는 읽기/마이그레이션 입력으로 허용한다. 갱신 범위에 포함된 활성 문서 포인터만 Markdown 링크로 보정하고, archive 스냅샷은 링크 표기만을 이유로 재포맷하지 않는다.
- `.agent-roadmap-sync/locks.yaml`의 `locked`, `rely-on.target`, Milestone identity(`<project>:agent-roadmap/...`), 명령 입력값처럼 machine-readable 계약 값은 raw 값을 유지할 수 있다. 다만 사용자-facing 설명에는 가능한 경우 별도 Markdown 문서 링크를 함께 붙인다.
## 구현 잠금
- `구현 잠금`은 승인 절차가 아니라 에이전트가 확정할 수 없는 결정이 필요한지 표시하는 얇은 상태다.
- 제품 방향, 범위, 우선순위, 책임 경계처럼 에이전트가 확정할 수 없는 항목이 남아 있으면 `잠금`으로 두고 `결정 필요` 목록에 남긴다.
- `구현 잠금`은 승인 절차가 아니라 사용자 결정이 필요한지 표시하는 얇은 상태다.
- 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 `잠금`으로 두고 `결정 필요` 체크리스트에 질문을 적는다.
- 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 `결정 필요`가 아니라 `작업 컨텍스트`의 표준선으로 기록한다.
- Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다.
- `구현 잠금` 섹션이 없거나, 상태가 `잠금`이거나, 미완료 `결정 필요` 항목이 하나라도 있으면 실구현 계획, 코드 구현, Milestone 완료 후보 전환을 차단한다.
- 잠금 상태에서 허용되는 갱신은 잠금 해소, SDD gate 처리, 범위 제외/후속 Milestone 이동, 작업 컨텍스트 정리 같은 roadmap-only 변경뿐이다.
- 남은 `결정 필요` 항목이 현재 Milestone 실구현 범위가 아니면 먼저 그 항목을 `범위 제외`, 후속 Milestone, 또는 `작업 컨텍스트`로 옮긴 뒤 `구현 잠금`을 `해제`한다. 잠금 해제 전에는 기능 Task 완료 근거가 있어도 `[검토중]`으로 올리지 않는다.
- SDD gate가 필요한 Milestone은 `구현 잠금`에 `SDD: 필요`, 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크, 잠금 해제 조건을 남기고 SDD 잠금이 해제될 때까지 `잠금`으로 둔다.
- 새 Milestone을 만들거나 `[스케치]`를 `[계획]`으로 승격하면서 `SDD: 필요`로 판정한 경우, 같은 `update-roadmap` 흐름 안에서 `roadmap-sdd create`까지 수행해 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`를 만든다. `SDD: 필요`와 SDD 문서 링크만 남기고 파일이 없는 상태로 종료하지 않는다.
- SDD 작성에 필요한 목표, 범위, 기능 Task, Acceptance Scenario 후보를 이미 판단했고 사용자만 결정할 항목이 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 두고 Milestone `구현 잠금`도 `해제`한다.
- 사용자만 결정할 항목이 있으면 SDD 초안을 만들고 `roadmap-sdd review-ready` 방식으로 `USER_REVIEW.md`를 남긴다. 이 경우 Milestone `구현 잠금`은 `잠금`으로 둔다.
- SDD 파일을 만들 수 없는 예외는 사용자가 명시적으로 SDD 생성을 뒤로 미룬 경우뿐이다. 이때 결과 보고에 `SDD gate: 필요-작성 전`과 구체적인 지연 사유를 남긴다.
- SDD gate가 불필요한 Milestone은 `SDD: 불필요`과 짧은 사유를 남긴다.
- SDD가 필요한 기준: cross-repo 계약, 외부 provider 쓰기, 상태 머신/lifecycle, idempotency/retry/identity map, API/proto/config/env/schema 변경, field smoke, 사용자 승인 gate 영향.
- SDD 사용자 리뷰가 필요한 결정은 chat으로 즉시 묻지 않고 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md`에 남긴다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다.
- 잠금 상태 변경은 Milestone 완료 판정이 아니므로 `기능` Task를 자동 완료 처리하지 않는다.
- `[스케치]` Milestone은 `구현 잠금`이 `해제`로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 승격 조건을 충족해 `[계획]`으로 전환한다.
@ -187,10 +135,10 @@ agent-roadmap/
2. 사용자가 명시한 프로젝트와 Milestone slug
3. 사용자가 명시한 프로젝트와 Milestone 제목의 정규화 일치
4. 잠긴 Milestone 문서의 `선행 <project> Milestone: ...`, `관련 <project> Milestone: ...`, `외부 의존 잠금: ...`에 적힌 slug/제목 힌트
5. 프로젝트명만 있고 Milestone 힌트가 없을 때만 해당 프로젝트 로컬 `current.md`의 활성 Milestone 단일 후보
5. 프로젝트명만 있고 Milestone 힌트가 없을 때만 해당 프로젝트 `current.md`의 활성 Milestone 단일 후보
- 정규화 비교는 소문자 변환, backtick/따옴표 제거, 영문/숫자가 아닌 연속 문자를 `-` 하나로 치환, 앞뒤 `-` 제거 후 비교한다. 정규화한 힌트는 Milestone 파일 slug와 정규화한 제목 둘 다에 대조한다.
- 2-4번 탐색은 대상 프로젝트의 `agent-roadmap/phase/*/milestones/*.md` 활성 문서만 대상으로 한다. archive 문서는 사용자가 archive 경로를 명시한 경우 외에는 읽거나 후보로 삼지 않는다.
- 후보가 없거나 둘 이상이면 `locks.yaml`을 만들거나 고치지 말고 모호성을 보고한다. 잠금 대상 확정이 제품/범위 결정이면 대상 Milestone의 `구현 잠금 > 결정 필요`로 분리한다.
- 후보가 없거나 둘 이상이면 `locks.yaml`을 만들거나 고치지 말고 사용자에게 대상 Milestone 선택을 요청한다.
- 외부 의존 잠금 요청이 있거나, 갱신 대상 Milestone이 `구현 잠금: 잠금`이며 문서에 외부 의존 잠금/선행 Milestone 컨텍스트가 있으면 `.agent-roadmap-sync/locks.yaml`을 upsert한다. resolvable한 외부 의존 문구를 Milestone에 남기고 lock entry를 누락하지 않는다.
- 외부 의존 잠금을 만들 때 대상 Milestone의 `구현 잠금`은 `잠금`으로 둔다.
- 새 `rely-on.status`는 선행 Milestone 상태에서 파생한다. `[검토중]` 또는 `[완료]`이면 `enable`, 그 외 상태거나 상태를 확인할 수 없으면 `disable`이다.
@ -205,42 +153,22 @@ agent-roadmap/
## 완료 리뷰와 검토중 상태
- Task 완료 또는 Milestone 갱신 후 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`인지 확인하고, `구현 잠금`이 `해제`이며 미완료 `결정 필요` 항목이 없는지 함께 확인한다.
- 기능 Task가 모두 충족되어도 `구현 잠금`이 남아 있으면 Milestone을 `[검토중]`으로 바꾸지 않는다. `완료 리뷰` 또는 `작업 컨텍스트`에 잠금 차단 항목을 남기고, 잠금 해소 roadmap 갱신을 먼저 요구한다.
- 기능 Task와 구현 잠금이 모두 충족된 것으로 보이면 Milestone을 `[완료]`로 바로 바꾸거나 archive로 이동하지 말고 `[검토중]`으로 바꾼다.
- Task 완료 또는 Milestone 갱신 후 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`인지 확인한다.
- 모두 충족된 것으로 보이면 Milestone을 `[완료]`로 바로 바꾸거나 archive로 이동하지 말고 `[검토중]`으로 바꾼다.
- `[검토중]`으로 바꿀 때는 Milestone 문서의 `완료 리뷰` 섹션을 만들거나 갱신한다.
- `완료 리뷰`에는 `상태: 검토중`, `요청일`, 완료 근거 1~3줄, 남은 차단 항목, 리뷰 코멘트를 남긴다. 에이전트가 확정할 수 없는 결정 항목은 완료 리뷰가 아니라 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
- `구현 잠금`이 해제되어 있지 않으면 `[완료]`로 전환하거나 archive하지 않는다. 잠금 해소 roadmap 갱신을 먼저 요구한다.
- 기능 Task, 검증, 구현 잠금이 모두 충족되어 있으면 `완료 리뷰`를 `상태: 통과`로 바꾸고 Milestone 상태를 `[완료]`로 전환한 뒤 archive 모드를 수행할 수 있다.
- 보완 근거가 있으면 `완료 리뷰`를 `상태: 보완 필요`로 바꾸고 Milestone 상태를 `[진행중]`으로 되돌린다. 이때 보완 방향을 `완료 리뷰` 또는 `작업 컨텍스트`에 남기며 별도 reopen 상태는 만들지 않는다.
- 보류 또는 폐기 근거가 있으면 `완료 리뷰`와 Milestone 상태를 각각 `보류`/`[보류]`, `폐기`/`[폐기]`로 맞춘다. `[폐기]`는 archive 대상이 될 수 있다.
- Phase는 하위 Milestone이 모두 `[완료]` 또는 `[폐기]`로 정리되고 Phase 목표도 충족된 것으로 보일 때 `[완료]` 또는 `[폐기]`로 archive한다.
### agent-ui 코드 동기화 Milestone 완료 리뷰
- 이 절은 `sync-agent-ui`가 코드 작업을 `milestone-required`로 라우팅했거나 사용자가 명시해 Milestone `완료 리뷰`에 `agent-ui 상태 반영: 대기`가 있는 경우에만 적용한다.
- agent-ui 문서만 갱신한 Milestone, 작은 `direct-sync` 작업, 일반 `plan-required` 작업, `agent-ui 상태 반영: 해당 없음`인 Milestone에는 적용하지 않는다.
- 기존 Milestone에 `agent-ui 상태 반영` 항목이 없으면 `해당 없음`으로 취급한다. 문서 구조 보정 또는 해당 Milestone 갱신 범위에 포함될 때만 `agent-ui 상태 반영: 해당 없음`을 보강한다.
- 사용자가 "이 Milestone을 종료해도 될지 검토", "마일스톤 완료 검토", "종료 검토"처럼 완료 리뷰를 요청했거나 `review-state=통과`로 갱신할 때 적용한다.
- agent-ui 코드 동기화 Milestone이 완료 리뷰 `통과` 조건을 충족하면 `[완료]` 전환 또는 archive 전에 관련 agent-ui view/component/frame 문서의 `status`를 `구현됨`으로 반영할 수 있다.
- 상태 반영은 완료 evidence가 직접 가리키는 agent-ui 활성 문서에만 적용한다. Milestone 전체 완료만을 근거로 `agent-ui/definition/**` 전체를 일괄 `구현됨`으로 바꾸지 않는다.
- 각 대상 문서는 실제 존재하는 code evidence path와 최종 검증 근거가 있어야 `구현됨`으로 바꾼다. 근거가 없으면 `계획` 또는 기존 상태를 유지하고 완료 리뷰를 `보완 필요`로 둔다.
- agent-ui 상태 반영은 `update-agent-ui`의 문서 갱신 규칙을 따르고, 반영 후 `validate-agent-ui`로 정합성을 확인한다. 이 단계는 이미 완료된 코드 반영의 문서 상태 갱신이므로 `sync-agent-ui`를 새로 실행하지 않는다.
- status/code evidence 반영과 `validate-agent-ui`가 모두 통과하면 Milestone `완료 리뷰`의 `agent-ui 상태 반영`을 `완료`로 바꾼다.
- 근거 부족, 미해결 USER_REVIEW, 또는 `validate-agent-ui` 실패로 반영하지 못하면 Milestone `완료 리뷰`의 `agent-ui 상태 반영`을 `차단: <사유>`로 바꾸고 `상태: 보완 필요`를 남긴다.
- `validate-agent-ui`가 FAIL이거나 현재 범위에 미해결 `agent-ui/USER_REVIEW.md`가 있으면 Milestone을 `[완료]`로 전환하지 않고 완료 리뷰를 `보완 필요`로 둔다.
- `agent-ui 상태 반영: 대기`가 아닌 Milestone에서는 완료 리뷰 중 agent-ui status를 변경하지 않는다.
- `완료 리뷰`에는 `상태: 요청됨`, `요청일`, 완료 근거 1~3줄, 사용자 최종 확인 항목, 리뷰 코멘트를 남긴다.
- 사용자가 승인하면 `완료 리뷰`를 `상태: 승인됨`으로 바꾸고 Milestone 상태를 `[완료]`로 전환한 뒤 archive 모드를 수행한다.
- 사용자가 보완을 요구하면 `완료 리뷰`를 `상태: 보완 필요`로 바꾸고 Milestone 상태를 `[진행중]`으로 되돌린다. 이때 보완 방향을 `완료 리뷰` 또는 `작업 컨텍스트`에 남기며 별도 reopen 상태는 만들지 않는다.
- 사용자가 보류 또는 폐기를 지시하면 `완료 리뷰`와 Milestone 상태를 각각 `보류`/`[보류]`, `폐기`/`[폐기]`로 맞춘다. `[폐기]`는 archive 대상이 될 수 있다.
- Phase는 하위 Milestone이 모두 `[완료]` 또는 `[폐기]`로 정리되고 Phase 목표도 충족된 것으로 보일 때 `[검토중]`으로 두고, 사용자 승인 후 `[완료]` 또는 `[폐기]`로 archive한다.
## Milestone task group 연동
- 런타임 완료 이벤트의 `origin-task`에서 `agent-task/` 다음 첫 path segment가 `m-<milestone-slug>`이면 Milestone 기반 plan/review 완료에서 온 요청으로 본다. `origin-task`는 archive 이동 전 active task 경로 또는 런타임이 그 형태로 정규화한 경로를 사용한다.
- `<milestone-slug>`는 활성 `agent-roadmap/phase/*/milestones/<milestone-slug>.md`에서 정확히 하나만 찾아야 한다. archive Milestone은 target 후보가 아니다.
- target이 없거나 둘 이상이면 Milestone 내용을 추정해 수정하지 말고 target 불명확으로 보고한다.
- target이 확정되어도 `complete-log` 입력이 없거나 해당 파일에 `Roadmap Completion` 섹션이 없으면 Milestone 기능 Task를 체크하지 않고 no-op으로 보고한다. 일반 `m-*` 완료 이벤트만으로 Task를 추정해 체크하지 않는다.
- `Roadmap Completion` 섹션이 있으면 Milestone 경로가 target과 일치하는지, Completed task ids의 각 id가 해당 Milestone의 기존 기능 Task id 하나와 정확히 일치하는지 확인한다. 하나라도 일치하지 않으면 수정하지 말고 target 불일치로 보고한다.
- target Milestone이 `SDD: 필요`이면 런타임 완료 이벤트의 `complete-log`에 있는 `Roadmap Completion`과 최종 검증 evidence가 SDD `Evidence Map`을 충족해야 한다. 사용자가 `update-roadmap` 요청에 별도 evidence를 명시해 수동 반영을 요구한 경우에만 Evidence Map 충족 근거를 보조 근거로 사용할 수 있다. 근거가 없으면 `Roadmap Completion`이 있어도 Task를 체크하지 않고 SDD evidence 부족으로 보고한다.
- 일치하면 PASS evidence, `complete.log`, final archive path, archived plan/review log 경로, code-review 결과 요약을 근거로 `Roadmap Completion`에 적힌 기능 Task만 `[x]`로 갱신한다. target routing 자체는 완료 이벤트의 `m-<milestone-slug>` task group과 `complete.log`의 `Roadmap Completion` 섹션으로 결정한다.
- 갱신 후 모든 기능 Task와 Task 안에 명시된 검증이 충족되어도 `구현 잠금`이 해제되어 있지 않으면 `[검토중]` 전환을 하지 않고 잠금 차단으로 보고한다. 기능 Task와 구현 잠금이 모두 충족될 때만 `[검토중]` 전환과 `완료 리뷰` 요청 규칙을 적용한다.
- target이 확정되면 PASS evidence, `complete.log`, final archive path, archived plan/review log 경로, code-review 결과 요약을 근거로 해당 Milestone의 기능 Task를 갱신한다. target routing 자체는 완료 이벤트의 `m-<milestone-slug>` task group으로만 결정한다.
- 갱신 후 모든 기능 Task와 Task 안에 명시된 검증이 충족되면 `[검토중]` 전환과 `완료 리뷰` 요청 규칙을 적용한다.
- target Milestone이 `[스케치]`이면 완료 이벤트를 반영하지 말고 상태 불일치로 보고한다. `[스케치]`는 Milestone 기반 `agent-task` 완료 이벤트의 target이 될 수 없다.
## 삽입 단위 정책
@ -252,7 +180,7 @@ agent-roadmap/
| 새 Epic | 기존 Milestone 안에서 여러 Task를 묶는 상위 capability 또는 산출물이다 |
| 새 Task | 기존 Epic 아래에 들어가는 완료 가능한 capability 또는 산출물이다. 검증이 필요한 경우에만 같은 Task 안에 붙인다 |
| 하위 작업 | 기존 Task를 완성하기 위한 구현 세부다. Milestone `기능`에는 하위 체크박스로 만들지 않고, plan 내부 체크리스트나 기존 Task의 `검증:`/설명 보강으로 다룬다 |
| 작업 컨텍스트/TODO | 에이전트가 확정할 수 없는 결정 또는 조사/확인이 먼저 필요해 기능 Task로 확정하기 어렵다 |
| 작업 컨텍스트/TODO | 사용자 결정 또는 조사/확인이 먼저 필요해 기능 Task로 확정하기 어렵다 |
- 먼저 요청 내용의 규모를 판정한다. 배치 위치를 찾기 전에 `phase`, `milestone`, `epic`, `task`, `subtask`, `context` 중 가장 작은 충분한 단위를 고른다.
- 요청이 방향성, 문제의식, 컨셉, 운영 원칙 수준이고 기능 Task나 실행 범위가 아직 부족하면 새 항목의 상태는 `[스케치]`로 둔다.
@ -263,12 +191,12 @@ agent-roadmap/
- `<item-id> 앞/뒤`는 같은 Epic 안의 형제 Task로 넣는다.
- `<item-id> 아래`는 해당 Task의 설명 또는 `검증:`을 보강한다. 구현 세부나 테스트만 따로 떼어낸 하위 체크박스는 Milestone `기능` 아래에 만들지 않는다.
- `<phase-name> 안`은 새 Milestone 또는 기존 Milestone/Epic/Task 중 작업 성격에 맞는 단위로 배치한다.
- 위치 지정이 없으면 `auto`로 본다. 로컬 `current.md`의 활성 창만으로 결정하지 않고, 필요한 경우 `ROADMAP.md`의 Phase 흐름까지 확인해 완료/검토중/진행중/계획/스케치 Phase를 비교한다.
- 위치 지정이 없으면 `auto`로 본다. `current.md`의 활성 창만으로 결정하지 않고, 필요한 경우 `ROADMAP.md`의 Phase 흐름까지 확인해 완료/검토중/진행중/계획/스케치 Phase를 비교한다.
- target 없는 신규 추가 요청은 요청 문장, 관련 파일/도메인 힌트, Phase 목표, Milestone 목표, 기존 Epic/Task, 선후 의존성, 상태, 활성 창을 비교해 가장 자연스러운 위치를 자동 판단한다.
- 자동 배치 후보가 여러 개이면 1순위와 2순위 후보를 비교하고, 선택한 Phase/Milestone/Epic/Task와 밀린 후보의 이유를 짧게 남긴다.
- 관련성이 비슷하면 `[진행중]` Milestone을 `[계획]` Milestone보다 우선하되, `[검토중]` Milestone은 리뷰 보완 요청이 아닌 신규 작업의 기본 배치 대상으로 삼지 않는다.
- 자동 배치한 경우 결과 보고에 선택한 삽입 단위, 위치, 판단 근거, 비교한 후보를 짧게 남긴다.
- 사용자 지정 위치가 Phase 목표, Milestone 범위 제외, 선후 의존성과 충돌하면 충돌을 보고하고 수정하지 않는다. 제품/범위 결정으로 해소해야 하면 대상 Milestone의 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
- 사용자 지정 위치가 Phase 목표, Milestone 범위 제외, 선후 의존성과 충돌하면 수정 전에 사용자에게 확인한다.
## 레벨별 탐색과 upsert 정책
@ -288,7 +216,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 조사, 결정, 보류 질문이면 작업 컨텍스트/TODO 규모다.
3. **레벨별 탐색**
- Phase 후보를 먼저 찾는다. 로컬 `current.md`의 활성 Phase를 우선 보되, target이 없거나 활성 범위 밖 가능성이 있으면 `ROADMAP.md`의 Phase 흐름도 본다.
- Phase 후보를 먼저 찾는다. `current.md`의 활성 Phase를 우선 보되, target이 없거나 활성 범위 밖 가능성이 있으면 `ROADMAP.md`의 Phase 흐름도 본다.
- 선택한 Phase 안에서 Milestone 후보를 찾는다. 활성 Milestone을 우선 보되, 요청이 계획 Milestone 목표와 더 직접 맞으면 계획 Milestone도 후보로 둔다.
- 선택한 Milestone 안에서 Epic 후보를 찾는다. `기능`의 Epic heading, 목표 설명, Task 묶음을 비교한다. 기존 문서가 `필수 기능`을 쓰면 갱신 시 `기능`으로 정규화한다.
- 선택한 Epic 안에서 Task 후보를 찾는다. item-id, 문장 의미, Task 안의 검증 문구, 관련 경로를 비교한다.
@ -298,7 +226,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 같은 id, 같은 제목, 같은 목표, 같은 관련 경로, 같은 Task 안의 검증 문구, 또는 같은 산출물을 다루면 동일/유사 후보로 본다.
- 동일 항목이면 새로 만들지 않고 기존 Phase/Milestone/Epic/Task를 업데이트한다.
- 기존 항목의 범위를 보강하는 내용이면 해당 항목의 설명, Task 안의 검증 문구, 작업 컨텍스트 중 알맞은 곳에 병합한다.
- 기존 항목과 충돌하거나 범위 제외를 건드리면 충돌을 보고하고 수정하지 않는다. 제품/범위 결정으로 해소해야 하면 대상 Milestone의 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
- 기존 항목과 충돌하거나 범위 제외를 건드리면 수정 전에 사용자에게 확인한다.
- 같은 레벨에 적절한 후보가 없을 때만 새 항목을 만든다. 새 항목도 판정한 규모보다 크게 만들지 않는다.
- 부모 레벨 후보는 있고 판정 규모의 항목만 없으면, 부모 아래에 판정 규모의 새 항목을 만든다. 부모 레벨도 없을 때만 필요한 부모 항목을 함께 만든다.
@ -307,30 +235,26 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
### Milestone archive
- 대상 Milestone이 `[완료]` 또는 `[폐기]`인지 확인한다.
- `[검토중]` Milestone은 archive하지 않는다. 완료 근거가 있어도 `구현 잠금`이 해제되어 있지 않으면 `[완료]`로 바꾸지 않는다. 명시적인 폐기 근거가 있으면 `[폐기]`로 바꾼 뒤 archive할 수 있다.
- `[완료]` archive 대상은 `구현 잠금`이 해제되어 있고 미완료 `결정 필요` 항목이 없어야 한다. `[폐기]` archive는 이 완료 잠금 조건을 요구하지 않는다.
- `[검토중]` Milestone은 archive하지 않는다. 사용자 완료 승인 또는 폐기 지시가 있으면 먼저 `[완료]` 또는 `[폐기]`로 바꾼 뒤 archive한다.
- archive 이동 전에 대상 Milestone의 활성 경로 identity(`<project>:agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`)를 보존한다.
- `locks.yaml`이 있으면 보존한 identity로 `--find-milestone "<identity>" both "<locks-file>"`를 실행해 이 Milestone이 `locked`인지, `rely-on.target`인지, 관련 lock이 없는지 먼저 확인한다.
- 보존한 identity가 `.agent-roadmap-sync/locks.yaml`의 `rely-on.target`에 있으면 archive 이동 전에 상태를 동기화한다. `[완료]`이면 `enable`, `[폐기]`이면 `disable`이다.
- 보존한 identity가 `.agent-roadmap-sync/locks.yaml`의 `locked`에 있으면 archive 이동 전에 의존 조건 충족 여부를 결과 보고에 남긴다.
- find 결과가 `none`이면 `Workspace 잠금: 관련 lock 없음`으로 보고한다.
- 대상 파일을 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`에서 `agent-roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md`로 이동한다.
- 활성 SDD 디렉터리 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/`가 있으면 `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/`로 이동한다. `USER_REVIEW.md`가 남아 있으면 archive하지 말고 해결 필요로 보고한다.
- 활성 `PHASE.md`의 Milestone 흐름에는 `[완료]` 또는 `[폐기]` 항목을 남기고, 경로는 archive 경로로 바꾼다.
- `priority-queue.md`가 있으면 대상 Milestone의 활성 경로 항목을 제거한다. archive 경로로 바꿔 남기지 않는다.
- 로컬 `current.md`의 활성 Milestone에서는 제거한다.
- `current.md`의 활성 Milestone에서는 제거한다.
- `ROADMAP.md`는 Phase 상태나 경로가 바뀌지 않으면 수정하지 않는다.
- 이동한 archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다.
### Phase archive
- Phase 전체가 `[완료]` 또는 `[폐기]`인지 확인한다.
- `[검토중]` Phase는 archive하지 않는다. 완료 또는 폐기 근거가 충족되면 먼저 `[완료]` 또는 `[폐기]`로 바꾼 뒤 archive한다.
- `[검토중]` Phase는 archive하지 않는다. 사용자 완료 승인 또는 폐기 지시가 있으면 먼저 `[완료]` 또는 `[폐기]`로 바꾼 뒤 archive한다.
- `agent-roadmap/phase/<phase-slug>/PHASE.md`를 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`로 이동한다.
- 해당 Phase의 하위 Milestone도 `archive/phase/<phase-slug>/milestones/` 아래로 이동한다.
- `ROADMAP.md`의 Phase 흐름에는 해당 Phase 항목을 남기고, 상태와 경로를 archive `PHASE.md`로 바꾼다.
- `priority-queue.md`가 있으면 해당 Phase 하위 활성 Milestone 항목을 모두 제거한다. archive 경로로 바꿔 남기지 않는다.
- 로컬 `current.md`의 활성 Phase와 활성 Milestone에서는 해당 Phase와 하위 Milestone을 제거한다.
- `current.md`의 활성 Phase와 활성 Milestone에서는 해당 Phase와 하위 Milestone을 제거한다.
- archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다.
## 실행 절차
@ -338,18 +262,15 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
1. **갱신 범위 결정**
- 요청에서 mode, 대상 Phase/Milestone, placement, placement-unit을 추론한다.
- 런타임 완료 이벤트의 `origin-task` task group이 `m-<milestone-slug>`이면 `target-milestone`을 활성 Milestone 경로 매칭으로 확정한다.
- 런타임 완료 이벤트가 `complete-log`를 전달하면 파일을 읽고 `Roadmap Completion` 섹션 유무와 Completed task ids를 확인한다. 섹션이 없으면 Milestone 기능 Task 체크는 no-op이다. SDD 대상 Milestone이면 SDD `Evidence Map` 충족 여부도 확인한다.
- 구조 전환, 템플릿 보정, current 동기화는 `sync`로 본다.
- `priority-queue.md` 생성, 순서 조정, 깨진 링크 복구, archive/폐기/경로 변경/split/merge 후 큐 정리는 `sync` 또는 `replan`으로 본다.
- 완료/폐기 근거가 충족된 이동은 `archive`로 본다.
- 완료 리뷰 요청에서 대상 Milestone의 `완료 리뷰`가 `agent-ui 상태 반영: 대기`인지 확인한다. 항목이 없거나 `대기`가 아니면 agent-ui 상태 반영 단계를 적용하지 않는다.
- 사용자 승인 이후의 완료/폐기 이동은 `archive`로 본다.
- 새 기능 배치, Epic/Task 추가는 `milestone` 또는 `phase`로 본다.
- "로드맵에 추가"처럼 target이 없는 신규 작업 요청은 `placement=auto`, `placement-unit=auto`, `new-feature=<요청 내용>`으로 본다.
- 외부 의존 잠금 요청이면 `workspace-lock` 갱신으로 본다.
- 외부 의존 잠금 요청이 아니어도, 갱신 대상 Milestone이 `구현 잠금: 잠금`이고 외부 의존 잠금/선행 Milestone 컨텍스트가 있으면 `workspace-lock` 동기화 후보로 본다.
- 외부 의존 잠금 요청에서 "현재 마일스톤" 또는 target 생략 표현이 있으면 로컬 `current.md`의 활성 Milestone 단일 후보를 잠긴 대상으로 확정한다.
- 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 로컬 `current.md` 단일 후보 순서로 확정한다.
- 잠긴 대상 또는 의존 대상 후보가 없거나 둘 이상이면 `locks.yaml`을 수정하지 말고 모호성을 보고한다. 잠금 대상 확정이 제품/범위 결정이면 대상 Milestone의 `구현 잠금 > 결정 필요`로 분리한다.
- 외부 의존 잠금 요청에서 "현재 마일스톤" 또는 target 생략 표현이 있으면 `current.md`의 활성 Milestone 단일 후보를 잠긴 대상으로 확정한다.
- 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 `current.md` 단일 후보 순서로 확정한다.
- 잠긴 대상 또는 의존 대상 후보가 없거나 둘 이상이면 `locks.yaml`을 수정하지 말고 사용자에게 Milestone 선택을 요청한다.
2. **요청 정규화와 규모 판정**
- 요청에서 기능명, 목표, 관련 경로, 명시 anchor, 완료 기대, 제약을 추출한다.
@ -357,34 +278,27 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 동일/유사 항목이 이미 있으면 신규 추가가 아니라 업데이트 후보로 기록한다.
3. **레벨별 후보 탐색**
- 로컬 `current.md`의 활성 Phase와 활성 Milestone 후보를 확인한다.
- `current.md`의 활성 Phase와 활성 Milestone 후보를 확인한다.
- target이 명시된 경우 대상 Phase의 `PHASE.md`를 읽고 Milestone 흐름과 Phase 경계를 확인한다.
- target이 없거나 활성 창 밖 배치 가능성이 있으면 `ROADMAP.md`의 Phase 흐름을 확인하고, 관련성이 높은 Phase 문서를 읽는다.
- 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. SDD가 필요한 Milestone이면 SDD 문서 링크와 사용자 리뷰 상태도 확인한다. 기존 문서에 `필수 기능`/`완료 기준`이 분리되어 있으면 갱신 범위에서 `기능` Task로 흡수할 후보를 기록한다.
- 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. 기존 문서에 `필수 기능`/`완료 기준`이 분리되어 있으면 갱신 범위에서 `기능` Task로 흡수할 후보를 기록한다.
- Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
- 로컬 `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다.
- `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다.
- 필요한 경우에만 `ROADMAP.md`를 읽어 전체 Phase 흐름을 확인한다.
- Phase를 가로지르는 다음 작업 후보를 고르거나 큐 정리가 필요하면 `priority-queue.md`를 읽는다. 링크가 깨진 항목은 추측하지 말고 활성 `phase/*/milestones/*.md` 후보를 기준으로 재정렬 또는 재생성 대상으로 기록한다.
4. **스케치 승격 판단**
- `target-status=[계획]`, `mode=concretize`, 또는 사용자가 "구체화", "계획으로 올려"처럼 요청하면 `[스케치] -> [계획]` 승격 검토로 본다.
- 대상이 `[스케치]`가 아니면 일반 상태 갱신이나 Milestone 갱신으로 처리한다.
- 대상이 `[스케치]`이면 `승격 조건`, `구현 잠금`, SDD 필요 여부, `목표`, `범위`, `기능`, `작업 컨텍스트`를 확인한다.
- `승격 조건` 체크리스트가 남아 있거나 구현 계획에 직접 필요한 결정 항목이 남아 있으면 상태를 `[스케치]`로 유지하고, 부족한 항목을 `승격 조건` 또는 `결정 필요`에 보강한다.
- 구현 가능한 목표, 범위, 기능 Task, 필요한 결정 항목, 후속 구현 단위가 정리되면 상태를 `[계획]`으로 전환하고, `승격 조건`은 충족 요약으로 남기거나 `- 없음`으로 정리한다.
- 대상이 `[스케치]`이면 `승격 조건`, `구현 잠금`, `목표`, `범위`, `기능`, `작업 컨텍스트`를 확인한다.
- `승격 조건` 체크리스트가 남아 있거나 구현 계획에 직접 필요한 사용자 결정이 남아 있으면 상태를 `[스케치]`로 유지하고, 부족한 항목을 `승격 조건` 또는 `결정 필요`에 보강한다.
- 구현 가능한 목표, 범위, 기능 Task, 직접 결정 항목, 후속 구현 단위가 정리되면 상태를 `[계획]`으로 전환하고, `승격 조건`은 충족 요약으로 남기거나 `- 없음`으로 정리한다.
- 승격은 구현 완료가 아니므로 `기능` Task를 자동 완료 처리하지 않는다.
5. **변경 내용 작성**
- `ROADMAP.md`는 전체 목표, Phase 흐름, 로딩 정책이 바뀔 때만 수정한다.
- `priority-queue.md`가 없고 로드맵 구조를 표준화하거나 생성/동기화하는 요청이면 `roadmap-priority-queue-template.md` 형식으로 만든다.
- `priority-queue.md`는 사용자 순서 조정 요청, archive/폐기 제거, 경로 변경, split/merge, 실행 의미 변경, 깨진 링크 복구 때만 수정한다.
- `priority-queue.md`를 수정할 때는 Milestone 제목 링크와 식별용 한 줄 설명만 남기고, 상태, 목표, 범위, 잠금, 기능, 완료 근거, 의존성 필드를 복제하지 않는다.
- 로컬 `current.md`는 활성 Phase/Milestone 창이 바뀔 때 수정한다.
- `.gitignore`의 Agent-Ops 관리 block에 `agent-roadmap/current.md`가 있는지 확인하고 없으면 추가한다.
- `current.md`는 활성 Phase/Milestone 창이 바뀔 때 수정한다.
- `PHASE.md`는 Phase 목표, 상태, Milestone 흐름, Phase 경계가 바뀔 때 수정한다.
- Milestone 문서는 목표, 상태, 승격 조건, 구현 잠금, 범위, Epic/Task, Task 안의 검증 문구, 완료 리뷰, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
- 신규 또는 갱신 Milestone이 SDD 대상이면 `구현 잠금`에 `SDD: 필요`, 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크, 잠금 해제 조건을 남기고 같은 흐름에서 `roadmap-sdd create`로 SDD 본문을 작성한다. 사용자 결정이 필요 없고 gate가 충족되면 SDD와 Milestone 잠금을 함께 해제한다.
- SDD 대상이 아니면 `구현 잠금`에 `SDD: 불필요`와 짧은 사유를 남긴다.
- 동일/유사 후보가 있으면 기존 항목을 업데이트하고 중복 항목을 만들지 않는다.
- 새 Milestone은 해당 Phase의 `milestones/` 아래에 만든다.
- 새 `[스케치]` Milestone은 `승격 조건` 섹션을 포함하고 `구현 잠금`은 `잠금`으로 둔다.
@ -392,12 +306,9 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 새 Task는 관련 Epic 아래 `- [ ] [item-id] 설명`으로 만든다. 검증이 필요한 경우에만 같은 항목에 `검증: <명령/확인 방법/기대 결과>`를 붙인다.
- 새 항목은 레벨별 탐색에서 적절한 기존 후보가 없을 때만 만든다.
- 완료 체크는 evidence가 있을 때만 `[x]`로 바꾼다.
- 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`이어도 `구현 잠금`이 `해제`가 아니거나 미완료 `결정 필요` 항목이 있으면 Milestone 상태를 `[검토중]`으로 바꾸지 않는다. `완료 리뷰` 또는 `작업 컨텍스트`에 잠금 차단 항목을 남긴다.
- 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`이고 `구현 잠금`도 해제되어 있으면 Milestone 상태를 `[검토중]`으로 바꾸고 `완료 리뷰`에 완료 근거와 남은 차단 항목을 남긴다.
- `[검토중]` 전환만으로 archive 이동, 로컬 `current.md` 제거, archive 링크 변경을 수행하지 않는다.
- `agent-ui 상태 반영: 대기`인 Milestone의 완료 리뷰가 `통과` 후보이면 `[완료]` 전환 전에 관련 agent-ui 문서의 `status`를 `구현됨`으로 갱신할 수 있는지 확인한다. 대상 문서, code evidence, 최종 검증 근거, `validate-agent-ui` 결과가 모두 충족될 때만 반영하고 `agent-ui 상태 반영: 완료`로 바꾼다.
- agent-ui 상태 반영이 필요한데 근거가 부족하거나 `validate-agent-ui`가 통과하지 않으면 Milestone 상태를 `[진행중]` 또는 `[검토중]`으로 유지하고 `완료 리뷰: 보완 필요`와 `agent-ui 상태 반영: 차단: <사유>`를 남긴다.
- 기능 Task, 검증, 구현 잠금, 완료 근거가 모두 충족되면 `[검토중]`을 `[완료]`로 전환하고 archive 모드를 수행할 수 있다.
- 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`이면 Milestone 상태를 `[검토중]`으로 바꾸고 `완료 리뷰`에 리뷰 요청과 근거를 남긴다.
- `[검토중]` 전환만으로 archive 이동, `current.md` 제거, archive 링크 변경을 수행하지 않는다.
- 사용자 승인 근거가 있으면 `[검토중]`을 `[완료]`로 전환하고 archive 모드를 수행할 수 있다.
- `locks.yaml`이 있으면 갱신 대상 Milestone identity로 `--find-milestone "<identity>" both "<locks-file>"`를 실행해 이 Milestone이 `locked`인지, `rely-on.target`인지, 관련 lock이 없는지 확인한다.
- archive 모드이면 파일 이동 전 active Milestone identity를 보존하고, 그 identity로 `--find-milestone "<identity>" both "<locks-file>"`를 먼저 실행한다.
- 외부 의존 잠금 요청 또는 외부 의존 컨텍스트 동기화가 필요하면 대상 Milestone의 `구현 잠금`을 `잠금`으로 두고 `.agent-roadmap-sync/locks.yaml`을 upsert한다.
@ -409,16 +320,11 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- archive 모드에서 보존한 active Milestone identity와 일치하는 `rely-on.target`도 archive 이동 전에 Milestone 상태 기준으로 `enable` 또는 `disable`을 동기화한다.
- 갱신하거나 선택한 Milestone identity와 일치하는 `locked` entry가 있으면 모든 `rely-on.status`가 `enable`인지 확인하고 결과 보고에 남긴다.
- archive 모드에서 보존한 active Milestone identity와 일치하는 `locked` entry도 archive 이동 전에 모든 `rely-on.status`가 `enable`인지 확인하고 결과 보고에 남긴다.
- archive, 폐기, 경로 변경, split/merge 결과로 `priority-queue.md`를 수정했다면 제거/갱신된 항목을 결과 보고에 남긴다.
6. **검증**
- 로컬 `current.md`의 활성 Phase/Milestone 경로가 실제 파일을 가리키는지 확인한다.
- 로컬 `current.md`의 활성 항목이 archive 경로를 가리키지 않는지 확인한다.
- 로컬 `current.md`의 활성 항목이 `[완료]` 또는 `[폐기]` 상태로 남아 있지 않은지 확인한다.
- `agent-roadmap/current.md`가 git 추적 대상으로 남아 있지 않은지 확인한다.
- `agent-roadmap/priority-queue.md`가 있으면 `실행 순서` 섹션이 있고 모든 링크가 실제 활성 Milestone 파일을 가리키는지 확인한다.
- `priority-queue.md`에 archive 경로, `[완료]` archive 대상, `[폐기]` Milestone 항목이 남아 있지 않은지 확인한다.
- `priority-queue.md`가 비어 있는데 활성 실행 후보가 있으면 큐 동기화 필요로 보고한다. 실행 후보가 없으면 빈 큐를 허용한다.
- `current.md`의 활성 Phase/Milestone 경로가 실제 파일을 가리키는지 확인한다.
- `current.md`의 활성 항목이 archive 경로를 가리키지 않는지 확인한다.
- `current.md`의 활성 항목이 `[완료]` 또는 `[폐기]` 상태로 남아 있지 않은지 확인한다.
- `ROADMAP.md`의 Phase 경로가 실제 `PHASE.md` 파일을 가리키는지 확인한다.
- 각 `PHASE.md`의 Milestone 경로가 실제 파일을 가리키는지 확인한다.
- 상태 표기가 표준값인지 확인한다.
@ -426,12 +332,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- `[계획]` 이상 Milestone에 `승격 조건` 섹션이 없더라도 오류로 보지 않는다. 섹션이 있으면 `- 없음` 또는 승격 충족 요약인지 확인한다.
- `[스케치] -> [계획]` 전환을 수행했다면 승격 조건 해소 근거가 Milestone 내용이나 결과 보고에 남았는지 확인한다.
- `[검토중]` Milestone이 archive 경로로 이동되지 않았는지 확인한다.
- 모든 기능 Task와 Task 안에 명시된 검증이 `[x]`인 Milestone은 `구현 잠금`이 해제되어야 `[검토중]`이 될 수 있다. 잠금이 남아 있으면 `완료 리뷰` 또는 `작업 컨텍스트`에 잠금 차단 항목이 있는지 확인한다.
- `[검토중]` Milestone에는 `완료 리뷰` 섹션과 완료 근거/남은 차단 항목이 있는지 확인한다.
- `agent-ui 상태 반영: 대기`인 Milestone을 `[완료]`로 전환하는 경우, 완료 evidence가 가리키는 agent-ui 문서의 status/code evidence 반영 여부와 `validate-agent-ui` 결과가 완료 리뷰에 남았는지 확인한다.
- `agent-ui 상태 반영: 대기`가 아닌 Milestone 완료 리뷰에서 agent-ui 문서 status를 변경하지 않았는지 확인한다.
- 각 Milestone의 `구현 잠금`에 SDD 필요 여부와 사유가 있는지 확인한다.
- `SDD: 필요` Milestone은 SDD 문서 링크, SDD 파일 존재, 잠금 해제 조건, SDD 사용자 리뷰 상태가 일관되는지 확인한다. 사용자가 명시적으로 SDD 생성을 뒤로 미루지 않았는데 SDD 파일이 없으면 검증 실패로 본다.
- 모든 기능 Task와 Task 안에 명시된 검증이 `[x]`인 Milestone에는 `완료 리뷰` 섹션과 사용자 리뷰 요청이 있는지 확인한다.
- Epic heading과 Task id 형식이 맞는지 확인한다.
- 요청 규모가 판정되었고 결과 보고에 남았는지 확인한다.
- 동일/유사 기존 항목을 검색했고 신규/업데이트 판정이 결과 보고에 남았는지 확인한다.
@ -441,8 +342,6 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 갱신 대상 Milestone identity가 `locked` 또는 `rely-on.target` 어느 쪽에 있든 결과 보고의 `Workspace 잠금`에 반영했는지 확인한다.
- `locks.yaml`이 있는데 갱신 대상 Milestone identity가 `locked`와 `rely-on.target` 어느 쪽에도 없으면 `Workspace 잠금: 관련 lock 없음`으로 보고했는지 확인한다.
- archive 모드이면 이동 전 active Milestone identity로 `locks.yaml`을 검사하고 필요한 `rely-on.status` 동기화 또는 `관련 lock 없음` 보고를 수행했는지 확인한다.
- 결과 보고와 갱신한 활성 로드맵 문서의 문서/산출물 포인터가 raw path만 남지 않고 Markdown 링크로 작성되었는지 확인한다.
- 갱신한 활성 로드맵 문서의 Markdown 링크 target에 템플릿 placeholder가 남지 않았는지 확인한다.
- `git diff --check`로 공백 오류를 확인한다.
7. **결과 보고**
@ -453,12 +352,9 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 변경된 Phase / Milestone / 상태
- 신규 작업의 삽입 단위와 배치 위치
- 자동 배치한 경우 비교한 후보와 선택 근거
- 전역 실행 순서 변경 사항
- 로컬 current.md 활성 창 변경 사항
- 완료 리뷰 상태와 남은 차단 항목
- `agent-ui 상태 반영: 대기`인 Milestone이면 agent-ui status 반영 여부와 validate-agent-ui 결과
- SDD gate 상태와 사용자 리뷰 필요 여부
- 런타임 완료 이벤트의 `origin-task`가 `m-<milestone-slug>`이면 원래 active task 경로와 매칭된 target Milestone, `Roadmap Completion` Task ids 또는 no-op 사유
- current.md 활성 창 변경 사항
- 완료 리뷰 상태와 사용자 확인 필요 항목
- 런타임 완료 이벤트의 `origin-task`가 `m-<milestone-slug>`이면 원래 active task 경로와 매칭된 target Milestone 또는 target 불명확 사유
- archive 모드이면 이동 경로와 남긴 링크
- 확인 필요로 남긴 항목
@ -469,15 +365,11 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 모드: <status | milestone | phase | replan | sync | concretize | archive>
- 수정 파일:
- [ROADMAP.md](agent-roadmap/ROADMAP.md)
- [priority-queue.md](agent-roadmap/priority-queue.md)
- [current.md](agent-roadmap/current.md) (local)
- [PHASE.md](agent-roadmap/phase/<phase-slug>/PHASE.md)
- [<milestone-slug>.md](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) (SDD 작성/갱신 시)
- [USER_REVIEW.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md) (SDD 사용자 리뷰 요청 시)
- [archive PHASE.md](agent-roadmap/archive/phase/<phase-slug>/PHASE.md) 또는 [archive Milestone](agent-roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md) (archive 모드)
- [archive SDD.md](agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/SDD.md) (SDD archive 시)
- agent-roadmap/ROADMAP.md
- agent-roadmap/current.md
- agent-roadmap/phase/<phase-slug>/PHASE.md
- agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md
- agent-roadmap/archive/phase/<phase-slug>/... (archive 모드)
## 변경 사항
@ -489,23 +381,20 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 신규/업데이트 판정: <신규 생성 | 기존 항목 업데이트 | 변경 없음> - <동일/유사 후보 근거>
- 배치: <사용자 지정 위치 반영 | 자동 배치 위치와 근거 | 변경 없음>
- 배치 후보: <자동 배치 시 1순위/2순위 후보와 선택/제외 근거 | 해당 없음>
- 템플릿 보정: <ROADMAP | local current.md | PHASE | Milestone | 이미 일치 | 변경 없음>
- 전역 실행 순서: <변경 없음 | 생성 | 순서 조정 | archive/폐기 항목 제거 | 경로 갱신 | 재생성 필요>
- 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 잠금 차단 | 변경 없음>; 결정 필요: <없음 | 항목 요약>
- SDD gate: <불필요 | 필요-작성 전 | 필요-잠금 | 필요-사용자 리뷰 | 필요-승인됨 | 변경 없음>
- 템플릿 보정: <ROADMAP | current.md | PHASE | Milestone | 이미 일치 | 변경 없음>
- 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>; 결정 필요: <없음 | 항목 요약>
- 승격 조건: <해당 없음 | 추가/수정/미충족 유지/충족 요약>
- 완료 리뷰: <변경 없음 | 검토중 | 통과 | 보완 필요 | 보류 | 폐기>
- agent-ui 상태 반영: <해당 없음 | 대기 | 완료 | 차단: 사유 | 변경 없음>
- 완료 리뷰: <변경 없음 | 요청됨 | 승인됨 | 보완 필요 | 보류 | 폐기>
- runtime m-task 라우팅: <해당 없음 | origin-task -> target Milestone | target 불명확>
- Workspace 잠금: <변경 없음 | 관련 lock 없음 | entry 생성/갱신 | rely-on enable | rely-on disable | 미충족 | 런타임 해제 대기>
- 활성 항목: <변경 없음 | Phase/Milestone 추가/제거 요약>
- 아카이브: <변경 없음 | 이동 링크와 남긴 링크>
- 아카이브: <변경 없음 | 이동 경로와 남긴 링크>
- 상태: <변경 없음 | 이전 -> 이후>
- Epic/Task: <추가/수정/완료/제거 요약>
## TODO 항목
- <남은 차단 항목 또는 `구현 잠금 > 결정 필요`/SDD `USER_REVIEW.md`로 분리한 항목> (해당 시)
- <확인이 필요한 항목> (해당 시)
```
## 금지 사항
@ -514,20 +403,13 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- evidence 없이 Phase, Milestone, Epic, Task를 `[완료]` 또는 `[검토중]`으로 처리하지 않는다.
- 전체 `ROADMAP.md`를 모든 작업의 필수 로딩 파일로 만들지 않는다.
- `ROADMAP.md`에 Milestone 상세 작업 체크리스트를 남기지 않는다.
- `priority-queue.md`에 상태, 목표, 범위, 잠금, 기능, 완료 근거, 의존성 필드를 복제하지 않는다.
- `priority-queue.md`에 archive 경로를 남기지 않는다.
- 사용자 순서 조정 요청 없이 `priority-queue.md`의 순서를 에이전트 판단만으로 바꾸지 않는다. 단, archive/폐기 제거, 경로 변경, split/merge, 실행 의미 변경, 깨진 링크 복구는 예외다.
- 로컬 `current.md`에 개인별 현재 작업 위치나 완료 상태를 남기지 않는다.
- 로컬 `current.md`에 `agent-roadmap/archive/**` 경로를 남기지 않는다.
- `agent-roadmap/current.md`를 git 추적 대상으로 만들지 않는다.
- `current.md`에 개인별 현재 작업 위치나 완료 상태를 남기지 않는다.
- `current.md`에 `agent-roadmap/archive/**` 경로를 남기지 않는다.
- archive 문서를 명시 요청 없이 읽거나 최신 템플릿으로 재포맷하지 않는다.
- 완료된 Phase/Milestone 기록을 삭제하지 않는다.
- Epic과 Task를 별도 파일로 분리하지 않는다.
- Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
- 에이전트가 확정할 수 없는 결정 항목이 남아 있는데 Milestone의 `구현 잠금`을 `해제`로 바꾸지 않는다.
- `구현 잠금`이 남아 있는 Milestone을 `[검토중]`, `[완료]`, 또는 완료 archive 대상으로 전환하지 않는다. 명시적인 폐기 근거가 있는 `[폐기]` archive는 허용한다.
- `agent-ui 상태 반영: 대기`가 아닌 Milestone 완료 리뷰에서 agent-ui 문서 status를 변경하지 않는다.
- `agent-ui 상태 반영: 대기`인 Milestone이라도 최종 검증과 실제 code evidence 없이 agent-ui status를 `구현됨`으로 바꾸지 않는다.
- 사용자만 결정할 수 있는 항목이 남아 있는데 Milestone의 `구현 잠금`을 `해제`로 바꾸지 않는다.
- 사용자가 지정한 Phase/Milestone/Epic/Task anchor를 무시하지 않는다.
- 사용자가 명시하지 않은 기존 epic-id나 item-id를 바꾸지 않는다.
- `rely-on.status=enable`만으로 다른 프로젝트 Milestone의 `구현 잠금`을 직접 해제하지 않는다.

124
agent-ops/skills/common/update-spec/SKILL.md
View file

@ -1,124 +0,0 @@
---
name: update-spec
version: 1.0.0
description: agent-spec 갱신, 구현 스펙 업데이트, 완료 기능 스펙 반영, 코드/계약/테스트 변경 후 living spec 동기화 요청에 사용한다. agent-spec/index.md에서 관련 spec을 찾아 현재 코드와 계약 기준으로 갱신하고 Spec updated, Spec update not needed, create-spec needed, Spec blocked 결과를 남긴다.
---
# update-spec
## 목적
기존 agent-spec 문서를 현재 코드, 계약, 테스트, 완료 evidence에 맞게 갱신한다.
이 스킬은 spec 문서만 책임지며 roadmap 상태 전환, Milestone archive, 코드 구현 계획 생성을 수행하지 않는다.
## 언제 호출할지
- 사용자가 "스펙 업데이트", "구현 스펙 갱신", "완료 기능 스펙 반영", "agent-spec 갱신"을 요청할 때
- 코드, 계약, config, event, runtime flow, 테스트가 바뀌어 현재 구현 spec이 달라질 수 있을 때
- `complete-milestone`이 Milestone 종료 전에 spec sync gate를 수행할 때
- `create-spec` 이후 불명확/부분 상태의 spec을 추가 evidence로 보강할 때
## 입력
- `target-spec`: 갱신할 spec id 또는 문서 경로. 없으면 index와 변경 근거에서 추론한다. (선택)
- `target-milestone`: spec 갱신 근거가 되는 Milestone 경로, 이름, slug. (선택)
- `changed-files`: spec 영향 판단에 사용할 코드/계약/테스트 파일 목록. (선택)
- `complete-log`: 완료 근거로 사용할 `complete.log` 경로. (선택)
- `mode`: `update` 또는 `check-only`. 기본값은 `update`다. (선택)
## 먼저 확인할 것
- [ ] `agent-ops/rules/common/rules-agent-spec.md`를 읽는다.
- [ ] `agent-spec/index.md`가 있는지 확인한다. 없으면 `create-spec` 필요 또는 `skipped-no-agent-spec`으로 보고한다.
- [ ] 매칭 spec 문서만 읽는다.
- [ ] 계약에 닿는 변경이면 `agent-contract/index.md`를 읽고 매칭 계약 문서만 읽는다.
- [ ] Milestone 또는 complete.log 근거가 있으면 해당 활성 Milestone, SDD gate, complete.log의 관련 섹션만 확인한다.
## 실행 절차
1. **대상 spec 확정**
- `target-spec`이 있으면 해당 문서가 활성 `agent-spec/**` 아래에 정확히 존재하는지 확인한다.
- `target-spec`이 없으면 `agent-spec/index.md`의 읽는 조건, spec id, path, evidence와 `changed-files`/Milestone/complete.log를 비교한다.
- 매칭 spec이 없고 구현 스펙 영향이 명확하면 `create-spec` 필요로 보고한다. 이 스킬에서 새 spec 문서를 직접 만들지 않는다.
- 매칭 spec이 없고 변경이 spec 대상이 아니면 `Spec update not needed`로 보고한다.
- 둘 이상의 spec이 매칭되면 모두 갱신 대상 후보로 두되, 각 spec별 영향 근거를 분리한다.
2. **현재 구현 재확인**
- spec 본문만 믿지 말고 관련 코드, 계약, 테스트, 설정 예시를 다시 확인한다.
- complete.log와 roadmap은 변경 근거로 쓰되 현재 동작은 코드/계약으로 검증한다.
- SDD가 있으면 acceptance/evidence가 현재 spec과 어긋나는지 확인한다.
- spec과 코드/계약이 충돌하면 코드/계약을 우선하고 spec을 수정한다.
3. **영향 판정**
- 기능 목록, 범위, 주요 흐름, 계약 링크, 설정/데이터/이벤트, 검증, 한계 중 바뀐 항목을 식별한다.
- 기능 이해에 필요한 최소 책임 설명이 바뀐 경우만 spec에 반영한다.
- 코드 배치, 구현 진입점, 유지할 패턴, 금지 사항 변경은 domain rule 갱신 대상으로 본다.
- 변경이 테스트 fixture, 내부 리팩터링, 문구 정리처럼 현재 구현 spec에 영향을 주지 않으면 `Spec update not needed: <사유>`를 남긴다.
- 판단 불가이면 spec을 추정 갱신하지 않고 `Spec blocked: <필요 evidence>`로 보고한다.
4. **문서 갱신**
- `mode=check-only`이면 쓰지 않고 갱신 후보만 보고한다.
- 영향이 있는 spec 문서만 수정한다.
- frontmatter `status`와 `source_evidence`를 현재 evidence에 맞게 보강한다.
- `rules-agent-spec.md`의 기본 섹션 기준을 따른다.
- 기능 목록은 `기능`과 `설명` 중심으로 유지한다. 기능별 `상태` 칼럼은 기본 추가하지 않는다.
- `주요 흐름`은 긴 텍스트보다 Mermaid `sequenceDiagram` 또는 `flowchart`를 우선 고려한다.
- `코드 진입점` 섹션은 추가하지 않는다. 기존 spec에 있으면 현재 기준에 맞춰 제거하거나 `source_evidence`로 옮긴다.
- 계약 원문을 복제하지 않고 링크만 보강한다.
- 변경 기록에 날짜, 변경 근거, 관련 Milestone/complete.log/코드 경로를 남긴다.
5. **index 동기화**
- spec 상태, 읽는 조건, path, 주요 근거가 바뀌었으면 `agent-spec/index.md`의 Spec Map을 갱신한다.
- 새 spec 문서가 필요하면 `create-spec` 대상으로 보고하고 index를 추정 갱신하지 않는다.
- 폐기된 spec은 활성 문서에 남기지 않고 archive log로 이동할 후보로 보고한다. 명시 요청 없이 archive 이동하지 않는다.
6. **결과 분류**
- 갱신한 문서가 있으면 `Spec updated`로 보고한다.
- 영향 없음이 확인되면 `Spec update not needed: <사유>`로 보고한다.
- 매칭 spec이 없고 신규 작성이 필요하면 `create-spec needed: <사유>`로 보고한다.
- evidence 부족, 대상 모호, 사용자 결정 필요이면 `Spec blocked: <사유>`로 보고한다.
## 실행 결과 검증
- [ ] `agent-spec/index.md`에서 관련 spec만 읽었는가
- [ ] 코드/계약/테스트 기준으로 현재 동작을 재확인했는가
- [ ] spec 문서의 기본 섹션 기준과 frontmatter가 유지되는가
- [ ] 기능 목록이 기능/설명 중심이며 불필요한 상태 칼럼이나 과한 상세 설명을 만들지 않았는가
- [ ] 코드 진입점, 패키지 배치, 도메인별 금지 사항을 spec 본문에 반복하지 않았는가
- [ ] index의 Spec Map이 갱신한 spec 상태와 일치하는가
- [ ] 계약 원문을 복제하지 않았는가
- [ ] 갱신/불필요/create 필요/차단 중 하나의 결과가 명확한가
- [ ] `complete-milestone`에서 호출된 경우 Milestone 완료 리뷰에 남길 spec sync 문구를 제공했는가
- [ ] `git diff --check`를 실행했는가
- 검증 실패 시: roadmap이나 코드 파일을 수정하지 말고 spec 갱신 실패 사유를 보고한다.
## 출력 형식
```markdown
## Spec 동기화 결과
- 결과: <Spec updated | Spec update not needed | create-spec needed | Spec blocked | skipped-no-agent-spec>
- 대상 spec:
- <없음 | [spec-id](agent-spec/<area>/<spec-id>.md)>
- 수정 파일:
- <없음 | [index.md](agent-spec/index.md) | [spec](agent-spec/<area>/<spec-id>.md)>
- 근거:
- <코드/계약/테스트/complete.log/Milestone 요약>
- Milestone 완료 리뷰 문구:
- `Spec sync: <완료 | 해당 없음 | create-spec 필요: 사유 | 차단: 사유>`
## TODO 항목
- <남은 확인 필요 또는 없음>
```
## 금지 사항
- roadmap 상태 전환이나 archive 이동을 수행하지 않는다.
- 새 spec 문서를 생성하지 않는다. 신규 작성이 필요하면 `create-spec`으로 넘긴다.
- 코드 구현이나 테스트 코드를 수정하지 않는다.
- spec과 코드가 충돌할 때 spec을 그대로 신뢰하지 않는다.
- 매칭되지 않는 spec을 광범위하게 읽거나 전부 갱신하지 않는다.
- archive spec을 명시 요청 없이 읽거나 갱신하지 않는다.
- complete.log나 roadmap 문구만으로 현재 동작을 단정하지 않는다.
- 코드 진입점, 구현 배치, 도메인 간 상세 책임 경계, 유지할 패턴, 금지 사항을 domain rule 대신 agent-spec에 길게 쓰지 않는다.

189
agent-ops/skills/common/validate-agent-ui/SKILL.md
View file

@ -1,189 +0,0 @@
---
name: validate-agent-ui
version: 1.1.0
description: agent-ui scaffold, definition/frame/component/wireframe/source evidence/status 정합성을 맞추고 필요한 USER_REVIEW와 code sync intent를 분리하는 스킬
---
# validate-agent-ui
## 목적
`agent-ui/` 구조와 문서 그래프 정합성을 검사하고 자동 보정한다.
definition, component, frame, visual source, USER_REVIEW, archive가 서로 뒤처진 상태를 같은 수준으로 맞추며, UI 의도 판단이 필요한 문제는 `agent-ui/USER_REVIEW.md`에 남긴다.
## 언제 호출할지
- agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때
- view/component/frame 문서가 서로 어긋났는지 확인할 때
- view/component의 Source Evidence와 Status가 근거와 맞는지 확인할 때
- Excalidraw visual source와 frame index 연결을 검사할 때
- agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때
- 수동 호출에서 정합성 통과 후 code sync가 필요한지 판단할 때
- 사용자가 "화면정의서와 코드가 안 맞아"처럼 UI 정의와 코드 결과물의 불일치를 보고할 때
## 입력
- `scope`: `all`, `internal`, `implementation`, `view:<view-id>`, `component:<component-id>`, `frame:<view-id>` 중 하나. 기본값은 `all` (선택)
- `repair`: `true` 또는 `false`. 기본값은 `true` (선택)
- `sync-intent`: `auto`, `required`, `skip`, `inherited` 중 하나. 기본값은 수동 호출에서 `auto`, `update-agent-ui` 후속 호출에서 `inherited` (선택)
- `sync-mode`: `incremental` 또는 `full`. 기본값은 `incremental` (선택)
## 먼저 확인할 것
- [ ] `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` 또는 sync intent가 있으면 Source Evidence의 code path와 UI 구현 후보 파일을 확인한다.
- [ ] `agent-ui/.sync-state.json`이 있으면 읽고, 없으면 sync 기준 없음으로 보고한다.
- [ ] 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`는 `구현됨`, `계획`, `가정`, `불명확` 중 하나여야 한다.
- `구현됨` 항목은 코드 반영 완료 상태여야 한다. 코드 근거가 있으면 실제 존재하는 code evidence path를 가져야 한다.
- `구현됨`의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 `repair=true`일 때 `계획`으로 낮추고 USER_REVIEW를 남길 수 있다.
- `가정`, `불명확` 항목이 코드 동기화 가능한 정의처럼 설명되면 자동 의미 변경하지 않고 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 이름 중심으로 후보를 좁힌다.
- 운영 단계에서는 코드 후보만 보고 agent-ui view/component를 새로 만들지 않는다.
- 코드 후보가 명확한 route/page/view/shell인데 agent-ui에 대응 view가 없으면 USER_REVIEW로 남기거나, 사용자가 코드 기준 반영을 명시한 경우 `update-agent-ui`로 돌린다.
- 코드 후보가 명확한 반복 widget/component/table/filter/log/status/action인데 agent-ui에 대응 component가 없으면 USER_REVIEW로 남기거나, 사용자가 코드 기준 반영을 명시한 경우 `update-agent-ui`로 돌린다.
- 코드 결과물이 `구현됨` 상태의 agent-ui 정의와 어긋난다는 사용자 보고가 있으면 해당 항목을 `계획`으로 낮추고 sync intent를 만든다.
- 후보가 임시/dev/debug 용도인지, view인지 component인지, region인지 판단이 필요하면 USER_REVIEW로 남긴다.
- 코드에서 사라진 evidence는 자동 삭제하지 않고, 명시된 code evidence 경로가 깨진 경우에만 `구현됨`을 `계획`으로 낮출 수 있다.
6. **USER_REVIEW 생성 또는 갱신**
- active review 파일은 `agent-ui/USER_REVIEW.md`를 사용한다.
- 새 항목 id는 기존 최대 `UIR-NNN` 다음 번호를 사용한다.
- 같은 경로와 같은 질문의 중복 항목은 만들지 않는다.
- 항목에는 `Source Skill: validate-agent-ui`, `Stage: document-consistency`, `Blocking Step`, Context, Options, Needed For를 포함한다.
7. **code sync intent 판정**
- `sync-intent=inherited`이면 `update-agent-ui`가 전달한 판단을 그대로 사용하고 재판단하지 않는다.
- 수동 호출이거나 `sync-intent=auto`이면 agent-ui 변경분과 `계획` 상태 항목을 보고 `sync-agent-ui` 필요 여부를 판단한다.
- `sync-intent=required`이면 validate 결과가 PASS 또는 자동 보정 완료 WARN이고 현재 범위에 미해결 USER_REVIEW가 없을 때 `sync-agent-ui`를 실행한다.
- `sync-intent=skip`이면 code sync 필요 여부를 보고만 하고 실행하지 않는다.
- 현재 범위에 `가정` 또는 `불명확` 항목이 있거나 미해결 USER_REVIEW가 있으면 `sync-agent-ui`를 실행하지 않는다.
- `sync-agent-ui`를 실행할 때는 이 스킬의 보정 결과를 입력으로 넘기고, 순서를 바꾸지 않는다.
8. **결과 판정**
- `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` 누락 포함
- 명시된 code evidence 경로가 실제 존재하지 않는 `구현됨`을 `계획`으로 낮추고 USER_REVIEW를 남기는 보정
## USER_REVIEW 대상
- 정의에는 없는 region이 기존 frame-view에 있고 추가/삭제 의도 판단이 필요한 경우
- frame-view가 있는데 frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우
- component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우
- 운영 단계에서 코드 후보가 view, component, region, 임시/dev/debug UI 중 무엇인지 판단이 필요한 경우
- 운영 단계에서 코드에만 있는 view/component를 agent-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 경로가 깨진 `구현됨`이 남아 있지 않은가
- [ ] `scope=implementation` 또는 `all`이면 명확한 UI 코드 후보와 agent-ui 불일치가 sync intent 또는 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: <활성 파일 목록>
- Sync Intent: <inherited|required|skip|auto 판단 결과>
- sync-agent-ui: <실행/보류/생략 사유>
```
## 금지 사항
- UI 의도 판단이 필요한 문제를 자동 수정하지 않는다.
- archive 본문을 일반 검증 컨텍스트로 읽지 않는다.
- `.excalidraw` 내용을 현재 UI 기준으로 단독 확정하지 않는다.
- 사용자 확인 없이 의미 있는 문서를 병합하거나 삭제하지 않는다.
- agent-ui 검증과 무관한 앱 구현 파일을 수정하지 않는다.
- 전달받은 sync intent가 있으면 같은 내용을 재판단하지 않는다.
- `sync-agent-ui`보다 뒤에 실행되어서는 안 된다.
- 운영 단계에서 코드 후보만 근거로 agent-ui view/component skeleton을 자동 생성하지 않는다.

6
agent-roadmap/ROADMAP.md
View file

@ -19,10 +19,10 @@ nexo-owned 제품 표면은 Flutter SDK, compose, 운영 계약, 앱별 integrat
- [검토중] 제품 기반 정리
- 경로: `agent-roadmap/phase/product-foundation/PHASE.md`
- 요약: nexo의 제품 경계, 모노레포 구조, upstream-followable 런타임 기준선을 고정했고 Phase 완료 확인을 기다린다.
- [검토중] 업스트림 런타임 운영화
- [진행중] 업스트림 런타임 운영화
- 경로: `agent-roadmap/phase/upstream-runtime/PHASE.md`
- 요약: Mattermost server/webapp/push-proxy 업데이트를 계속 따라가기 위한 기준, CI/CD, 장애 대응 루프를 정리했고 Phase 완료 확인을 기다린다.
- [진행중] 메시징 런타임 표준화
- 요약: Mattermost server/webapp/push-proxy 업데이트를 계속 따라가기 위한 기준, CI/CD, 장애 대응 루프를 만든다.
- [계획] 메시징 런타임 표준화
- 경로: `agent-roadmap/phase/messaging-runtime/PHASE.md`
- 요약: nexo-owned Flutter SDK와 upstream runtime이 공유할 메시징/알림 계약, 테스트, 앱별 사용 채널 모델을 정리한다.

83
agent-roadmap/archive/phase/messaging-runtime/milestones/flutter-web-notification-smoke.md
View file

@ -1,83 +0,0 @@
# Milestone: Flutter Web 알림 Smoke 보완
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Flutter Web foreground browser notification이 실제 브라우저 환경에서 반복 검증될 수 있게 한다.
기존 API와 fake interop 단위 테스트 근거만으로 완료 처리된 gap을 보완하고, 원격 runner에서 열린 Flutter Web server를 사용자가 forwarded localhost URL로 접근해 permission, display, click/open routing을 확인할 수 있는 smoke 기준을 만든다.
## 상태
[완료]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요: 없음
## 범위
- `apps/flutter-test`를 Flutter Web build/run 대상 host scaffold로 구성한다.
- `packages/messaging_flutter`의 VM 단위 테스트와 Chrome/web 테스트를 분리해 각 platform expectation이 충돌하지 않게 정리한다.
- 원격 runner의 Flutter Web server와 사용자가 여는 forwarded localhost URL을 전제로 browser notification permission, display, click/open routing smoke 절차를 만든다.
- `bin/test`, `bin/lint`, `bin/build` 또는 별도 opt-in 명령에서 web smoke/build 검증이 누락되지 않도록 workspace helper와 테스트 기준을 보강한다.
## 기능
### Epic: [web-host] Web 테스트 Host
Flutter Web 알림 smoke가 실제 브라우저에서 열릴 수 있도록 test host와 실행 경계를 만든다.
- [x] [web-scaffold] `apps/flutter-test`에 Flutter Web scaffold를 추가하고 web build가 통과하도록 구성한다. 검증: 원격 runner에서 `apps/flutter-test` web build가 성공해야 한다.
- [x] [web-runtime] 원격 Flutter Web server와 forwarded localhost URL 기반 수동 smoke 절차를 정리한다. 검증: 사용자가 forwarded URL에서 permission 요청, notification display, click/open routing 상태를 확인할 수 있어야 한다.
### Epic: [web-tests] Web 검증 분리
VM 단위 테스트와 Chrome/web 테스트가 서로 다른 platform expectation을 올바르게 검증하도록 나눈다.
- [x] [chrome-tests] `packages/messaging_flutter`의 Chrome/web 테스트가 web runtime에서는 browser notification support를 기대하고, VM 테스트는 non-web unsupported를 기대하도록 분리한다. 검증: 원격 runner에서 package Chrome 테스트가 통과해야 한다.
- [x] [helper-route] workspace helper 또는 테스트 규칙에 web build/smoke opt-in 경로를 추가해 `bin/test`만으로 web smoke가 완료된 것처럼 보이지 않게 한다. 검증: web 검증을 생략한 경우 skip 또는 미실행 사유가 명확히 보고되어야 한다.
### Epic: [evidence] 완료 Evidence
완료 판정이 fake interop 단위 테스트에만 기대지 않도록 browser evidence 기준을 남긴다.
- [x] [manual-evidence] browser notification permission/display/click 수동 smoke evidence 기준을 민감값 없이 정리한다. 검증: 완료 리뷰에 원격 실행 명령, 사용자 확인 결과, 생략된 Full Web Push 범위가 함께 남아야 한다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-06-08
- 승인일: 2026-06-09
- 완료 근거:
- `agent-task/archive/2026/06/m-flutter-web-notification-smoke/01_web_scaffold/complete.log`
- `agent-task/archive/2026/06/m-flutter-web-notification-smoke/02+01_web_runtime/complete.log`
- `agent-task/archive/2026/06/m-flutter-web-notification-smoke/03_chrome_tests/complete.log`
- `agent-task/archive/2026/06/m-flutter-web-notification-smoke/04+03_manual_evidence_closeout/complete.log`
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-09 코드 관점 재검토에서 foreground web notification permission result와 notification별 click routing data 보강 후 `flutter analyze --no-fatal-infos`, `flutter test`, Chrome web test, 기본/opt-in `bin/test`가 통과했다.
## 범위 제외
- 브라우저가 닫힌 상태에서도 수신되는 Full Web Push 구현
- service worker, VAPID, `web_rn-v2` server device-token 등록, core/push-proxy web target 구현
- Mattermost webapp UI/Redux 알림 구현 복제
- 제품 앱 UI 또는 앱별 메시징 화면 구현
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/`, `apps/flutter-test/`, `bin/`, `agent-test/local/`
- 표준선(선택): 실제 host, port, credential, 포워딩 명령 원문은 tracked roadmap/docs에 쓰지 않고 ignored local test environment 문서 또는 사용자 제공 환경 기준에서 확인한다.
- 선행 작업: Flutter Web 알림
- 후속 작업: Full Web Push platform 계약
- 확인 필요: `web-scaffold`, `web-runtime`, `helper-route` evidence는 완료됐다. 남은 확인은 Chrome/web test 분리와 수동 evidence 기준 closeout이다.

85
agent-roadmap/archive/phase/messaging-runtime/milestones/flutter-web-notification.md
View file

@ -1,85 +0,0 @@
# Milestone: Flutter Web 알림
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
`packages/messaging_flutter`를 Flutter Web/Chrome 알림의 source of truth로 확장한다.
먼저 웹앱이 열려 있는 상태의 browser notification permission, 표시, click/open routing을 패키지 API로 제공하고, 브라우저가 닫힌 상태의 Full Web Push는 별도 후속 범위로 분리한다.
## 상태
[완료]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요: 없음
## 범위
- `packages/messaging_flutter`의 web platform 등록과 browser notification public API 추가
- Chrome/Flutter Web foreground 알림 permission, 표시, click/open event를 기존 `onNotification`, `onNotificationOpened`, channel/thread callback 계약에 연결
- `apps/flutter-test`에 Flutter Web 검증 host scaffold와 민감값 없는 smoke 기준 추가
- Full Web Push에 필요한 `web_rn-v2` token, service worker, VAPID, core/push-proxy platform 확장은 후속 작업으로 경계화
## 기능
### Epic: [web-baseline] Web 플랫폼 기준선
Flutter Web을 패키지 지원 플랫폼으로 올릴 때 기존 Android-first 계약을 깨지 않도록 기준선을 만든다.
- [x] [plugin-web] `nexo_messaging`에 Flutter Web plugin 등록과 web 전용 구현 파일을 추가한다.
- [x] [api-options] 기존 `initialize()` 호출을 깨지 않는 옵션 모델을 추가하고, web notification permission/display 정책과 token prefix 경계를 문서화한다.
- [x] [interop] browser `Notification` API 연동은 `package:web` 기반으로 작성하고, Android/iOS/macOS import와 분리한다.
### Epic: [foreground] Chrome foreground 알림
웹앱이 열려 있는 상태에서 Chrome browser notification을 패키지 책임으로 표시하고 routing event를 재사용한다.
- [x] [permission] Web notification 지원 여부와 permission 상태를 조회/요청하는 API를 제공한다.
- [x] [display] foreground payload를 browser notification으로 표시하고 click 이벤트를 `NotificationOpenedEvent`와 host navigation callback으로 변환한다.
- [x] [event-map] Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다.
### Epic: [smoke] Web Smoke
민감값 없이 반복 가능한 검증 기준을 만들고, Full Web Push는 별도 설계 항목으로 남긴다.
- [x] [test-host] `apps/flutter-test`에서 Flutter Web smoke scaffold와 permission/display/click 상태 표시를 제공한다.
- [x] [auto-test] web interop을 직접 띄우지 않는 Dart API/mapper 단위 테스트를 추가한다. 검증: `bin/test`
- [x] [push-follow-up] service worker, VAPID, `web_rn-v2` device token, core/push-proxy platform 분기 설계를 후속 Milestone 후보로 정리한다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-06-07
- 완료 근거:
- `test-host`가 `agent-task/archive/2026/06/m-flutter-web-notification_1/complete.log`의 Roadmap Completion 근거로 PASS 처리되었다.
- Flutter Web foreground notification permission/display/click routing 범위의 모든 기능 Task가 `[x]` 상태다.
- 검증: `cd apps/flutter-test && flutter test`, `bin/test`, `bin/lint` PASS. Go test/vet은 opt-in 환경 변수 미설정으로 skip되었다.
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자 요청으로 현재 Milestone을 종료하고 archive로 이동한다. Full Web Push 구현은 범위 제외 및 후속 Milestone 후보로 남긴다.
## 범위 제외
- 브라우저가 닫힌 상태에서도 수신되는 Full Web Push 구현
- `services/core`의 push platform 상수 추가, session device id 마이그레이션, push-proxy web target 구현
- Mattermost webapp UI/Redux 알림 구현 복제
- 제품 앱 UI 또는 앱별 메시징 화면 구현
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/`, `apps/flutter-test/`, `services/core/server/public/model/push_notification.go`, `services/push-proxy/server/`
- 표준선(선택): 1차는 Flutter Web foreground browser notification으로 제한하고, Full Web Push는 `web_rn-v2` token 및 service worker 기반 후속 Milestone으로 분리한다.
- 선행 작업: 알림 파이프라인 고도화
- 후속 작업: Full Web Push platform 계약
- 확인 필요: 실제 Chrome smoke에 사용할 Firebase web config, VAPID key, private host 값은 tracked 문서에 기록하지 않고 host 환경 책임으로 둔다.

80
agent-roadmap/archive/phase/messaging-runtime/milestones/ios-notification-preflight.md
View file

@ -1,80 +0,0 @@
# Milestone: iOS 알림 선행 정리
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Apple Developer 계정, APNs 인증 자산, Firebase iOS app, 실제 기기가 준비되기 전에도 iOS 알림 구현과 테스트를 막는 선행 계약을 정리한다.
iOS token 계약, native bridge 최소 범위, placeholder, fixture, evidence 템플릿을 먼저 고정해 후속 `iOS 알림 테스트`가 외부 자산 검증에만 집중하게 만든다.
## 상태
[완료]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요:
- 없음
## 범위
- iOS device token prefix와 APNs/FCM token 구분 기준
- Dart가 기대하는 iOS EventChannel/MethodChannel 최소 bridge 계약
- `apps/flutter-test/ios` host placeholder와 ignored credential 위치
- APNs/FCM payload fixture와 local/simulator opened-routing injection 기준
- 실제 APNs delivery 전후로 재사용할 smoke evidence 템플릿
## 기능
### Epic: [preflight] iOS 선행 정리
Apple/Firebase/APNs 실자산이 없어도 먼저 확정할 수 있는 계약과 검증 표면을 분리한다.
- [x] [token-contract] iOS device token prefix, FCM/APNs token 구분, nexo server 등록 호환 기준을 정리한다.
- [x] [bridge-scope] Dart가 기대하는 EventChannel/MethodChannel 이름, iOS 최소 구현 method, no-op/fallback 경계를 정리한다.
- [x] [host-placeholder] entitlements, `GoogleService-Info.example.plist`, ignored credential 위치, Xcode target resource 기준을 정리한다.
- [x] [fixtures] APNs/FCM payload fixture와 simulator/local injection으로 검증할 opened-routing 시나리오를 작성한다.
- [x] [evidence-template] permission, APNs/FCM token, foreground/background/open routing, ACK/dismiss gap evidence 템플릿을 작성한다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-06-01
- 완료 근거:
- 기존 선행 정리 작업으로 `token-contract`, `host-placeholder`, `fixtures`, `evidence-template` 산출물이 반영되어 `[x]` 상태다.
- `agent-task/archive/2026/06/m-ios-notification-preflight/complete.log`의 Roadmap Completion에서 남은 `bridge-scope` 작업 PASS와 미완료 task 없음 확인.
- 최종 검증으로 `packages/messaging_flutter` Flutter test/analyze, `apps/flutter-test` Flutter test, remote iOS `xcodebuild test` PASS 기록 확인.
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 기능 작업 완료와 archive 이동 승인을 확인해 `[완료]`로 전환하고 archive로 이동했다.
## 범위 제외
- 실제 Apple Developer Team, APNs key/certificate, provisioning profile, Firebase project/app 생성은 이 Milestone에서 결정하지 않는다.
- 실제 iOS 기기 APNs/FCM delivery smoke는 `iOS 알림 테스트`에서 다룬다.
- iOS native bridge 전체 구현은 선행 계약 정리 이후 별도 구현 계획으로 분리할 수 있다.
- Android FCM 구현 변경은 이 Milestone에서 다루지 않는다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/ios/`, `packages/messaging_flutter/lib/`, `apps/flutter-test/ios/`, `docs/ios-notification-test-guide.md`
- 표준선(선택): 민감값 없이 placeholder, fixture, event 계약, evidence 양식을 먼저 고정한다
- 민감값 기준: Apple/Firebase/APNs credential, Team ID, profile, token, private host 값은 tracked 문서에 쓰지 않는다
- 진행 근거:
- `packages/messaging_flutter/README.md`와 `docs/ios-notification-test-guide.md`에 iOS `apple_rn-v2:<raw-apns-token>` server-registration 후보와 FCM/APNs token 구분을 기록했다.
- `apps/flutter-test/ios/Runner/GoogleService-Info.example.plist`와 `apps/flutter-test/ios/Runner/Runner.example.entitlements`를 tracked placeholder로 추가했다.
- `apps/flutter-test/ios/Fixtures/open_channel.apns`와 `apps/flutter-test/ios/Fixtures/open_thread.apns`에 local/simulator opened-routing fixture를 추가했다.
- `docs/ios-notification-smoke-evidence-template.md`에 permission, APNs/FCM token, open routing, ACK/dismiss/inline reply gap evidence 양식을 추가했다.
- `agent-task/archive/2026/06/m-ios-notification-preflight/complete.log` 기준 `[bridge-scope]` PASS, iOS notification EventChannel/action MethodChannel 등록, legacy channel 유지, validation-only no-op 경계, RunnerTests 보강, 문서 갱신, Flutter/analyze/iOS xcodebuild 검증 통과를 확인했다.
- 선행 작업: 알림 파이프라인 고도화
- 후속 작업: iOS 알림 테스트
- 확인 필요: 없음

73
agent-roadmap/archive/phase/messaging-runtime/milestones/linux-notification-preflight.md
View file

@ -1,73 +0,0 @@
# Milestone: Linux 알림 선행 정리
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Linux 배포판, desktop environment, notification daemon, 테스트 장비 결정을 기다리지 않고 Linux 알림 지원에 필요한 선행 계약을 정리한다.
Linux plugin 등록, notification daemon 연동 후보, bridge 계약, fixture, evidence 템플릿을 먼저 고정해 후속 `Linux 알림 테스트`가 실제 환경 smoke에 집중하게 만든다.
## 상태
[완료]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요:
- 없음
## 범위
- Linux Flutter plugin 등록 방식과 host scaffold 필요 범위
- Dart가 기대하는 Linux EventChannel/MethodChannel 최소 bridge 계약
- D-Bus notification daemon, desktop portal, package/runtime dependency 후보 비교
- local/debug notification payload fixture와 opened-routing injection 기준
- 실제 Linux OS UI smoke 전후로 재사용할 evidence 템플릿
## 기능
### Epic: [preflight] Linux 선행 정리
Linux 장비, 배포판, desktop environment 결정을 기다리지 않고 먼저 확정할 수 있는 계약과 검증 표면을 분리한다.
- [x] [platform-contract] Linux plugin 등록 방식, Dart channel 이름, host scaffold 필요 범위를 정리한다.
- [x] [bridge-scope] Linux notification daemon click/open event를 `NotificationOpenedEvent`와 channel/thread callback에 연결하는 최소 bridge 계약을 정리한다.
- [x] [api-matrix] D-Bus notification daemon, desktop portal, package/runtime dependency 후보와 제약을 비교한다.
- [x] [fixtures] local/debug notification payload fixture와 opened-routing injection 시나리오를 작성한다.
- [x] [evidence-template] display, click/open routing, lifecycle, ACK/dismiss gap evidence 템플릿을 작성한다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-06-02
- 완료 근거:
- `docs/linux-notification-test-guide.md`에 Linux platform registration, bridge scope, API matrix, runtime dependency boundary, payload mapping, fixture 사용 기준을 정리했다.
- `apps/flutter-test/linux/Fixtures/*.json`에 channel/thread open routing fixture를 추가했다.
- `docs/linux-notification-smoke-evidence-template.md`에 display, click/open routing, lifecycle, ACK/dismiss/inline reply gap evidence 양식을 추가했다.
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 모든 기능 Task가 문서/fixture/evidence 기준으로 충족되어 완료 승인 및 archive 대상으로 전환한다. 실제 Linux plugin scaffold, platform registration, native bridge 구현과 OS notification UI smoke는 후속 Milestone 또는 별도 plan 대상이다.
## 범위 제외
- Linux 배포판, desktop environment, notification daemon, 테스트 장비 책임 결정은 이 Milestone에서 하지 않는다.
- 실제 Linux notification UI smoke와 package/runtime 검증은 `Linux 알림 테스트`에서 다룬다.
- Linux native implementation 전체 완성은 선행 계약 정리 이후 별도 구현 계획으로 분리할 수 있다.
- macOS/Windows 검증은 각 OS별 Milestone에서 다룬다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/pubspec.yaml`, `packages/messaging_flutter/lib/`, `packages/messaging_flutter/README.md`, `apps/flutter-test/README.md`
- 표준선(선택): 실제 Linux 장비 없이 platform 등록 후보, notification daemon 후보, event 계약, fixture, evidence 양식을 먼저 고정한다
- 선행 작업: 알림 파이프라인 고도화
- 후속 작업: Linux 알림 테스트
- 확인 필요: 없음

74
agent-roadmap/archive/phase/messaging-runtime/milestones/macos-notification-preflight.md
View file

@ -1,74 +0,0 @@
# Milestone: macOS 알림 선행 정리
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Apple signing, macOS 테스트 장비, 실제 OS notification UI 검증 전에 macOS 알림 구현과 테스트를 막는 선행 계약을 정리한다.
macOS native bridge 최소 범위, host placeholder, payload fixture, evidence 템플릿을 먼저 고정해 후속 `macOS 알림 테스트`가 장비와 OS UI smoke에 집중하게 만든다.
## 상태
[완료]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요:
- 없음
## 범위
- Dart가 기대하는 macOS EventChannel/MethodChannel 최소 bridge 계약
- `apps/flutter-test/macos` host placeholder와 entitlement/signing 기준
- macOS notification userInfo와 `NotificationOpenedEvent` 매핑 기준
- local notification payload fixture와 click/open routing injection 기준
- 실제 macOS OS UI smoke 전후로 재사용할 evidence 템플릿
## 기능
### Epic: [preflight] macOS 선행 정리
Apple signing, 장비, OS UI 수동 검증 전에 먼저 확정할 수 있는 계약과 검증 표면을 분리한다.
- [x] [bridge-scope] Dart가 기대하는 EventChannel/MethodChannel 이름, macOS 최소 구현 method, no-op/fallback 경계를 정리한다.
- [x] [host-placeholder] entitlement, signing/notarization placeholder, ignored credential 위치, macOS target resource 기준을 정리한다.
- [x] [payload-map] macOS notification userInfo를 `NotificationOpenedEvent`와 channel/thread callback에 매핑하는 기준을 정리한다.
- [x] [fixtures] local notification payload fixture와 click/open routing injection 시나리오를 작성한다.
- [x] [evidence-template] permission, display, click/open routing, lifecycle, ACK/dismiss gap evidence 템플릿을 작성한다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-06-02
- 완료 근거:
- `docs/macos-notification-test-guide.md`에 macOS bridge scope, host placeholder, userInfo mapping, fixture 사용 기준을 정리했다.
- `apps/flutter-test/macos/Fixtures/*.json`에 channel/thread open routing fixture를 추가했다.
- `docs/macos-notification-smoke-evidence-template.md`에 permission, display, click/open routing, lifecycle, ACK/dismiss/inline reply gap evidence 양식을 추가했다.
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자가 완료와 다음 마일스톤 지점 업데이트를 요청했다. 실제 macOS native bridge 구현과 OS notification UI smoke는 후속 Milestone 또는 별도 plan 대상이다.
## 범위 제외
- 실제 Apple Team, signing certificate, provisioning, notarization 책임 결정은 이 Milestone에서 하지 않는다.
- 실제 macOS OS notification UI smoke는 `macOS 알림 테스트`에서 다룬다.
- macOS native bridge 전체 구현은 선행 계약 정리 이후 별도 구현 계획으로 분리할 수 있다.
- iOS/APNs, Windows, Linux 검증은 각 OS별 Milestone에서 다룬다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/macos/`, `packages/messaging_flutter/lib/`, `apps/flutter-test/macos/`, `packages/messaging_flutter/README.md`
- 표준선(선택): 민감값과 실제 장비 없이 placeholder, fixture, event 계약, evidence 양식을 먼저 고정한다
- 민감값 기준: Apple credential, Team ID, profile, private host 값은 tracked 문서에 쓰지 않는다
- 선행 작업: 알림 파이프라인 고도화
- 후속 작업: macOS 알림 테스트
- 확인 필요: 없음

73
agent-roadmap/archive/phase/messaging-runtime/milestones/windows-notification-preflight.md
View file

@ -1,73 +0,0 @@
# Milestone: Windows 알림 선행 정리
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Windows 테스트 장비, 계정/권한, packaging 결정을 기다리지 않고 Windows 알림 지원에 필요한 선행 계약을 정리한다.
Windows plugin 등록, native notification API 후보, bridge 계약, fixture, evidence 템플릿을 먼저 고정해 후속 `Windows 알림 테스트`가 OS smoke와 packaging 검증에 집중하게 만든다.
## 상태
[완료]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요:
- 없음
## 범위
- Windows Flutter plugin 등록 방식과 host scaffold 필요 범위
- Dart가 기대하는 Windows EventChannel/MethodChannel 최소 bridge 계약
- Windows notification API 후보와 MSIX/package 제약 비교
- local/debug notification payload fixture와 opened-routing injection 기준
- 실제 Windows OS UI smoke 전후로 재사용할 evidence 템플릿
## 기능
### Epic: [preflight] Windows 선행 정리
Windows 장비, 계정, packaging 결정을 기다리지 않고 먼저 확정할 수 있는 계약과 검증 표면을 분리한다.
- [x] [platform-contract] Windows plugin 등록 방식, Dart channel 이름, host scaffold 필요 범위를 정리한다.
- [x] [bridge-scope] Windows native notification open event를 `NotificationOpenedEvent`와 channel/thread callback에 연결하는 최소 bridge 계약을 정리한다.
- [x] [api-matrix] Windows notification API 후보와 app packaging/MSIX 여부에 따른 제약을 비교한다.
- [x] [fixtures] local/debug notification payload fixture와 opened-routing injection 시나리오를 작성한다.
- [x] [evidence-template] display, click/open routing, lifecycle, ACK/dismiss gap evidence 템플릿을 작성한다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-06-02
- 완료 근거:
- `docs/windows-notification-test-guide.md`에 Windows platform registration, bridge scope, API matrix, payload mapping, fixture 사용 기준을 정리했다.
- `apps/flutter-test/windows/Fixtures/*.json`에 channel/thread open routing fixture를 추가했다.
- `docs/windows-notification-smoke-evidence-template.md`에 display, click/open routing, lifecycle, ACK/dismiss/inline reply gap evidence 양식을 추가했다.
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 모든 기능 Task가 문서/fixture/evidence 기준으로 충족되어 완료 승인 및 archive 대상으로 전환한다. 실제 Windows plugin scaffold, platform registration, native bridge 구현과 OS notification UI smoke는 후속 Milestone 또는 별도 plan 대상이다.
## 범위 제외
- Windows OS 버전, 테스트 장비, 계정/권한 책임 결정은 이 Milestone에서 하지 않는다.
- 실제 Windows notification UI smoke와 packaging 검증은 `Windows 알림 테스트`에서 다룬다.
- Windows native implementation 전체 완성은 선행 계약 정리 이후 별도 구현 계획으로 분리할 수 있다.
- macOS/Linux 검증은 각 OS별 Milestone에서 다룬다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/pubspec.yaml`, `packages/messaging_flutter/lib/`, `packages/messaging_flutter/README.md`, `apps/flutter-test/README.md`
- 표준선(선택): 실제 Windows 장비 없이 platform 등록 후보, native API 후보, event 계약, fixture, evidence 양식을 먼저 고정한다
- 선행 작업: 알림 파이프라인 고도화
- 후속 작업: Windows 알림 테스트
- 확인 필요: 없음

69
agent-roadmap/archive/phase/messaging-runtime/milestones/workspace-port-env-standardization.md
View file

@ -1,69 +0,0 @@
# Milestone: 워크스페이스 포트/환경 표준화
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Nexo의 upstream-followable Mattermost runtime, push-proxy, Flutter test host, web preview, remote runner 문서가 workspace 공통 포트 대역을 일관되게 말하도록 정리한다. 기존 core `18065`와 push-proxy `18066`은 외부 소비자가 있을 수 있으므로 즉시 변경하지 않고, 표준 대역과 호환성 메모를 먼저 남긴다.
## 상태
[완료]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요: 없음
## 범위
- Mattermost core HTTP, push-proxy HTTP, Flutter test/web host, upstream dev service 포트 inventory
- 기존 외부 endpoint `18065/18066` 유지 여부와 workspace backend 대역 후보의 migration note
- upstream dev compose의 PostgreSQL, Redis, MinIO, mail, search, metrics, dashboard 포트를 nexo-owned runtime 포트와 분리해 문서화
- Android/iOS/Web notification smoke에서 사용하는 host/base URL과 private Firebase/APNs 값의 기록 경계 정리
## 기능
### Epic: [inventory] Nexo runtime inventory
Nexo가 소유한 runtime 포트와 upstream 개발 보조 포트를 분리해 정리한다.
- [x] [runtime-map] core HTTP, push-proxy, Flutter test host, web preview 포트를 host publish와 container/internal 기준으로 나눠 정리한다.
- [x] [upstream-map] upstream Mattermost dev compose의 DB/cache/object/search/mail/metrics/dashboard 포트를 nexo-owned runtime과 구분해 충돌 후보를 표시한다.
- [x] [slot-plan] Nexo 기본 후보를 frontend `13040`, backend `18065/18066` 유지, compose-internal DB/cache 우선으로 문서화하고 변경 필요 시 `18040` 계열 후보를 남긴다.
- [x] [secret-boundary] Firebase, APNs, Mattermost token, private host 값은 tracked 문서에 쓰지 않고 evidence 위치와 책임 경계만 남긴다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-06-07
- 완료 근거:
- `services/core/compose/README.md`에 nexo runtime, upstream dev auxiliary, slot plan, tracked value boundary inventory를 추가했다.
- `README.md`, `apps/flutter-test/README.md`, `docs/runtime-image-validation.md`가 같은 포트/환경 기준을 가리키도록 정리했다.
- 검증: `git diff --check`, `rg --sort path -n '(^## Port And Environment Inventory|^### Nexo Runtime|^### Upstream Dev Services|^### Slot Plan|^### Tracked Value Boundary|워크스페이스 포트 기준|frontend slot `13040`|source of truth|현재 포트)' README.md services/core/compose/README.md apps/flutter-test/README.md docs/runtime-image-validation.md`
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자 요청으로 마일스톤을 종료하고 다음 마일스톤으로 이동한다.
## 범위 제외
- 원격 runtime core/push-proxy 포트 즉시 변경
- Mattermost upstream service 구조 변경
- iOS/APNs, Firebase, Mattermost credential 기록
- Flutter Web 알림 또는 iOS 알림 구현
## 작업 컨텍스트
- 관련 경로: `services/core/`, `services/push-proxy/`, `apps/flutter-test/`, `packages/messaging_flutter/`, `agent-test/local/`
- 표준선(선택): 외부 소비자가 있는 `18065/18066`은 compatibility baseline으로 유지하고, 신규 preview/test host publish만 workspace 대역으로 먼저 정렬한다.
- 선행 작업: workspace 공통 포트 inventory 정리
- 후속 작업: compose/env/test smoke 갱신과 drift 방지
- 확인 필요: 없음

84
agent-roadmap/archive/phase/upstream-runtime/milestones/cicd-operations.md
View file

@ -1,84 +0,0 @@
# Milestone: CI/CD와 운영 업데이트 루프
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/upstream-runtime/PHASE.md`
## 목표
Mattermost server/webapp/push-proxy update와 nexo Flutter SDK 검증을 반복 가능한 CI/CD와 운영 runbook으로 연결한다.
upstream 업데이트에 따른 이슈를 빠르게 분류하고, 수정/보류/rollback 결정을 남길 수 있는 흐름을 만든다.
## 상태
[완료]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요:
- 없음
- 결정 완료:
- [x] 2026-05-27: upstream update를 쉽게 따라가기 위한 CI/CD와 이슈 대응 루프를 프로젝트 방향성에 포함한다.
- [x] 2026-05-30: CI 검증 기준은 workspace helper, optional gate, compose smoke, SDK optional check로 정리했고, 남은 결정은 마일스톤 전체 잠금이 아니라 `deploy-pipeline` 구현 컨텍스트로 좁힌다.
- [x] 2026-05-30: `deploy-pipeline` 표준선은 private/internal compose lane, ignored secret profile, release note/follow-up issue의 sanitized rollback evidence로 정한다.
## 범위
- workspace `bin/test`, `bin/lint`, `bin/build` 기반 기본 검증
- optional Go test/vet/build와 webapp/npm 검증
- compose smoke, server ping, webapp 접근, push-proxy smoke
- Flutter SDK Dart/integration/Android native test
- upstream update 실패 이슈화, rollback, release note 흐름
## 기능
### Epic: [ci] Continuous verification
upstream-followable runtime과 nexo SDK를 같은 변경 흐름에서 검증한다.
- [x] [workspace-checks] CI에서 `bin/test`, `bin/lint`, `bin/build`를 실행하고 skip된 도구를 보고하는 기준을 만든다. 검증: `agent-task/archive/2026/05/m-cicd-operations/01_core_webapp_checks/complete.log`에서 `bin/test`, `bin/lint`, `bin/build` 실행과 기본 skip 출력 계약 PASS를 확인했다.
- [x] [core-checks] optional Go test/vet/build와 webapp 검증을 upstream update 또는 core 변경 시 실행하는 기준을 만든다. 검증: `agent-task/archive/2026/05/m-cicd-operations/01_core_webapp_checks/complete.log`에서 core Go/webapp optional gate와 `NEXO_CORE_WEBAPP_*` 계약 PASS를 확인했다.
- [x] [compose-smoke] compose로 core, webapp, db, push-proxy를 올리고 최소 smoke를 확인하는 CI 또는 원격 검증 흐름을 만든다. 검증: `agent-task/archive/2026/05/m-cicd-operations/02_compose_smoke/complete.log`에서 `bin/smoke-compose` helper, 원격 runtime smoke, core/db/webapp/push-proxy 확인 PASS를 확인했다.
- [x] [sdk-checks] Flutter SDK Dart test, client integration test, Android native unit test를 환경별로 나누어 실행하는 기준을 만든다. 검증: `agent-task/archive/2026/05/m-cicd-operations/03_sdk_checks/complete.log`에서 Flutter integration/Android native optional gate와 evidence sanitation PASS를 확인했다.
### Epic: [cd] Deployment loop
업데이트와 배포 실패가 추적 가능한 이슈로 남도록 운영 루프를 만든다.
- [x] [update-branch] Mattermost server/webapp/push-proxy baseline update용 branch, diff, patch inventory 절차를 정리한다. 검증: `agent-task/archive/2026/05/m-cicd-operations/04_update_response_loop/complete.log`에서 README와 각 `UPSTREAM.md`의 branch, snapshot diff, patch inventory, smoke evidence 계약 및 최종 `rg`/`git diff --check` PASS를 확인했다.
- [x] [deploy-pipeline] dev/test/production-like compose 배포, secret 주입, rollback 절차를 정리한다. 검증: `agent-task/archive/2026/05/m-cicd-operations/05_deploy_pipeline/complete.log`에서 `README.md`, `docs/README.md`, `services/core/compose/README.md`의 deploy loop, secret injection, rollback contract 정리와 최종 `rg`/`git diff --check` PASS(code-review PASS)를 확인했다. 2026-05-30 사용자 완료/아카이빙 지시 뒤 누락된 code-review 종결을 보완해 task를 archive로 이동했다.
- [x] [issue-loop] upstream update 실패를 server, webapp, push-proxy, SDK contract, infra 중 하나로 분류하고 후속 이슈로 남기는 절차를 만든다. 검증: `agent-task/archive/2026/05/m-cicd-operations/04_update_response_loop/complete.log`에서 실패 분류와 follow-up/rollback/defer 기록 기준 및 최종 PASS 리뷰를 확인했다.
- [x] [release-note] server/front/push-proxy baseline과 Flutter SDK compatibility를 한 번에 볼 수 있는 release note 기준을 만든다. 검증: `agent-task/archive/2026/05/m-cicd-operations/04_update_response_loop/complete.log`에서 release note decision loop와 compatibility 요약 기준 및 최종 PASS 리뷰를 확인했다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-05-30
- 완료 근거: CI Epic 전체와 CD Epic의 update-branch, issue-loop, release-note는 archived complete.log로 확인했다. `deploy-pipeline`은 archived `complete.log`(code-review PASS)로 확인했다. 2026-05-30 사용자 완료/아카이빙 지시 당시 누락됐던 code-review 종결(로그 아카이브 + `complete.log` + task 디렉터리 이동)을 보완해 형제 task와 동일한 archive 상태로 맞췄다.
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-05-30 사용자가 "마일스톤 완료로 하고 아카이빙해"라고 지시했다.
## 범위 제외
- production hardening 전체 구현은 배포 대상과 secret 정책 결정 전까지 진행하지 않는다.
- 외부 공개용 landing page나 marketing site는 포함하지 않는다.
- billing, organization management, 별도 admin console은 포함하지 않는다.
## 작업 컨텍스트
- 관련 경로: `.github/`, `bin/`, `services/core/`, `services/core/compose/`, `packages/messaging_flutter/`, `apps/flutter-test/`, `docs/`
- 표준선(선택): 먼저 private/internal deployment loop를 만들고, runner와 secret 정책이 확정되면 production-like CD로 확장한다
- 선행 작업: 업스트림 팔로잉 기준선
- 후속 작업: 운영 runbook, release/versioning 고도화
- 확인 완료: `deploy-pipeline`은 private/internal compose lane을 production-like 기준으로 삼고, secret은 ignored profile과 runtime data에 주입하며, rollback evidence는 private run log 참조와 release note/follow-up issue의 sanitized 판정으로 남긴다.
- 2026-05-30 동기화: `m-cicd-operations/01_core_webapp_checks`, `02_compose_smoke`, `03_sdk_checks`, `04_update_response_loop` PASS 완료 이벤트를 반영했다. CI Epic의 workspace/core/compose/SDK 검증 기준과 CD Epic의 update branch 절차, issue loop 분류, release note 기준은 완료됐다.
- 2026-05-30 완료 동기화: `agent-task/m-cicd-operations/05_deploy_pipeline/CODE_REVIEW-cloud-G07.md`의 구현 완료 기록과 사용자 완료/아카이빙 지시를 근거로 `[deploy-pipeline]`을 완료 처리했다.
- 2026-05-30 종결 동기화: 누락됐던 code-review 종결을 보완했다. `CODE_REVIEW-cloud-G07.md`에 PASS 판정을 append하고 `plan_cloud_G07_0.log`/`code_review_cloud_G07_0.log`로 아카이브, `complete.log` 작성 후 task 디렉터리를 `agent-task/archive/2026/05/m-cicd-operations/05_deploy_pipeline/`로 이동했다. 근거 경로를 archive `complete.log`로 갱신해 형제 task와 싱크를 맞췄다.

12
agent-roadmap/archive/phase/upstream-runtime/milestones/upstream-following.md
View file

@ -61,15 +61,11 @@ nexo 변경이 upstream merge를 어렵게 만들지 않도록 허용 경계를
- 상태: 승인됨
- 요청일: 2026-05-30
- 완료 근거:
- `docs/README.md`에 baseline 기록, snapshot script 계약, push-proxy 추적 선택, release watch, patch policy를 정리했다.
- `services/core/UPSTREAM.md`, `services/push-proxy/UPSTREAM.md`, `apps/mattermost/UPSTREAM.md`에 모듈별 patch boundary와 update gate를 보강했다.
- `git diff --check`, task/status `rg`, 활성 경로 확인을 통과했고, workspace lock 관련 항목은 없었다.
- 현재 마일스톤 기능 Task 7개는 문서화 범위 안에서 충족되었고, 실제 snapshot 자동화 스크립트 구현은 이번 마일스톤의 계약 정리 범위를 넘는 별도 큰 작업으로 분리 가능하다.
- 완료 근거: `services/core/UPSTREAM.md`, `services/push-proxy/UPSTREAM.md`, `README.md`에 upstream baseline, snapshot script 계약, push-proxy 추적 방식, release watch, patch boundary 기준을 정리했다.
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-05-30 사용자 요청에 따라 `[완료]` 전환 후 archive 이동했다.
- 리뷰 코멘트: 2026-05-30 사용자 승인에 따라 완료 처리하고 archive로 이동한다.
## 범위 제외
@ -83,7 +79,5 @@ nexo 변경이 upstream merge를 어렵게 만들지 않도록 허용 경계를
- 표준선(선택): server/webapp/push-proxy는 upstream-followable runtime, Flutter SDK는 nexo-owned embedded SDK
- upstream 추적 방식: 프로젝트 규칙이 repository별 branch, staging 위치, snapshot 기록, merge 분리 원칙을 정의하고, workspace script는 외부 `mattermost/` staging clone update와 이 repo로의 snapshot copy만 자동화한다. 반영 여부는 diff/smoke 확인 후 repo별 merge 요청에서 결정한다.
- 선행 작업: 정체성 기준선
- 후속 작업: 메시징 계약 표준화
- 완료된 관련 작업: CI/CD와 운영 업데이트 루프는 2026-05-30 archive 완료
- 다음 작업 지점: `agent-roadmap/phase/messaging-runtime/milestones/messaging-contract.md`
- 후속 작업: CI/CD와 운영 업데이트 루프, 메시징 계약 표준화
- 확인 필요: 없음

28
agent-roadmap/current.md Normal file
View file

@ -0,0 +1,28 @@
# 현재 로드맵 컨텍스트
## 활성 Phase
- [진행중] 업스트림 런타임 운영화
- 경로: `agent-roadmap/phase/upstream-runtime/PHASE.md`
## 활성 Milestone
- [계획] 내부 검증 파이프라인과 업데이트 대응 루프
- Phase: `agent-roadmap/phase/upstream-runtime/PHASE.md`
- 경로: `agent-roadmap/phase/upstream-runtime/milestones/cicd-operations.md`
## 선택 규칙
- 이 문서는 활성 Phase와 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
- 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`를 가리킨다.
- 활성 Milestone은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`를 가리킨다.
- 활성 항목은 아카이브 경로를 포함하지 않는다.
- `[검토중]` 항목은 사용자 완료 확인 전까지 활성 항목으로 남길 수 있다.
- `[스케치]` 항목은 활성 후보로 남길 수 있지만 구현 계획 생성 대상은 아니며, `[계획]` 승격 조건을 정리하는 대상으로만 다룬다.
- `[완료]` 또는 `[폐기]` 항목은 archive 링크를 남긴 뒤 활성 항목에서 제거한다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Phase와 Milestone을 선택하고 같은 세션에서 1회 읽는다.
- 활성 Phase 또는 Milestone 둘 이상에 걸치면 필요한 문서를 모두 읽고 작업 범위를 좁힌다.
- 활성 범위 밖의 작업이면 `agent-roadmap/ROADMAP.md`의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- 완료된 과거 내용이 필요할 때만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 읽는다.
- 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금을 유지한 채 진행할 수 있으며, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다.
- 선택된 Milestone 상태가 `[스케치]`이면 `구현 잠금` 상태와 관계없이 구현이나 구현 계획을 시작하지 않고 `[계획]` 승격 필요를 보고한다.

48
agent-roadmap/phase/messaging-runtime/PHASE.md
View file

@ -2,7 +2,7 @@
## 상태
[진행중]
[계획]
## 목표
@ -16,48 +16,12 @@ Mattermost server/webapp/push-proxy는 upstream-followable runtime으로 두고,
완료, 검토중, 진행중, 계획, 스케치 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
스케치 Milestone은 아직 구현 가능한 계획이 아니므로 계획 Milestone보다 아래에 둔다.
- [완료] 메시징 계약 표준화
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/messaging-contract.md`
- 요약: 서버와 Flutter 플러그인이 공유할 메시징/알림 API, 이벤트, 저장 계약을 정리했다.
- [완료] 알림 파이프라인 고도화
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/notification-pipeline.md`
- [계획] 메시징 계약 표준화
- 경로: `agent-roadmap/phase/messaging-runtime/milestones/messaging-contract.md`
- 요약: 서버와 Flutter 플러그인이 공유할 메시징/알림 API, 이벤트, 저장 계약을 정리한다.
- [계획] 알림 파이프라인 고도화
- 경로: `agent-roadmap/phase/messaging-runtime/milestones/notification-pipeline.md`
- 요약: FCM, ACK, inline reply, dismiss, open routing을 안정된 플러그인 책임으로 만든다.
- [완료] iOS 알림 선행 정리
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/ios-notification-preflight.md`
- 요약: Apple/Firebase/APNs 실자산 없이 iOS token 계약, native bridge 최소 범위, fixture, evidence 기준을 정리했다.
- [완료] macOS 알림 선행 정리
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/macos-notification-preflight.md`
- 요약: Apple signing/장비 없이 macOS native bridge 최소 범위, host placeholder, fixture, evidence 기준을 먼저 정리한다.
- [완료] Windows 알림 선행 정리
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/windows-notification-preflight.md`
- 요약: Windows 장비/packaging 결정 없이 plugin 등록, native API 후보, bridge 계약, fixture, evidence 기준을 먼저 정리했다.
- [완료] Linux 알림 선행 정리
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/linux-notification-preflight.md`
- 요약: Linux 배포판/desktop environment 결정 없이 plugin 등록, notification daemon 후보, bridge 계약, fixture, evidence 기준을 먼저 정리했다.
- [완료] 워크스페이스 포트/환경 표준화
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/workspace-port-env-standardization.md`
- 요약: Mattermost core, push-proxy, Flutter test/web surface, upstream dev services 포트를 workspace 공통 대역과 remote runtime 문서 기준으로 정리했다.
- [완료] Flutter Web 알림
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/flutter-web-notification.md`
- 요약: `packages/messaging_flutter`를 Flutter Web/Chrome foreground browser notification까지 확장하고, Full Web Push는 별도 후속 계약으로 분리한다.
- [완료] Flutter Web 알림 Smoke 보완
- 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/flutter-web-notification-smoke.md`
- 요약: Flutter Web foreground browser notification smoke가 원격 web runner와 forwarded localhost URL에서 실제로 재현되도록 host scaffold, Chrome 테스트, 수동 evidence 기준을 보완한다.
- [진행중] iOS 알림 테스트
- 경로: `agent-roadmap/phase/messaging-runtime/milestones/ios-notification-test.md`
- 요약: 선행 정리 후 iOS/APNs 권한, token, open routing, ACK/dismiss 계약을 실제 설정과 smoke 기준으로 검증한다.
- [계획] macOS 알림 테스트
- 경로: `agent-roadmap/phase/messaging-runtime/milestones/macos-notification-test.md`
- 요약: 선행 정리 후 macOS scaffold/stub 상태의 알림 기준과 구현 gap, smoke 경계를 실제 OS 조건으로 확인한다.
- [계획] Windows 알림 테스트
- 경로: `agent-roadmap/phase/messaging-runtime/milestones/windows-notification-test.md`
- 요약: 선행 정리 후 Windows를 공통 플러그인의 지원 대상으로 두고 native API, packaging/test 조건을 검증한다.
- [계획] Linux 알림 테스트
- 경로: `agent-roadmap/phase/messaging-runtime/milestones/linux-notification-test.md`
- 요약: 선행 정리 후 Linux를 공통 플러그인의 지원 대상으로 두고 배포판, desktop environment, notification daemon, packaging/test 조건을 검증한다.
- [스케치] Full Web Push platform 계약
- 경로: `agent-roadmap/phase/messaging-runtime/milestones/full-web-push-platform-contract.md`
- 요약: 브라우저가 닫힌 상태에서도 수신되는 Web Push를 위해 service worker, VAPID, `web_rn-v2` token, core/push-proxy platform 분기 계약을 정리한다.
- [스케치] 멀티앱 채널 모델
- 경로: `agent-roadmap/phase/messaging-runtime/milestones/multi-app-channel.md`
- 요약: 추가 앱이 생길 때 사용 채널만 늘려 분기할 수 있는 서비스 모델을 검토한다.

69
agent-roadmap/phase/messaging-runtime/milestones/full-web-push-platform-contract.md
View file

@ -1,69 +0,0 @@
# Milestone: Full Web Push platform 계약
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
브라우저가 닫힌 상태에서도 수신되는 Full Web Push를 구현하기 전에, Flutter Web 앱, service worker, Mattermost core, push-proxy가 공유할 platform 계약을 정리한다.
`web_rn-v2` device token, VAPID/Firebase web config, service worker ownership, server/push-proxy platform 분기 범위를 민감값 없이 문서화한다.
## 상태
[스케치]
## 승격 조건
- [ ] service worker 소유 경계가 `packages/messaging_flutter`, host app, 또는 별도 web scaffold 중 어디에 있는지 정리한다.
- [ ] VAPID/Firebase web config는 tracked 문서에 원문 값을 남기지 않고 어떤 local/host 책임으로 주입할지 정리한다.
- [ ] `web_rn-v2` token 저장과 core/push-proxy platform 분기에서 Android/iOS/macOS token 계약을 깨지 않는 범위를 정리한다.
- [ ] 구현 가능한 기능 Task와 검증 명령을 Milestone 문서에 확정한다.
## 구현 잠금
- 상태: 잠금
- 결정 필요:
- service worker ownership과 host app integration 책임 경계를 정해야 한다.
- VAPID/Firebase web config를 어느 환경 책임으로 주입할지 정해야 한다.
## 범위
- Full Web Push service worker 등록과 notification click/open routing 계약
- `web_rn-v2` device token format, 저장, server registration 경계
- Mattermost core push platform 상수와 push-proxy web target 후보
- 민감값 없는 local/remote smoke evidence 기준
## 기능
### Epic: [contract] Web Push 계약 스케치
브라우저 foreground 알림과 Full Web Push 구현 경계를 분리하고 후속 구현 계획으로 승격할 수 있는 계약 후보를 만든다.
- [ ] [sw-boundary] service worker 소유권, 등록 위치, click/open routing 책임을 정리한다.
- [ ] [token-platform] `web_rn-v2` token format과 core/push-proxy platform 분기 후보를 정리한다.
- [ ] [config-evidence] VAPID/Firebase web config 주입 방식과 민감값 없는 smoke evidence 기준을 정리한다.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
- Full Web Push 구현
- 실제 VAPID key, Firebase web config, private host 값 기록
- Mattermost webapp UI/Redux 알림 구현 복제
- 제품 앱 UI 또는 앱별 메시징 화면 구현
## 작업 컨텍스트
- 선행 작업: Flutter Web 알림
- 관련 경로: `packages/messaging_flutter/`, `apps/flutter-test/`, `services/core/`, `services/push-proxy/`
- 표준선(선택): foreground browser notification은 현 Milestone의 완료 범위로 두고, 브라우저 종료 상태 수신은 이 후보 Milestone에서 별도 계약으로 승격한다.

91
agent-roadmap/phase/messaging-runtime/milestones/ios-notification-test.md
View file

@ -1,91 +0,0 @@
# Milestone: iOS 알림 테스트
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Android 중심으로 정리된 nexo 알림 계약을 iOS/APNs 환경에서 어느 수준까지 동일하게 검증할 수 있는지 확인한다.
현재 iOS native plugin은 scaffold/stub 상태이므로 production-ready로 단정하지 않고, 권한 요청, APNs/FCM token, notification open routing, ACK/dismiss 계약을 구현 gap과 smoke 기준으로 나누어 정리한다.
## 상태
[진행중]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 잠금
- 결정 필요:
- [ ] iOS smoke 기준으로 사용할 Apple Developer Team, bundle identifier, provisioning profile 생성/관리 책임을 정한다.
- [ ] APNs 인증 방식은 key 기반인지 certificate 기반인지, 그리고 인증 자산 보관 위치와 접근 책임을 정한다.
- [ ] Firebase iOS app을 새로 만들지 기존 app을 사용할지, `GoogleService-Info.plist` 제공/보관 방식을 정한다.
- [ ] 실제 기기 smoke를 수행할 기기, Apple 계정, 테스트 앱 설치 방식, evidence 제출 방식을 정한다.
- [ ] CI/headless에서 수행할 검증 범위와 수동 검증으로 남길 APNs delivery 범위를 정한다.
## 범위
- iOS plugin scaffold와 `apps/flutter-test/ios` host 설정의 현재 지원 상태 확인
- APNs entitlement, Firebase iOS 설정, notification permission, APNs/FCM token 획득과 host handoff 조건 정리
- iOS foreground/background/terminated notification open routing의 Dart event 계약 확인
- iOS에서 ACK, dismiss, inline reply가 가능한 native hook과 아직 없는 구현 gap 분리
- 실제 기기, simulator, headless test runner별 검증 가능/불가 경계와 evidence 위치 정리
## 기능
### Epic: [baseline] iOS 기준선
iOS 알림이 Android와 같은 계약으로 검증되기 전에 필요한 platform baseline을 확인한다.
- [x] [platform-state] 선행 정리 결과를 바탕으로 `packages/messaging_flutter/ios`와 `apps/flutter-test/ios`의 scaffold, 등록 지점, 남은 no-op gap을 확인한다.
- [ ] [permission-token] APNs entitlement, Firebase config, notification permission, APNs/FCM token 획득과 host handoff 조건을 정리한다.
- [ ] [device-limits] simulator, physical device, CI/headless 환경에서 가능한 검증과 불가능한 검증을 구분한다.
### Epic: [contract] iOS 알림 계약
iOS native event가 Dart API와 host routing callback으로 연결되기 위한 계약을 구체화한다.
- [x] [native-bridge] 선행 정리한 bridge 계약 대비 permission, token refresh, notification opened event를 Flutter method/event channel로 넘기는 iOS 구현 gap을 확인한다.
- [x] [payload-map] 선행 fixture 계약을 실제 APNs/FCM payload의 `server_url`, `server_id`, `channel_id`, `root_id`, `ack_id` 매핑에 대조한다.
- [ ] [ack-dismiss] iOS에서 ACK, dismiss, inline reply를 처리할 수 있는 native hook과 후속 구현이 필요한 gap을 분리한다.
### Epic: [smoke] iOS Smoke
구현 gap을 숨기지 않고 iOS에서 반복 가능한 수동/자동 smoke 기준을 만든다.
- [ ] [manual-smoke] 실제 기기 기준 permission, token handoff, foreground/background/open routing smoke checklist와 evidence 경로를 작성한다.
- [ ] [automation-boundary] widget/integration test로 자동화할 항목과 실제 APNs delivery가 필요한 수동 항목을 분리한다.
- [ ] [follow-up] smoke 결과에 따라 iOS native bridge 구현, host 설정 보강, 문서 보강 중 후속 Milestone 후보를 정리한다.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
- Android FCM 구현 변경은 이 Milestone에서 다루지 않는다.
- macOS, Windows, Linux desktop 알림 검증은 각 OS별 알림 테스트 Milestone에서 다룬다.
- 멀티앱 channel/tenant/server 분기 모델과 push credential 분리 정책은 멀티앱 채널 모델에서 결정한다.
- iOS native bridge 전체 구현은 gap 확인 후 별도 구현 Milestone으로 분리할 수 있다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/ios/`, `packages/messaging_flutter/lib/`, `packages/messaging_flutter/README.md`, `apps/flutter-test/ios/`, `apps/flutter-test/README.md`
- 표준선(선택): iOS scaffold/stub 상태를 먼저 명확히 하고, 가능한 smoke 기준과 후속 구현 gap을 분리한다
- 민감값 기준: Apple/Firebase/APNs credential, team id, profile, token, private host 값은 tracked 문서에 쓰지 않고 책임 경계와 evidence 위치만 기록한다
- 선행 작업: 알림 파이프라인 고도화, iOS 알림 선행 정리
- 후속 작업: 멀티앱 채널 모델
- 확인 필요: 프로비저닝, APNs 인증, Firebase iOS 설정, 실제 기기/CI smoke 환경 결정
- 현재 동기화(2026-06-05): `packages/messaging_flutter/ios/Classes/NexoMessagingPlugin.swift`와 `apps/flutter-test/ios/RunnerTests/RunnerTests.swift` 기준으로 최소 debug/action bridge, device token 저장/조회, auth/signing no-op bridge는 확인됐고, APNs 등록, Firebase token refresh, notification center delegate, ACK, dismiss, inline reply는 구현 gap으로 남아 있다.
- 현재 동기화(2026-06-05): `apps/flutter-test/ios/Runner/Runner.example.entitlements`, `apps/flutter-test/ios/Runner/GoogleService-Info.example.plist`, `apps/flutter-test/ios/Fixtures/*.apns`, `docs/ios-notification-test-guide.md` 기준으로 placeholder와 민감값 제외/evidence 경계는 확인됐고, 실제 Apple/Firebase/기기 smoke 결정은 아직 잠금 항목으로 남아 있다.

68
agent-roadmap/phase/messaging-runtime/milestones/linux-notification-test.md
View file

@ -1,68 +0,0 @@
# Milestone: Linux 알림 테스트
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Linux 환경에서 nexo 알림 계약을 공통 플러그인의 지원 대상으로 포함하기 위해 필요한 배포판, desktop environment, notification daemon, packaging/test 조건을 정리한다.
지원 여부 자체가 아니라 Linux에서 같은 Dart 계약을 제공하기 위한 구현 방식, 테스트 환경, 후속 구현 단위를 확정한다.
## 상태
[계획]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 잠금
- 결정 필요:
- [ ] Linux smoke 대상 배포판, desktop environment, notification daemon, 테스트 장비 책임을 정한다.
- [ ] Linux native notification 연동 방식과 package/runtime dependency 기준을 정한다.
- [ ] Linux 구현을 macOS/Windows 이후 순차 진행할지, iOS/macOS와 병렬로 baseline 조사할지 우선순위를 정한다.
## 범위
- Linux Flutter plugin platform 등록 여부와 필요한 native notification 구현 후보 확인
- Linux notification display, click/open routing, lifecycle 처리를 위한 구현 gap 정리
- Linux에서 ACK, dismiss, inline reply를 Android와 같은 계약으로 다룰 수 있는지 gap 정리
- 실제 OS UI 수동 검증과 자동화 가능 항목의 경계 초안 작성
## 기능
### Epic: [baseline] Linux 기준선
Linux 알림 지원에 필요한 platform baseline을 확인한다.
- [ ] [platform-state] 선행 정리 결과를 바탕으로 Linux plugin platform 등록 여부와 host scaffold 필요 범위를 확인한다.
- [ ] [native-api] 선택한 Linux notification daemon/native 연동 방식과 package/runtime 제약을 smoke 기준으로 확인한다.
- [ ] [test-env] 배포판, desktop environment, 테스트 장비, 수동/자동 smoke 가능 범위를 정리한다.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
- macOS scaffold/stub smoke는 macOS 알림 테스트 Milestone에서 다룬다.
- Windows 알림 지원은 Windows 알림 테스트 Milestone에서 다룬다.
- Linux native implementation 전체 완성은 baseline 확인 후 별도 구현 계획으로 분리할 수 있다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/pubspec.yaml`, `packages/messaging_flutter/README.md`, `apps/flutter-test/README.md`
- 표준선(선택): Linux는 공통 플러그인의 지원 대상이며, 먼저 배포판/desktop environment, notification daemon, packaging/test 조건을 정리한 뒤 구현 단위를 확정한다
- 선행 작업: 알림 파이프라인 고도화, Linux 알림 선행 정리
- 후속 작업: Linux native notification 구현 후보
- 확인 필요: Linux 배포판/desktop environment, native 연동 방식, package/runtime dependency, 진행 우선순위

87
agent-roadmap/phase/messaging-runtime/milestones/macos-notification-test.md
View file

@ -1,87 +0,0 @@
# Milestone: macOS 알림 테스트
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
macOS 환경에서 nexo 알림 계약을 어느 수준까지 검증할 수 있는지 확인한다.
현재 macOS plugin은 scaffold/stub 상태이므로 production-ready로 단정하지 않고, notification permission, display, click/open routing, app lifecycle 조건을 구현 gap과 smoke 기준으로 나누어 정리한다.
## 상태
[계획]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 잠금
- 결정 필요:
- [ ] macOS smoke를 수행할 macOS 버전과 테스트 장비 책임을 정한다.
- [ ] Apple Developer Team, signing, notarization 필요 여부와 entitlement 관리 책임을 정한다.
- [ ] macOS notification smoke를 실제 OS UI 수동 검증으로 볼지, Flutter/widget/integration test와 어떤 경계로 나눌지 정한다.
- [ ] macOS에서 ACK, dismiss, inline reply를 같은 Milestone에서 gap 확인만 할지 후속 구현 후보까지 구체화할지 정한다.
## 범위
- macOS plugin scaffold/stub과 `apps/flutter-test/macos` host 설정의 현재 지원 상태 확인
- macOS notification permission, display, click/open routing, app lifecycle 조건 정리
- macOS에서 ACK, dismiss, inline reply를 Android와 같은 계약으로 다룰 수 있는지 gap 정리
- OS notification UI가 필요한 수동 검증과 headless 자동화 가능 항목의 경계 정리
## 기능
### Epic: [baseline] macOS 기준선
macOS 알림이 Android/iOS와 같은 계약으로 검증되기 전에 필요한 platform baseline을 확인한다.
- [ ] [platform-state] 선행 정리 결과를 바탕으로 `packages/messaging_flutter/macos`와 `apps/flutter-test/macos`의 scaffold, 등록 지점, 남은 no-op gap을 확인한다.
- [ ] [macos-host] app delegate, entitlement, permission/display 준비 조건을 확인한다.
- [ ] [device-limits] macOS 버전, signing/notarization, headless 환경에서 가능한 검증과 불가능한 검증을 구분한다.
### Epic: [contract] macOS 알림 계약
macOS notification event가 Dart API와 host routing callback으로 연결되기 위한 계약을 구체화한다.
- [ ] [display-open] 선행 정리한 payload/event 계약 대비 macOS notification display와 click/open routing 연결 gap을 확인한다.
- [ ] [lifecycle] foreground, background, minimized, terminated 상태에서 macOS notification 처리 기준과 제한을 실제 OS 조건에 대조한다.
- [ ] [ack-dismiss] macOS에서 ACK, dismiss, inline reply를 처리할 수 있는 platform hook과 후속 구현 gap을 분리한다.
### Epic: [smoke] macOS Smoke
구현 gap을 숨기지 않고 macOS에서 반복 가능한 수동/자동 smoke 기준을 만든다.
- [ ] [manual-smoke] macOS permission, display, click/open routing smoke checklist와 evidence 경로를 작성한다.
- [ ] [automation-boundary] OS notification UI 때문에 수동 확인이 필요한 항목과 Flutter integration test로 대체 가능한 항목을 분리한다.
- [ ] [follow-up] smoke 결과에 따라 macOS native bridge 구현, host 설정 보강, 문서 보강 중 후속 Milestone 후보를 정리한다.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
- iOS/APNs 알림 검증은 iOS 알림 테스트 Milestone에서 다룬다.
- Android FCM 구현 변경은 이 Milestone에서 다루지 않는다.
- Windows/Linux desktop 알림 검증과 신규 native implementation은 각 OS별 Milestone에서 다룬다.
- 멀티앱 channel/tenant/server 분기 모델과 push credential 분리 정책은 멀티앱 채널 모델에서 결정한다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/macos/`, `packages/messaging_flutter/pubspec.yaml`, `packages/messaging_flutter/README.md`, `apps/flutter-test/macos/`, `apps/flutter-test/README.md`
- 표준선(선택): macOS scaffold/stub 상태를 먼저 검증하고, 가능한 smoke 기준과 후속 구현 gap을 분리한다
- 민감값 기준: Apple credential, team id, profile, private host 값은 tracked 문서에 쓰지 않고 책임 경계와 evidence 위치만 기록한다
- 선행 작업: 알림 파이프라인 고도화, macOS 알림 선행 정리
- 후속 작업: Windows 알림 테스트, Linux 알림 테스트, 멀티앱 채널 모델
- 확인 필요: macOS 버전/장비, signing/notarization 필요 여부, 수동/자동 smoke 경계 결정

46
agent-roadmap/archive/phase/messaging-runtime/milestones/messaging-contract.md → agent-roadmap/phase/messaging-runtime/milestones/messaging-contract.md
View file

@ -12,7 +12,7 @@ upstream-followable server/push runtime과 nexo-owned Flutter SDK가 주고받
## 상태
[완료]
[계획]
## 승격 조건
@ -20,12 +20,11 @@ upstream-followable server/push runtime과 nexo-owned Flutter SDK가 주고받
## 구현 잠금
- 상태: 해제
- 상태: 잠금
- 결정 필요:
- 없음
- [ ] 메시징 전체 기능 중 Flutter 앱에 우선 노출할 범위를 결정한다.
- 결정 완료:
- [x] 2026-05-27: Flutter public API는 nexo-owned SDK wrapper로 유지하고, server/push runtime compatibility와 분리한다.
- [x] 2026-05-30: 이번 단계의 Flutter 앱 공식 노출 범위는 메시징 UI 전체가 아니라 알림 수신, 열기 라우팅, device token, auth, signing key, ACK 호환 계약까지로 충분하다고 결정했다.
## 범위
@ -41,34 +40,29 @@ upstream-followable server/push runtime과 nexo-owned Flutter SDK가 주고받
앱이 의존할 수 있는 최소 메시징/알림 API 표면을 정리한다.
- [x] [dart-api] Dart public API에서 유지할 이름, deprecated 후보, nexo wrapper 후보를 분리한다.
- [x] [event-shape] notification event, opened event, token event의 payload shape와 backward compatibility 기준을 문서화한다.
- [x] [token-flow] device token 저장, auth token 저장, signing key 저장 책임과 호출 순서를 정리한다.
- [x] [sdk-runtime-boundary] Flutter SDK가 server/push contract를 추적하되 Mattermost mobile implementation을 팔로잉하지 않는 경계를 문서화한다.
- [ ] [dart-api] Dart public API에서 유지할 이름, deprecated 후보, nexo wrapper 후보를 분리한다.
- [ ] [event-shape] notification event, opened event, token event의 payload shape와 backward compatibility 기준을 문서화한다.
- [ ] [token-flow] device token 저장, auth token 저장, signing key 저장 책임과 호출 순서를 정리한다.
- [ ] [sdk-runtime-boundary] Flutter SDK가 server/push contract를 추적하되 Mattermost mobile implementation을 팔로잉하지 않는 경계를 문서화한다.
### Epic: [server-contract] Server contract
서버 core와 플러그인이 공유하는 메시징/알림 계약을 확인 가능한 형태로 만든다.
- [x] [push-payload] push payload 필드와 검증 기준을 서버/플러그인 양쪽 문서에서 연결한다.
- [x] [ack-contract] ACK 요청 형식과 실패 처리 기준을 정리한다.
- [x] [routing-contract] channel/thread navigation event가 client router로 전달되는 기준을 정리한다.
- [x] [front-compat] Mattermost webapp/reference front에서 동작하는 기본 메시징 기능과 Flutter SDK embedded 흐름이 충돌하지 않는 기준을 정리한다.
- [ ] [push-payload] push payload 필드와 검증 기준을 서버/플러그인 양쪽 문서에서 연결한다.
- [ ] [ack-contract] ACK 요청 형식과 실패 처리 기준을 정리한다.
- [ ] [routing-contract] channel/thread navigation event가 client router로 전달되는 기준을 정리한다.
- [ ] [front-compat] Mattermost webapp/reference front에서 동작하는 기본 메시징 기능과 Flutter SDK embedded 흐름이 충돌하지 않는 기준을 정리한다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-05-30
- 승인일: 2026-05-30
- 완료 근거:
- `packages/messaging_flutter/README.md`에 plugin-side public API, event shape, token/credential flow, push payload, ACK, routing, reference front compatibility 기준을 정리했다.
- `services/core/compose/README.md`에 server-side source anchors, payload fields, ACK endpoint, webapp/reference front compatibility 기준을 연결했다.
- 모든 기능 Task가 문서/테스트/source anchor 근거와 함께 완료 후보가 되었다.
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] Flutter 앱 우선 노출 범위가 현재 Public API Contract 기준으로 충분한지 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: Flutter 앱은 Mattermost 앱 전체를 포함하지 않고 메시징/알림 기본 기능을 사용하기 위한 SDK 범위로 충분하다는 사용자 결정을 반영해 완료 및 archive를 승인했다.
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
@ -80,10 +74,6 @@ upstream-followable server/push runtime과 nexo-owned Flutter SDK가 주고받
- 관련 경로: `packages/messaging_flutter/lib/`, `packages/messaging_flutter/android/`, `services/core/server/`, `services/core/webapp/`, `services/core/compose/`, `apps/flutter-test/`
- 표준선(선택): SDK public API는 nexo-owned wrapper로 유지하고, server/webapp/push-proxy compatibility는 얇은 layer로 흡수한다
- 진행 근거:
- 2026-05-30 `packages/messaging_flutter/README.md`에 Public API Contract 섹션을 추가해 유지 API, compatibility/deprecated 후보, nexo wrapper 후보를 분리했다.
- 2026-05-30 `packages/messaging_flutter/README.md`의 Event Shape Contract, Token And Credential Flow, SDK Ownership Boundary, Runtime Tracking Boundary 섹션과 `packages/messaging_flutter/test/nexo_messaging_test.dart` 근거로 event shape, token flow, SDK/runtime boundary, routing contract를 완료로 판정했다.
- 2026-05-30 `packages/messaging_flutter/README.md`와 `services/core/compose/README.md`를 상호 연결해 push payload, ACK, reference front compatibility 계약 기준을 완료 후보로 정리했다.
- 선행 작업: 정체성 기준선, 업스트림 팔로잉 기준선, 클라이언트 검증 기준선
- 후속 작업: 알림 파이프라인 고도화, 멀티앱 채널 모델
- 확인 완료: Flutter 앱 우선 노출 범위는 메시징/알림 기본 기능 사용에 필요한 계약까지로 한정한다.
- 확인 필요: Flutter 앱 우선 노출 범위

5
agent-roadmap/phase/messaging-runtime/milestones/multi-app-channel.md
View file

@ -18,9 +18,6 @@ server/webapp/push-proxy는 upstream-followable runtime으로 두고, 앱별 내
## 승격 조건
- [ ] 첫 번째 외부 소비 앱 또는 내부 테스트 앱 후보를 정한다.
- [ ] iOS 알림 테스트 Milestone에서 iOS/APNs 알림 smoke 기준과 구현 gap을 확인한다.
- [ ] macOS 알림 테스트 Milestone에서 macOS desktop 알림 smoke 기준과 구현 gap을 확인한다.
- [ ] Windows/Linux 알림 테스트 Milestone에서 각 OS의 native API, packaging/test 조건과 구현 단위를 확인한다.
- [ ] 앱별 channel namespace, team/server 분리, tenant 분리 중 어떤 모델을 쓸지 결정한다.
- [ ] 앱별 push credential과 routing callback 분리 기준을 정한다.
- [ ] 구현 가능한 후속 Milestone을 API, server config, client integration 중 하나 이상으로 나눈다.
@ -77,6 +74,6 @@ server/webapp/push-proxy는 upstream-followable runtime으로 두고, 앱별 내
- 관련 경로: `services/core/`, `packages/messaging_flutter/`, `apps/flutter-test/`
- 표준선(선택): 먼저 channel 기반 최소 모델을 검토하고, 운영 비용이 커질 때 tenant/server 분리를 검토한다
- 선행 작업: 메시징 계약 표준화, 알림 파이프라인 고도화, iOS 알림 테스트, macOS 알림 테스트, Windows 알림 테스트, Linux 알림 테스트
- 선행 작업: 메시징 계약 표준화, 알림 파이프라인 고도화
- 후속 작업: 업스트림 런타임 운영화 Phase의 CI/CD와 운영 업데이트 루프
- 확인 필요: 앱별 분기 단위와 credential 분리 기준

42
agent-roadmap/archive/phase/messaging-runtime/milestones/notification-pipeline.md → agent-roadmap/phase/messaging-runtime/milestones/notification-pipeline.md
View file

@ -13,7 +13,7 @@ Android 구현은 Mattermost mobile code 팔로잉 대상이 아니라 nexo-owne
## 상태
[완료]
[계획]
## 승격 조건
@ -21,9 +21,10 @@ Android 구현은 Mattermost mobile code 팔로잉 대상이 아니라 nexo-owne
## 구현 잠금
- 상태: 해제
- 상태: 잠금
- 결정 필요:
- 없음
- [ ] iOS/APNS 구현을 Android 안정화 이후로 미룰지, 같은 Phase에서 병행할지 결정한다.
- [ ] push ACK 실패와 offline queue를 어디까지 plugin 책임으로 볼지 결정한다.
## 범위
@ -40,44 +41,39 @@ Android 구현은 Mattermost mobile code 팔로잉 대상이 아니라 nexo-owne
Android-first 알림 파이프라인을 안정된 제품 책임으로 만든다.
- [x] [verify-payload] signing key 기반 payload 검증과 drop 조건을 테스트 가능한 형태로 유지한다.
- [x] [display-notification] message/thread notification display 기준을 정리하고 회귀 테스트 후보를 만든다.
- [x] [ack-delivery] ACK request, local pending queue, bounded retry, 영구 실패 전달 기준을 정리한다.
- [x] [reply-dismiss] inline reply와 dismiss action의 storage/network 경계를 정리한다.
- [x] [platform-follow] Mattermost mobile implementation merge 대신 server/push contract, FCM, Android notification platform 변경을 추적하는 기준을 정리한다.
- [ ] [verify-payload] signing key 기반 payload 검증과 drop 조건을 테스트 가능한 형태로 유지한다.
- [ ] [display-notification] message/thread notification display 기준을 정리하고 회귀 테스트 후보를 만든다.
- [ ] [ack-delivery] ACK request 성공/실패 처리와 retry 후보를 정리한다.
- [ ] [reply-dismiss] inline reply와 dismiss action의 storage/network 경계를 정리한다.
- [ ] [platform-follow] Mattermost mobile implementation merge 대신 server/push contract, FCM, Android notification platform 변경을 추적하는 기준을 정리한다.
### Epic: [host-routing] Host routing
host app이 받아야 할 최소 이벤트만 노출한다.
- [x] [opened-event] notification-open event가 channel/thread routing으로 이어지는 기준을 유지한다.
- [x] [host-contract] host app이 반드시 구현해야 할 callback과 login/logout hook을 문서화한다.
- [ ] [opened-event] notification-open event가 channel/thread routing으로 이어지는 기준을 유지한다.
- [ ] [host-contract] host app이 반드시 구현해야 할 callback과 login/logout hook을 문서화한다.
## 완료 리뷰
- 상태: 승인됨
- 요청일: 2026-05-31
- 완료 근거:
- `m-notification-pipeline/01_android_payload_display` PASS: `verify-payload`, `display-notification`, `platform-follow` 완료와 remote Flutter/Android native 검증 통과가 기록됐다.
- `m-notification-pipeline/02+01_ack_actions` PASS: `ack-delivery`, `reply-dismiss` 완료와 analyze/package test/Android unit test 통과가 기록됐다.
- `m-notification-pipeline/03_host_routing_contract` PASS: `opened-event`, `host-contract` 완료와 package/widget/integration/doc grep 검증 통과가 기록됐다.
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [x] 사용자가 완료 결과를 확인했다
- [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-05-31 사용자 요청으로 현 마일스톤 완료와 archive 이동을 승인했다.
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
- full message composer나 chat screen UI 구현은 포함하지 않는다.
- APNS/iOS 구현은 Android 안정화 이후 후속 후보로 미룬다.
- APNS/iOS 구현은 결정 전까지 스캐폴드 유지로 둔다.
- 서버 core의 대규모 fork 변경은 포함하지 않는다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/android/`, `packages/messaging_flutter/lib/`, `apps/flutter-test/integration_test/`
- 표준선(선택): Android-first nexo SDK로 자동화 가능한 테스트를 늘리고, FCM delivery는 수동 smoke로 분리한다
- 결정됨: iOS/APNS 구현은 Android 안정화 이후로 미룬다.
- 결정됨: ACK/offline queue는 plugin이 알림 액션 ACK, inline reply, dismiss의 local pending queue와 bounded retry까지 책임지고, 로그인 만료, 서버 거절, 장기 오프라인 같은 영구 실패는 host callback 또는 telemetry로 넘긴다.
- 선행 작업: 메시징 계약 표준화
- 후속 작업: 멀티앱 채널 모델, iOS/APNS 후보
- 확인 필요: 없음
- 확인 필요: iOS 우선순위와 ACK 실패 책임 범위

68
agent-roadmap/phase/messaging-runtime/milestones/windows-notification-test.md
View file

@ -1,68 +0,0 @@
# Milestone: Windows 알림 테스트
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md`
## 목표
Windows 환경에서 nexo 알림 계약을 공통 플러그인의 지원 대상으로 포함하기 위해 필요한 platform 등록, native notification API, packaging/test 조건을 정리한다.
지원 여부 자체가 아니라 Windows에서 같은 Dart 계약을 제공하기 위한 구현 방식, 테스트 환경, 후속 구현 단위를 확정한다.
## 상태
[계획]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 잠금
- 결정 필요:
- [ ] Windows smoke 대상 OS 버전, 테스트 장비, 계정/권한 책임을 정한다.
- [ ] Windows native notification API와 app packaging 기준을 정한다.
- [ ] Windows 구현을 macOS 이후 순차 진행할지, iOS/macOS와 병렬로 baseline 조사할지 우선순위를 정한다.
## 범위
- Windows Flutter plugin platform 등록 여부와 필요한 native notification 구현 후보 확인
- Windows notification display, click/open routing, lifecycle 처리를 위한 구현 gap 정리
- Windows에서 ACK, dismiss, inline reply를 Android와 같은 계약으로 다룰 수 있는지 gap 정리
- 실제 OS UI 수동 검증과 자동화 가능 항목의 경계 초안 작성
## 기능
### Epic: [baseline] Windows 기준선
Windows 알림 지원에 필요한 platform baseline을 확인한다.
- [ ] [platform-state] 선행 정리 결과를 바탕으로 Windows plugin platform 등록 여부와 host scaffold 필요 범위를 확인한다.
- [ ] [native-api] 선택한 Windows native notification API와 packaging 제약을 smoke 기준으로 확인한다.
- [ ] [test-env] Windows 버전, 테스트 장비, 수동/자동 smoke 가능 범위를 정리한다.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
- macOS scaffold/stub smoke는 macOS 알림 테스트 Milestone에서 다룬다.
- Linux 알림 지원은 Linux 알림 테스트 Milestone에서 다룬다.
- Windows native implementation 전체 완성은 baseline 확인 후 별도 구현 계획으로 분리할 수 있다.
## 작업 컨텍스트
- 관련 경로: `packages/messaging_flutter/pubspec.yaml`, `packages/messaging_flutter/README.md`, `apps/flutter-test/README.md`
- 표준선(선택): Windows는 공통 플러그인의 지원 대상이며, 먼저 platform 등록, native API, packaging/test 조건을 정리한 뒤 구현 단위를 확정한다
- 선행 작업: 알림 파이프라인 고도화, Windows 알림 선행 정리
- 후속 작업: Windows native notification 구현 후보
- 확인 필요: Windows OS 버전/장비, native API, packaging/test 기준, 진행 우선순위

Some files were not shown because too many files have changed in this diff Show more