diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md index bb10ab3..6eb980b 100644 --- a/agent-ops/roadmap/ROADMAP.md +++ b/agent-ops/roadmap/ROADMAP.md @@ -4,38 +4,40 @@ NomadCode는 모바일 앱, 웹 콘솔, core 서비스, 공유 계약, agent-operation 규칙을 하나의 원레포로 묶어 AI-assisted development workflow를 조율하는 프로젝트다. -현재 로드맵은 기존 `services/core/README.md`의 단계별 다음 작업을 `agent-ops/roadmap/` 구조로 옮긴 것이다. 범위는 우선 core 백엔드 오케스트레이션의 서버 골격, workflow 안정화, 외부 통합 준비에 둔다. +현재 로드맵은 기존 `services/core/README.md`의 단계별 다음 작업을 `agent-ops/roadmap/` 구조로 옮긴 것이다. 범위는 우선 core 백엔드 오케스트레이션의 서버 골격을 바탕으로 Plane issue 기반의 얇은 e2e cycle을 먼저 닫고, 그 실제 흐름을 기준으로 workflow 안정화와 외부 통합 확장을 이어가는 데 둔다. -## Phase 개요 +## Phase 흐름 -진행 순서는 이 문서의 위에서 아래 흐름으로 해석한다. Phase와 Milestone 표시명에는 순번을 붙이지 않는다. - -### Server Skeleton - -서버 실행 골격, task 저장 구조, 로컬 모델 호출 기반 비동기 job 실행, Adapter stub을 구성한다. - -### Workflow Core - -task 상태 전이와 enqueue / running / completed / failed 흐름을 안정화하고 retry, timeout, notification event의 기본 구조를 정리한다. - -### External Integration - -Plane, Mattermost, Agent Integrator, IOP 연결을 실제 통합 흐름으로 확장한다. +- Server Skeleton: 서버 실행 골격, task 저장 구조, 로컬 모델 호출 기반 비동기 job 실행, Adapter stub을 구성한다. +- Plane Thin E2E: Plane issue를 core task와 연결하고 실행 결과를 Plane comment/status로 되돌리는 최소 제품 e2e cycle을 완성한다. +- Workflow Core: Plane thin e2e cycle에서 관찰되는 실제 상태 변화를 기준으로 task 상태 전이, retry, timeout, notification event의 기본 구조를 안정화한다. +- External Integration: Plane thin e2e 이후 Mattermost, Agent Integrator, IOP 연결을 실제 통합 흐름으로 확장한다. ## Milestone 목록 -| Milestone | Phase | 상태 | 문서 | -|-----------|-------|------|------| -| Server Skeleton | Server Skeleton | 완료 | `agent-ops/roadmap/milestones/server-skeleton.md` | -| Workflow Core | Workflow Core | 계획 | `agent-ops/roadmap/milestones/workflow-core.md` | -| External Integration | External Integration | 계획 | `agent-ops/roadmap/milestones/external-integration.md` | +### Server Skeleton + +- [Server Skeleton](milestones/server-skeleton.md) - 상태: 완료; 목표: core 서버 실행 골격과 task 저장, 비동기 job, 외부 Adapter stub을 구성한다. + +### Plane Thin E2E + +- [Plane Thin E2E Loop](milestones/plane-thin-e2e-loop.md) - 상태: 진행 중; 목표: Plane issue에서 core task 실행 결과가 다시 Plane에 남는 최소 e2e cycle을 닫는다. + +### Workflow Core + +- [Workflow Core](milestones/workflow-core.md) - 상태: 계획; 목표: 실제 e2e 흐름을 기준으로 task lifecycle, retry, timeout, notification event를 안정화한다. + +### External Integration + +- [External Integration](milestones/external-integration.md) - 상태: 계획; 목표: Plane 확장, Mattermost, Agent Integrator, IOP 연결을 실제 통합 흐름으로 확장한다. ## 로딩 정책 -- 일반 기능 작업에서는 이 전체 로드맵을 매번 읽지 않는다. -- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업에서는 먼저 `agent-ops/roadmap/current.md`를 읽는다. +- 일반 작업에서는 `agent-ops/roadmap/ROADMAP.md`를 매번 읽지 않는다. +- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다. - `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다. +- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. - 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다. -- 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. - 활성 Milestone 밖의 작업이면 이 문서의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. -- Phase 전환, Milestone 추가/수정, 전체 로드맵 갱신 요청에서만 `agent-ops/roadmap/ROADMAP.md`를 읽는다. +- 이 문서는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. +- 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다. diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md index 62a7df6..19bfd19 100644 --- a/agent-ops/roadmap/current.md +++ b/agent-ops/roadmap/current.md @@ -2,10 +2,11 @@ ## 활성 Milestone -- Workflow Core: agent-ops/roadmap/milestones/workflow-core.md +- Plane Thin E2E Loop: agent-ops/roadmap/milestones/plane-thin-e2e-loop.md ## 선택 규칙 -- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택한다. +- 이 문서는 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택하고 같은 세션에서 1회 읽는다. - 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. - 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. diff --git a/agent-ops/roadmap/milestones/external-integration.md b/agent-ops/roadmap/milestones/external-integration.md index 2803d30..af888d6 100644 --- a/agent-ops/roadmap/milestones/external-integration.md +++ b/agent-ops/roadmap/milestones/external-integration.md @@ -2,19 +2,19 @@ ## 목표 -Plane, Mattermost, Agent Integrator, IOP 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. +Plane thin e2e 이후 남은 Plane 확장, Mattermost, Agent Integrator, IOP 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. ## 단계 -- External Integration +External Integration ## 상태 -- 계획 +계획 ## 범위 -- Plane issue 생성 / comment / status update 구현 +- Plane issue 생성 / comment / status update 확장 - Mattermost 메시지 발송 구현 - Agent Integrator 호출 구조 추가 - IOP 호출 구조 추가 @@ -23,19 +23,19 @@ Plane, Mattermost, Agent Integrator, IOP 연결을 stub 또는 호환 호출 경 ## 필수 기능 -- Plane issue 생성, comment, status update adapter 구현 -- Mattermost 메시지 발송 adapter 구현 -- Agent Integrator 호출 경계 정의 -- IOP OpenAI-compatible API를 단순 모델/chat completion 호환 호출에 사용 -- IOP A2A JSON-RPC 경로를 외부 agent 작업 위임과 task 상태, artifact, cancel 흐름 공유에 사용 +- [ ] Plane issue 생성, comment, status update adapter 확장 +- [ ] Mattermost 메시지 발송 adapter 구현 +- [ ] Agent Integrator 호출 경계 정의 +- [ ] IOP OpenAI-compatible API를 단순 모델/chat completion 호환 호출에 사용 +- [ ] IOP A2A JSON-RPC 경로를 외부 agent 작업 위임과 task 상태, artifact, cancel 흐름 공유에 사용 ## 완료 기준 -- core가 Plane에 issue, comment, status update를 요청할 수 있다. -- core가 Mattermost에 메시지를 발송할 수 있다. -- Agent Integrator 또는 그 대체 연결 지점이 명확히 정의되어 있다. -- IOP compatible 호출 경로가 core workflow와 연결된다. -- 외부 provider별 세부 구현이 adapter 경계 밖으로 새지 않는다. +- [ ] core가 Plane에 issue, comment, status update를 요청할 수 있다. +- [ ] core가 Mattermost에 메시지를 발송할 수 있다. +- [ ] Agent Integrator 또는 그 대체 연결 지점이 명확히 정의되어 있다. +- [ ] IOP compatible 호출 경로가 core workflow와 연결된다. +- [ ] 외부 provider별 세부 구현이 adapter 경계 밖으로 새지 않는다. ## 범위 제외 @@ -49,4 +49,5 @@ Plane, Mattermost, Agent Integrator, IOP 연결을 stub 또는 호환 호출 경 - 이전 출처: `services/core/README.md`의 `## 단계별 다음 작업` - 주요 작업 영역: `services/core/internal/adapters/`, `services/core/internal/scheduler/`, `services/core/internal/workflow/` +- 선행 작업: Plane Thin E2E Loop, Workflow Core - 확인 필요: IOP native protocol과 Agent Integrator의 최종 계약은 구현 전 별도 확인이 필요하다. diff --git a/agent-ops/roadmap/milestones/plane-thin-e2e-loop.md b/agent-ops/roadmap/milestones/plane-thin-e2e-loop.md new file mode 100644 index 0000000..ceea445 --- /dev/null +++ b/agent-ops/roadmap/milestones/plane-thin-e2e-loop.md @@ -0,0 +1,55 @@ +# Plane Thin E2E Loop + +## 목표 + +Plane issue를 core task의 외부 출처로 연결하고, task 실행 결과를 Plane comment/status로 되돌려보내는 최소 e2e cycle을 완성한다. Workflow Core의 retry, timeout, notification event 정책은 이 실제 loop가 관찰된 뒤 안정화한다. + +## 단계 + +Plane Thin E2E + +## 상태 + +진행 중 + +## 범위 + +- Plane issue 기반 작업 입력과 core task 생성 경로 +- core task와 Plane issue의 외부 참조 연결 +- task 완료와 실패 결과의 Plane comment/status 반영 +- 최소 e2e 검증 절차와 운영 설정 문서화 + +## 필수 기능 + +- [ ] Plane issue를 core task로 연결하는 최소 입력 계약을 정한다. + - [ ] task에 `provider`, `external_id`, `external_url` 등 외부 참조를 저장하는 방식을 정한다. + - [ ] Plane issue title/description/comment 중 어떤 값을 task title/payload로 매핑할지 정한다. +- [ ] Plane adapter에서 issue comment와 status update 실제 호출을 구현한다. + - [ ] `PLANE_BASE_URL`, `PLANE_TOKEN` 설정과 adapter client 동작을 README 또는 운영 문서와 맞춘다. +- [ ] task 완료/실패 시 Plane에 결과를 남기는 발행 지점을 workflow 또는 scheduler에 연결한다. + - [ ] completed 결과는 Plane comment로 남긴다. + - [ ] failed 결과는 Plane comment 또는 status로 관찰 가능하게 남긴다. +- [ ] Plane issue에서 core task 실행 결과가 Plane에 다시 남는 e2e 검증 시나리오를 정리한다. + +## 완료 기준 + +- [ ] Plane issue 하나를 기준으로 core task를 만들고 enqueue할 수 있다. +- [ ] core task의 completed 결과가 Plane issue comment 또는 status에 반영된다. +- [ ] core task의 failed 결과가 Plane issue에서 관찰 가능하게 남는다. +- [ ] e2e loop 검증 명령이나 수동 절차가 문서에 남아 있다. +- [ ] Workflow Core에서 후속으로 정리할 retry, timeout, notification event TODO가 실제 loop 기준으로 드러난다. + +## 범위 제외 + +- Plane 전체 양방향 동기화 +- Plane webhook 기반 자동 수집의 완전한 운영화 +- Mattermost 메시지 발송 구현 +- Agent Integrator와 IOP의 추가 통합 +- 복잡한 workflow DSL + +## 작업 컨텍스트 + +- 관련 경로: `services/core/internal/adapters/plane/`, `services/core/internal/workflow/`, `services/core/internal/scheduler/`, `services/core/internal/storage/` +- 선행 작업: Server Skeleton +- 후속 작업: Workflow Core +- 확인 필요: Plane issue 상태 값과 comment API의 실제 계약은 구현 전에 확인이 필요하다. diff --git a/agent-ops/roadmap/milestones/server-skeleton.md b/agent-ops/roadmap/milestones/server-skeleton.md index 1a5944a..1ea3c38 100644 --- a/agent-ops/roadmap/milestones/server-skeleton.md +++ b/agent-ops/roadmap/milestones/server-skeleton.md @@ -6,11 +6,11 @@ core 서비스의 서버 실행 골격을 구성하고, task 저장 구조와 ## 단계 -- Server Skeleton +Server Skeleton ## 상태 -- 완료 +완료 ## 범위 @@ -21,23 +21,23 @@ core 서비스의 서버 실행 골격을 구성하고, task 저장 구조와 ## 필수 기능 -- Go HTTP server 실행 골격 -- health / readiness endpoint -- task 생성, 조회, 목록, enqueue API -- PostgreSQL 기반 task 저장 -- goose migration과 sqlc 기반 DB query 생성 구조 -- River 기반 task job -- 모델 호출 경로 -- Plane Adapter stub -- Mattermost Adapter stub +- [x] Go HTTP server 실행 골격 +- [x] health / readiness endpoint +- [x] task 생성, 조회, 목록, enqueue API +- [x] PostgreSQL 기반 task 저장 +- [x] goose migration과 sqlc 기반 DB query 생성 구조 +- [x] River 기반 task job +- [x] 모델 호출 경로 +- [x] Plane Adapter stub +- [x] Mattermost Adapter stub ## 완료 기준 -- core 서버를 로컬에서 실행할 수 있다. -- task 생성부터 조회, enqueue까지 기본 API 흐름이 동작한다. -- DB migration과 sqlc query 생성 흐름이 정리되어 있다. -- River job이 task를 처리하는 기본 경로를 가진다. -- Plane과 Mattermost는 실제 API 호출 전 stub 경계로 분리되어 있다. +- [x] core 서버를 로컬에서 실행할 수 있다. +- [x] task 생성부터 조회, enqueue까지 기본 API 흐름이 동작한다. +- [x] DB migration과 sqlc query 생성 흐름이 정리되어 있다. +- [x] River job이 task를 처리하는 기본 경로를 가진다. +- [x] Plane과 Mattermost는 실제 API 호출 전 stub 경계로 분리되어 있다. ## 범위 제외 @@ -52,4 +52,5 @@ core 서비스의 서버 실행 골격을 구성하고, task 저장 구조와 - 이전 출처: `services/core/README.md`의 `## 단계별 다음 작업` - 주요 작업 영역: `services/core/` +- 후속 작업: Plane Thin E2E Loop - 검증 기준: core 변경은 `go test ./...` 또는 `bin/test`를 우선 사용한다. diff --git a/agent-ops/roadmap/milestones/workflow-core.md b/agent-ops/roadmap/milestones/workflow-core.md index 663a01c..1ab1e55 100644 --- a/agent-ops/roadmap/milestones/workflow-core.md +++ b/agent-ops/roadmap/milestones/workflow-core.md @@ -2,15 +2,15 @@ ## 목표 -task 상태 전이를 정리하고 enqueue / running / completed / failed 흐름을 안정화한다. retry, timeout, notification event의 기본 구조를 추가해 core workflow의 운영 기준을 만든다. +Plane thin e2e cycle에서 관찰되는 실제 상태 변화를 기준으로 task 상태 전이를 정리하고 enqueue / running / completed / failed 흐름을 안정화한다. retry, timeout, notification event의 기본 구조를 추가해 core workflow의 운영 기준을 만든다. ## 단계 -- Workflow Core +Workflow Core ## 상태 -- 계획 +계획 ## 범위 @@ -18,21 +18,22 @@ task 상태 전이를 정리하고 enqueue / running / completed / failed 흐름 - enqueue / running / completed / failed 흐름 안정화 - retry / timeout 기본 구조 추가 - notification event 구조 정리 +- Plane thin e2e loop에서 확인된 상태 변화와 실패 케이스 반영 ## 필수 기능 -- task lifecycle 상태 모델 점검 -- scheduler와 workflow service의 상태 전이 책임 정리 -- 실패 task 처리 기준 -- retry와 timeout의 최소 정책 -- notification event 모델과 발행 지점 +- [ ] task lifecycle 상태 모델 점검 +- [ ] scheduler와 workflow service의 상태 전이 책임 정리 +- [ ] 실패 task 처리 기준 +- [ ] retry와 timeout의 최소 정책 +- [ ] notification event 모델과 발행 지점 ## 완료 기준 -- task가 enqueue 이후 running, completed, failed 상태로 일관되게 전이된다. -- 실패와 timeout이 관찰 가능한 상태로 남는다. -- retry 정책의 최소 동작 방식이 구현되거나 명확히 문서화된다. -- notification event가 workflow 상태 변화와 연결된다. +- [ ] task가 enqueue 이후 running, completed, failed 상태로 일관되게 전이된다. +- [ ] 실패와 timeout이 관찰 가능한 상태로 남는다. +- [ ] retry 정책의 최소 동작 방식이 구현되거나 명확히 문서화된다. +- [ ] notification event가 workflow 상태 변화와 연결된다. ## 범위 제외 @@ -45,4 +46,6 @@ task 상태 전이를 정리하고 enqueue / running / completed / failed 흐름 - 이전 출처: `services/core/README.md`의 `## 단계별 다음 작업` - 주요 작업 영역: `services/core/internal/workflow/`, `services/core/internal/scheduler/`, `services/core/internal/notification/` +- 선행 작업: Plane Thin E2E Loop +- 후속 작업: External Integration - 검증 기준: scheduler, persistence, adapter behavior를 크게 바꾸면 관련 테스트를 함께 갱신한다. diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 5c3d94c..ea91b76 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -61,10 +61,12 @@ NomadCode는 AI 병렬 작업 운용을 위한 원레포다. 백엔드 오케스 - 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다. - `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다. +- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. - 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다. - 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. - 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. - `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. +- 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다. - 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. ## 주의사항