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

This commit is contained in:
toki 2026-05-25 21:08:13 +09:00
parent acd4f5e354
commit fc41f03148
11 changed files with 93 additions and 30 deletions

View file

@ -1 +1 @@
1.1.53
1.1.54

View file

@ -40,13 +40,18 @@
## 상태 표기
- Phase와 Milestone 상태 표기는 `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- Phase와 Milestone 상태 표기는 `[스케치]`, `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- `[스케치]`는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 `agent-task` 구현 계획 생성과 코드 구현을 시작하지 않는다.
- `[스케치]` 항목은 `[계획]`으로 승격하기 위한 `승격 조건`, 사용자 결정, 범위 경계, 후속 Milestone 후보를 정리하는 것이 목적이다.
- `[계획]` 이상 상태의 Milestone에서 `승격 조건` 섹션은 선택 사항이다. 섹션이 없거나 `- 없음`이면 템플릿 오류로 보지 않는다.
- `[스케치]``[계획]`으로 전환하려면 `승격 조건`의 미정 항목이 해소되고, 목표, 범위, 완료 기준, 직접적인 사용자 결정 항목, 후속 구현 단위가 구현 계획을 만들 수 있을 만큼 정리되어야 한다.
- `[계획]`은 목표, 범위, 완료 기준, 구현 잠금, 결정 필요 항목이 정리되어 구현 계획을 만들 수 있는 상태다.
- 갱신 범위에 포함된 기존 진행 상태 표기는 `[진행중]`으로 정리한다.
- `[검토중]`은 모든 필수 작업과 완료 기준이 충족된 것으로 보이나, 사용자의 최종 완료 확인과 archive 승인이 아직 남은 완료 후보 상태다.
- `[검토중]` 항목은 활성 경로에 남기고 `current.md`의 활성 후보로 유지할 수 있다.
- 검토 결과 보완이 필요하면 별도 reopen 상태를 만들지 않고 `[진행중]`으로 되돌린 뒤 `완료 리뷰` 또는 `작업 컨텍스트`에 보완 방향을 남긴다.
- 검토 결과 보류 또는 폐기 결정이 나면 `[보류]` 또는 `[폐기]`로 전환한다.
- `ROADMAP.md`의 Phase 흐름과 `PHASE.md`의 Milestone 흐름은 완료, 검토중, 진행중, 계획 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
- `ROADMAP.md`의 Phase 흐름과 `PHASE.md`의 Milestone 흐름은 완료, 검토중, 진행중, 계획, 스케치 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
## 구현 잠금
@ -57,6 +62,7 @@
- 선택한 Milestone에 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 사용자에게 확인한다.
- 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 표준선으로 처리 가능한 작업을 막지 않는다.
- 잠금 상태를 바꾸더라도 `필수 기능`이나 `완료 기준`을 자동 완료 처리하지 않는다.
- `[스케치]` 상태의 Milestone은 `구현 잠금``해제`로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 `[계획]`으로 승격해야 한다.
## Epic과 Task id
@ -80,6 +86,7 @@
- 런타임 완료 이벤트가 최종 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에서 follow-up plan/review를 이어간다.
- `[스케치]` Milestone은 Milestone 기반 `agent-task` 생성 대상이 아니다. 런타임이나 plan 스킬은 이를 구현 작업으로 라우팅하지 않고 `[계획]` 승격 필요를 보고한다.
## 완료 리뷰

View file

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

View file

@ -11,7 +11,23 @@
## 상태
[<계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>]
[<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>]
## 승격 조건
<!--
[스케치] Milestone일 때만 필수다.
[스케치]에서는 [계획]으로 전환하기 위해 필요한 정의, 결정, 경계, 후속 구현 Milestone 후보를 체크리스트로 적는다.
[계획] 이상 상태에서는 이 섹션을 생략하거나 아래처럼 `- 없음`으로 둔다.
-->
- 없음
<!-- [스케치] 예시:
- [ ] 구현 가능한 목표와 범위를 확정한다.
- [ ] 사용자만 결정할 제품/우선순위/책임 경계를 정리한다.
- [ ] 완료 기준과 후속 구현 Milestone 후보를 나눈다.
-->
## 구현 잠금

