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

sync: agent-ops from agentic-framework v1.1.166

Browse source
This commit is contained in:
toki 2026-07-15 14:49:53 +09:00
parent e5b4dee853
commit a6fa2bbc37
9 changed files with 106 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
agent-ops/.version
View file

@ -1 +1 @@
1.1.165
1.1.166

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

@ -5,6 +5,7 @@
## 구조
- 최상위 로드맵은 `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>`는 소문자 영문, 숫자, 하이픈만 사용한다.
@ -35,10 +36,12 @@
## 로딩
- 세션 최초 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 없음으로 보고한 뒤 `ROADMAP.md`의 Phase 흐름만 보여준다.
- 일반 작업에서는 `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` 존재 여부를 확인한다.
@ -49,6 +52,10 @@
## 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`만 대상으로 한다.
@ -192,5 +199,6 @@
- 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 선택이나 위치 분석의 후보로 삼지 않는다.
- 아카이브 문서는 과거 기록 스냅샷으로 보고, 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.

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

@ -1,5 +1,10 @@
# 현재 로드맵 컨텍스트
## 고정 참조
- Phase를 가로지르는 다음 작업 후보는 [전역 마일스톤 실행 순서](priority-queue.md)를 먼저 확인한다.
- Phase는 도메인/책임 영역이며 순차 실행 게이트가 아니다.
## 활성 Phase
- [<스케치 | 계획 | 진행중 | 검토중 | 보류>] <phase-name>

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

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

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

@ -1,5 +1,16 @@
# 로드맵
## 고정 실행 순서
- 전역 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문장으로 작성>
@ -18,6 +29,7 @@
## 로딩 정책
- 일반 작업에서는 [ROADMAP.md](ROADMAP.md)를 매번 읽지 않는다.
- Phase를 가로지르는 다음 작업 후보를 고를 때는 [전역 마일스톤 실행 순서](priority-queue.md)를 먼저 확인한다.
- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 [current.md](current.md)를 먼저 읽는다.
- `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
- `current.md`는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다. 로드맵 기반 계획/갱신에서 없으면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 생성해 사용하고, 읽기 전용 현지점 확인에서는 생성하지 않는다.

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

@ -1,6 +1,6 @@
---
name: complete-milestone
version: 1.0.0
version: 1.1.0
description: "마일스톤 완료해도 될지 검토, 현 마일스톤 종료 검토, 현재 마일스톤 닫고 다음 마일스톤 지정, 검토중 Milestone 코드레벨 종료 감사 요청에 사용한다. 코드/테스트/계약/evidence를 점검하고 작은 보완은 처리하거나 큰 보완은 plan으로 넘기며, agent-spec이 있으면 update-spec을 필수 gate로 수행한 뒤 update-roadmap으로 완료/archive와 다음 Milestone 지정을 처리한다."
---
@ -28,6 +28,7 @@ description: "마일스톤 완료해도 될지 검토, 현 마일스톤 종료
## 먼저 확인할 것
- [ ] `agent-roadmap/current.md`와 대상 활성 Milestone, 대상 Phase `PHASE.md`를 읽는다.
- [ ] `agent-roadmap/priority-queue.md`가 있으면 종료 후 다음 후보와 archive 제거 대상 확인을 위해 읽는다.
- [ ] 대상 Milestone의 `상태`, `기능`, `구현 잠금`, `완료 리뷰`, `작업 컨텍스트`, SDD gate를 확인한다.
- [ ] 완료 근거 동기화가 필요하면 `sync-milestone-workstate` 절차를 확인한다.
- [ ] 종료/archive가 가능하면 `update-roadmap` 절차를 확인한다.
@ -73,11 +74,13 @@ description: "마일스톤 완료해도 될지 검토, 현 마일스톤 종료
- 모든 기능 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`에 반영한다.
- 없으면 같은 Phase의 Milestone 흐름에서 완료/폐기/archive가 아닌 다음 후보를 찾는다.
- 없고 `priority-queue.md`가 있으면 큐의 위에서 아래 순서 중 완료/archive 대상이 아니고 `[폐기]`가 아닌 첫 활성 Milestone을 다음 후보로 찾는다.
- `priority-queue.md`가 없으면 같은 Phase의 Milestone 흐름에서 완료/폐기/archive가 아닌 다음 후보를 찾는다.
- 후보가 없거나 둘 이상이면 자동 지정하지 않고 후보와 이유를 보고한다.
- 다음 후보가 `[스케치]`이면 구현 대상이 아니라 구체화 대상임을 보고한다.
@ -93,6 +96,7 @@ description: "마일스톤 완료해도 될지 검토, 현 마일스톤 종료
- [ ] `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`를 실행했는가

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

