toki/nexo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexo/agent-ops/skills/common/update-roadmap/SKILL.md

31 KiB
Raw Blame History

name version description
update-roadmap 1.19.0 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, 승인된 archive 이동을 처리한다.

로드맵 업데이트

목적

기존 agent-ops/roadmap/ 구조를 현재 프로젝트 방향과 진행 상태에 맞게 갱신한다. 표준 구조는 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 창이 실제 작업 후보 목록으로 동작하게 한다.

Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서로 유지한다. Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 기능 안에서 관리한다. 별도 완료 기준 섹션은 만들지 않고, 검증이 필요한 기능에만 같은 Task 안의 검증: 문구로 통합한다.

언제 호출할지

  • 사용자가 "로드맵 업데이트", "마일스톤 갱신", "phase 변경", "현재 활성 마일스톤 바꿔줘"라고 요청할 때
  • 사용자가 "로드맵에 추가", "로드맵 작업 추가", "로드맵 기능 추가", "로드맵 Epic/Task 추가", "로드맵 에픽/태스크 추가", "마일스톤에 추가", "마일스톤 추가"처럼 로드맵에 새 내용을 넣어 달라고 요청할 때
  • Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때
  • Phase 완료, 보류, 폐기, 신규 추가가 필요할 때
  • 완료 또는 폐기된 Phase/Milestone을 archive로 이동해야 할 때
  • 런타임이 m-<milestone-slug> task group의 PASS 완료 이벤트를 Milestone에 반영해야 할 때
  • 특정 기능이나 작업을 새 Milestone, 기존 Milestone의 Epic, 기존 Epic의 Task 중 적절한 위치에 추가해야 할 때
  • 활성 Phase/Milestone 창에 포함할 목록이 달라졌을 때
  • 기존 로드맵을 phase/<phase-slug>/PHASE.md scaffold로 마이그레이션하거나 표준화해야 할 때

입력

  • mode: status / milestone / phase / replan / sync / concretize / archive 중 하나 (선택, 요청에서 추론 가능)
  • target-phase: 갱신할 Phase 이름, slug, 파일 경로 (선택)
  • target-milestone: 갱신할 Milestone 이름, slug, 파일 경로 (선택)
  • active-phases: 활성 Phase 창에 둘 Phase 이름, slug, 파일 경로 목록 (선택)
  • active-milestones: 활성 Milestone 창에 둘 Milestone 이름, slug, 파일 경로 목록 (선택)
  • 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, 테스트, 커밋, 사용자 설명 (선택)
  • 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 아카이브 날짜. 없으면 현재 날짜를 사용한다 (선택)

표준 구조

agent-ops/roadmap/
  ROADMAP.md
  current.md
  phase/
    <phase-slug>/
      PHASE.md
      milestones/
        <milestone-slug>.md
  archive/
    phase/
      <phase-slug>/
        PHASE.md
        milestones/
          <milestone-slug>.md
  • 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/만 있을 수 있다.
  • <phase-slug>와 <milestone-slug>는 소문자 영문, 숫자, 하이픈만 사용한다.
  • current.md는 활성 Phase와 활성 Milestone을 모두 가리킨다.
  • current.md에는 archive 경로를 넣지 않는다.
  • current.md에는 [완료] 또는 [폐기] Phase/Milestone을 남기지 않는다. 완료 후보는 사용자 승인 전까지 [검토중]으로 둔다.

상태와 id

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