View file

@ -2,7 +2,7 @@
## 상태
[<계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>]
[<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>]
## 목표
@ -10,10 +10,11 @@
## Milestone 흐름
완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획 또는 보류 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다.
완료, 검토중, 진행중, 계획 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획, 스케치 또는 보류 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다.
완료, 검토중, 진행중, 계획, 스케치 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
스케치 Milestone은 아직 구현 가능한 계획이 아니므로 계획 Milestone보다 아래에 둔다.
- [<계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] <Milestone 이름>
- [<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] <Milestone 이름>
- 경로: `agent-ops/roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md` 또는 `agent-ops/roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md`
- 요약: <목표 또는 결과 1문장>

View file

@ -7,6 +7,7 @@
- 우선순위 추천: <단일 후보 | 1순위: phase/milestone; 2순위: phase/milestone; 추천 근거>
- 신뢰도: <높음 | 중간 | 낮음>
- 구현 잠금: <해제 | 잠금 | 정보 없음>
- 승격 조건: <없음 | [스케치] 항목의 [계획] 전환 조건 요약 | 정보 없음; [계획] 이상에서 섹션이 없으면 없음>
- 완료 리뷰: <없음 | 요청됨 | 보완 필요 | 승인됨 | 보류 | 폐기 | 정보 없음>
- 결정 필요: <없음 | 현재 요청에 직접 영향을 주는 사용자 결정 항목 요약>
- 한 줄 결론: <현재 작업 지점과 가장 중요한 다음 판단을 1문장으로 요약>

View file

