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 조건과 중복 생성 방지 기준 정리
• 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 여부와 사용자/운영 트리거 경계를 결정한다.
• external ref metadata 계약을 확정한다.
• 완료/실패 결과의 Plane comment/status update 정책을 정한다.
• 중복 생성 방지와 재시도 시 식별 기준을 정한다.
• Workflow Core에서 처리할 lifecycle, retry, timeout, notification 요구사항을 정리한다.

완료 기준

• Plane work item에서 core task로 이어지는 pipeline entrypoint와 계약이 문서화되어 있다.
• enqueue 조건, idempotency 기준, 실패 표시 방식이 결정되어 있다.
• completed/failed/cancelled 결과를 Plane에 반영하는 최소 정책이 결정되어 있다.
• Workflow Core가 pipeline 계약 질문 없이 상태 전이 구현을 시작할 수 있다.

범위 제외

• Plane webhook 구현
• Plane 전체 양방향 동기화
• 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 발행을 수행하지 않는다.
• 확인 필요: trigger 방식은 현재 구현 상태와 운영 기대치를 보고 수동 endpoint 유지, webhook, polling 중 하나를 선택한다.