nomadcode/agent-ops/roadmap/milestones/plane-task-pipeline-design.md

Plane Task Pipeline Design

목표

Plane Communication Foundation 다음 단계로 Plane work item과 core task pipeline 사이의 최소 제품 흐름을 확정한다. 자동 실행 구현에 들어가기 전에 생성, enqueue, 상태 투영, 중복 방지, 결과 발행 경계를 정리해 Workflow Core가 참조할 상태 변화와 실패 케이스를 명확히 한다.

단계

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 요구사항 정리

필수 기능

• Plane work item -> core task 생성/연결 흐름을 문서화한다.
  • 초기 entrypoint는 기존 POST /api/integrations/plane/tasks를 기준선으로 삼는다.
  • 생성 단계는 Plane work item 조회와 core task 저장까지만 담당한다.
  • 생성된 task는 pending 상태로 남기고 enqueue는 별도 단계에서 처리한다.
  • Plane 연결 정보는 provider-neutral external ref와 Plane metadata에 함께 저장한다.
• 자동 enqueue 여부와 사용자/운영 트리거 경계를 결정한다.
• provider-neutral 상태와 projection 계약을 확정한다.
  • board state는 backlog, todo, in_progress, testing, complete, cancel로 둔다.
  • in_progress 내부 agent 상태는 core task metadata를 canonical source로 둔다.
  • Plane/Jira provider projection은 label-first로 둔다.
  • provider 본문(description)은 agent 실행 상태 저장소로 쓰지 않는다.
  • core task metadata schema와 provider label mapping을 구현 대상으로 확정한다.
• 완료/실패 결과의 Plane comment/status update 정책을 정한다.
  • agent 단계 완료 기록은 prefix와 이모지가 있는 comment로 남기는 방향을 샘플 검증한다.
  • comment prefix 세트와 작성 타이밍을 확정한다.
• 중복 생성 방지와 재시도 시 식별 기준을 정한다.
• Workflow Core에서 처리할 lifecycle, retry, timeout, notification 요구사항을 정리한다.

완료 기준

• 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 계약 질문 없이 상태 전이 구현을 시작할 수 있다.

범위 제외

• Plane webhook 구현
• Plane 전체 양방향 동기화
• Plane custom property 또는 work item type Pro 기능 의존
• task lifecycle, retry, timeout의 실제 구현
• 외부 협업 도구로 notification 발송
• Mattermost 메시지 발송 구현
• 복잡한 workflow DSL
• Plane token 생성/보관/교체 운영 절차

작업 컨텍스트

• 관련 경로: 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 Communication Foundation
• 후속 작업: Workflow Core
• 초기 생성/연결 흐름:
  • 운영자 또는 상위 자동화가 POST /api/integrations/plane/tasks를 호출한다.
  • 요청 필수값은 workspace_slug, project_id, work_item_id이고, state_id, external_url, comment는 선택값으로 받는다.
  • core는 Plane adapter로 work item detail을 조회해 title과 description 후보를 얻는다.
  • task title은 Plane work item name을 우선하고, 비어 있으면 work_item_id를 사용한다.
  • task payload의 message는 요청 comment, Plane stripped description, plain description, HTML description, title 순서로 선택한다.
  • 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 중 하나를 선택한다.