toki/nomadcode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nomadcode/agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md

21 KiB
Raw Permalink Blame History

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/Jira 같은 work item provider는 사용자가 작업 상태를 움직이는 primary control UI가 될 수 있으며, NomadCode Core는 provider command와 agent-roadmap 변경을 같은 sync domain에서 검증해 Milestone item과 work item이 동일한 구조로 수렴하도록 한다. agent-roadmap은 장기 원장으로 유지하고, agent-ops 스킬은 문서 작성, 의미 해석, 변경 제안 계층으로 낮춘다. 외부 agent 제어 표면은 이 마일스톤의 확정 범위가 아니며 후속 스케치에서 별도로 검토한다.

상태

[완료]

승격 조건

  • 없음

구현 잠금

  • 상태: 해제
  • SDD: 불필요 - 상위 방향과 계약 정리용 문서 마일스톤이며, 기능 Task의 문서/계약 산출물 검증으로 닫는다.
  • 결정 필요: 없음

범위

  • NomadCode Core가 품을 roadmap/action core 책임 정의
  • HTTP API, provider webhook, internal integration의 역할 경계 정의
  • 사용자 입력, 출력 검토, 승인, 보완, archive 확인을 NomadCode 라인에서 처리하는 흐름 정의
  • Plane 상위 티켓 1개를 Milestone 1개로 보고, Plane 하위 티켓을 Milestone 기능 Task로 투영하는 사용자 플로우 계약 정의
  • Plane/Jira 같은 provider work item과 agent-roadmap Milestone item 사이의 양방향 동기화 도메인 책임, 변경 감지, 수렴 정책 정의
  • Plane/Jira provider project 단위로 sync를 묶고 provider project target, git remote, 실제 작업 workspace 설정을 Core DB 모델로 관리하는 기준 정의
  • Plane-origin authoring에서 workspace agent를 IOP CLI 1차 통로로 실행하는 기준 정의
  • Plane 상태 Backlog, Todo, In Progress, User Review, Done, Cancelled를 roadmap/agent-task lifecycle command로 해석하는 기준 정의
  • Backlog + AGENT assignee에서 Milestone 초안을 작성하고 Plane 티켓을 Todo 검토 상태로 옮긴 뒤, 사용자가 In Progress로 옮길 때 실제 실행과 하위 티켓 생성을 시작하는 gate 정의
  • agent-ops roadmap skills를 작성/제안 계층으로 낮추는 방향 정의
  • completion event, USER_REVIEW.md, 완료 리뷰, dependency lock을 Core action으로 다루는 기준 정의

기능

Epic: [control-plane] Roadmap operations control plane

