로드맵 규칙

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

구조

최상위 로드맵은 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>는 소문자 영문, 숫자, 하이픈만 사용한다.
완료된 Phase는 scaffold 그대로 agent-roadmap/archive/phase/<phase-slug>/PHASE.md로 이동하고, 하위 Milestone도 archive/phase/<phase-slug>/milestones/ 아래에 둔다.
진행중 Phase 안에서 완료된 Milestone은 활성 PHASE.md에 짧은 archive 링크를 남기고, 상세 문서는 agent-roadmap/archive/phase/<phase-slug>/milestones/로 이동한다.
archive PHASE.md는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 milestones/만 있을 수 있다.
큰 Milestone의 설계 게이트는 agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md에 둔다.
SDD 사용자 리뷰가 필요하면 같은 디렉터리에 USER_REVIEW.md를 둔다. 해결된 리뷰는 user_review_N.log로 남긴다.
완료 또는 폐기된 Milestone의 SDD는 agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/로 이동한다.

링크 표기

사용자에게 보여주는 답변과 활성 로드맵 문서의 문서 포인터는 raw path만 쓰지 말고 [표시 제목](상대경로) Markdown 링크로 쓴다.
로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: ROADMAP.md에서는 [PHASE.md](phase/example-phase/PHASE.md), Phase 문서에서는 [Milestone](milestones/example-milestone.md), Milestone 문서에서는 [ROADMAP.md](../../../ROADMAP.md)와 [PHASE.md](../PHASE.md)를 쓴다.
채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: [PHASE.md](agent-roadmap/phase/example-phase/PHASE.md).
채팅 결과에 로드맵 문서에서 읽은 링크를 재사용할 때는 원본 Markdown 파일 위치 기준으로 target을 해석한 뒤 repo root 기준 상대경로로 다시 쓴다. 예: agent-roadmap/current.md에서 읽은 (phase/foo/PHASE.md)는 채팅 출력에서 (agent-roadmap/phase/foo/PHASE.md)로, agent-roadmap/phase/foo/PHASE.md에서 읽은 (milestones/bar.md)는 (agent-roadmap/phase/foo/milestones/bar.md)로 쓴다.
실제 활성 로드맵 문서에는 <phase-slug>, <milestone-slug>, <relative-...> 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 문서 생성/갱신 시 실제 파일 위치 기준 상대경로 또는 없음으로 치환한다.
기존 raw path 또는 backtick path는 읽기 입력으로 허용한다. 갱신 범위에 포함된 활성 문서 포인터만 Markdown 링크로 보정하고, archive 스냅샷은 링크 표기만을 이유로 재포맷하지 않는다.
.agent-roadmap-sync/locks.yaml의 locked, rely-on.target, Milestone identity(<project>:agent-roadmap/...)처럼 machine-readable 계약 값은 raw 값을 유지할 수 있다. 사용자-facing 설명에는 가능하면 별도 Markdown 문서 링크를 함께 붙인다.

Runtime Action Boundary

로드맵 스킬은 기본적으로 로드맵 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당한다.
Core/MCP가 있는 프로젝트에서는 Phase/Milestone 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리한다.
Core/MCP가 없거나 아직 해당 action을 제공하지 않는 프로젝트에서만 update-roadmap 스킬이 file-based fallback으로 직접 문서를 갱신한다.
update-roadmap은 fallback 갱신을 수행하더라도 런타임 action 경계를 문서화하고, Core/MCP로 넘길 수 있는 입력과 결과를 함께 남긴다.

로딩