@ -1,15 +1,16 @@
---
name: create-roadmap
version: 1.17.0
description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, 로컬 current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하고, agent-ui 코드 동기화 Milestone의 완료 리뷰 상태 반영 항목을 포함하는 공통 스킬
version: 1.18.0
description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, 전역 priority-queue.md 실행 순서 문서, 로컬 current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하고, agent-ui 코드 동기화 Milestone의 완료 리뷰 상태 반영 항목을 포함하는 공통 스킬
---
# 로드맵 생성
## 목적
`agent-roadmap/` 하위에 `Roadmap -> Phase -> Milestone` 기반 한국어 로드맵 구조를 처음 생성한다.
`agent-roadmap/` 하위에 `Roadmap -> priority-queue -> Phase -> Milestone` 기반 한국어 로드맵 구조를 처음 생성한다.
전체 로드맵은 전체 방향과 Phase index만 담당하고, 일반 작업에서는 브랜치별 로컬 `current.md`의 활성 Phase/Milestone 링크와 관련 문서만 읽도록 만든다.
`priority-queue.md`는 Phase를 가로지르는 실행 순서만 담당한다.
Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서다.
Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능` 안에서 관리한다. 별도 `완료 기준` 섹션은 만들지 않고, 검증이 필요한 기능에만 같은 Task 안의 `검증:` 문구로 통합한다.
@ -32,6 +33,7 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능
```text
agent-roadmap/
ROADMAP.md
priority-queue.md
current.md # local, git ignored
phase/
<phase-slug>/
@ -58,6 +60,7 @@ agent-roadmap/
| 파일 | 역할 |
|------|------|
| `agent-roadmap/ROADMAP.md` | 전체 목표와 Phase 흐름만 담는 최상위 지도. 로드맵 생성/갱신/Phase 전환 때만 읽는다 |
| `agent-roadmap/priority-queue.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 체크리스트, 범위 제외 항목 |
@ -69,12 +72,14 @@ 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`에는 Milestone 상세 체크리스트를 넣지 않는다.
- `priority-queue.md`는 순서 전용 문서이며, Milestone 제목 링크와 식별용 한 줄 설명만 둔다.
- `current.md`는 git 추적 대상이 아니며, 예시 파일을 `agent-roadmap/`에 따로 만들지 않는다.
- `current.md`는 활성 Phase/Milestone 후보만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다.
- archive 경로는 `current.md`의 활성 항목에 넣지 않는다.
@ -86,7 +91,10 @@ agent-roadmap/
- `[스케치]`는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 구현 계획 생성 대상이 아니다.
- `[계획]`은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 문서화되어 잠금 해제 후 구현 계획을 만들 수 있는 상태다.
- Phase와 Milestone 이름, 파일명에는 `1`, `2`, `M01`, `P1` 같은 순번을 붙이지 않는다.
- 진행 순서는 `ROADMAP.md`와 각 `PHASE.md`의 위에서 아래 순서로 표현한다.
- Phase 흐름은 `ROADMAP.md`와 각 `PHASE.md`의 위에서 아래 순서로 표현한다.
- Phase를 가로지르는 실제 실행 순서는 `priority-queue.md`의 위에서 아래 순서로 표현한다.
- `priority-queue.md`에는 상태, 목표, 범위, 잠금, 기능, 완료 근거, 의존성 필드를 복제하지 않는다.
- 실행 후보가 없더라도 `priority-queue.md` 파일과 `실행 순서` 섹션은 생성한다.
- Phase 파일명은 `agent-roadmap/phase/<phase-slug>/PHASE.md`로 만든다.
- Milestone 파일명은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`로 만든다.
- `<phase-slug>`와 `<milestone-slug>`는 소문자 영문, 숫자, 하이픈만 사용하고, 공백/언더스코어/순번 prefix를 넣지 않는다.
@ -128,7 +136,7 @@ agent-roadmap/
- [ ] 이미 존재하면 덮어쓰지 말고 `update-roadmap` 스킬 사용을 안내
- [ ] `README.md`, `agent-ops/GUIDE.md`, `agent-ops/rules/project/rules.md` 등 프로젝트 방향을 설명하는 문서를 확인
- [ ] `rg --files`로 현재 프로젝트의 주요 구조를 가볍게 확인
- [ ] `roadmap-template.md`, `roadmap-current-template.md`, `roadmap-phase-template.md`, `roadmap-milestone-template.md`를 읽어 최신 형식 확인
- [ ] `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`를 읽어 최신 절차와 형식 확인
- [ ] `agent-ops/rules/common/rules.md`가 로드맵 디렉터리 존재 시 `agent-ops/rules/common/rules-roadmap.md`를 읽도록 라우팅하는지 확인
@ -150,7 +158,9 @@ agent-roadmap/
- Milestone 내부에서 여러 기능 묶음이 필요하면 Epic으로 선언하고, Epic 아래 flat Task 체크리스트를 둔다.
4. **파일 생성**
- `ROADMAP.md`, 로컬 `current.md`, 각 Phase의 `PHASE.md`, 각 Milestone 문서를 템플릿 순서대로 생성한다.
- `ROADMAP.md`, `priority-queue.md`, 로컬 `current.md`, 각 Phase의 `PHASE.md`, 각 Milestone 문서를 템플릿 순서대로 생성한다.
- `ROADMAP.md` 최상단에는 `priority-queue.md`를 먼저 확인하도록 `고정 실행 순서` 섹션을 둔다.
- `priority-queue.md`에는 Phase를 가로지르는 실행 후보 Milestone을 위에서 아래 순서로 둔다. 후보가 없으면 `실행 순서` 섹션만 비워 둔다.
- 활성 Phase와 활성 Milestone은 `current.md`에 모두 기록한다.
- `.gitignore`의 Agent-Ops 관리 block에 `agent-roadmap/current.md`가 있는지 확인하고 없으면 추가한다.
- `ROADMAP.md`의 Phase 흐름에는 완료/검토중/진행중/계획/스케치 Phase 모두를 위에서 아래 순서로 두고, 계획 Phase는 진행중 Phase보다 아래에, 스케치 Phase는 계획 Phase보다 아래에 둔다.
@ -163,6 +173,8 @@ agent-roadmap/
5. **검증**
- 생성한 링크가 실제 파일을 가리키는지 확인한다.
- `priority-queue.md`가 존재하고 `실행 순서` 섹션이 있는지 확인한다.
- `priority-queue.md`의 모든 링크가 활성 Milestone 파일을 가리키는지 확인한다. 실행 후보가 없어서 빈 큐이면 정상으로 보고하되, 활성 실행 후보가 있는데 비어 있으면 큐 동기화 필요로 본다.
- 생성한 로드맵 문서의 문서/산출물 포인터가 raw path만 남지 않고 Markdown 링크로 작성되었는지 확인한다.
- 생성한 로드맵 문서의 Markdown 링크 target에 템플릿 placeholder가 남지 않았는지 확인한다.
- 로컬 `current.md` 활성 항목에 `agent-roadmap/archive/**` 경로가 없는지 확인한다.
@ -183,6 +195,7 @@ agent-roadmap/
## 생성 결과
- 로드맵: [ROADMAP.md](agent-roadmap/ROADMAP.md)
- 전역 실행 순서: [priority-queue.md](agent-roadmap/priority-queue.md)
- 로컬 현재 컨텍스트: [current.md](agent-roadmap/current.md)
- Phase 문서: <N개>
- Milestone 문서: <N개>
@ -190,6 +203,7 @@ agent-roadmap/
- 활성 Milestone: <N개>
- 구현 잠금: <잠금 Milestone N개 | 해제 Milestone N개>
- SDD gate: <필요 N개 | 불필요 N개 | 작성 N개 | pass N개 | review-required N개 | blocked/invalid N개>
- 전역 실행 순서: <항목 N개 | 빈 큐 | 동기화 필요>
- 최종 확인: <통과 | 사용자 리뷰 필요 | 보완 필요: SDD gate/링크/상태/형식>
- Workspace 잠금: <생성/갱신 N개 | 없음>
- 공통 로드맵 룰: <확인함 | 설치 필요 | 해당 없음>
@ -208,6 +222,8 @@ agent-roadmap/
- 기존 `agent-roadmap/` 파일을 덮어쓰지 않는다.
- 일반 작업마다 전체 `ROADMAP.md`를 읽도록 규칙을 만들지 않는다.
- `priority-queue.md`를 두 번째 로드맵처럼 사용하지 않는다. 상태, 목표, 범위, 잠금, 기능, 완료 근거를 복제하지 않는다.
- `priority-queue.md`에 archive Milestone 링크를 넣지 않는다.
- 로컬 `current.md`에 `agent-roadmap/archive/**` 경로를 넣지 않는다.
- `agent-roadmap/current.md`를 git 추적 대상으로 만들지 않는다.
- Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.

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

@ -148,6 +148,9 @@ If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G
로드맵 확인:
- `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으로 빠지지 않는다.
- `current.md`가 `agent-roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 활성 Phase/Milestone이 아니라고 보고한다.
- 선택한 Phase를 한 번 읽어 Phase 목표, Milestone 흐름, Phase 경계를 확인한다.

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

@ -1,7 +1,7 @@
---
name: update-roadmap
version: 1.22.0
description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 로컬 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, agent-ui 코드 동기화 Milestone의 종료 검토 시 구현됨 상태 반영, 완료 근거 충족 archive 이동, workspace 외부 의존 잠금 양방향 동기화를 처리한다.
version: 1.23.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 외부 의존 잠금 양방향 동기화를 처리한다.
---
# 로드맵 업데이트
@ -9,9 +9,10 @@ description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/
## 목적
기존 `agent-roadmap/` 구조를 현재 프로젝트 방향과 진행 상태에 맞게 갱신한다.
표준 구조는 `ROADMAP.md -> phase/<phase-slug>/PHASE.md -> phase/<phase-slug>/milestones/<milestone-slug>.md`다.
표준 구조는 `ROADMAP.md -> priority-queue.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 상세 정보는 복제하지 않는다.
Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서로 유지한다.
Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능` 안에서 관리한다. 별도 `완료 기준` 섹션은 만들지 않고, 검증이 필요한 기능에만 같은 Task 안의 `검증:` 문구로 통합한다.
@ -27,6 +28,9 @@ 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 프로젝트 작업 뒤에 진행되어야 한다", "의존성 설정해"처럼 외부 의존 잠금을 말할 때
## 입력
@ -52,12 +56,14 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능
- `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
phase/
<phase-slug>/
@ -81,7 +87,8 @@ agent-roadmap/
SDD.md
```
- `ROADMAP.md`는 전체 목표와 Phase 흐름만 담는다.
- `ROADMAP.md`는 전체 목표와 Phase 흐름, `priority-queue.md` 고정 라우팅만 담는다.
- `priority-queue.md`는 Phase를 가로지르는 Milestone 실행 순서만 담는다. 항목은 Milestone 제목 링크와 식별용 한 줄 설명만 둔다.
- `PHASE.md`는 해당 Phase의 목표, 상태, Milestone 흐름, Phase 경계를 담는다.
- Milestone 문서는 해당 Phase 하위 `milestones/`에 둔다.
- 완료된 Phase는 `archive/phase/<phase-slug>/PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
@ -95,6 +102,7 @@ agent-roadmap/
- `current.md`는 git 추적 대상이 아니며, 공유 진행 상태는 `ROADMAP.md`, `PHASE.md`, Milestone 문서, `.agent-roadmap-sync/locks.yaml`에 기록한다.
- `current.md`에는 archive 경로를 넣지 않는다.
- `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 완료 근거와 archive 전환이 정리될 때까지 `[검토중]`으로 둔다.
- `priority-queue.md`에는 archive 경로를 넣지 않는다. 완료 Milestone은 archive 시 제거하고, 폐기 Milestone은 큐에서 제거한다.
## 상태와 id
@ -119,6 +127,7 @@ agent-roadmap/
- 일반 갱신은 로컬 `current.md`, 관련 활성 Phase, 관련 활성 Milestone을 우선 읽는다.
- `current.md`가 없고 활성 창 갱신이 필요하면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 로컬 파일을 만든다.
- `ROADMAP.md`는 Phase 흐름, 전체 구조, 활성 범위 밖 작업, 전체 재계획, archive 링크 갱신이 필요할 때 읽는다.
- `priority-queue.md`는 Phase를 가로지르는 다음 작업 후보 선택, 사용자가 요청한 순서 조정, archive/폐기/경로 변경/split/merge 후 큐 정리, 깨진 링크 복구가 필요할 때 읽고 갱신한다.
- `agent-roadmap/archive/**`는 일반 작업이나 sync에서 읽지 않는다.
- archive 모드에서 이동 대상이 아직 활성 경로에 있으면 그 대상 문서는 읽을 수 있다.
- 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 요청이면 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라 필요한 archive 문서만 읽는다.
@ -126,6 +135,7 @@ 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`
@ -134,7 +144,7 @@ agent-roadmap/
## 링크 표기
- 사용자에게 보여주는 결과 보고와 새로 생성/갱신하는 로드맵 문서에서 `ROADMAP.md`, `current.md`, `PHASE.md`, Milestone 문서, SDD, `USER_REVIEW.md`, archive 문서, `complete.log` 같은 문서/산출물 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
- 사용자에게 보여주는 결과 보고와 새로 생성/갱신하는 로드맵 문서에서 `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 링크로 작성한다.
@ -306,6 +316,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 대상 파일을 `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에서는 제거한다.
- `ROADMAP.md`는 Phase 상태나 경로가 바뀌지 않으면 수정하지 않는다.
- 이동한 archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다.
@ -317,6 +328,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- `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을 제거한다.
- archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다.
@ -327,6 +339,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 런타임 완료 이벤트의 `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 상태 반영 단계를 적용하지 않는다.
- 새 기능 배치, Epic/Task 추가는 `milestone` 또는 `phase`로 본다.
@ -350,6 +363,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
- 로컬 `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다.
- 필요한 경우에만 `ROADMAP.md`를 읽어 전체 Phase 흐름을 확인한다.
- Phase를 가로지르는 다음 작업 후보를 고르거나 큐 정리가 필요하면 `priority-queue.md`를 읽는다. 링크가 깨진 항목은 추측하지 말고 활성 `phase/*/milestones/*.md` 후보를 기준으로 재정렬 또는 재생성 대상으로 기록한다.
4. **스케치 승격 판단**
- `target-status=[계획]`, `mode=concretize`, 또는 사용자가 "구체화", "계획으로 올려"처럼 요청하면 `[스케치] -> [계획]` 승격 검토로 본다.
@ -361,6 +375,9 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
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`가 있는지 확인하고 없으면 추가한다.
- `PHASE.md`는 Phase 목표, 상태, Milestone 흐름, Phase 경계가 바뀔 때 수정한다.
@ -391,12 +408,16 @@ 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`가 비어 있는데 활성 실행 후보가 있으면 큐 동기화 필요로 보고한다. 실행 후보가 없으면 빈 큐를 허용한다.
- `ROADMAP.md`의 Phase 경로가 실제 `PHASE.md` 파일을 가리키는지 확인한다.
- 각 `PHASE.md`의 Milestone 경로가 실제 파일을 가리키는지 확인한다.
- 상태 표기가 표준값인지 확인한다.
@ -431,6 +452,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 변경된 Phase / Milestone / 상태
- 신규 작업의 삽입 단위와 배치 위치
- 자동 배치한 경우 비교한 후보와 선택 근거
- 전역 실행 순서 변경 사항
- 로컬 current.md 활성 창 변경 사항
- 완료 리뷰 상태와 남은 차단 항목
- `agent-ui 상태 반영: 대기`인 Milestone이면 agent-ui status 반영 여부와 validate-agent-ui 결과
@ -447,6 +469,7 @@ 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)
@ -466,6 +489,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 배치: <사용자 지정 위치 반영 | 자동 배치 위치와 근거 | 변경 없음>
- 배치 후보: <자동 배치 시 1순위/2순위 후보와 선택/제외 근거 | 해당 없음>
- 템플릿 보정: <ROADMAP | local current.md | PHASE | Milestone | 이미 일치 | 변경 없음>
- 전역 실행 순서: <변경 없음 | 생성 | 순서 조정 | archive/폐기 항목 제거 | 경로 갱신 | 재생성 필요>
- 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 잠금 차단 | 변경 없음>; 결정 필요: <없음 | 항목 요약>
- SDD gate: <불필요 | 필요-작성 전 | 필요-잠금 | 필요-사용자 리뷰 | 필요-승인됨 | 변경 없음>
- 승격 조건: <해당 없음 | 추가/수정/미충족 유지/충족 요약>
@ -489,6 +513,9 @@ 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 추적 대상으로 만들지 않는다.