NomadCode 내부 core logic이 roadmap 기반 작업 운영을 소유하고, provider/UI/agent 입력을 검증 가능한 Core action으로 수렴시키는 구조를 정리한다.

  • [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 후보로 정의한다.
  • [http-role] HTTP API는 Flutter UI, webhook, internal integration용 표면으로 유지하고, 실행 side effect는 Core action의 revision/idempotency 계약을 거치도록 하는 기준을 정한다.
  • [review-gates] 사용자 입력, 출력 검토, USER_REVIEW.md, 완료 승인, archive 승인을 NomadCode workflow 안의 review gate로 처리하는 흐름을 정한다.
  • [plane-control-flow] Plane을 primary control UI로 쓰는 lifecycle을 정리한다. 검증: Backlog + AGENT assignee -> Todo -> In Progress -> User Review -> Done/Cancelled 상태가 Milestone 초안, 사용자 검토, 실행 시작, 사용자 검토, 완료/archive 또는 폐기로 어떻게 연결되는지 문서에서 일관되게 읽힌다.
  • [plane-identity] Plane 상위 티켓을 Milestone, 하위 티켓을 Milestone 기능 Task로 매핑하는 id 계약을 정한다. 검증: Milestone id는 파일명으로 유지하고, Plane work item id는 외부 provider id로 보존하는 기준이 명확하다.
  • [todo-draft-gate] Backlog + AGENT assignee를 Milestone 초안 생성/갱신 trigger로 정의하고, develop branch의 agent-roadmap에 반영된 뒤 Plane 티켓을 Todo로 이동하는 gate를 정한다. 검증: Todo 진입은 자동 실행이 아니라 develop에 존재하는 Milestone의 사용자 검토 단계임이 명확하다.
  • [in-progress-exec-gate] 사용자가 Plane 상위 티켓을 In Progress로 옮길 때 실제 실행과 하위 티켓 전환을 시작하는 기준을 정한다. 검증: Milestone Task가 Plane 하위 티켓으로 생성되고 plan/code-review 루프로 들어가는 시점이 명확하다.
  • [cancelled-discard] 사용자가 Plane 상위 티켓을 Cancelled로 옮길 때 Milestone 초안 폐기 또는 보류를 처리하는 기준을 정한다. 검증: Plane 폐기 상태가 agent-roadmap의 [폐기] 또는 [보류] 중 어느 상태로 연결되는지와 사용자 승인 없는 archive 이동 금지가 설명된다.
  • [child-task-review-policy] Milestone에서 만들어진 하위 작업은 막혔을 때만 User Review로 보내고, 정상 PASS 시 기본적으로 Done으로 보내는 정책을 정한다. 검증: 하위 작업의 기본 완료 흐름과 blocker review 흐름이 구분된다.
  • [milestone-review-loop] 모든 하위 작업이 완료되면 상위 Milestone 티켓을 User Review로 보내고, 사용자가 Done으로 옮기면 완료/archive, Todo로 되돌리면 보완 루프로 처리하는 기준을 정한다.
  • [first-slice] 첫 구현 단위를 roadmap.validate, roadmap.get_position, roadmap.ingest_completion_event 중 어떤 순서로 자를지 정한다.

Epic: [sync-domain] Milestone/work item sync domain

Plane/Jira 같은 provider work item과 agent-roadmap Milestone item을 동일한 작업 구조로 유지하는 별도 Core sync domain을 정의한다.

  • [sync-owner] sync domain의 소유 책임을 정의한다. 검증: provider adapter는 native API read/write만 담당하고, Milestone/work item identity mapping, revision 비교, 수렴 적용은 Core sync domain 책임으로 읽힌다.
  • [sync-identity] Milestone, Epic/Task item id, provider work item id, parent-child 관계, provider revision, roadmap revision을 묶는 identity 계약을 정한다. 검증: Plane/Jira 어느 쪽에서 시작해도 같은 Milestone item 구조로 매핑되는 기준이 명확하다.
  • [sync-project-config] provider project 단위 sync 설정 모델과 저장 경계를 정한다. 검증: provider project target, git remote URL, source-of-truth branch, workspace id/path가 Core DB에 저장되는 project sync 설정으로 정의되고, 설정 누락 또는 중복 시 생성 동기화를 진행하지 않는 기준이 있다.
  • [sync-detection] provider webhook, provider polling, roadmap file/index scan, agent-task completion event를 같은 변경 감지 입력으로 정리한다. 검증: 양쪽 중 어느 쪽에서 변경이 발생해도 sync event로 정규화되는 흐름이 문서화되어 있다.
  • [sync-convergence] 한쪽 변경을 다른 쪽에 반영해 Milestone item과 work item이 동일 형태로 수렴하는 apply 정책을 정한다. 검증: 생성, 제목/설명, 상태, parent-child, 완료/검토 흐름이 양방향으로 어떻게 반영되는지 설명된다.
  • [sync-conflict] 동시 수정, revision mismatch, 삭제/archive, 사용자 승인 필요 변경의 conflict 처리 정책을 정한다. 검증: Core가 조용히 덮어쓰지 않고 review gate 또는 dry-run proposal로 멈추는 기준이 있다.
  • [sync-schedule] sync domain의 scheduler 책임을 정한다. 검증: webhook이 없는 provider나 누락 이벤트를 주기 polling으로 보정하고, 같은 idempotency/revision 계약을 쓰는 방향이 명확하다.
  • [sync-contract] packages/contracts에 sync event/action 후보를 남긴다. 검증: roadmap_sync.inspect, roadmap_sync.apply, roadmap_sync.changed 같은 후보 표면과 필수 입력 필드가 compatibility note에 정리되어 있다.
  • [plane-origin-flow] Plane-origin Milestone 생성 시나리오를 정한다. 검증: Backlog 티켓 본문을 입력으로 IOP CLI 1차 통로를 통해 실행된 workspace agent가 같은 Milestone 파일 작성/push 경로에서 roadmap skill로 Milestone 초안을 만들고, develop 반영 후 sync layer가 pushed Milestone의 provider/work item identity를 검증한 뒤 원본 본문은 사용자 요청: 댓글로 보존하며, Plane 본문은 develop의 Milestone 내용으로 치환하고, 제목은 [milestone-id] 제목 형식으로 바꾼 뒤 Todo로 이동하는 순서가 문서화되어 있다.
  • [agent-origin-flow] Agent-origin Milestone 생성 시나리오를 정한다. 검증: 에이전트 대화로 생성된 Milestone이 develop branch에 반영되었을 때 Plane parent ticket을 Todo 상태로 생성하고 identity map을 연결하는 흐름이 문서화되어 있다.
  • [sync-idempotency] Plane-origin과 Agent-origin 생성의 중복 방지와 부분 실패 복구 정책을 정한다. 검증: 같은 Plane 티켓 또는 같은 Milestone path가 재처리되어도 중복 Milestone/티켓을 만들지 않고, 댓글 보존/본문 치환/제목 변경/상태 이동 중 실패한 단계를 재시도할 수 있다.

완료 리뷰

  • 상태: 통과
  • 요청일: 2026-06-23
  • 완료 근거: Roadmap Operations Control Plane과 Milestone/work item sync domain의 상위 계약 후보가 packages/contracts/notes/flutter-core-api-candidates.md에 compatibility note로 정리되었고, 관련 core sync 경계 테스트가 통과했다. 이 문서의 기능 Task가 모두 충족되었고, 구현 잠금은 해제 상태이며 SDD는 불필요로 판정되어 있다.
  • 리뷰 필요:
    • 사용자가 완료 결과를 확인했다
    • archive 이동을 승인했다
  • 리뷰 코멘트: 2026-06-23 코드 레벨 종료 검토에서 stale README 표현을 보정했고, 관련 core packages 테스트와 문서 diff 검증이 통과해 archive했다.

범위 제외

  • IOP 내부 모델 라우팅, output validation, RAG, context compression 구현
  • 외부 agent 제어 표면과 tool policy 확정 또는 구현
  • 전체 Flutter UI 구현
  • Project sync 설정 관리 UI/UX 실제 구현
  • Plane/Jira/Mattermost provider projection 세부 구현, Plane webhook/하위 티켓 생성 adapter 실제 구현. 단, Milestone/work item sync domain의 provider-neutral 책임과 계약 후보 정의는 포함한다.
  • 사용자 승인 없는 자동 archive 이동
  • agentic-framework 공통 스킬의 실제 개편

작업 컨텍스트

  • 관련 경로: services/core/internal/workflow/, services/core/internal/scheduler/, services/core/internal/http/, services/core/internal/workitem/, services/core/internal/db/, services/core/migrations/, services/core/queries/, 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
  • 표준선(선택): develop branch의 agent-roadmap을 Milestone sync의 source of truth로 둔다. Plane/Jira 같은 work item provider는 사용자의 primary control UI와 projection 표면이 될 수 있고, provider 상태 변화와 agent-roadmap 변경은 NomadCode Core sync domain이 검증해 실행하는 command로 본다. NomadCode Core는 roadmap/action side effect, Milestone/work item identity mapping, idempotency/revision 검증, conflict review gate를 소유하고, agent-ops 스킬은 사용자의 자연어와 문서 초안을 Core action 제안 입력으로 정리한다.
  • 프로젝트 설정 기준: Sync는 Plane/Jira provider project 단위로 묶으며, 각 project sync 설정은 provider project target, git remote URL, source-of-truth branch, 실제 작업 workspace를 Core DB에 저장한다. 이 설정은 이후 Project settings UI/UX에서 확인/수정할 수 있어야 한다.
  • 로컬 제어 표면 후보: http://127.0.0.1:8080/v1
  • 선행 작업: Workflow Core, External Integration, Project Workspace Management UX, 로드맵 스킬 운영 복잡도 평가
  • 후속 작업: Milestone Execution Lifecycle Sync, 외부 agent 제어 표면 스케치
  • 현재 지점: 이 Phase의 Milestone Work Item Creation Sync, Plane Work Item Webhook Intake, Gito branch/webhook wakeup 연동은 완료되어 archive에 남아 있다. 이 마일스톤은 roadmap/action core 책임과 Milestone/work item sync domain을 구현 가능한 Core action 후보로 정리하는 상위 설계/계약 문서이며, Milestone/work item sync domain의 후보 계약은 packages/contracts/notes/flutter-core-api-candidates.md까지 반영되어 있다.
  • 완료 체크 근거:
    • [plane-control-flow], [plane-identity], [todo-draft-gate], [plane-origin-flow]: Phase 흐름에 완료로 남은 Milestone Work Item Creation Sync와 Plane Work Item Webhook Intake가 Plane-origin Milestone 작성, Todo projection, provider identity 보존, Backlog+AGENT webhook intake까지 닫은 근거다.
    • [in-progress-exec-gate], [cancelled-discard], [child-task-review-policy], [milestone-review-loop]: 이 문서의 Plane 제어 플로우가 Todo -> In Progress -> User Review -> Done/Cancelled 이후 실행 시작, 하위 티켓 기본 완료/차단 리뷰, 상위 Milestone 완료/보완/폐기 루프를 설명한다.
    • [sync-owner]: 현재 문서의 동기화 도메인 방향이 provider adapter와 Core sync domain 책임을 분리하고, 완료된 Plane/Gito sync slice가 이 경계를 따라 구현되어 있다.
    • [sync-project-config]: project sync 설정 기준이 현재 문서에 남아 있고, Core 내부 경로 services/core/internal/projectsync/, services/core/internal/roadmapsync/, services/core/internal/roadmapsyncpipeline/가 provider project target, repository, workspace 기반 동기화 경계를 구현한다.
    • [core-state], [core-actions], [http-role], [review-gates], [first-slice]: packages/contracts/notes/flutter-core-api-candidates.md의 Roadmap Operations Control Plane 계약 후보가 roadmap state model, roadmap.validate/get_position/propose_change/apply_change/transition/archive/dependency_check/ingest_completion_event, HTTP wrapper 원칙, review gate, 첫 구현 순서를 compatibility note로 정리한다.
    • [sync-identity], [sync-detection], [sync-convergence], [sync-conflict], [sync-schedule], [sync-contract]: packages/contracts/notes/flutter-core-api-candidates.md의 Roadmap / Work Item Sync 계약 후보가 identity field, roadmap_sync.changed, roadmap_sync.inspect/apply/reconcile, convergence, conflict, polling 보정 기준을 compatibility note로 정리한다.
    • [agent-origin-flow], [sync-idempotency]: 이 문서의 Agent-origin 생성 플로우와 시나리오 점검, contracts note의 idempotency/revision 원칙이 develop 반영 후 Plane Todo 생성, identity map 연결, 중복 적용 방지, 단계별 재시도 경계를 설명한다.
  • 실행 경계: 이 마일스톤은 상위 방향과 계약 정리용이다. 실제 구현은 Milestone Work Item Creation Sync부터 진행하고, Milestone Execution Lifecycle Sync는 사용자가 해제할 때까지 잠근다.
  • 동기화 도메인 방향:
    • Sync domain은 provider adapter보다 위에 위치하며, provider native DTO를 직접 소유하지 않는다.
    • Sync domain의 Milestone source of truth는 develop branch의 agent-roadmap이다. Plane/Jira work item은 intake/projection/review UI로 본다.
    • Sync domain은 provider project 단위 project sync 설정을 먼저 해석한 뒤 git repository와 workspace를 선택한다.
    • Plane-origin authoring은 IOP CLI 1차 통로로 workspace agent를 실행하며, 이 통로가 없으면 Plane authoring 단계는 잠긴다.
    • Sync domain은 Milestone <-> provider parent work item, Milestone Task <-> provider child work item 관계를 같은 identity map으로 관리한다.
    • 변경 감지는 provider webhook을 우선하되, 누락/미지원 provider는 scheduler polling으로 보정한다.
    • agent-roadmap 문서 변경, provider work item 변경, agent-task completion event는 모두 같은 provider-neutral sync event로 정규화한다.
    • 양쪽 변경이 충돌하면 조용히 덮어쓰지 않고 expected revision mismatch로 멈춘 뒤 사용자 review gate 또는 dry-run proposal로 올린다.
  • 용어 경계: Plane User Review는 provider board state이고, agent-task USER_REVIEW.md는 자동 plan/code-review 루프를 멈추는 내부 stop artifact다. 둘은 모두 사용자 판단 신호지만 저장 위치와 트리거가 다르다.
  • Plane 제어 플로우:
    • Backlog: 사용자가 해야 할 일을 Plane 상위 티켓으로 작성하는 아이디어/요청 상태다.
    • Backlog + AGENT assignee: 실제 등록된 agent user에게 티켓이 할당되면 NomadCode가 Plane 티켓 본문을 읽고, project sync 설정으로 선택한 workspace slot 안에서 IOP CLI 1차 통로로 workspace agent를 실행해 roadmap skill로 Milestone 파일을 생성하거나 갱신한다.
    • Milestone 초안 생성 후: NomadCode는 Plane 티켓 본문을 기반으로 workspace agent가 Milestone 파일을 만들게 하되, develop branch의 agent-roadmap에 commit/push되기 전까지 Plane Todo projection 대상으로 보지 않는다.
    • develop 반영 후: NomadCode는 원본 사용자 본문을 Plane 댓글에 사용자 요청: prefix로 보존하고, Plane 본문을 develop에 반영된 Milestone 내용으로 치환하며, 제목을 [milestone-id] 제목 형식으로 바꾼 뒤 티켓을 Todo로 옮긴다. 여기서 milestone-id는 develop의 Milestone 파일 slug를 기본값으로 쓴다.
    • Todo: 사용자가 develop에 존재하는 Milestone 내용을 Plane에서 검토하는 상태다. 자동 실행 gate가 아니며, 사용자는 작업 착수 시 In Progress, 폐기 시 Cancelled로 옮긴다.
    • 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: 기본적으로 폐기 후보 루트이며, 일시 중단으로 해석해야 하는 경우에는 [보류] 후보로 사용자 review gate에 올린다. archive 이동은 사용자의 명시 승인 전에는 수행하지 않는다.
  • Agent-origin 생성 플로우:
    • 에이전트와의 대화 중 사용자가 Milestone 생성을 요청하면 현재 roadmap 규칙에 따라 프로젝트 안에 Milestone 문서를 만든다.
    • 생성된 Milestone이 develop branch에 반영되면 sync domain은 해당 Milestone을 Plane 상위 티켓으로 생성하고 Todo 상태에 둔다.
    • Plane 티켓 제목은 [milestone-id] 제목 형식을 사용하고, 본문은 Milestone 내용으로 채우며, identity map에는 Milestone path와 Plane work item id를 함께 저장한다. 여기서 milestone-id는 Milestone 파일 slug를 기본값으로 쓴다.
  • 시나리오 점검:
    • Agent user assignment가 trigger이므로 NomadCode가 자기 자신이 만든 상태/본문 변경을 다시 trigger로 오인하지 않도록 actor guard와 idempotency key가 필요하다.
    • 원본 본문을 댓글로 보존한 뒤 본문을 치환하므로, 댓글 생성 실패 후 본문 치환이 진행되지 않게 단계별 apply 순서와 재시도 정책이 필요하다.
    • Plane-origin은 별도 구조화 응답을 받아 적용하는 방식이 아니라, IDE-origin과 같은 workspace agent 파일 작성 및 push 경로를 사용한다.
    • Plane Todo 이동은 workspace agent 실행 직후가 아니라 develop push 완료를 sync layer가 감지한 뒤 수행한다.
    • Sync layer는 push 성공만으로 Plane을 갱신하지 않고, pushed Milestone의 provider/work item identity가 원래 Plane 티켓과 매칭되는지 확인한다.
    • [milestone-id] 제목의 milestone id는 develop의 Milestone 파일 slug를 기본값으로 고정한다. 제목 변경만으로 identity를 추적하지 않는다.
    • Agent-origin sync는 feature branch 초안이 아니라 develop branch에 반영된 Milestone만 Plane에 Todo 티켓으로 만든다.
    • Plane-origin과 Agent-origin 모두 project sync 설정을 통해 provider project, git repository, workspace를 확정하며, 설정이 없거나 둘 이상이면 생성 동기화를 멈추고 사용자 설정 또는 운영자 조치를 요구한다.
    • Cancelled는 사용자 폐기 신호지만 archive 이동은 사용자 승인 경계를 지켜야 하므로, 우선 [폐기] 후보 또는 review gate로 처리한다.
  • 남은 작업: 없음.
  • 확인 필요: 없음