nomadcode/agent-ops/skills/common/update-roadmap/SKILL.md

name	version	description
update-roadmap	1.0.0	기존 Goal, Phase, Milestone 기반 로드맵을 갱신하고 current.md와 Active Milestone 정의를 동기화하는 공통 스킬

Update Roadmap

목적

기존 agent-ops/roadmap/ 구조를 현재 프로젝트 방향과 진행 상태에 맞게 갱신한다. 로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, current.md와 Active Milestone 문서가 실제 작업 기준으로 동작하게 한다.

언제 호출할지

• 사용자가 "로드맵 업데이트", "마일스톤 갱신", "phase 변경", "현재 마일스톤 바꿔줘"라고 요청할 때
• Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때
• Active Milestone의 Goal, Scope, Required Features, Success Criteria가 달라졌을 때
• 실제 구현 상태와 로드맵 파일이 어긋난 것 같아 동기화가 필요할 때

입력

• mode: status / milestone / phase / replan / sync 중 하나 (선택, 요청에서 추론 가능)
• target-milestone: 갱신할 Milestone ID 또는 이름 (선택)
• change-summary: 반영할 방향 변경 또는 진행 상황 요약 (선택)
• evidence: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택)

모드

mode	사용 상황
status	기능 체크박스, Milestone 상태, 완료 기준만 갱신
milestone	Milestone Goal, Scope, 기능 목록, Success Criteria 수정
phase	Active Phase 또는 Active Milestone 전환
replan	전체 Phase/Milestone 흐름 재구성
sync	실제 프로젝트 상태와 로드맵 불일치 점검 후 보정

먼저 확인할 것

• agent-ops/roadmap/ROADMAP.md 존재 여부 확인
• agent-ops/roadmap/current.md 존재 여부 확인
• current.md가 가리키는 Active Milestone 문서 존재 여부 확인
• current.md가 정해진 형식을 유지하는지 확인
• 로드맵 파일이 없으면 create-roadmap 스킬 사용을 안내하고 중단
• 완료 상태로 바꾸는 경우 사용자의 명시 또는 확인 가능한 evidence가 있는지 확인

실행 절차

1. 갱신 범위 결정

   • 요청에서 mode와 target milestone을 추론한다
   • status 갱신이면 current.md와 대상 Milestone 문서를 우선 읽는다
   • Phase 전환, Milestone 추가/삭제, 순서 변경, 전체 재계획이면 ROADMAP.md도 읽는다
   • 불필요하게 모든 Milestone 문서를 읽지 않는다

2. 현재 로드맵 상태 파악

   • ROADMAP.md의 전체 Goal, Phase 개요, Milestone 인덱스를 확인한다
   • current.md의 Active Phase와 Active Milestone 포인터를 확인한다
   • 대상 Milestone 문서의 Goal, Scope, Required Features, Success Criteria, Non-Goals를 확인한다

3. 변경 내용 검증

   • 기능 완료 체크는 사용자 설명 또는 파일/테스트/커밋 등 확인 가능한 근거를 기준으로 한다
   • evidence 없이 완료 여부가 불확실하면 체크하지 않고 TODO 또는 확인 필요로 남긴다
   • 변경 요청이 전체 Goal 또는 Phase Goal과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다

4. 로드맵 파일 갱신

   • ROADMAP.md는 전체 Goal, Phase 개요, Milestone 인덱스, 현재 위치가 바뀔 때만 수정한다
   • current.md는 Active Phase 또는 Active Milestone이 바뀔 때 아래 형식으로 수정한다

     # Current Roadmap Context
     
     - Active Phase: <phase-name>
     - Active Milestone: <MNN milestone-name>
     - Active Milestone File: agent-ops/roadmap/milestones/MNN-<milestone-slug>.md
     

   • Milestone 문서는 해당 Milestone의 Goal, Scope, Required Features, Success Criteria, Non-Goals, Context for Work가 바뀔 때 수정한다
   • 상태 값은 Planned, Active, Done, Paused, Dropped 중 하나만 사용한다
   • 완료된 Milestone의 기록은 삭제하지 않고 상태만 변경한다

5. 마일스톤 컨텍스트 로딩 규칙 점검

   • agent-ops/rules/project/rules.md가 있으면 ## 마일스톤 컨텍스트 로딩 섹션이 있는지 확인한다
   • 없으면 create-roadmap과 동일한 로딩 규칙을 추가한다
   • 기존 섹션이 있으면 전체 ROADMAP.md를 일반 작업마다 읽도록 되어 있지 않은지 확인하고 보정한다

6. 결과 보고

   • 수정한 파일 목록
   • 변경된 Phase / Milestone / 상태
   • 체크하거나 추가/제거한 Required Features
   • 확인 필요로 남긴 항목

실행 결과 검증

• current.md의 Active Milestone 경로가 실제 파일을 가리키는가
• current.md가 # Current Roadmap Context, Active Phase, Active Milestone, Active Milestone File 형식을 유지하는가
• ROADMAP.md의 현재 위치와 Milestone 인덱스가 current.md와 일치하는가
• 대상 Milestone 문서의 상태가 ROADMAP.md의 Milestone 인덱스 상태와 일치하는가
• 완료 처리한 기능에 사용자 설명 또는 확인 가능한 evidence가 있는가
• rules/project/rules.md가 있는 경우 마일스톤 컨텍스트 로딩 섹션이 유지되는가
• 검증 실패 시: 불일치한 파일만 다시 읽고 해당 항목만 수정한다

출력 형식

## 업데이트 완료

- Mode: <status | milestone | phase | replan | sync>
- 수정 파일:
  - agent-ops/roadmap/ROADMAP.md
  - agent-ops/roadmap/current.md
  - agent-ops/roadmap/milestones/MNN-<milestone-slug>.md

## 변경 사항

- Phase: <변경 없음 | 이전 → 이후>
- Active Milestone: <변경 없음 | 이전 → 이후>
- Status: <변경 없음 | 이전 → 이후>
- Required Features: <추가/수정/완료/제거 요약>

## TODO 항목

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

금지 사항

• 로드맵 파일이 없는데 새 구조를 임의로 만들지 않는다. 이 경우 create-roadmap을 사용한다
• evidence 없이 기능이나 Milestone을 완료 처리하지 않는다
• 전체 ROADMAP.md를 모든 작업의 필수 로딩 파일로 만들지 않는다
• 완료된 Milestone 기록을 삭제하지 않는다
• Milestone Goal과 Non-Goals를 무시하고 기능 목록만 갱신하지 않는다
• 타겟 프로젝트에서 agent-ops/rules/common/ 또는 agent-ops/skills/common/을 직접 수정하지 않는다