@ -8,9 +8,10 @@
위에서 아래로 진행된 순서와 예정 흐름을 나타낸다.
완료된 Phase도 로드맵에서 제거하지 않고, archive의 Phase 문서로 연결한다.
검토중 또는 진행중 Phase는 계획 Phase보다 위에 두어, 아래로 갈수록 미래 계획에 가까워지게 정렬한다.
검토중 또는 진행중 Phase는 계획 Phase보다 위에 두어, 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
스케치 Phase는 아직 구현 가능한 계획이 아니므로 계획 Phase보다 아래에 둔다.
- [<계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] <Phase 이름>
- [<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] <Phase 이름>
- 경로: `agent-ops/roadmap/phase/<phase-slug>/PHASE.md` 또는 `agent-ops/roadmap/archive/phase/<phase-slug>/PHASE.md`
- 요약: < Phase의 목표와 역할 1문장>
@ -27,6 +28,8 @@
- 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다.
- 상세 작업과 완료 기준은 각 Milestone 문서의 `필수 기능`, `완료 기준`으로 관리한다.
- `[스케치]` Phase/Milestone은 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태이며 구현 계획 생성 대상이 아니다.
- `[스케치]` 항목은 `승격 조건`을 정리해 `[계획]`으로 전환한 뒤 구현 계획을 만든다.
- 모든 필수 작업과 완료 기준이 충족된 Milestone은 먼저 `[검토중]`으로 두고, 사용자 완료 확인과 archive 승인을 받은 뒤 `[완료]`로 전환한다.
- 완료된 Phase는 `agent-ops/roadmap/archive/phase/<phase-slug>/PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 `agent-ops/roadmap/archive/phase/<phase-slug>/milestones/`로 이동한다.

View file

@ -1,6 +1,6 @@
---
name: analyze-roadmap-position
version: 1.9.0
version: 1.9.1
description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확인 요청에 대해 로드맵이 있으면 활성 Phase/Milestone과 코드 상태를 함께 읽고, 로드맵이 없으면 git/active task 기준으로 현재 작업 지점과 남은 일을 추정하는 읽기 전용 스킬"
---
@ -41,7 +41,7 @@ Milestone의 `필수 기능`에 Epic/Task id가 있으면 남은 작업과 판
- `agent-ops/roadmap/current.md`를 읽고 활성 Phase, 활성 Milestone 후보와 선택 규칙을 파악한다.
- `current.md`의 후보가 `agent-ops/roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 로드맵 갱신 필요 항목으로 기록한다.
- 관련 활성 Phase 문서를 읽고 Phase 목표, Milestone 흐름, Phase 경계를 확인한다.
- 관련 활성 Milestone 문서를 읽고 목표, 범위, 필수 기능, 완료 기준, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다.
- 관련 활성 Milestone 문서를 읽고 목표, 상태, 승격 조건, 범위, 필수 기능, 완료 기준, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. `승격 조건``[스케치]`에서만 필수이며, `[계획]` 이상에서 섹션이 없으면 `없음`으로 본다.
- 목록이 많으면 사용자 요청이나 변경 파일과 관련 높은 Phase/Milestone부터 읽는다.
- `current.md` 형식이 맞지 않으면 `ROADMAP.md`를 자동으로 읽지 말고 로드맵 컨텍스트 불확실성을 보고한다.
@ -60,7 +60,7 @@ Milestone의 `필수 기능`에 Epic/Task id가 있으면 남은 작업과 판
- 하나의 Milestone에 명확히 속하면 단일 후보로 보고한다.
- 둘 이상의 Phase 또는 Milestone에 걸치면 복수 후보로 보고하고, 어떤 파일이나 기능이 어느 후보에 닿는지 나눈다.
- 복수 후보일 때는 후보 우선순위를 추천한다. 요청 문장/변경 파일 직접성, 현재 diff 근거, Milestone 상태, 구현 잠금, 선후 의존성, Phase/Milestone 흐름상 위치를 함께 본다.
- 관련성이 비슷하면 `[검토중]` 후보는 리뷰/승인 요청에서 우선하고, 구현 작업 요청에서는 `[진행중]` 후보를 `[계획]` 후보보다 우선한다. 같은 상태라면 현재 변경 파일을 더 많이 설명하는 후보를 우선한다.
- 관련성이 비슷하면 `[검토중]` 후보는 리뷰/승인 요청에서 우선하고, 구현 작업 요청에서는 `[진행중]` 후보를 `[계획]` 후보보다 우선한다. `[스케치]` 후보는 구현 작업보다 컨셉 보강/계획 승격 요청에서 우선한다. 같은 상태라면 현재 변경 파일을 더 많이 설명하는 후보를 우선한다.
- 사용자가 특정 Phase, Milestone, epic-id, item-id, 파일 경로를 명시했으면 그 후보를 우선하되, 범위 제외나 잠금 결정 필요가 있으면 우선순위 근거에 같이 적는다.
- 로드맵이 있고 활성 Phase/Milestone 밖으로 보이면 `ROADMAP.md`의 Phase 흐름을 확인하고 전환 또는 신규 Phase/Milestone 필요성을 제안한다.
@ -87,6 +87,8 @@ Milestone의 `필수 기능`에 Epic/Task id가 있으면 남은 작업과 판
- [ ] 로드맵이 있는 프로젝트에서 `current.md`만 근거로 현재 위치를 단정하지 않았는가
- [ ] 로드맵이 있는 프로젝트에서 활성 Phase 문서의 목표와 Phase 경계를 확인했는가
- [ ] 로드맵이 있는 프로젝트에서 활성 Milestone 문서의 목표와 범위 제외 항목을 확인했는가
- [ ] 로드맵이 있는 프로젝트에서 `[스케치]` Phase/Milestone의 승격 조건과 구현 계획 금지 여부를 확인했는가
- [ ] `[계획]` 이상 Milestone에 `승격 조건` 섹션이 없어도 템플릿 문제로 보고하지 않았는가
- [ ] 로드맵이 있는 프로젝트에서 활성 Milestone 문서의 `완료 리뷰` 섹션과 `[검토중]` 상태 여부를 확인했는가
- [ ] `agent-ops/roadmap/archive/**` 문서를 명시 요청 없이 읽지 않았는가
- [ ] 로드맵이 있는 프로젝트에서 활성 Milestone 문서의 `구현 잠금` 섹션 존재 여부, 상태, `결정 필요` 항목을 확인했는가

View file