로딩 원칙

  • 일반 갱신은 current.md, 관련 활성 Phase, 관련 활성 Milestone을 우선 읽는다.
  • ROADMAP.md는 Phase 흐름, 전체 구조, 활성 범위 밖 작업, 전체 재계획, archive 링크 갱신이 필요할 때 읽는다.
  • agent-ops/roadmap/archive/**는 일반 작업이나 sync에서 읽지 않는다.
  • archive 모드에서 이동 대상이 아직 활성 경로에 있으면 그 대상 문서는 읽을 수 있다.
  • 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 요청이면 ROADMAP.md 또는 PHASE.md의 archive 링크를 따라 필요한 archive 문서만 읽는다.

템플릿

  • ROADMAP.md: agent-ops/skills/common/_templates/roadmap-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

구현 잠금

  • 구현 잠금은 승인 절차가 아니라 사용자 결정이 필요한지 표시하는 얇은 상태다.
  • 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 잠금으로 두고 결정 필요 체크리스트에 질문을 적는다.
  • 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 결정 필요가 아니라 작업 컨텍스트의 표준선으로 기록한다.
  • Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 해제로 둔다.
  • 잠금 상태 변경은 Milestone 완료 판정이 아니므로 기능 Task를 자동 완료 처리하지 않는다.
  • [스케치] Milestone은 구현 잠금이 해제로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 승격 조건을 충족해 [계획]으로 전환한다.

완료 리뷰와 검토중 상태

  • Task 완료 또는 Milestone 갱신 후 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 [x]인지 확인한다.
  • 모두 충족된 것으로 보이면 Milestone을 [완료]로 바로 바꾸거나 archive로 이동하지 말고 [검토중]으로 바꾼다.
  • [검토중]으로 바꿀 때는 Milestone 문서의 완료 리뷰 섹션을 만들거나 갱신한다.
  • 완료 리뷰에는 상태: 요청됨, 요청일, 완료 근거 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-ops/roadmap/phase/*/milestones/<milestone-slug>.md에서 정확히 하나만 찾아야 한다. archive Milestone은 target 후보가 아니다.
  • target이 없거나 둘 이상이면 Milestone 내용을 추정해 수정하지 말고 target 불명확으로 보고한다.
  • 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이 될 수 없다.

삽입 단위 정책

삽입 단위 사용 기준
새 Phase 독립적인 제품 진화 단계와 여러 Milestone 묶음이 필요하다
새 Milestone 독립적인 목표와 기능 Task 묶음이 필요하고 Phase 흐름에 의미 있는 경계를 만든다
새 Epic 기존 Milestone 안에서 여러 Task를 묶는 상위 capability 또는 산출물이다
새 Task 기존 Epic 아래에 들어가는 완료 가능한 capability 또는 산출물이다. 검증이 필요한 경우에만 같은 Task 안에 붙인다
하위 작업 기존 Task를 완성하기 위한 구현 세부다. Milestone 기능에는 하위 체크박스로 만들지 않고, plan 내부 체크리스트나 기존 Task의 검증:/설명 보강으로 다룬다
작업 컨텍스트/TODO 사용자 결정 또는 조사/확인이 먼저 필요해 기능 Task로 확정하기 어렵다
  • 먼저 요청 내용의 규모를 판정한다. 배치 위치를 찾기 전에 phase, milestone, epic, task, subtask, context 중 가장 작은 충분한 단위를 고른다.
  • 요청이 방향성, 문제의식, 컨셉, 운영 원칙 수준이고 기능 Task나 실행 범위가 아직 부족하면 새 항목의 상태는 [스케치]로 둔다.
  • [스케치] Phase/Milestone을 만들 때는 승격 조건에 [계획]으로 전환하기 위해 필요한 정의, 결정, 경계, 후속 구현 Milestone 후보를 체크리스트로 남긴다.
  • 가장 작은 충분한 단위 원칙을 따른다. 애매하면 새 Phase나 새 Milestone으로 키우지 말고, 기존 Milestone의 Epic/Task에 넣을 수 있는지 먼저 확인한다.
  • 위치 지정이 있으면 anchor의 레벨을 먼저 확인한다.
  • <epic-id> 아래는 해당 Epic 아래 Task로 넣는다.
  • <item-id> 앞/뒤는 같은 Epic 안의 형제 Task로 넣는다.
  • <item-id> 아래는 해당 Task의 설명 또는 검증:을 보강한다. 구현 세부나 테스트만 따로 떼어낸 하위 체크박스는 Milestone 기능 아래에 만들지 않는다.
  • <phase-name> 안은 새 Milestone 또는 기존 Milestone/Epic/Task 중 작업 성격에 맞는 단위로 배치한다.
  • 위치 지정이 없으면 auto로 본다. current.md의 활성 창만으로 결정하지 않고, 필요한 경우 ROADMAP.md의 Phase 흐름까지 확인해 완료/검토중/진행중/계획/스케치 Phase를 비교한다.
  • target 없는 신규 추가 요청은 요청 문장, 관련 파일/도메인 힌트, Phase 목표, Milestone 목표, 기존 Epic/Task, 선후 의존성, 상태, 활성 창을 비교해 가장 자연스러운 위치를 자동 판단한다.
  • 자동 배치 후보가 여러 개이면 1순위와 2순위 후보를 비교하고, 선택한 Phase/Milestone/Epic/Task와 밀린 후보의 이유를 짧게 남긴다.
  • 관련성이 비슷하면 [진행중] Milestone을 [계획] Milestone보다 우선하되, [검토중] Milestone은 리뷰 보완 요청이 아닌 신규 작업의 기본 배치 대상으로 삼지 않는다.
  • 자동 배치한 경우 결과 보고에 선택한 삽입 단위, 위치, 판단 근거, 비교한 후보를 짧게 남긴다.
  • 사용자 지정 위치가 Phase 목표, Milestone 범위 제외, 선후 의존성과 충돌하면 수정 전에 사용자에게 확인한다.

