From 3a71d13055e1e05ea71cd9b438ac446084dd8953 Mon Sep 17 00:00:00 2001 From: toki Date: Sat, 23 May 2026 16:47:06 +0900 Subject: [PATCH] update roadmap and domain rules --- agent-ops/roadmap/ROADMAP.md | 4 +-- .../milestones/plane-task-pipeline-design.md | 36 +++++++++++++++++-- agent-ops/rules/project/domain/core/rules.md | 21 +++++++++-- 3 files changed, 54 insertions(+), 7 deletions(-) diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md index 8f33303..bbfb835 100644 --- a/agent-ops/roadmap/ROADMAP.md +++ b/agent-ops/roadmap/ROADMAP.md @@ -10,7 +10,7 @@ NomadCode는 모바일 앱, 웹 콘솔, core 서비스, 공유 계약, agent-ope - 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, 결과 발행 계약을 정리한다. +- Plane Task Pipeline Design: Plane work item과 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 정리한다. - Workflow Core: Plane task pipeline 설계가 정리된 뒤 상태 전이, retry, timeout, notification event의 기본 구조를 안정화한다. - External Integration: Plane 통신 토대와 workflow core 이후 Mattermost, Agent Integrator, IOP 연결을 실제 통합 흐름으로 확장한다. @@ -26,7 +26,7 @@ NomadCode는 모바일 앱, 웹 콘솔, core 서비스, 공유 계약, agent-ope ### Plane Task Pipeline Design -- [Plane Task Pipeline Design](milestones/plane-task-pipeline-design.md) - 상태: 진행 중; 목표: Plane work item과 core task 사이의 생성, enqueue, 결과 발행 계약을 정리한다. +- [Plane Task Pipeline Design](milestones/plane-task-pipeline-design.md) - 상태: 계획; 목표: Plane work item과 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 정리한다. ### Workflow Core diff --git a/agent-ops/roadmap/milestones/plane-task-pipeline-design.md b/agent-ops/roadmap/milestones/plane-task-pipeline-design.md index 76c819f..d3c3e77 100644 --- a/agent-ops/roadmap/milestones/plane-task-pipeline-design.md +++ b/agent-ops/roadmap/milestones/plane-task-pipeline-design.md @@ -2,7 +2,7 @@ ## 목표 -Plane Communication Foundation 다음 단계로 Plane work item과 core task pipeline 사이의 최소 제품 흐름을 확정한다. 자동 실행 구현에 들어가기 전에 생성, enqueue, 중복 방지, 결과 발행 경계를 정리해 Workflow Core가 참조할 상태 변화와 실패 케이스를 명확히 한다. +Plane Communication Foundation 다음 단계로 Plane work item과 core task pipeline 사이의 최소 제품 흐름을 확정한다. 자동 실행 구현에 들어가기 전에 생성, enqueue, 상태 투영, 중복 방지, 결과 발행 경계를 정리해 Workflow Core가 참조할 상태 변화와 실패 케이스를 명확히 한다. ## 단계 @@ -10,13 +10,15 @@ Plane Task Pipeline Design ## 상태 -진행 중 +계획 ## 범위 - Plane work item에서 core task를 생성하고 연결하는 entrypoint 후보 정리 - 수동 endpoint, webhook, polling 등 trigger 방식의 다음 구현 경로 결정 - core task enqueue 조건과 중복 생성 방지 기준 정리 +- provider board state와 agent 내부 실행 상태의 분리 계약 정리 +- Plane/Jira에서 공통으로 읽히는 label/comment 기반 상태 투영 방식 정리 - task 완료/실패 결과를 Plane comment/status로 발행하는 최소 정책 정리 - Plane workspace/project/work item/state metadata 사용 방식 확정 - Workflow Core에 넘길 상태 변화, 실패 케이스, notification 요구사항 정리 @@ -29,8 +31,15 @@ Plane Task Pipeline Design - [x] 생성된 task는 `pending` 상태로 남기고 enqueue는 별도 단계에서 처리한다. - [x] Plane 연결 정보는 provider-neutral external ref와 Plane metadata에 함께 저장한다. - [ ] 자동 enqueue 여부와 사용자/운영 트리거 경계를 결정한다. -- [ ] external ref metadata 계약을 확정한다. +- [ ] 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 정책을 정한다. + - [x] agent 단계 완료 기록은 prefix와 이모지가 있는 comment로 남기는 방향을 샘플 검증한다. + - [ ] comment prefix 세트와 작성 타이밍을 확정한다. - [ ] 중복 생성 방지와 재시도 시 식별 기준을 정한다. - [ ] Workflow Core에서 처리할 lifecycle, retry, timeout, notification 요구사항을 정리한다. @@ -38,6 +47,7 @@ Plane Task Pipeline Design - [ ] Plane work item에서 core task로 이어지는 pipeline entrypoint와 계약이 문서화되어 있다. - [ ] enqueue 조건, idempotency 기준, 실패 표시 방식이 결정되어 있다. +- [ ] provider board state, core canonical state, label/comment projection 계약이 문서화되어 있다. - [ ] completed/failed/cancelled 결과를 Plane에 반영하는 최소 정책이 결정되어 있다. - [ ] Workflow Core가 pipeline 계약 질문 없이 상태 전이 구현을 시작할 수 있다. @@ -45,6 +55,7 @@ Plane Task Pipeline Design - Plane webhook 구현 - Plane 전체 양방향 동기화 +- Plane custom property 또는 work item type Pro 기능 의존 - task lifecycle, retry, timeout의 실제 구현 - 외부 협업 도구로 notification 발송 - Mattermost 메시지 발송 구현 @@ -65,4 +76,23 @@ Plane Task Pipeline Design - task source는 `plane`, external provider는 `plane`, external id는 `work_item_id`로 저장한다. - `workspace_slug`, `project_id`, `work_item_id`, `state_id`, `external_url`은 `payload.plane`과 `external_metadata`에 저장한다. - 생성 직후 task 상태는 `pending`이며, 이 entrypoint는 enqueue, Plane 상태 변경, 결과 comment 발행을 수행하지 않는다. +- 상태 설계 결정: + - provider board state는 `backlog`, `todo`, `in_progress`, `testing`, `complete`, `cancel`의 소유권/검증 단계로 유지한다. + - `in_progress`를 planning, implementing, review 같은 board state로 쪼개지 않고, agent 내부 실행 상태는 core task metadata에 canonical 값으로 저장한다. + - agent 내부 실행 상태 후보는 `agent_run_state`, `agent_phase`, `wait_type`, `status_reason`, `last_heartbeat_at`, `plan_ref`, `attempt`다. + - agent가 작업 중 사용자 판단을 기다릴 때는 board state를 `in_progress`로 유지하고 `agent_run_state=waiting_for_user`와 `wait_type`으로 멈춤 이유를 표현한다. + - `testing`은 agent가 plan, 구현, 자체 테스트, 자체 리뷰 루프를 끝낸 뒤 사용자가 직접 테스트하는 단계다. + - provider projection은 라벨을 우선 사용한다. 예: `agent:waiting-user`, `phase:planning`, `agent:blocked`, `agent:failed`. + - 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 내부 실행 상태 분리 방식을 보여준다. +- comment 기록 규칙 후보: + - `🧭 PLAN | <요약>`: plan 작성 또는 계획 검토 단계 완료 기록 + - `🛠️ WORK | <요약>`: 구현 또는 문서 반영 단계 완료 기록 + - `🔎 REVIEW | <요약>`: 코드리뷰/self-review 단계 완료 기록 + - `✅ VERIFY | <요약>`: 테스트/검증 완료 기록 + - 각 comment 본문은 1~2줄 요약을 기본으로 하며, 자세한 실행 로그나 상태 metadata는 core에 남긴다. +- 착수 상태: + - 이 마일스톤은 방향성과 샘플을 정리했지만, 당장 구현 착수 대상으로 보지는 않는다. + - 다음 착수 시에는 trigger 경계, core metadata schema, provider label mapping을 먼저 확정한다. - 확인 필요: trigger 방식은 현재 구현 상태와 운영 기대치를 보고 수동 endpoint 유지, webhook, polling 중 하나를 선택한다. diff --git a/agent-ops/rules/project/domain/core/rules.md b/agent-ops/rules/project/domain/core/rules.md index 2552d9b..0534eb4 100644 --- a/agent-ops/rules/project/domain/core/rules.md +++ b/agent-ops/rules/project/domain/core/rules.md @@ -1,7 +1,7 @@ --- domain: core -last_rule_review_commit: e3b5dae725db62dd7a47c563abcce557e0557551 -last_rule_updated_at: 2026-05-21 +last_rule_review_commit: cc00ac25fb862e6ff2d4269f0c78cf1278e10e69 +last_rule_updated_at: 2026-05-23 --- # core @@ -45,8 +45,23 @@ NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduli - `internal/notification/service.go` — task 완료 notification 발행. - `internal/adapters/openai/client.go` — OpenAI integration. - `internal/adapters/a2a/client.go` — A2A integration. +- `internal/adapters/plane/client.go` — Plane work item 조회, comment 생성, state update integration. - `internal/db/tasks.sql.go` — SQLC generated query boundary. +## Plane dev 작업 메모 + +- dev Plane URL은 `https://plane.toki-labs.com`이다. +- dev Plane 서버 확인이 필요하면 `ssh toki@toki-labs.com`으로 접속하고, Plane compose 위치는 `~/docker/services/plane/compose`다. +- 원격 SSH의 기본 shell에서는 `docker`가 PATH에 없을 수 있으므로 `zsh -lc`로 실행한다. 예: `cd ~/docker/services/plane/compose && docker compose ps`. +- compose service 이름은 `plane-api`, `plane-worker`, `plane-beat`, `plane-frontend`, `postgres`, `redis`, `rabbitmq`, `minio`다. 실제 컨테이너 이름은 `plane-api`, `plane-worker`, `plane-beat`, `plane-frontend`, `plane-postgres`, `plane-redis`, `plane-rabbitmq`, `plane-minio`다. +- NomadCode dev Plane workspace slug는 `general`, workspace id는 `dadf050e-cd1e-4590-bc33-672511630841`, project id는 `a6beb42f-7a8a-410c-b50f-ea3ca94828f3`, project identifier는 `NOMAD`다. +- NomadCode project state id: Backlog `62d4c50c-0cea-4a76-a0ed-ec97498b2d5f`, Todo `45ba7449-f684-4381-af6d-5854747c5e8d`, In Progress `c6ac1a6b-74d5-47fb-8b36-646d2bf0284d`, Done `ea2e5b48-8bf1-4723-b749-de7723be41e9`, Cancelled `f29c06c2-d70c-4b56-a83c-fccc4db60ae4`. +- Plane API token이나 서버 `.env`의 secret 값은 domain rule에 기록하지 않는다. API 호출은 가능하면 `PLANE_TOKEN` 환경 변수로 수행하고, 토큰이 없을 때 서버 내부 조작이 명시적으로 요청되면 `plane-api`의 Django shell/ORM을 우선 사용한다. +- Plane custom property는 work item types 기반 기능이며, 현재 NomadCode dev project의 `is_issue_type_enabled`는 `False`다. 무료 self-hosted/free tier에서는 이 기능을 전제로 설계하지 않는다. +- Plane work item 샘플 `NOMAD-13`은 `In Progress` state에 있으며, board state와 agent 내부 실행 상태를 분리하는 예시다. external source/id는 `nomadcode` / `sample-agent-in-progress-state`이고, 라벨 `agent:waiting-user`, `phase:planning`으로 내부 상태를 보드에서 보이게 한다. +- provider-neutral 상태 설계는 board state를 `backlog`, `todo`, `in_progress`, `testing`, `complete`, `cancel`로 두고, canonical agent 실행 상태는 core task metadata에 저장한다. provider에는 labels를 우선 투영하고, 자세한 사유는 comment로 남긴다. +- Plane과 Jira 모두 provider workflow status는 가볍게 유지한다. agent 내부 실행 상태는 우선 labels로 투영하고, Jira에서는 필요 시 issue property/custom field를 보조 저장소로 쓸 수 있게 adapter 경계를 둔다. + ## 유지할 패턴 - Go package 경계는 `internal/` 단위로 유지한다. @@ -55,6 +70,8 @@ NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduli - 환경 변수 기본값과 alias는 `internal/config`에서 관리하고 README의 실행 예시와 어긋나지 않게 유지한다. - scheduler 변경은 가능한 한 job 단위 테스트를 추가한다. - HTTP API 변경은 web/mobile 영향과 contracts 반영 필요성을 함께 판단한다. +- Plane 관련 작업에서는 board state와 agent 내부 실행 상태를 같은 workflow state로 섞지 않는다. `testing`은 agent가 자체 검증과 리뷰 루프를 끝낸 뒤 사용자 테스트를 기다리는 상태로 사용한다. +- Plane/Jira work item 본문(description)은 작업 요구사항과 맥락의 원본으로 취급하고, agent 실행 상태를 매번 갱신하는 저장소로 사용하지 않는다. ## 다른 도메인과의 경계