@ -1,6 +1,6 @@
---
name: create-roadmap
version: 1.12.0
version: 1.13.1
description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하는 공통 스킬
---
@ -52,7 +52,7 @@ agent-ops/
| `agent-ops/roadmap/ROADMAP.md` | 전체 목표와 Phase 흐름만 담는 최상위 지도. 로드맵 생성/갱신/Phase 전환 때만 읽는다 |
| `agent-ops/roadmap/current.md` | 활성 Phase와 활성 Milestone 후보, 선택 규칙을 담는 얇은 포인터 |
| `agent-ops/roadmap/phase/<phase-slug>/PHASE.md` | Phase 목표, 상태, Milestone 흐름, Phase 경계를 담는 문서 |
| `agent-ops/roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md` | 일반 작업 시 읽는 Milestone 단위 목표, 구현 잠금, 범위, Epic/Task 체크리스트, 완료 기준, 범위 제외 항목 |
| `agent-ops/roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md` | 일반 작업 시 읽는 Milestone 단위 목표, 스케치 승격 조건, 구현 잠금, 범위, Epic/Task 체크리스트, 완료 기준, 범위 제외 항목 |
| `agent-ops/roadmap/archive/phase/<phase-slug>/...` | 완료 또는 폐기되어 현재 후보에서 제외한 과거 Phase/Milestone. 일반 작업에서는 읽지 않는다 |
## 템플릿
@ -68,7 +68,9 @@ agent-ops/
## 작성 규칙
- 기본 작성 언어는 한국어다.
- 상태 표기는 `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- 상태 표기는 `[스케치]`, `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- `[스케치]`는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 구현 계획 생성 대상이 아니다.
- `[계획]`은 목표, 범위, 완료 기준, 구현 잠금, 결정 필요 항목이 정리되어 구현 계획을 만들 수 있는 상태다.
- Phase와 Milestone 이름, 파일명에는 `1`, `2`, `M01`, `P1` 같은 순번을 붙이지 않는다.
- 진행 순서는 `ROADMAP.md`와 각 `PHASE.md`의 위에서 아래 순서로 표현한다.
- Phase 파일명은 `agent-ops/roadmap/phase/<phase-slug>/PHASE.md`로 만든다.
@ -78,8 +80,11 @@ agent-ops/
## Milestone 작성 규칙
- Milestone 표준 섹션은 `위치`, `목표`, `상태`, `구현 잠금`, `범위`, `필수 기능`, `완료 기준`, `완료 리뷰`, `범위 제외`, `작업 컨텍스트`다.
- Milestone 기본 섹션은 `위치`, `목표`, `상태`, `구현 잠금`, `범위`, `필수 기능`, `완료 기준`, `완료 리뷰`, `범위 제외`, `작업 컨텍스트`다.
- `승격 조건``[스케치]` Milestone에서 필수다. `[계획]` 이상 상태에서는 섹션을 생략하거나 `- 없음`으로 둘 수 있다.
- `[스케치]` Milestone은 `승격 조건`을 체크리스트로 작성하고, `[계획]`으로 전환하기 위해 필요한 정의, 결정, 경계, 후속 구현 Milestone 후보를 적는다.
- 새 Milestone은 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 `구현 잠금``잠금`으로 둔다.
- 새 `[스케치]` Milestone은 `구현 잠금``잠금`으로 둔다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다.
- `구현 잠금`에는 상태와 `결정 필요` 체크리스트만 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적는다.
- `필수 기능`은 Epic heading과 Task 체크리스트로 작성한다.
@ -119,7 +124,7 @@ agent-ops/
4. **파일 생성**
- `ROADMAP.md`, `current.md`, 각 Phase의 `PHASE.md`, 각 Milestone 문서를 템플릿 순서대로 생성한다.
- 활성 Phase와 활성 Milestone은 `current.md`에 모두 기록한다.
- `ROADMAP.md`의 Phase 흐름에는 완료/검토중/진행중/계획 Phase 모두를 위에서 아래 순서로 두고, 계획 Phase는 진행중 Phase보다 아래에 둔다.
- `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/`만 둘 수 있다.
@ -129,6 +134,7 @@ agent-ops/
- `current.md` 활성 항목에 `agent-ops/roadmap/archive/**` 경로가 없는지 확인한다.
- Epic heading과 Task 체크리스트 id가 형식을 따르는지 확인한다.
- 상태 표기가 `[진행중]`처럼 공백 없는 표준값인지 확인한다.
- `[스케치]` Milestone에 `승격 조건` 섹션이 있고 `구현 잠금``잠금`인지 확인한다.
- Milestone 문서에 `완료 리뷰` 섹션이 있는지 확인한다.
## 출력 형식