레벨별 탐색과 upsert 정책

target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다.

  1. 요청 정규화

    • 요청 문장에서 기능명, 목표, 산출물, 관련 경로/도메인, 완료 기대, 제약, 명시 anchor를 뽑는다.
    • 사용자가 Phase/Milestone/Epic/Task/id/path를 명시했으면 그 anchor를 우선 후보로 둔다.

  2. 규모 판정

    • 여러 Milestone을 묶는 제품/운영 단계면 Phase 규모다.
    • 독립 목표, 기능 Task 묶음, 여러 Epic이 필요한 결과면 Milestone 규모다.
    • 컨셉은 충분히 크지만 구현 가능한 목표/범위/기능 Task가 아직 없으면 [스케치] Phase 또는 Milestone 후보로 둔다.
    • 한 Milestone 안의 capability 묶음이면 Epic 규모다.
    • Epic 아래에서 완료 가능한 단일 capability 또는 산출물이면 Task 규모다. 검증이 필요한 경우에만 같은 Task 안에 포함한다.
    • Task를 완성하기 위한 구현 세부면 subtask 규모다. roadmap에는 하위 체크박스로 기록하지 않고, 구현 계획 내부 또는 기존 Task 보강으로 처리한다.
    • 조사, 결정, 보류 질문이면 작업 컨텍스트/TODO 규모다.

  3. 레벨별 탐색

    • Phase 후보를 먼저 찾는다. current.md의 활성 Phase를 우선 보되, target이 없거나 활성 범위 밖 가능성이 있으면 ROADMAP.md의 Phase 흐름도 본다.
    • 선택한 Phase 안에서 Milestone 후보를 찾는다. 활성 Milestone을 우선 보되, 요청이 계획 Milestone 목표와 더 직접 맞으면 계획 Milestone도 후보로 둔다.
    • 선택한 Milestone 안에서 Epic 후보를 찾는다. 기능의 Epic heading, 목표 설명, Task 묶음을 비교한다. 기존 문서가 필수 기능을 쓰면 갱신 시 기능으로 정규화한다.
    • 선택한 Epic 안에서 Task 후보를 찾는다. item-id, 문장 의미, Task 안의 검증 문구, 관련 경로를 비교한다.
    • archive 문서는 기본 탐색 대상이 아니다. 사용자가 과거 기록 비교를 명시했거나 완료 내용 확인이 필요한 경우에만 ROADMAP.md 또는 PHASE.md의 archive 링크를 따라 필요한 문서만 읽는다.

  4. 중복/업데이트 판정

    • 같은 id, 같은 제목, 같은 목표, 같은 관련 경로, 같은 Task 안의 검증 문구, 또는 같은 산출물을 다루면 동일/유사 후보로 본다.
    • 동일 항목이면 새로 만들지 않고 기존 Phase/Milestone/Epic/Task를 업데이트한다.
    • 기존 항목의 범위를 보강하는 내용이면 해당 항목의 설명, Task 안의 검증 문구, 작업 컨텍스트 중 알맞은 곳에 병합한다.
    • 기존 항목과 충돌하거나 범위 제외를 건드리면 수정 전에 사용자에게 확인한다.
    • 같은 레벨에 적절한 후보가 없을 때만 새 항목을 만든다. 새 항목도 판정한 규모보다 크게 만들지 않는다.
    • 부모 레벨 후보는 있고 판정 규모의 항목만 없으면, 부모 아래에 판정 규모의 새 항목을 만든다. 부모 레벨도 없을 때만 필요한 부모 항목을 함께 만든다.

