# Milestone: Roadmap Driven Agent-Ops Automation

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md`

## 목표

NomadCode가 로드맵을 중심으로 사용자 입력, 실행 상태, 출력 검토, 완료 승인까지 한 흐름에서 운영하도록 Roadmap Operations Control Plane의 방향을 정한다. Plane은 사용자가 work item 상태를 움직이는 primary control UI이며, NomadCode Core는 Plane command를 검증해 roadmap/workflow/action side effect를 실행하고, agent-roadmap은 장기 원장으로 유지한다. 외부 에이전트는 MCP-first 제어 표면을 통해 Core를 호출하며, agent-ops 스킬은 문서 작성, 의미 해석, 변경 제안, MCP 호출 준비 계층으로 낮춘다.

## 상태

[계획]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- NomadCode Core가 품을 roadmap/action core 책임 정의
- MCP-first 외부 agent 제어 표면 방향 정의
- HTTP API와 MCP의 역할 분리
- 사용자 입력, 출력 검토, 승인, 보완, archive 확인을 NomadCode 라인에서 처리하는 흐름 정의
- Plane 상위 티켓 1개를 Milestone 1개로 보고, Plane 하위 티켓을 Milestone 기능 Task로 투영하는 사용자 플로우 계약 정의
- Plane 상태 `Backlog`, `Todo`, `In Progress`, `User Review`, `Done`, `Cancelled`를 roadmap/agent-task lifecycle command로 해석하는 기준 정의
- `Todo + AGENT assignee`에서 Milestone 초안을 작성하고, `In Progress`에서 실제 실행과 하위 티켓 생성을 시작하는 gate 정의
- agent-ops roadmap skills를 작성/제안/MCP 호출 준비 계층으로 낮추는 방향 정의
- completion event, `USER_REVIEW.md`, 완료 리뷰, dependency lock을 Core action으로 다루는 기준 정의

## 기능

### Epic: [control-plane] Roadmap operations control plane

NomadCode 내부 core logic이 roadmap 기반 작업 운영을 소유하고, 외부 agent는 MCP를 통해 제어하는 구조를 정리한다.

- [ ] [core-state] roadmap, Phase, Milestone, plan, code-review, completion event, approval 상태를 Core가 다루는 state model과 revision/idempotency 계약으로 정리한다.
- [ ] [core-actions] validate, position, propose/apply change, transition, archive, dependency check, completion event ingest를 Core action 후보로 정의한다.
- [ ] [mcp-tools] 외부 agent용 MCP tool 표면을 Core action wrapper로 정의하고 `dry_run`, `expected_revision`, `idempotency_key`, `actor`, `reason` 입력 원칙을 정한다.
- [ ] [http-role] HTTP API는 Flutter UI, webhook, internal integration용 표면으로 유지하고, 외부 agent 제어는 MCP-first로 여는 기준을 정한다.
- [ ] [review-gates] 사용자 입력, 출력 검토, `USER_REVIEW.md`, 완료 승인, archive 승인을 NomadCode workflow 안의 review gate로 처리하는 흐름을 정한다.
- [ ] [plane-control-flow] Plane을 primary control UI로 쓰는 lifecycle을 정리한다. 검증: `Backlog -> Todo -> In Progress -> User Review -> Done` 상태가 Milestone 초안, 실행 시작, 사용자 검토, 완료 archive로 어떻게 연결되는지 문서에서 일관되게 읽힌다.
- [ ] [plane-identity] Plane 상위 티켓을 Milestone, 하위 티켓을 Milestone 기능 Task로 매핑하는 id 계약을 정한다. 검증: Milestone id는 파일명으로 유지하고, Plane work item id는 외부 provider id로 보존하는 기준이 명확하다.
- [ ] [todo-draft-gate] `Todo + AGENT assignee`를 Milestone 초안 생성/갱신 gate로 정의한다. 검증: Todo 진입이 자동 실행이 아니라 사용자 검토용 Milestone 작성 단계임이 명확하다.
- [ ] [in-progress-exec-gate] 사용자가 Plane 상위 티켓을 `In Progress`로 옮길 때 실제 실행과 하위 티켓 전환을 시작하는 기준을 정한다. 검증: Milestone Task가 Plane 하위 티켓으로 생성되고 plan/code-review 루프로 들어가는 시점이 명확하다.
- [ ] [child-task-review-policy] Milestone에서 만들어진 하위 작업은 막혔을 때만 `User Review`로 보내고, 정상 PASS 시 기본적으로 `Done`으로 보내는 정책을 정한다. 검증: 하위 작업의 기본 완료 흐름과 blocker review 흐름이 구분된다.
- [ ] [milestone-review-loop] 모든 하위 작업이 완료되면 상위 Milestone 티켓을 `User Review`로 보내고, 사용자가 `Done`으로 옮기면 완료/archive, `Todo`로 되돌리면 보완 루프로 처리하는 기준을 정한다.
- [ ] [skill-adapter] agent-ops roadmap skills가 action owner가 아니라 semantic authoring/proposal layer와 MCP call preparation layer가 되도록 축소 기준을 정한다.
- [ ] [first-slice] 첫 구현 단위를 `roadmap.validate`, `roadmap.get_position`, `roadmap.ingest_completion_event` 중 어떤 순서로 자를지 정한다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- IOP 내부 모델 라우팅, MCP/tool policy, output validation, RAG, context compression 구현
- 전체 Flutter UI 구현
- Plane/Jira/Mattermost provider projection 세부 구현, Plane webhook/하위 티켓 생성 adapter 실제 구현
- 사용자 승인 없는 자동 archive 이동
- agentic-framework 공통 스킬의 실제 개편

## 작업 컨텍스트

- 관련 경로: `services/core/internal/workflow/`, `services/core/internal/scheduler/`, `services/core/internal/http/`, `packages/contracts/`, `agent-roadmap/`, `agent-ops/skills/common/update-roadmap/SKILL.md`, `agent-ops/skills/common/plan/SKILL.md`, `agent-ops/skills/common/code-review/SKILL.md`
- 표준선(선택): Plane은 사용자의 primary control UI이고, Plane 상태 변화는 NomadCode Core가 검증해 실행하는 command로 본다. NomadCode Core는 roadmap/action side effect와 idempotency/revision 검증을 소유하고, agent-roadmap은 장기 원장으로 유지한다. agent-ops 스킬은 사용자의 자연어와 문서 초안을 Core/MCP 호출 입력으로 정리한다.
- 로컬 제어 표면 후보: `http://127.0.0.1:8080/v1`
- 선행 작업: Workflow Core, External Integration, Project Workspace Management UX, 로드맵 스킬 운영 복잡도 평가
- 후속 작업: Roadmap Operations Control Plane 첫 구현 slice, MCP tool contract 작성
- 현재 지점: 사용자 결정에 따라 현재 작업 후보에서 제외하고 로드맵 마지막 Phase로 이동했다. Workflow Core와 외부 통합, 프로젝트 제어 UX가 먼저 닫힌 뒤 roadmap/action core 책임과 MCP-first 제어 표면을 구현 가능한 Core action 후보로 정리한다.
- 용어 경계: Plane `User Review`는 provider board state이고, agent-task `USER_REVIEW.md`는 자동 plan/code-review 루프를 멈추는 내부 stop artifact다. 둘은 모두 사용자 판단 신호지만 저장 위치와 트리거가 다르다.
- Plane 제어 플로우:
  - `Backlog`: 아이디어/후보이며 아직 Milestone 확정이 아니다.
  - `Todo + AGENT assignee`: NomadCode가 Plane 티켓 내용을 바탕으로 Milestone 초안을 생성하거나 갱신한다. 원본 사용자 요청은 Plane comment 히스토리로 보존하고, Milestone 본문에는 정제된 목표/범위/기능/작업 컨텍스트를 둔다.
  - `In Progress`: 사용자가 Milestone 초안을 검토한 뒤 실행을 승인한 상태다. NomadCode는 Milestone 기능 Task를 Plane 하위 티켓으로 전환하고 `agent-task/m-<milestone-id>` plan/code-review 루프를 시작한다.
  - 하위 티켓: Milestone에서 만들어진 작업은 정상 PASS 시 기본적으로 `Done`으로 이동한다. 작업 중 사용자 결정, 외부 환경, 범위 충돌처럼 자동 진행이 막힐 때만 `User Review`로 이동한다.
  - `User Review`: 상위 Milestone 티켓은 모든 하위 작업이 완료되었거나 사용자 판단이 필요한 경우 이동한다. 사용자가 `Done`으로 옮기면 `[완료]`와 archive를 수행하고, `Todo`로 되돌리면 내부 Milestone을 `[진행중]`/보완 필요로 되돌려 추가 요구사항을 반영하는 루프로 처리한다.
  - `Done`: 사용자 최종 완료 승인이다.
  - `Cancelled`: 폐기 또는 중단 루트다.
- 확인 필요: 없음