View file

@ -124,7 +124,8 @@ The routed plan file is the loop entry point. A missing active plan normally mea
- `agent-ops/roadmap/current.md`가 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다.
- `current.md``agent-ops/roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 활성 Phase/Milestone이 아니라고 보고한다.
- 선택한 Phase를 한 번 읽어 Phase 목표, Milestone 흐름, Phase 경계를 확인한다.
- 선택한 Milestone을 한 번 읽어 목표, 범위, 필수 기능, 완료 기준, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인하고, 그 결정 없이는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, file/API/package 수준 구현 단계를 확정하지 않는다.
- 선택한 Milestone을 한 번 읽어 목표, 상태, 승격 조건, 범위, 필수 기능, 완료 기준, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. `승격 조건``[스케치]`에서만 필수이며, `[계획]` 이상에서 섹션이 없으면 `없음`으로 본다. `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인하고, 그 결정 없이는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, file/API/package 수준 구현 단계를 확정하지 않는다.
- 선택한 Phase 또는 Milestone 상태가 `[스케치]`이면 구현 계획 파일을 만들지 않는다. `[스케치]`는 컨셉 상태이므로 `update-roadmap`의 concretize 흐름으로 승격 조건, 결정 필요, 범위, 완료 기준을 정리해 `[계획]`으로 전환해야 한다고 보고한다.
- Phase 또는 Milestone 후보가 여럿이면 요청 문장, 변경 경로 직접성, Milestone 상태, 구현 잠금, 선후 의존성, Phase/Milestone 흐름상 위치를 기준으로 1순위와 2순위를 추천하고 필요한 후보 문서만 읽어 범위를 좁힌다.
- 로드맵 current가 있고 활성 Phase/Milestone 밖 작업이면 `ROADMAP.md`의 Phase 흐름을 확인하고 전환, 신규 Phase/Milestone, 또는 기존 활성 범위 내 배치 필요성을 보고한다.
- 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조, 도메인 rule, 플랫폼 관례로 정할 수 있는 세부는 표준선/가정으로 계획에 기록하고 진행할 수 있다.

View file