archive 정책

Milestone archive

  • 대상 Milestone이 [완료] 또는 [폐기]인지 확인한다.
  • [검토중] Milestone은 archive하지 않는다. 사용자 완료 승인 또는 폐기 지시가 있으면 먼저 [완료] 또는 [폐기]로 바꾼 뒤 archive한다.
  • 대상 파일을 agent-ops/roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md에서 agent-ops/roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md로 이동한다.
  • 활성 PHASE.md의 Milestone 흐름에는 [완료] 또는 [폐기] 항목을 남기고, 경로는 archive 경로로 바꾼다.
  • current.md의 활성 Milestone에서는 제거한다.
  • ROADMAP.md는 Phase 상태나 경로가 바뀌지 않으면 수정하지 않는다.
  • 이동한 archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다.

Phase archive

  • Phase 전체가 [완료] 또는 [폐기]인지 확인한다.
  • [검토중] Phase는 archive하지 않는다. 사용자 완료 승인 또는 폐기 지시가 있으면 먼저 [완료] 또는 [폐기]로 바꾼 뒤 archive한다.
  • agent-ops/roadmap/phase/<phase-slug>/PHASE.md를 agent-ops/roadmap/archive/phase/<phase-slug>/PHASE.md로 이동한다.
  • 해당 Phase의 하위 Milestone도 archive/phase/<phase-slug>/milestones/ 아래로 이동한다.
  • ROADMAP.md의 Phase 흐름에는 해당 Phase 항목을 남기고, 상태와 경로를 archive PHASE.md로 바꾼다.
  • current.md의 활성 Phase와 활성 Milestone에서는 해당 Phase와 하위 Milestone을 제거한다.
  • archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다.

