# NomadCode 로드맵

## 전체 목표

NomadCode는 Flutter 기반 앱, core 서비스, 공유 계약, agent-operation 규칙을 하나의 원레포로 묶어 AI-assisted development workflow를 조율하는 프로젝트다.

현재 로드맵은 [ROADMAP.md](ROADMAP.md) -> [Agent-Ops Work Item Lifecycle PHASE.md](phase/agent-ops-work-item-lifecycle/PHASE.md) -> [Milestone Execution Lifecycle Sync](phase/agent-ops-work-item-lifecycle/milestones/milestone-execution-lifecycle-sync.md) 같은 scaffold를 기준으로 관리한다. React/Vite 웹 콘솔 제거, 서버/Plane/provider 기반 작업, Flutter-first 클라이언트 정리, Mattermost push plugin extraction, client integration 표준화, workspace 포트/환경 표준화, External Integration, Milestone Work Item Creation Sync, Plane Work Item Webhook Intake, Gito Branch Event Creation Sync Bridge, Gito proto-socket consumer wire readiness, Gito HTTP Webhook Consumer Readiness, Plane-Origin Authoring Roundtrip Sync, Roadmap Driven Agent-Ops Automation, Agent-Origin Milestone Creation Sync는 완료되었다. Agent-Ops Work Item Lifecycle에서는 다음 후보인 Milestone Execution Lifecycle Sync로 Todo 이후 실행 lifecycle을 다룬다. 외부 agent 제어 표면과 MCP 여부는 현재 ops 작업과 섞지 않고 별도 MCP Control Surface Phase로 분리해 가장 뒤의 스케치로 미룬다.

IOP 외부 실행 호출은 OpenAI-compatible Responses API 방식을 기본 계약으로 채택하고, NomadCode/IOP 고유의 task, workspace, session, approval, artifact, notification 문맥은 별도 `iop` wrapper field가 아니라 `metadata` 확장으로 전달한다. A2A는 agent-to-agent delegation이 명확히 필요할 때 재검토하며, IOP native protocol은 NomadCode의 기본 외부 실행 호출 표면으로 쓰지 않는다.

## Phase 흐름

위에서 아래로 진행된 순서와 예정 흐름을 나타낸다.
완료된 Phase도 로드맵에서 제거하지 않고, archive의 Phase 문서로 연결한다.
검토중 또는 진행중 Phase는 계획 Phase보다 위에 두어, 아래로 갈수록 미래 계획에 가까워지게 정렬한다.

- [완료] Server Skeleton
  - 경로: [Server Skeleton PHASE.md](archive/phase/server-skeleton/PHASE.md)
  - 요약: core 서버 실행 골격, task 저장 구조, 비동기 job 실행, Adapter stub을 구성했다.
- [완료] Plane Communication Foundation
  - 경로: [Plane Communication Foundation PHASE.md](archive/phase/plane-communication-foundation/PHASE.md)
  - 요약: Plane self-hosted 인스턴스와 통신하기 위한 인증, API client, 외부 참조 저장, smoke 검증 토대를 만들었다.
- [완료] Client Platform Consolidation
  - 경로: [Client Platform Consolidation PHASE.md](archive/phase/client-platform-consolidation/PHASE.md)
  - 요약: React/Vite 웹 콘솔을 제품 UI 경로에서 걷어내고 Flutter 앱을 NomadCode 클라이언트 source of truth로 정리했다.
- [완료] Work Item Provider Pipeline Design
  - 경로: [Work Item Provider Pipeline Design PHASE.md](archive/phase/work-item-provider-pipeline-design/PHASE.md)
  - 요약: Plane/Jira 등 work item provider와 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 provider-neutral하게 정리했다.
- [완료] Mattermost Push Plugin Extraction
  - 경로: [Mattermost Push Plugin Extraction PHASE.md](archive/phase/mattermost-push-plugin-extraction/PHASE.md)
  - 요약: Flutter 앱에 섞인 Mattermost push notification migration을 분리했고, 현재 package 경로는 `../nexo/packages/messaging_flutter`다.
