From fef4b514e767e2ef44bc346b5e86f8ae8643e730 Mon Sep 17 00:00:00 2001 From: toki Date: Sat, 23 May 2026 16:59:13 +0900 Subject: [PATCH] update roadmap and milestones --- agent-ops/roadmap/ROADMAP.md | 8 +-- agent-ops/roadmap/current.md | 2 +- .../milestones/external-integration.md | 7 ++- .../milestones/plane-task-pipeline-design.md | 54 ++++++++++++++----- 4 files changed, 51 insertions(+), 20 deletions(-) diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md index bbfb835..ccbcb0f 100644 --- a/agent-ops/roadmap/ROADMAP.md +++ b/agent-ops/roadmap/ROADMAP.md @@ -4,13 +4,13 @@ NomadCode는 모바일 앱, 웹 콘솔, core 서비스, 공유 계약, agent-operation 규칙을 하나의 원레포로 묶어 AI-assisted development workflow를 조율하는 프로젝트다. -현재 로드맵은 기존 `services/core/README.md`의 단계별 다음 작업을 `agent-ops/roadmap/` 구조로 옮긴 것이다. 범위는 우선 core 백엔드 오케스트레이션의 서버 골격을 바탕으로 Plane과의 실제 통신 기반을 안정화하고, 그 뒤에 Plane task pipeline과 workflow 안정화를 설계하는 데 둔다. +현재 로드맵은 기존 `services/core/README.md`의 단계별 다음 작업을 `agent-ops/roadmap/` 구조로 옮긴 것이다. 범위는 우선 core 백엔드 오케스트레이션의 서버 골격을 바탕으로 Plane과의 실제 통신 기반을 안정화하고, 그 뒤에 Plane/Jira 같은 여러 work item provider를 adapter로 붙일 수 있는 task pipeline과 workflow 안정화를 설계하는 데 둔다. ## Phase 흐름 - Server Skeleton: 서버 실행 골격, task 저장 구조, 로컬 모델 호출 기반 비동기 job 실행, Adapter stub을 구성한다. - Plane Communication Foundation: Plane self-hosted 인스턴스와 통신하기 위한 인증, API client, 외부 참조 저장, smoke 검증 토대를 만든다. -- Plane Task Pipeline Design: Plane work item과 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 정리한다. +- Work Item Provider Pipeline Design: Plane/Jira 등 work item provider와 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 provider-neutral하게 정리한다. - Workflow Core: Plane task pipeline 설계가 정리된 뒤 상태 전이, retry, timeout, notification event의 기본 구조를 안정화한다. - External Integration: Plane 통신 토대와 workflow core 이후 Mattermost, Agent Integrator, IOP 연결을 실제 통합 흐름으로 확장한다. @@ -24,9 +24,9 @@ NomadCode는 모바일 앱, 웹 콘솔, core 서비스, 공유 계약, agent-ope - [Plane Communication Foundation](milestones/plane-thin-e2e-loop.md) - 상태: 완료; 목표: Plane 인스턴스와의 인증/API 통신, 외부 참조 저장, 수동 smoke 검증 토대를 만든다. -### Plane Task Pipeline Design +### Work Item Provider Pipeline Design -- [Plane Task Pipeline Design](milestones/plane-task-pipeline-design.md) - 상태: 계획; 목표: Plane work item과 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 정리한다. +- [Work Item Provider Pipeline Design](milestones/plane-task-pipeline-design.md) - 상태: 계획; 목표: Plane/Jira 등 work item provider와 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 provider-neutral하게 정리한다. ### Workflow Core diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md index 07b099a..8c64f00 100644 --- a/agent-ops/roadmap/current.md +++ b/agent-ops/roadmap/current.md @@ -2,7 +2,7 @@ ## 활성 Milestone -- Plane Task Pipeline Design: agent-ops/roadmap/milestones/plane-task-pipeline-design.md +- Work Item Provider Pipeline Design (상태: 계획, 구현 착수 전): agent-ops/roadmap/milestones/plane-task-pipeline-design.md ## 선택 규칙 diff --git a/agent-ops/roadmap/milestones/external-integration.md b/agent-ops/roadmap/milestones/external-integration.md index 76245fb..edf50de 100644 --- a/agent-ops/roadmap/milestones/external-integration.md +++ b/agent-ops/roadmap/milestones/external-integration.md @@ -2,7 +2,7 @@ ## 목표 -Plane 통신 토대와 workflow core 이후 남은 Plane 확장, Mattermost, Agent Integrator, IOP 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. +Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확장, Mattermost, Agent Integrator, IOP 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. ## 단계 @@ -15,6 +15,7 @@ External Integration ## 범위 - Plane issue 생성 / comment / status update 확장 +- Jira issue 조회 / comment / status transition adapter 구현 - Mattermost 메시지 발송 구현 - Agent Integrator 호출 구조 추가 - IOP 호출 구조 추가 @@ -24,6 +25,7 @@ External Integration ## 필수 기능 - [ ] Plane issue 생성, comment, status update adapter 확장 +- [ ] Jira issue 조회, comment, status transition adapter 구현 - [ ] Mattermost 메시지 발송 adapter 구현 - [ ] Agent Integrator 호출 경계 정의 - [ ] IOP OpenAI-compatible API를 단순 모델/chat completion 호환 호출에 사용 @@ -32,6 +34,7 @@ External Integration ## 완료 기준 - [ ] core가 Plane에 issue, comment, status update를 요청할 수 있다. +- [ ] core가 Jira에 issue 조회, comment, status transition을 요청할 수 있다. - [ ] core가 Mattermost에 메시지를 발송할 수 있다. - [ ] Agent Integrator 또는 그 대체 연결 지점이 명확히 정의되어 있다. - [ ] IOP compatible 호출 경로가 core workflow와 연결된다. @@ -49,5 +52,5 @@ External Integration - 이전 출처: `services/core/README.md`의 `## 단계별 다음 작업` - 주요 작업 영역: `services/core/internal/adapters/`, `services/core/internal/scheduler/`, `services/core/internal/workflow/` -- 선행 작업: Plane Communication Foundation, Workflow Core +- 선행 작업: Work Item Provider Pipeline Design, Workflow Core - 확인 필요: IOP native protocol과 Agent Integrator의 최종 계약은 구현 전 별도 확인이 필요하다. diff --git a/agent-ops/roadmap/milestones/plane-task-pipeline-design.md b/agent-ops/roadmap/milestones/plane-task-pipeline-design.md index d3c3e77..d3a2015 100644 --- a/agent-ops/roadmap/milestones/plane-task-pipeline-design.md +++ b/agent-ops/roadmap/milestones/plane-task-pipeline-design.md @@ -1,12 +1,12 @@ -# Plane Task Pipeline Design +# Work Item Provider Pipeline Design ## 목표 -Plane Communication Foundation 다음 단계로 Plane work item과 core task pipeline 사이의 최소 제품 흐름을 확정한다. 자동 실행 구현에 들어가기 전에 생성, enqueue, 상태 투영, 중복 방지, 결과 발행 경계를 정리해 Workflow Core가 참조할 상태 변화와 실패 케이스를 명확히 한다. +Plane Communication Foundation 다음 단계로 Plane/Jira 등 work item provider와 core task pipeline 사이의 최소 제품 흐름을 확정한다. 자동 실행 구현에 들어가기 전에 provider-neutral 생성, enqueue, 상태 투영, 중복 방지, 결과 발행 경계를 정리해 Workflow Core가 참조할 상태 변화와 실패 케이스를 명확히 한다. ## 단계 -Plane Task Pipeline Design +Work Item Provider Pipeline Design ## 상태 @@ -14,30 +14,41 @@ Plane Task Pipeline Design ## 범위 -- Plane work item에서 core task를 생성하고 연결하는 entrypoint 후보 정리 +- Plane/Jira 같은 work item provider에서 core task를 생성하고 연결하는 entrypoint 후보 정리 - 수동 endpoint, webhook, polling 등 trigger 방식의 다음 구현 경로 결정 - core task enqueue 조건과 중복 생성 방지 기준 정리 +- provider별 직접 접속부와 core 내부 pipeline 계약을 분리하는 adapter interface 정리 - provider board state와 agent 내부 실행 상태의 분리 계약 정리 - Plane/Jira에서 공통으로 읽히는 label/comment 기반 상태 투영 방식 정리 -- task 완료/실패 결과를 Plane comment/status로 발행하는 최소 정책 정리 -- Plane workspace/project/work item/state metadata 사용 방식 확정 +- task 완료/실패 결과를 provider comment/status로 발행하는 최소 정책 정리 +- provider별 workspace/project/work item/state metadata 사용 방식 확정 - Workflow Core에 넘길 상태 변화, 실패 케이스, notification 요구사항 정리 ## 필수 기능 -- [x] Plane work item -> core task 생성/연결 흐름을 문서화한다. +- [x] Plane work item -> core task 생성/연결 흐름을 현재 구현 기준으로 문서화한다. - [x] 초기 entrypoint는 기존 `POST /api/integrations/plane/tasks`를 기준선으로 삼는다. - [x] 생성 단계는 Plane work item 조회와 core task 저장까지만 담당한다. - [x] 생성된 task는 `pending` 상태로 남기고 enqueue는 별도 단계에서 처리한다. - [x] Plane 연결 정보는 provider-neutral external ref와 Plane metadata에 함께 저장한다. - [ ] 자동 enqueue 여부와 사용자/운영 트리거 경계를 결정한다. +- [ ] work item provider adapter interface를 설계한다. + - [ ] core pipeline이 사용할 provider-neutral DTO를 정의한다. + - [ ] work item 조회, comment 작성, status/state 변경, label projection 경계를 interface로 분리한다. + - [ ] Plane adapter와 Jira adapter가 같은 interface를 구현할 수 있는지 검증한다. + - [ ] provider별 상태/라벨/comment 매핑은 adapter 설정으로 분리한다. +- [ ] 현재 Plane 고정 진입부를 provider-neutral 구조로 리팩토링한다. + - [ ] `POST /api/integrations/plane/tasks`의 Plane 전용 흐름을 generic pipeline service 아래로 옮긴다. + - [ ] HTTP handler가 Plane 타입과 직접 결합하지 않도록 요청 DTO와 변환 책임을 분리한다. + - [ ] `buildPlaneCreateTaskInput`의 core task 생성 로직을 provider-neutral mapper로 분리한다. + - [ ] 기존 Plane endpoint는 compatibility entrypoint로 유지하거나 generic endpoint로 대체할지 결정한다. - [ ] provider-neutral 상태와 projection 계약을 확정한다. - [x] board state는 `backlog`, `todo`, `in_progress`, `testing`, `complete`, `cancel`로 둔다. - [x] `in_progress` 내부 agent 상태는 core task metadata를 canonical source로 둔다. - [x] Plane/Jira provider projection은 label-first로 둔다. - [x] provider 본문(description)은 agent 실행 상태 저장소로 쓰지 않는다. - [ ] core task metadata schema와 provider label mapping을 구현 대상으로 확정한다. -- [ ] 완료/실패 결과의 Plane comment/status update 정책을 정한다. +- [ ] 완료/실패 결과의 provider comment/status update 정책을 정한다. - [x] agent 단계 완료 기록은 prefix와 이모지가 있는 comment로 남기는 방향을 샘플 검증한다. - [ ] comment prefix 세트와 작성 타이밍을 확정한다. - [ ] 중복 생성 방지와 재시도 시 식별 기준을 정한다. @@ -45,15 +56,18 @@ Plane Task Pipeline Design ## 완료 기준 -- [ ] Plane work item에서 core task로 이어지는 pipeline entrypoint와 계약이 문서화되어 있다. +- [ ] Plane/Jira work item에서 core task로 이어지는 provider-neutral pipeline entrypoint와 계약이 문서화되어 있다. +- [ ] core workflow/pipeline 계층이 Plane package 타입에 직접 의존하지 않는다. +- [ ] Plane 직접 접속부는 adapter 구현에 격리되고, Jira adapter 추가 지점이 명확하다. - [ ] enqueue 조건, idempotency 기준, 실패 표시 방식이 결정되어 있다. - [ ] provider board state, core canonical state, label/comment projection 계약이 문서화되어 있다. -- [ ] completed/failed/cancelled 결과를 Plane에 반영하는 최소 정책이 결정되어 있다. +- [ ] completed/failed/cancelled 결과를 provider에 반영하는 최소 정책이 결정되어 있다. - [ ] Workflow Core가 pipeline 계약 질문 없이 상태 전이 구현을 시작할 수 있다. ## 범위 제외 - Plane webhook 구현 +- Jira adapter 실제 구현 - Plane 전체 양방향 동기화 - Plane custom property 또는 work item type Pro 기능 의존 - task lifecycle, retry, timeout의 실제 구현 @@ -65,8 +79,15 @@ Plane Task Pipeline Design ## 작업 컨텍스트 - 관련 경로: `services/core/internal/adapters/plane/`, `services/core/internal/http/`, `services/core/internal/storage/`, `services/core/internal/scheduler/`, `services/core/internal/workflow/`, `services/core/README.md` +- 파일명 메모: 기존 Plane 중심 파일명 `plane-task-pipeline-design.md`는 대규모 rename을 피하기 위해 유지하되, 마일스톤 이름과 내용은 Work Item Provider Pipeline Design으로 일반화한다. - 선행 작업: Plane Communication Foundation - 후속 작업: Workflow Core +- 현재 코드 결합 상태: + - HTTP router는 `POST /api/integrations/plane/tasks`로 Plane 전용 entrypoint를 가진다. + - handler는 `PlaneWorkItemClient`, `plane.WorkItemRef`, `plane.WorkItem`에 직접 의존한다. + - `buildPlaneCreateTaskInput`이 Plane 조회 결과를 core task payload/external ref로 직접 변환한다. + - DB schema는 `external_provider`, `external_id`, `external_url`, `external_metadata`로 provider-neutral 토대가 있으므로 유지한다. + - 리팩토링 목표는 Plane/Jira 직접 접속부를 adapter로 격리하고, 그 아래 pipeline/service 계층은 provider-neutral DTO와 interface만 보게 하는 것이다. - 초기 생성/연결 흐름: - 운영자 또는 상위 자동화가 `POST /api/integrations/plane/tasks`를 호출한다. - 요청 필수값은 `workspace_slug`, `project_id`, `work_item_id`이고, `state_id`, `external_url`, `comment`는 선택값으로 받는다. @@ -86,13 +107,20 @@ Plane Task Pipeline Design - provider 본문(description)은 작업 요구사항과 맥락의 원본으로 보고, agent 실행 상태를 매번 갱신하는 저장소로 쓰지 않는다. - Plane custom property는 현재 NomadCode dev project에서 `is_issue_type_enabled=False`라 기본 경로로 전제하지 않는다. - Plane 샘플 work item `NOMAD-13`은 `In Progress` state와 `agent:waiting-user`, `phase:planning` 라벨로 board state와 agent 내부 실행 상태 분리 방식을 보여준다. +- provider abstraction 결정: + - Plane은 첫 구현 provider일 뿐이며 core pipeline의 도메인 모델이 되어서는 안 된다. + - Jira도 같은 workflow state, label/comment projection, idempotency 계약을 공유할 수 있어야 한다. + - provider별 API 인증, URL, workspace/project/issue 식별자, status id, label id는 adapter 설정과 metadata로만 다룬다. + - core의 canonical 상태와 agent 실행 metadata는 provider에서 읽어온 값이 아니라 NomadCode task 상태의 진실로 둔다. - comment 기록 규칙 후보: - `🧭 PLAN | <요약>`: plan 작성 또는 계획 검토 단계 완료 기록 - `🛠️ WORK | <요약>`: 구현 또는 문서 반영 단계 완료 기록 - `🔎 REVIEW | <요약>`: 코드리뷰/self-review 단계 완료 기록 - `✅ VERIFY | <요약>`: 테스트/검증 완료 기록 - 각 comment 본문은 1~2줄 요약을 기본으로 하며, 자세한 실행 로그나 상태 metadata는 core에 남긴다. -- 착수 상태: - - 이 마일스톤은 방향성과 샘플을 정리했지만, 당장 구현 착수 대상으로 보지는 않는다. - - 다음 착수 시에는 trigger 경계, core metadata schema, provider label mapping을 먼저 확정한다. +- 현재 지점 / 착수 상태: + - 현재 상태는 `계획`이며, 구현 착수 전 설계 정리 지점이다. + - 정리된 내용은 provider-neutral 방향성, Plane/Jira adapter 추상화 필요성, label/comment 기반 상태 투영 샘플이다. + - 아직 확정되지 않은 다음 결정은 provider adapter interface, trigger 경계, core metadata schema, provider label mapping이다. + - 다음에 이 마일스톤을 착수하면 Plane 고정 진입부 리팩토링 전에 위 결정 항목을 먼저 닫는다. - 확인 필요: trigger 방식은 현재 구현 상태와 운영 기대치를 보고 수동 endpoint 유지, webhook, polling 중 하나를 선택한다.