실행 절차

  1. 갱신 범위 결정

    • 요청에서 mode, 대상 Phase/Milestone, placement, placement-unit을 추론한다.
    • 런타임 완료 이벤트의 origin-task task group이 m-<milestone-slug>이면 target-milestone을 활성 Milestone 경로 매칭으로 확정한다.
    • 구조 전환, 템플릿 보정, current 동기화는 sync로 본다.
    • 사용자 승인 이후의 완료/폐기 이동은 archive로 본다.
    • 새 기능 배치, Epic/Task 추가는 milestone 또는 phase로 본다.
    • "로드맵에 추가"처럼 target이 없는 신규 작업 요청은 placement=auto, placement-unit=auto, new-feature=<요청 내용>으로 본다.

  2. 요청 정규화와 규모 판정

    • 요청에서 기능명, 목표, 관련 경로, 명시 anchor, 완료 기대, 제약을 추출한다.
    • phase, milestone, epic, task, subtask, context 중 가장 작은 충분한 규모를 판정한다.
    • 동일/유사 항목이 이미 있으면 신규 추가가 아니라 업데이트 후보로 기록한다.

  3. 레벨별 후보 탐색

    • current.md의 활성 Phase와 활성 Milestone 후보를 확인한다.
    • target이 명시된 경우 대상 Phase의 PHASE.md를 읽고 Milestone 흐름과 Phase 경계를 확인한다.
    • target이 없거나 활성 창 밖 배치 가능성이 있으면 ROADMAP.md의 Phase 흐름을 확인하고, 관련성이 높은 Phase 문서를 읽는다.
    • 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. 기존 문서에 필수 기능/완료 기준이 분리되어 있으면 갱신 범위에서 기능 Task로 흡수할 후보를 기록한다.
    • Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
    • current.md에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다.
    • 필요한 경우에만 ROADMAP.md를 읽어 전체 Phase 흐름을 확인한다.

  4. 스케치 승격 판단

    • target-status=[계획], mode=concretize, 또는 사용자가 "구체화", "계획으로 올려"처럼 요청하면 [스케치] -> [계획] 승격 검토로 본다.
    • 대상이 [스케치]가 아니면 일반 상태 갱신이나 Milestone 갱신으로 처리한다.
    • 대상이 [스케치]이면 승격 조건, 구현 잠금, 목표, 범위, 기능, 작업 컨텍스트를 확인한다.
    • 승격 조건 체크리스트가 남아 있거나 구현 계획에 직접 필요한 사용자 결정이 남아 있으면 상태를 [스케치]로 유지하고, 부족한 항목을 승격 조건 또는 결정 필요에 보강한다.
    • 구현 가능한 목표, 범위, 기능 Task, 직접 결정 항목, 후속 구현 단위가 정리되면 상태를 [계획]으로 전환하고, 승격 조건은 충족 요약으로 남기거나 - 없음으로 정리한다.
    • 승격은 구현 완료가 아니므로 기능 Task를 자동 완료 처리하지 않는다.

  5. 변경 내용 작성

    • ROADMAP.md는 전체 목표, Phase 흐름, 로딩 정책이 바뀔 때만 수정한다.
    • current.md는 활성 Phase/Milestone 창이 바뀔 때 수정한다.
    • PHASE.md는 Phase 목표, 상태, Milestone 흐름, Phase 경계가 바뀔 때 수정한다.
    • Milestone 문서는 목표, 상태, 승격 조건, 구현 잠금, 범위, Epic/Task, Task 안의 검증 문구, 완료 리뷰, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
    • 동일/유사 후보가 있으면 기존 항목을 업데이트하고 중복 항목을 만들지 않는다.
    • 새 Milestone은 해당 Phase의 milestones/ 아래에 만든다.
    • 새 [스케치] Milestone은 승격 조건 섹션을 포함하고 구현 잠금은 잠금으로 둔다.
    • 새 Epic은 기능 아래 ### Epic: [epic-id] <이름>으로 만든다.
    • 새 Task는 관련 Epic 아래 - [ ] [item-id] 설명으로 만든다. 검증이 필요한 경우에만 같은 항목에 검증: <명령/확인 방법/기대 결과>를 붙인다.
    • 새 항목은 레벨별 탐색에서 적절한 기존 후보가 없을 때만 만든다.
    • 완료 체크는 evidence가 있을 때만 [x]로 바꾼다.
    • 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 [x]이면 Milestone 상태를 [검토중]으로 바꾸고 완료 리뷰에 리뷰 요청과 근거를 남긴다.
    • [검토중] 전환만으로 archive 이동, current.md 제거, archive 링크 변경을 수행하지 않는다.
    • 사용자 승인 근거가 있으면 [검토중]을 [완료]로 전환하고 archive 모드를 수행할 수 있다.

  6. 검증

    • current.md의 활성 Phase/Milestone 경로가 실제 파일을 가리키는지 확인한다.
    • current.md의 활성 항목이 archive 경로를 가리키지 않는지 확인한다.
    • current.md의 활성 항목이 [완료] 또는 [폐기] 상태로 남아 있지 않은지 확인한다.
    • ROADMAP.md의 Phase 경로가 실제 PHASE.md 파일을 가리키는지 확인한다.
    • 각 PHASE.md의 Milestone 경로가 실제 파일을 가리키는지 확인한다.
    • 상태 표기가 표준값인지 확인한다.
    • [스케치] Milestone에 승격 조건이 있고 구현 잠금이 잠금인지 확인한다.
    • [계획] 이상 Milestone에 승격 조건 섹션이 없더라도 오류로 보지 않는다. 섹션이 있으면 - 없음 또는 승격 충족 요약인지 확인한다.
    • [스케치] -> [계획] 전환을 수행했다면 승격 조건 해소 근거가 Milestone 내용이나 결과 보고에 남았는지 확인한다.
    • [검토중] Milestone이 archive 경로로 이동되지 않았는지 확인한다.
    • 모든 기능 Task와 Task 안에 명시된 검증이 [x]인 Milestone에는 완료 리뷰 섹션과 사용자 리뷰 요청이 있는지 확인한다.
    • Epic heading과 Task id 형식이 맞는지 확인한다.
    • 요청 규모가 판정되었고 결과 보고에 남았는지 확인한다.
    • 동일/유사 기존 항목을 검색했고 신규/업데이트 판정이 결과 보고에 남았는지 확인한다.
    • 자동 배치한 신규 작업이면 선택한 후보와 밀린 후보의 근거가 결과 보고에 포함되는지 확인한다.
    • git diff --check로 공백 오류를 확인한다.

  7. 결과 보고

    • 수정한 파일 목록
    • 요청 규모 판정과 근거
    • Phase -> Milestone -> Epic -> Task 탐색 경로와 후보
    • 신규 추가인지 기존 항목 업데이트인지
    • 변경된 Phase / Milestone / 상태
    • 신규 작업의 삽입 단위와 배치 위치
    • 자동 배치한 경우 비교한 후보와 선택 근거
    • current.md 활성 창 변경 사항
    • 완료 리뷰 상태와 사용자 확인 필요 항목
    • 런타임 완료 이벤트의 origin-task가 m-<milestone-slug>이면 원래 active task 경로와 매칭된 target Milestone 또는 target 불명확 사유
    • archive 모드이면 이동 경로와 남긴 링크
    • 확인 필요로 남긴 항목