세션 최초 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 없음으로 보고한 뒤 priority-queue.md가 있으면 전역 실행 순서와 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 존재 여부를 확인한다.
로드맵 현지점 확인은 로컬 current.md, priority-queue.md의 실행 순서, ROADMAP.md의 Phase 흐름, 활성 PHASE.md의 Milestone 흐름, 활성 Milestone의 제목/목표/상태를 기본으로 읽는다. SDD: 필요이면 SDD 본문을 읽지 말고 SDD 문서 링크와 USER_REVIEW.md 존재 여부만 확인한다.
ROADMAP.md는 로드맵 생성/갱신, Phase 추가/삭제/전환, 전체 구조 변경, 활성 범위 밖 작업 확인 때만 읽는다.
과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 ROADMAP.md 또는 PHASE.md에 있는 archive 링크를 따라가서 필요한 archive 문서만 읽는다.

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만 대상으로 한다.
current.md에는 [완료] 또는 [폐기] Phase/Milestone을 남기지 않는다. 완료 후보는 완료 근거와 archive 전환이 정리될 때까지 [검토중]으로 둔다.
"로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 update-roadmap 스킬로 배치 제안 또는 file-based fallback 갱신을 처리하고, 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의 목표 또는 범위 제외와 요청이 충돌하면 구현을 진행하지 않고 충돌을 보고한다. 에이전트가 확정할 수 없는 제품/범위 결정은 Milestone 구현 잠금 > 결정 필요 또는 SDD USER_REVIEW.md로 분리한다.

상태 표기

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

구현 잠금

구현 잠금은 승인 의식이 아니라 에이전트가 확정할 수 없는 결정이 필요한지 표시하는 얇은 상태다.
제품 방향, 범위, 우선순위, 책임 경계처럼 에이전트가 확정할 수 없는 항목이 남아 있으면 상태를 잠금으로 두고 결정 필요 목록에 남긴다.
기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 결정 필요가 아니라 작업 컨텍스트의 표준선이나 구현 가정으로 기록한다.
Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 해제로 둔다.
선택한 Milestone에 구현 잠금 섹션이 없거나, 상태가 잠금이거나, 미완료 결정 필요 항목이 하나라도 있으면 코드 구현, agent-task 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
잠금 상태에서 허용되는 작업은 로드맵 현지점 확인, 잠금 해소, SDD gate 처리, 범위/후속 Milestone 정리 같은 roadmap-only 갱신뿐이다. 실구현 계획 요청이면 잠금 차단으로 보고하고 PLAN-*.md/CODE_REVIEW-*.md를 만들지 않는다.
남은 결정 필요 항목이 현재 Milestone 실구현 범위가 아니라면 먼저 update-roadmap으로 범위 제외, 후속 Milestone, 또는 작업 컨텍스트로 옮기고 구현 잠금을 해제한 뒤 별도 실구현 계획을 시작한다.
구현 잠금은 SDD gate를 포함할 수 있다. SDD: 필요이면 SDD 상태가 [승인됨]이고 SDD 잠금이 해제이며 SDD USER_REVIEW.md가 없어야 구현 잠금 해제 후보가 된다.
SDD 사용자 리뷰는 채팅 질문으로 직접 처리하지 않고 agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md에 남긴다. 사용자의 답변이 반영되면 user_review_N.log로 이동한다.
SDD가 필요한데 문서가 없거나 gate 정보가 부족하면 Milestone 구현 잠금을 해제하지 않는다. 실구현 계획 요청은 잠금 차단으로 보고하고, SDD 작성/확인은 roadmap-sdd 또는 update-roadmap 흐름에서 처리한다.
SDD가 불필요한 Milestone은 SDD: 불필요과 짧은 사유를 구현 잠금에 남긴다.
잠금 상태의 Milestone에서는 "현재 요청과 직접 관련 없음"을 이유로 실구현 계획이나 코드 구현을 진행하지 않는다. 관련 없음 판단은 잠금 해소용 roadmap-only 갱신으로 먼저 문서화한다.
잠금 상태를 바꾸더라도 기능 Task를 자동 완료 처리하지 않는다.
[스케치] 상태의 Milestone은 구현 잠금이 해제로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 [계획]으로 승격해야 한다.

프로젝트 간 잠금

