nomadcode/agent-ops/rules/common/rules-roadmap.md

로드맵 규칙

agent-ops/roadmap/ 디렉터리가 있는 프로젝트에서만 적용한다.

구조

• 최상위 로드맵은 agent-ops/roadmap/ROADMAP.md다.
• 활성 Phase는 agent-ops/roadmap/phase/<phase-slug>/PHASE.md에 둔다.
• 활성 Milestone은 해당 Phase 아래 agent-ops/roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md에 둔다.
• <phase-slug>와 <milestone-slug>는 소문자 영문, 숫자, 하이픈만 사용한다.
• 완료된 Phase는 scaffold 그대로 agent-ops/roadmap/archive/phase/<phase-slug>/PHASE.md로 이동하고, 하위 Milestone도 archive/phase/<phase-slug>/milestones/ 아래에 둔다.
• 진행중 Phase 안에서 완료된 Milestone은 활성 PHASE.md에 짧은 archive 링크를 남기고, 상세 문서는 agent-ops/roadmap/archive/phase/<phase-slug>/milestones/로 이동한다.
• archive PHASE.md는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 milestones/만 있을 수 있다.

로딩

• 세션 최초 1회 agent-ops/roadmap/current.md를 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다.
• 일반 작업에서는 ROADMAP.md를 읽지 않는다.
• 일반 작업에서는 agent-ops/roadmap/archive/**를 읽지 않는다.
• 기능 추가, 구조 변경, 구현 계획, 현재 작업 분석 전에는 요청과 변경 파일에 맞는 활성 Phase와 활성 Milestone 문서를 읽는다.
• ROADMAP.md는 로드맵 생성/갱신, Phase 추가/삭제/전환, 전체 구조 변경, 활성 범위 밖 작업 확인 때만 읽는다.
• 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 ROADMAP.md 또는 PHASE.md에 있는 archive 링크를 따라가서 필요한 archive 문서만 읽는다.

Phase와 Milestone 선택

• current.md는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
• 활성 Phase는 agent-ops/roadmap/phase/**/PHASE.md만 대상으로 한다.
• 활성 Milestone은 agent-ops/roadmap/phase/**/milestones/*.md만 대상으로 한다.
• current.md에는 [완료] 또는 [폐기] Phase/Milestone을 남기지 않는다. 완료 후보는 승인 전까지 [검토중]으로 둔다.
• "로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 update-roadmap 스킬로 처리하고, Phase/Milestone/Epic/Task 배치를 자동 판단한다.
• target 없는 신규 추가 요청은 먼저 요청 규모를 phase, milestone, epic, task, subtask, context 중 가장 작은 충분한 단위로 판정한다.
• target 없는 신규 추가 요청은 활성 창만으로 결정하지 말고 필요한 경우 ROADMAP.md의 Phase 흐름과 관련 Phase/Milestone 문서를 비교한다.
• 배치는 Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
• 동일/유사 항목이 이미 있으면 새로 만들지 말고 기존 항목을 업데이트한다.
• 적절한 기존 후보가 없을 때만 판정한 규모에 맞는 새 항목을 만든다.
• 부모 후보는 있고 판정 규모의 항목만 없으면 부모 아래에 새 항목을 만들고, 부모도 없을 때만 필요한 부모 항목을 함께 만든다.
• 자동 배치할 때는 선택한 Phase/Milestone/Epic/Task와 밀린 후보의 이유를 결과에 남긴다.
• current.md가 아카이브 경로를 가리키면 해당 항목은 활성 후보로 읽지 말고 로드맵 갱신이 필요하다고 보고한다.
• 선택한 Phase/Milestone의 목표 또는 범위 제외와 요청이 충돌하면 구현 전에 사용자에게 확인한다.

상태 표기

• Phase와 Milestone 상태 표기는 [스케치], [계획], [진행중], [검토중], [완료], [보류], [폐기] 중 하나만 사용한다.
• [스케치]는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 agent-task 구현 계획 생성과 코드 구현을 시작하지 않는다.
• [스케치] 항목은 [계획]으로 승격하기 위한 승격 조건, 사용자 결정, 범위 경계, 후속 Milestone 후보를 정리하는 것이 목적이다.
• [계획] 이상 상태의 Milestone에서 승격 조건 섹션은 선택 사항이다. 섹션이 없거나 - 없음이면 템플릿 오류로 보지 않는다.
• [스케치]를 [계획]으로 전환하려면 승격 조건의 미정 항목이 해소되고, 목표, 범위, 완료 기준, 직접적인 사용자 결정 항목, 후속 구현 단위가 구현 계획을 만들 수 있을 만큼 정리되어야 한다.
• [계획]은 목표, 범위, 완료 기준, 구현 잠금, 결정 필요 항목이 정리되어 구현 계획을 만들 수 있는 상태다.
• 갱신 범위에 포함된 기존 진행 상태 표기는 [진행중]으로 정리한다.
• [검토중]은 모든 필수 작업과 완료 기준이 충족된 것으로 보이나, 사용자의 최종 완료 확인과 archive 승인이 아직 남은 완료 후보 상태다.
• [검토중] 항목은 활성 경로에 남기고 current.md의 활성 후보로 유지할 수 있다.
• 검토 결과 보완이 필요하면 별도 reopen 상태를 만들지 않고 [진행중]으로 되돌린 뒤 완료 리뷰 또는 작업 컨텍스트에 보완 방향을 남긴다.
• 검토 결과 보류 또는 폐기 결정이 나면 [보류] 또는 [폐기]로 전환한다.
• ROADMAP.md의 Phase 흐름과 PHASE.md의 Milestone 흐름은 완료, 검토중, 진행중, 계획, 스케치 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.

구현 잠금

• 구현 잠금은 승인 의식이 아니라 사용자 결정이 필요한지 표시하는 얇은 상태다.
• 제품 방향, 범위, 우선순위, 책임 경계처럼 사용자만 결정할 수 있는 항목이 남아 있으면 상태를 잠금으로 두고 결정 필요 체크리스트에 질문을 적는다.
• 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 결정 필요가 아니라 작업 컨텍스트의 표준선이나 구현 가정으로 기록한다.
• Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 해제로 둔다.
• 선택한 Milestone에 구현 잠금 섹션이 없거나 상태가 잠금이면 코드 구현, agent-task 구현 계획, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 결정 필요 항목만 사용자에게 확인한다.
• 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 표준선으로 처리 가능한 작업을 막지 않는다.
• 잠금 상태를 바꾸더라도 필수 기능이나 완료 기준을 자동 완료 처리하지 않는다.
• [스케치] 상태의 Milestone은 구현 잠금이 해제로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 [계획]으로 승격해야 한다.

Epic과 Task id

• Milestone 문서의 필수 기능은 Epic heading과 Task 체크리스트로 작성한다.
• Epic heading은 ### Epic: [epic-id] <이름> 형식을 사용한다.
• Task는 - [ ] [item-id] 설명 또는 - [x] [item-id] 설명 형식을 사용한다.
• epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 영문/숫자 segment 14개로 작성하고 segment 구분자는 -, _, +, =만 사용한다. 가능하면 13 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
• epic-id와 item-id는 해당 Milestone 안에서만 유일하면 된다.
• 다른 Milestone에서는 같은 id를 다시 사용할 수 있다. 여러 Milestone 후보에서 같은 id가 발견되면 Milestone 이름이나 문서 경로로 대상을 확정한다.
• 사용자가 epic-id 또는 item-id를 언급하면 해당 Milestone의 Epic/Task 항목을 우선 anchor로 삼고, 기존 id는 명시적 요청 없이 바꾸지 않는다.

Milestone 기반 agent-task

• plan 스킬이 활성 Milestone 범위의 구현 계획을 만들면 task group은 agent-task/m-<milestone-slug>/ 형식을 사용한다.
• <milestone-slug>는 활성 Milestone 파일명에서 .md를 제거한 값이며, Phase slug, Epic id, Task id, 별도 task slug를 task group에 넣지 않는다.
• split 작업은 기존 규칙 그대로 agent-task/m-<milestone-slug>/<subtask_dir>/ 아래에 둔다.
• 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>를 판별하고, 상태 체크 후 update-roadmap 흐름으로 Milestone 업데이트를 호출한다.
• 런타임 완료 이벤트가 최종 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를 이어가지만, code-review의 user-review gate가 트리거되면 USER_REVIEW.md를 남기고 사용자 판단을 기다린다.
• [스케치] Milestone은 Milestone 기반 agent-task 생성 대상이 아니다. 런타임이나 plan 스킬은 이를 구현 작업으로 라우팅하지 않고 [계획] 승격 필요를 보고한다.

완료 리뷰

• Task 완료나 Milestone 갱신 시 필수 Epic/Task와 완료 기준이 모두 evidence와 함께 [x]가 되었는지 확인한다.
• 모두 충족된 것으로 보이면 Milestone을 [완료]로 바로 바꾸거나 archive로 이동하지 말고 [검토중]으로 바꾼다.
• [검토중]으로 바꿀 때는 Milestone 문서에 완료 리뷰 섹션을 만들거나 갱신하고, 완료 근거 1~3줄과 사용자에게 필요한 최종 확인 항목을 남긴다.
• 사용자가 완료를 승인한 뒤에만 [완료]로 전환하고 archive 이동을 수행한다.
• Phase도 모든 하위 Milestone이 [완료] 또는 [폐기]로 정리되어 Phase 완료 후보가 되면 [검토중]으로 두고 사용자 최종 확인을 받은 뒤 [완료] 또는 [폐기]로 전환한다.

작업 지점 분석

• 현재 작업 지점이나 남은 작업 분석 요청은 analyze-roadmap-position 스킬로 처리한다.
• 분석 답변은 agent-ops/skills/common/_templates/roadmap-position-report-template.md 섹션과 필드 순서를 따른다.
• 이때 current.md만으로 단정하지 말고 코드, git 상태, diff, 활성 Phase, 활성 Milestone 문서를 함께 본다.
• Phase 또는 Milestone 후보가 여럿이면 단순 나열하지 말고 1순위와 2순위를 추천하고 근거를 함께 제시한다.

아카이브

• 완료 또는 폐기되어 현재 작업 후보에서 제외할 Phase/Milestone은 update-roadmap 스킬로 아카이빙한다.
• [검토중] Phase/Milestone은 archive 대상이 아니며, 사용자 승인 전까지 활성 경로에 남긴다.
• Phase 아카이브 대상은 agent-ops/roadmap/archive/phase/<phase-slug>/PHASE.md와 같은 scaffold로 이동한다.
• Milestone 아카이브 대상은 agent-ops/roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md로 이동한다.
• 아카이빙할 때는 활성 ROADMAP.md 또는 활성 PHASE.md에 archive 문서 링크와 짧은 요약만 남긴다.
• 아카이브된 Phase/Milestone은 current.md에 남기지 않고, 일반 Phase/Milestone 선택이나 위치 분석의 후보로 삼지 않는다.
• 아카이브 문서는 과거 기록 스냅샷으로 보고, 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.