출력 형식

## 업데이트 완료

- 모드: <status | milestone | phase | replan | sync | concretize | archive>
- 수정 파일:
  - agent-ops/roadmap/ROADMAP.md
  - agent-ops/roadmap/current.md
  - agent-ops/roadmap/phase/<phase-slug>/PHASE.md
  - agent-ops/roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md
  - agent-ops/roadmap/archive/phase/<phase-slug>/... (archive 모드)

## 변경 사항

- Phase: <변경 없음 | 요약>
- Milestone: <변경 없음 | 요약>
- 삽입 단위: <Phase | Milestone | Epic | Task | 하위 작업 | 작업 컨텍스트/TODO | 변경 없음>
- 규모 판정: <phase | milestone | epic | task | subtask | context | 변경 없음> - <근거>
- 탐색 경로: <Phase 후보 -> Milestone 후보 -> Epic 후보 -> Task 후보 | 해당 없음>
- 신규/업데이트 판정: <신규 생성 | 기존 항목 업데이트 | 변경 없음> - <동일/유사 후보 근거>
- 배치: <사용자 지정 위치 반영 | 자동 배치 위치와 근거 | 변경 없음>
- 배치 후보: <자동 배치 시 1순위/2순위 후보와 선택/제외 근거 | 해당 없음>
- 템플릿 보정: <ROADMAP | current.md | PHASE | Milestone | 이미 일치 | 변경 없음>
- 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>; 결정 필요: <없음 | 항목 요약>
- 승격 조건: <해당 없음 | 추가/수정/미충족 유지/충족 요약>
- 완료 리뷰: <변경 없음 | 요청됨 | 승인됨 | 보완 필요 | 보류 | 폐기>
- runtime m-task 라우팅: <해당 없음 | origin-task -> target Milestone | target 불명확>
- 활성 항목: <변경 없음 | Phase/Milestone 추가/제거 요약>
- 아카이브: <변경 없음 | 이동 경로와 남긴 링크>
- 상태: <변경 없음 | 이전 -> 이후>
- Epic/Task: <추가/수정/완료/제거 요약>

## TODO 항목

- <확인이 필요한 항목> (해당 시)

금지 사항

  • 로드맵 파일이 없는데 새 구조를 임의로 만들지 않는다. 이 경우 create-roadmap을 사용한다.
  • evidence 없이 Phase, Milestone, Epic, Task를 [완료] 또는 [검토중]으로 처리하지 않는다.
  • 전체 ROADMAP.md를 모든 작업의 필수 로딩 파일로 만들지 않는다.
  • ROADMAP.md에 Milestone 상세 작업 체크리스트를 남기지 않는다.
  • current.md에 개인별 현재 작업 위치나 완료 상태를 남기지 않는다.
  • current.md에 agent-ops/roadmap/archive/** 경로를 남기지 않는다.
  • archive 문서를 명시 요청 없이 읽거나 최신 템플릿으로 재포맷하지 않는다.
  • 완료된 Phase/Milestone 기록을 삭제하지 않는다.
  • Epic과 Task를 별도 파일로 분리하지 않는다.
  • Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
  • 사용자만 결정할 수 있는 항목이 남아 있는데 Milestone의 구현 잠금을 해제로 바꾸지 않는다.
  • 사용자가 지정한 Phase/Milestone/Epic/Task anchor를 무시하지 않는다.
  • 사용자가 명시하지 않은 기존 epic-id나 item-id를 바꾸지 않는다.