프로젝트 상위 .agent-roadmap-sync/locks.yaml은 프로젝트 간 Milestone 잠금 인덱스다. 외부 의존 잠금을 생성하거나 동기화해야 하면 Core/MCP가 있으면 그쪽 action이 만들고, 없으면 update-roadmap file-based fallback이 디렉터리와 파일을 만든다.
entry는 id, locked, rely-on[].target, rely-on[].status, rely-on[].note만 사용한다.
locks.yaml은 root sequence block style을 기본으로 작성한다. 예: - id: ... 아래에 locked, rely-on을 둔다.
id는 기본적으로 <잠긴-project>:<잠긴-milestone-slug>로 만든다.
locked와 rely-on[].target은 <project>:agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md 형식으로 기록한다.
Milestone 경로가 agent-roadmap/... 상대 경로이면 현재 프로젝트명을 prefix로 붙인다. workspace 하위 절대/상대 경로이면 workspace 바로 아래 디렉터리명을 project로 삼고, 그 뒤 agent-roadmap/... 경로를 붙인다.
locked는 잠긴 Milestone, rely-on.target은 선행 조건 Milestone이다. 둘 다 같은 workspace의 어느 활성 Phase 하위 Milestone이어도 된다. 의존 대상이 current.md에 있어야 한다고 가정하지 않는다.
"현재 마일스톤은 X 프로젝트 작업 뒤에 진행", "X 프로젝트 때문에 현재 작업 잠금", "의존성 설정해"처럼 잠긴 Milestone을 생략한 외부 의존 잠금 요청은 현재 프로젝트 로컬 current.md의 활성 Milestone 단일 후보를 잠긴 대상으로 삼는다.
의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 로컬 current.md가 있을 때의 단일 후보 순서로 확정한다.
정규화 비교는 소문자 변환, backtick/따옴표 제거, 영문/숫자가 아닌 연속 문자를 - 하나로 치환, 앞뒤 - 제거 후 Milestone 파일 slug와 정규화한 제목에 대조한다.
의존 대상 탐색은 대상 프로젝트의 agent-roadmap/phase/*/milestones/*.md 활성 문서만 대상으로 한다. archive 문서는 사용자가 archive 경로를 명시한 경우 외에는 읽거나 후보로 삼지 않는다.
후보가 없거나 둘 이상이면 locks.yaml을 만들거나 고치지 말고 모호성을 보고한다. 잠금 대상 확정이 제품/범위 결정이면 대상 Milestone의 구현 잠금 > 결정 필요로 분리한다.
외부 의존 잠금을 만들 때 대상 Milestone의 구현 잠금은 잠금으로 둔다.
새 rely-on.status는 선행 Milestone 상태에서 파생한다. [검토중] 또는 [완료]이면 enable, 그 외 상태거나 상태를 확인할 수 없으면 disable이다.
같은 id entry를 upsert할 때 기존 rely-on 항목을 삭제하지 않는다. 같은 rely-on.target만 status/note를 갱신하고, 없는 target은 추가하며, locked 경로가 바뀐 경우에만 locked를 갱신한다.
locks.yaml이 있고 Milestone을 갱신하거나 archive할 때는 대상 Milestone identity로 agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" both "<locks-file>"를 먼저 실행한다.
find 결과가 none이면 결과 보고의 Workspace 잠금에 관련 lock 없음을 남긴다. 외부 의존 잠금 생성/동기화 요청이 아니라면 locks.yaml을 새로 만들거나 수정하지 않는다.
Core/MCP action 또는 update-roadmap fallback이 갱신한 Milestone identity가 어느 entry의 rely-on.target과 일치하면 Milestone 상태 기준으로 status를 동기화한다. [검토중] 또는 [완료]이면 enable, 그 외 상태면 disable이다.
Core/MCP action 또는 update-roadmap fallback이 갱신하거나 선택한 Milestone identity가 어느 entry의 locked와 일치하면 모든 rely-on.status가 enable인지 결과 보고에 남긴다. 모든 조건이 충족되어도 잠금 해제 실행은 Core/MCP 또는 런타임의 별도 action으로 처리한다.
archive 모드에서는 파일 이동 전에 대상 Milestone의 활성 경로 identity를 보존하고, 그 identity로 --find-milestone "<identity>" both "<locks-file>"를 먼저 실행한다. 보존한 identity가 어느 entry의 rely-on.target과 일치하고 Milestone 상태가 [완료]이면 archive 이동 전에 해당 rely-on.status를 enable로 바꾼다.
archive 모드에서 보존한 identity가 어느 entry의 locked와 일치하면 archive 이동 전에 모든 rely-on.status가 enable인지 결과 보고에 남긴다. 미충족이어도 archive 자체는 막지 않고 Workspace 잠금: 미충족으로 보고한다.
잠금 해제 조건 충족 여부만 확인할 때는 agent-ops/skills/common/check-roadmap-dependency/SKILL.md를 읽는다. lock id가 없으면 해당 스킬은 agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" "<direction>" "<locks-file>"로 현재 Milestone이 locked인지 rely-on.target인지 양방향으로 찾은 뒤 agent-ops/bin/roadmap-dependency-checker.sh "<lock-id>" "<locks-file>"를 사용한다.
checker exit code는 0=true, 1=false, 2=설정/입력/파싱 오류로 해석한다.

SDD 게이트

SDD는 큰 Milestone의 설계 계약을 로드맵에 녹이는 하위 문서다. 별도 작업 관리 체계로 쓰지 않는다.
SDD 작성, 갱신, gate 확인, 사용자 리뷰 대기, 잠금 해제는 agent-ops/skills/common/roadmap-sdd/SKILL.md를 따른다.
SDD는 cross-repo 계약, 외부 provider 쓰기, 상태 머신, idempotency/retry/identity map, API/proto/config/env/schema, field smoke, 사용자 승인 gate에 영향을 주는 Milestone에만 강제한다.
작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강, Milestone Task의 검증:만으로 닫히는 작업에는 SDD를 강제하지 않는다.
로드맵 갱신으로 새 Milestone을 만들거나 [스케치] Milestone을 [계획]으로 승격하면서 SDD: 필요로 판정하면 같은 흐름에서 SDD 파일도 만든다. 사용자가 명시적으로 SDD 생성을 뒤로 미루지 않았는데 SDD: 필요와 SDD 문서 링크만 있고 파일이 없는 상태로 종료하지 않는다.
SDD 문서는 agent-ops/skills/common/_templates/roadmap-sdd-template.md의 표준 섹션, 순서, 필수 표 컬럼을 유지해야 한다.
SDD의 Acceptance Scenarios는 Milestone 기능 Task id와 연결되어야 한다.
SDD의 Evidence Map은 code-review/complete.log의 Roadmap Completion과 최종 검증 evidence로 검증 가능해야 한다.
SDD: 필요 Milestone의 구현 계획은 승인된 SDD를 입력으로 삼아 작성한다. 구현 계획은 Milestone 기능 Task만 보고 실행 항목을 만들지 않고, 연결된 Acceptance Scenario와 Evidence Map에서 구현 범위, 검증, 완료 evidence를 역산해야 한다.
외부 API 또는 프로젝트 간 호출 계약 원문은 agent-contract/에 두고 SDD에는 링크만 남긴다.
SDD 전체 검토를 채팅 질문으로 처리하지 않는다. 에이전트가 확정할 수 없는 source of truth, 상태 전이, 책임 경계, 권한, 비용, 데이터 보존, 실패 처리만 USER_REVIEW.md로 분리한다.

Epic과 Task id

Milestone 문서의 실행 체크리스트는 기능 섹션 하나로 작성한다. 새 Milestone이나 갱신 범위에 포함된 Milestone에는 별도 완료 기준 섹션을 만들지 않는다.
기존 Milestone에 필수 기능과 완료 기준이 분리되어 있으면, 갱신 시 완료 기준을 관련 기능 Task 안의 선택적 검증: 문구로 흡수하고 섹션을 제거한다.
기능 Task는 기능 또는 산출물 단위다. 검증이 필요한 기능만 같은 Task 안에 검증: <명령/확인 방법/기대 결과>를 붙인다.
검증이 명시된 Task의 [x]는 기능/산출물과 해당 검증이 모두 충족되었다는 뜻이다. 검증이 명시되지 않은 Task의 [x]는 기능/산출물 완료 근거가 충분하다는 뜻이다.
에이전트가 확정할 수 없는 검토/선택/우선순위 항목은 기능 Task로 쓰지 않는다. 현재 구현에 직접 필요하면 구현 잠금 > 결정 필요 또는 SDD USER_REVIEW.md로 분리하고, 그렇지 않으면 작업 컨텍스트에 표준선/가정/후속 후보로 남긴다.
기능 섹션의 Task 체크리스트는 Epic 바로 아래의 flat list를 기본으로 한다. 구현 세부, 테스트만 따로 떼어낸 하위 체크박스는 roadmap에 만들지 말고 plan 내부 체크리스트나 같은 Task의 검증:으로 흡수한다.
Epic heading은 ### Epic: [epic-id] <이름> 형식을 사용한다.
Task는 - [ ] [item-id] 설명 또는 - [x] [item-id] 설명 형식을 사용한다.
epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 영문/숫자 segment 1~~4개로 작성하고 segment 구분자는 -, _, +, =만 사용한다. 가능하면 1~~3 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>를 판별하고, 상태 체크 후 Core/MCP action으로 Milestone 업데이트를 호출한다. Core/MCP action이 없으면 update-roadmap file-based fallback 흐름을 호출한다. 단, Milestone 기능 Task 체크는 complete.log에 Roadmap Completion 섹션과 명시 Task id가 있을 때만 수행하고, 섹션이 없으면 no-op으로 둔다.
SDD 대상 Milestone은 런타임 완료 이벤트의 complete.log에 있는 Roadmap Completion과 최종 검증 evidence가 SDD Evidence Map을 충족해야 roadmap Task 체크 후보가 된다. 단, 사용자가 명시적으로 evidence를 전달한 수동 update-roadmap 갱신에서는 Evidence Map 충족 근거를 보조 근거로 사용할 수 있다.
런타임 완료 이벤트가 최종 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에서 후속 계획/리뷰를 이어가지만, code-review의 user-review gate가 트리거되면 연결된 Milestone 잠금 결정을 USER_REVIEW.md에 남긴다.
[스케치] Milestone은 Milestone 기반 agent-task 생성 대상이 아니다. 런타임이나 plan 스킬은 이를 구현 작업으로 라우팅하지 않고 [계획] 승격 필요를 보고한다.

완료 리뷰

Task 완료나 Milestone 갱신 시 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 [x]가 되었는지 확인하고, 구현 잠금이 해제이며 미완료 결정 필요 항목이 없는지 함께 확인한다.
기능 Task가 모두 충족되어도 구현 잠금이 남아 있으면 Milestone을 [검토중]으로 바꾸지 않는다. 완료 리뷰 또는 작업 컨텍스트에 잠금 차단 항목을 남기고, 잠금 해소 roadmap 갱신을 먼저 요구한다.
기능 Task와 구현 잠금이 모두 충족된 것으로 보이면 Milestone을 [완료]로 바로 바꾸거나 archive로 이동하지 말고 [검토중]으로 바꾼다.
[검토중]으로 바꿀 때는 Milestone 문서에 완료 리뷰 섹션을 만들거나 갱신하고, 완료 근거 1~3줄과 남은 차단 항목을 남긴다. 에이전트가 확정할 수 없는 결정 항목은 완료 리뷰가 아니라 구현 잠금 > 결정 필요 또는 SDD USER_REVIEW.md로 분리한다.
기능 Task, 검증, 구현 잠금이 모두 충족되면 [완료] 전환과 archive 이동을 수행할 수 있다.
Phase도 모든 하위 Milestone이 [완료] 또는 [폐기]로 정리되고 Phase 목표가 충족되면 [완료] 또는 [폐기]로 전환한다.

로드맵 현지점

현재 작업 지점이나 로드맵상 현 위치 확인 요청은 analyze-roadmap-position 스킬로 처리한다.
답변은 agent-ops/skills/common/_templates/roadmap-position-report-template.md 섹션과 필드 순서를 따른다.
기본 동작에서는 코드, git 상태, diff를 읽지 않고 로드맵 > Phase > Milestone breadcrumb와 흐름 목록으로 현재 좌표를 보여준다.
current가 Phase 또는 Milestone 후보를 여럿 가리키면 모두 현재 후보로 표시하고 짧은 역할 태그만 붙인다.

30 KiB Raw Blame History

로드맵 규칙

구조

링크 표기

Runtime Action Boundary

로딩

Phase와 Milestone 선택

상태 표기

구현 잠금

프로젝트 간 잠금

SDD 게이트

Epic과 Task id

Milestone 기반 agent-task

완료 리뷰

로드맵 현지점

아카이브

30 KiB

Raw Blame History