- [완료] Workflow Core
  - 경로: [Workflow Core PHASE.md](archive/phase/workflow-core/PHASE.md)
  - 요약: proto-socket 내부 통신 레일을 정리한 뒤 client-core 통신과 실제 e2e 흐름을 기준으로 task lifecycle, retry, timeout, notification event를 안정화한다.
- [완료] External Integration
  - 경로: [External Integration PHASE.md](archive/phase/external-integration/PHASE.md)
  - 요약: Plane 확장, Jira-compatible provider 추상화, Mattermost, Agent Integrator, IOP OpenAI-compatible Responses 호출 경계를 실제 통합 adapter 흐름으로 확장했고, metadata 실행 문맥 전달, IOP Edge `/v1/responses`, NomadCode Core 원격 create/enqueue/poll smoke를 완료했다.
- [진행중] Agent-Ops Work Item Lifecycle
  - 경로: [Agent-Ops Work Item Lifecycle PHASE.md](phase/agent-ops-work-item-lifecycle/PHASE.md)
  - 요약: 로드맵 기반 agent-ops 운영 자동화와 Plane/Jira 같은 work item provider의 Todo 이후 실행 lifecycle을 다룬다. 다음 후보는 Milestone Execution Lifecycle Sync이며, MCP와 외부 agent 제어 표면은 이 Phase 범위에서 제외한다.
- [계획] Project Workspace Management UX
  - 경로: [Project Workspace Management UX PHASE.md](phase/project-workspace-management-ux/PHASE.md)
  - 요약: client integration 표준화, core workflow, 외부 통합 기준 이후 프로젝트 단위 앱 UX를 다루며, provider slot 기반 외부 console composition은 계획 후보로 둔다.
- [스케치] MCP Control Surface
  - 경로: [MCP Control Surface PHASE.md](phase/mcp-control-surface/PHASE.md)
  - 요약: 외부 agent 제어 표면을 MCP로 둘지 여부, tool policy, 권한, side effect 경계를 현재 ops lifecycle과 분리해 마지막 후보로 검토한다.

## 로딩 정책

- 일반 작업에서는 [ROADMAP.md](ROADMAP.md)를 매번 읽지 않는다.
- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 [current.md](current.md)를 먼저 읽는다.
- `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
- `current.md`의 활성 Phase는 [Agent-Ops Work Item Lifecycle PHASE.md](phase/agent-ops-work-item-lifecycle/PHASE.md)를 가리킨다.
- `current.md`의 활성 Milestone은 [Milestone Execution Lifecycle Sync](phase/agent-ops-work-item-lifecycle/milestones/milestone-execution-lifecycle-sync.md)를 가리킨다.
- `current.md`는 `agent-roadmap/archive/**` 경로를 활성 항목으로 포함하지 않는다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Phase와 Milestone 문서를 같은 세션에서 1회 읽는다.
- 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다.
- 상세 작업은 각 Milestone 문서의 `기능`으로 관리한다. 검증이 필요한 기능만 같은 Task 안에 `검증:`으로 통합한다.
- 모든 기능 Task와 Task 안에 명시된 검증이 충족된 Milestone은 먼저 `[검토중]`으로 두고, 사용자 완료 확인과 archive 승인을 받은 뒤 `[완료]`로 전환한다.
- 완료된 Phase는 archive의 해당 PHASE 문서로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 해당 archive milestones 디렉터리로 이동한다.
- archive `PHASE.md`는 Phase 자체가 완료 또는 폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다.
- `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라가서 읽는다.
- 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.
- 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획 생성, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다.
- 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조/도메인 rule/플랫폼 관례로 정할 수 있는 작업은 표준선으로 기록하고 진행할 수 있다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `구현 잠금` 상태를 `해제`로 둔다.