@ -1,6 +1,6 @@
---
name: update-roadmap
version: 1.17.0
version: 1.18.1
description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, 승인된 archive 이동을 처리한다.
---
@ -38,6 +38,7 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `필수
- `new-feature`: 추가할 기능, 작업, 또는 새 Milestone 설명 (선택)
- `placement`: 새 작업 배치 위치. 예: `<phase-name> 안`, `<milestone-name> 안`, `<epic-id> 아래`, `<item-id> 앞`, `<item-id> 뒤`, `auto` (선택)
- `placement-unit`: 삽입 단위. `phase` / `milestone` / `epic` / `task` / `subtask` / `auto` 중 하나 (선택)
- `target-status`: 전환할 Phase/Milestone 상태. `[스케치]` / `[계획]` / `[진행중]` / `[검토중]` / `[완료]` / `[보류]` / `[폐기]` 중 하나 (선택)
- `lock-state`: Milestone 구현 잠금 상태. `잠금` / `해제` 중 하나 (선택)
- `decision-needed`: `구현 잠금`에 남길 사용자만 결정할 수 있는 질문 목록 (선택)
- `evidence`: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택)
@ -78,12 +79,17 @@ agent-ops/roadmap/
## 상태와 id
- 상태 표기는 `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- 상태 표기는 `[스케치]`, `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다.
- 기존 비표준 상태 표기는 갱신 범위에 포함될 때 표준 상태 표기로 정리한다.
- `[스케치]`는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 `agent-task` 구현 계획 생성과 코드 구현 대상으로 삼지 않는다.
- `[스케치]` 항목은 `[계획]`으로 승격하기 위한 `승격 조건`, 사용자 결정, 범위 경계, 후속 Milestone 후보를 정리한다.
- `[계획]` 이상 Milestone에서 `승격 조건` 섹션은 선택 사항이다. 섹션이 없거나 `- 없음`이면 템플릿 오류로 보지 않는다.
- `[스케치]``[계획]`으로 전환할 때는 `승격 조건`의 미정 항목이 해소되고, 목표, 범위, 완료 기준, 직접적인 사용자 결정 항목, 후속 구현 단위가 구현 계획을 만들 수 있을 만큼 정리되었는지 확인한다.
- `[계획]`은 목표, 범위, 완료 기준, 구현 잠금, 결정 필요 항목이 정리되어 구현 계획을 만들 수 있는 상태다.
- `[검토중]`은 모든 필수 작업과 완료 기준이 충족된 것으로 보이나, 사용자 최종 확인과 archive 승인이 남은 완료 후보 상태다.
- 검토 결과 보완이 필요하면 별도 reopen 상태를 만들지 않고 `[진행중]`으로 되돌린 뒤 `완료 리뷰` 또는 `작업 컨텍스트`에 보완 방향을 남긴다.
- 검토 결과 보류 또는 폐기 결정이 나면 `[보류]` 또는 `[폐기]`로 전환한다.
- `ROADMAP.md`의 Phase 흐름과 `PHASE.md`의 Milestone 흐름은 완료, 검토중, 진행중, 계획 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
- `ROADMAP.md`의 Phase 흐름과 `PHASE.md`의 Milestone 흐름은 완료, 검토중, 진행중, 계획, 스케치 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
- Epic heading은 `### Epic: [epic-id] <이름>` 형식으로 작성한다.
- Task는 `- [ ] [item-id] 설명` 또는 `- [x] [item-id] 설명` 형식으로 작성한다.
- epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 해당 Milestone 안에서만 유일하면 된다.
@ -111,6 +117,7 @@ agent-ops/roadmap/
- 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 `결정 필요`가 아니라 `작업 컨텍스트`의 표준선으로 기록한다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다.
- 잠금 상태 변경은 Milestone 완료 판정이 아니므로 `필수 기능``완료 기준`을 자동 완료 처리하지 않는다.
- `[스케치]` Milestone은 `구현 잠금``해제`로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 승격 조건을 충족해 `[계획]`으로 전환한다.
## 완료 리뷰와 검토중 상태
@ -130,6 +137,7 @@ agent-ops/roadmap/
- target이 없거나 둘 이상이면 Milestone 내용을 추정해 수정하지 말고 target 불명확으로 보고한다.
- target이 확정되면 PASS evidence, `complete.log`, final archive path, archived plan/review log 경로, code-review 결과 요약을 근거로 해당 Milestone의 Epic/Task와 완료 기준을 갱신한다. target routing 자체는 완료 이벤트의 `m-<milestone-slug>` task group으로만 결정한다.
- 갱신 후 필수 Epic/Task와 완료 기준이 모두 충족되면 `[검토중]` 전환과 `완료 리뷰` 요청 규칙을 적용한다.
- target Milestone이 `[스케치]`이면 완료 이벤트를 반영하지 말고 상태 불일치로 보고한다. `[스케치]`는 Milestone 기반 `agent-task` 완료 이벤트의 target이 될 수 없다.
## 삽입 단위 정책
@ -143,13 +151,15 @@ agent-ops/roadmap/
| 작업 컨텍스트/TODO | 사용자 결정 또는 조사/확인이 먼저 필요해 필수 기능으로 확정하기 어렵다 |
- 먼저 요청 내용의 규모를 판정한다. 배치 위치를 찾기 전에 `phase`, `milestone`, `epic`, `task`, `subtask`, `context` 중 가장 작은 충분한 단위를 고른다.
- 요청이 방향성, 문제의식, 컨셉, 운영 원칙 수준이고 완료 기준이나 실행 범위가 아직 부족하면 새 항목의 상태는 `[스케치]`로 둔다.
- `[스케치]` Phase/Milestone을 만들 때는 `승격 조건``[계획]`으로 전환하기 위해 필요한 정의, 결정, 경계, 후속 구현 Milestone 후보를 체크리스트로 남긴다.
- 가장 작은 충분한 단위 원칙을 따른다. 애매하면 새 Phase나 새 Milestone으로 키우지 말고, 기존 Milestone의 Epic/Task에 넣을 수 있는지 먼저 확인한다.
- 위치 지정이 있으면 anchor의 레벨을 먼저 확인한다.
- `<epic-id> 아래`는 해당 Epic 아래 Task로 넣는다.
- `<item-id> 앞/뒤`는 같은 Epic 안의 형제 Task로 넣는다.
- `<item-id> 아래`는 해당 Task의 하위 작업으로 넣는다.
- `<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은 리뷰 보완 요청이 아닌 신규 작업의 기본 배치 대상으로 삼지 않는다.
@ -167,6 +177,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
2. **규모 판정**
- 여러 Milestone을 묶는 제품/운영 단계면 Phase 규모다.
- 독립 목표, 별도 완료 기준, 여러 Epic이 필요한 결과면 Milestone 규모다.
- 컨셉은 충분히 크지만 구현 가능한 목표/범위/완료 기준이 아직 없으면 `[스케치]` Phase 또는 Milestone 후보로 둔다.
- 한 Milestone 안의 capability 묶음이면 Epic 규모다.
- Epic 아래에서 완료 가능한 단일 capability, 산출물, 검증 항목이면 Task 규모다.
- Task를 완성하기 위한 구현 세부면 subtask 규모다.
@ -228,18 +239,27 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- `current.md`의 활성 Phase와 활성 Milestone 후보를 확인한다.
- target이 명시된 경우 대상 Phase의 `PHASE.md`를 읽고 Milestone 흐름과 Phase 경계를 확인한다.
- target이 없거나 활성 창 밖 배치 가능성이 있으면 `ROADMAP.md`의 Phase 흐름을 확인하고, 관련성이 높은 Phase 문서를 읽는다.
- 대상 또는 후보 Milestone 문서의 목표, 범위, 필수 기능, 완료 기준, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다.
- 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 필수 기능, 완료 기준, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다.
- Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
- `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다.
- 필요한 경우에만 `ROADMAP.md`를 읽어 전체 Phase 흐름을 확인한다.
4. **변경 내용 작성**
4. **스케치 승격 판단**
- `target-status=[계획]`, `mode=concretize`, 또는 사용자가 "구체화", "계획으로 올려"처럼 요청하면 `[스케치] -> [계획]` 승격 검토로 본다.
- 대상이 `[스케치]`가 아니면 일반 상태 갱신이나 Milestone 갱신으로 처리한다.
- 대상이 `[스케치]`이면 `승격 조건`, `구현 잠금`, `목표`, `범위`, `완료 기준`, `필수 기능`, `작업 컨텍스트`를 확인한다.
- `승격 조건` 체크리스트가 남아 있거나 구현 계획에 직접 필요한 사용자 결정이 남아 있으면 상태를 `[스케치]`로 유지하고, 부족한 항목을 `승격 조건` 또는 `결정 필요`에 보강한다.
- 구현 가능한 목표, 범위, 완료 기준, 직접 결정 항목, 후속 구현 단위가 정리되면 상태를 `[계획]`으로 전환하고, `승격 조건`은 충족 요약으로 남기거나 `- 없음`으로 정리한다.
- 승격은 구현 완료가 아니므로 `필수 기능``완료 기준`을 자동 완료 처리하지 않는다.
5. **변경 내용 작성**
- `ROADMAP.md`는 전체 목표, Phase 흐름, 로딩 정책이 바뀔 때만 수정한다.
- `current.md`는 활성 Phase/Milestone 창이 바뀔 때 수정한다.
- `PHASE.md`는 Phase 목표, 상태, Milestone 흐름, Phase 경계가 바뀔 때 수정한다.
- Milestone 문서는 목표, 상태, 구현 잠금, 범위, Epic/Task, 완료 기준, 완료 리뷰, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
- Milestone 문서는 목표, 상태, 승격 조건, 구현 잠금, 범위, Epic/Task, 완료 기준, 완료 리뷰, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
- 동일/유사 후보가 있으면 기존 항목을 업데이트하고 중복 항목을 만들지 않는다.
- 새 Milestone은 해당 Phase의 `milestones/` 아래에 만든다.
- 새 `[스케치]` Milestone은 `승격 조건` 섹션을 포함하고 `구현 잠금``잠금`으로 둔다.
- 새 Epic은 `필수 기능` 아래 `### Epic: [epic-id] <이름>`으로 만든다.
- 새 Task는 관련 Epic 아래 `- [ ] [item-id] 설명`으로 만든다.
- 새 항목은 레벨별 탐색에서 적절한 기존 후보가 없을 때만 만든다.
@ -248,13 +268,16 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- `[검토중]` 전환만으로 archive 이동, `current.md` 제거, archive 링크 변경을 수행하지 않는다.
- 사용자 승인 근거가 있으면 `[검토중]``[완료]`로 전환하고 archive 모드를 수행할 수 있다.
5. **검증**
6. **검증**
- `current.md`의 활성 Phase/Milestone 경로가 실제 파일을 가리키는지 확인한다.
- `current.md`의 활성 항목이 archive 경로를 가리키지 않는지 확인한다.
- `current.md`의 활성 항목이 `[완료]` 또는 `[폐기]` 상태로 남아 있지 않은지 확인한다.
- `ROADMAP.md`의 Phase 경로가 실제 `PHASE.md` 파일을 가리키는지 확인한다.
- 각 `PHASE.md`의 Milestone 경로가 실제 파일을 가리키는지 확인한다.
- 상태 표기가 표준값인지 확인한다.
- `[스케치]` Milestone에 `승격 조건`이 있고 `구현 잠금``잠금`인지 확인한다.
- `[계획]` 이상 Milestone에 `승격 조건` 섹션이 없더라도 오류로 보지 않는다. 섹션이 있으면 `- 없음` 또는 승격 충족 요약인지 확인한다.
- `[스케치] -> [계획]` 전환을 수행했다면 승격 조건 해소 근거가 Milestone 내용이나 결과 보고에 남았는지 확인한다.
- `[검토중]` Milestone이 archive 경로로 이동되지 않았는지 확인한다.
- 필수 Epic/Task와 완료 기준이 모두 `[x]`인 Milestone에는 `완료 리뷰` 섹션과 사용자 리뷰 요청이 있는지 확인한다.
- Epic heading과 Task id 형식이 맞는지 확인한다.
@ -263,7 +286,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 자동 배치한 신규 작업이면 선택한 후보와 밀린 후보의 근거가 결과 보고에 포함되는지 확인한다.
- `git diff --check`로 공백 오류를 확인한다.
6. **결과 보고**
7. **결과 보고**
- 수정한 파일 목록
- 요청 규모 판정과 근거
- Phase -> Milestone -> Epic -> Task 탐색 경로와 후보
@ -302,6 +325,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
- 배치 후보: <자동 배치 1순위/2순위 후보와 선택/제외 근거 | 해당 없음>
- 템플릿 보정: <ROADMAP | current.md | PHASE | Milestone | 이미 일치 | 변경 없음>
- 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>; 결정 필요: <없음 | 항목 요약>
- 승격 조건: <해당 없음 | 추가/수정/미충족 유지/충족 요약>
- 완료 리뷰: <변경 없음 | 요청됨 | 승인됨 | 보완 필요 | 보류 | 폐기>
- runtime m-task 라우팅: <해당 없음 | origin-task -> target Milestone | target 불명확>
- 활성 항목: <변경 없음 | Phase/Milestone 추가/제거 요약>