toki/nomadcode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nomadcode/agent-ops/roadmap/milestones/plane-task-pipeline-design.md
toki 3e0fd2a268 update roadmap milestones
2026-05-24 06:59:35 +09:00

15 KiB
Raw Blame History

Work Item Provider Pipeline Design

목표

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

단계

Work Item Provider Pipeline Design

상태

진행 중

구현 잠금

  • 상태: 해제
  • 이유: 이 Milestone은 이미 진행 중이며 provider-neutral pipeline 경계, 상태/projection 결정, 구현 검증 근거가 작업 컨텍스트에 누적되어 있다. 남은 작업은 같은 범위 안의 계약 보강과 구현 정리로 이어진다.
  • 해제 조건:
    • provider-neutral 생성, adapter interface, board state와 agent 실행 상태 분리 방향이 문서화되어 있다.
    • 현재 구현 상태와 남은 결정 항목이 작업 컨텍스트에 정리되어 있다.
    • 사용자가 현재 활성 Milestone의 잠금 보정을 승인했다.
  • 잠금 중 금지:
    • 해당 없음

범위

  • 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 완료/실패 결과를 provider comment/status로 발행하는 최소 정책 정리
  • provider별 workspace/project/work item/state metadata 사용 방식 확정
  • Workflow Core에 넘길 상태 변화, 실패 케이스, notification 요구사항 정리

필수 기능

  • [create-flow] Plane work item -> core task 생성/연결 흐름을 현재 구현 기준으로 문서화한다.
    • [create-entrypoint] 초기 entrypoint는 기존 POST /api/integrations/plane/tasks를 기준선으로 삼는다.
    • [create-scope] 생성 단계는 Plane work item 조회와 core task 저장까지만 담당한다.
    • [create-pending] 생성된 task는 pending 상태로 남기고 enqueue는 별도 단계에서 처리한다.
    • [create-metadata] Plane 연결 정보는 provider-neutral external ref와 work item metadata에 함께 저장한다.
  • [enqueue-trigger] 자동 enqueue 여부와 사용자/운영 트리거 경계를 결정한다.
    • [user-todo] backlog에서 todo로 옮기는 주체는 사용자로 둔다.
    • [todo-assignee] todo 상태여도 agent 작업자가 지정된 work item만 자동 실행 후보로 본다.
    • [service-token] provider API 인증은 일반 사용자형 service account token을 기본으로 둔다.
    • [token-local] Plane dev service account token은 ignored local file .env.plane.local에 저장하고, NomadCode project Admin 권한으로 검증한다.
    • [assignee-agent] agent 작업자 지정 신호는 provider assignee가 AGENT 일반 사용자형 service account인 경우로 확정한다.
    • [profile-metadata] worker profile과 실행 단계는 core metadata와 label/comment prefix로 표현한다.
    • [trigger-webhook] webhook-first trigger와 polling fallback의 세부 조건을 확정한다.
    • [labels-display] worker:*, agent:*, phase:* label은 실행 조건이 아니라 worker profile/실행 상태 표시용으로 둔다.
  • [adapter-interface] work item provider adapter interface를 설계한다.
    • [dto-contract] core pipeline이 사용할 provider-neutral DTO를 정의한다.
    • [provider-facets] work item 조회, comment 작성, status/state 변경, label projection 경계를 interface로 분리한다.
    • [adapter-mapping] Plane adapter와 Jira adapter가 같은 interface를 구현할 수 있는지 검증한다.
    • [provider-config] provider별 상태/라벨/comment 매핑은 adapter 설정으로 분리한다.
  • [generic-pipeline] 현재 Plane 고정 진입부를 provider-neutral 구조로 리팩토링한다.
    • [route-service] POST /api/integrations/plane/tasks의 Plane 전용 흐름을 generic pipeline service 아래로 옮긴다.
    • [handler-dto] HTTP handler가 Plane 타입과 직접 결합하지 않도록 요청 DTO와 변환 책임을 분리한다.
    • [task-mapper] buildPlaneCreateTaskInput의 core task 생성 로직을 provider-neutral mapper로 분리한다.
    • [compat-route] 기존 Plane endpoint는 compatibility entrypoint로 유지하거나 generic endpoint로 대체할지 결정한다.
  • [projection-contract] provider-neutral 상태와 projection 계약을 확정한다.
    • [board-states] board state는 backlog, todo, in_progress, testing, complete, cancel로 둔다.
    • [agent-metadata] in_progress 내부 agent 상태는 core task metadata를 canonical source로 둔다.
    • [label-first] Plane/Jira provider projection은 label-first로 둔다.
    • [desc-readonly] provider 본문(description)은 agent 실행 상태 저장소로 쓰지 않는다.
    • [metadata-schema] core task metadata schema와 provider label mapping을 구현 대상으로 확정한다.
  • [result-policy] 완료/실패 결과의 provider comment/status update 정책을 정한다.
    • [comment-prefix-sample] agent 단계 완료 기록은 prefix와 이모지가 있는 comment로 남기는 방향을 샘플 검증한다.
    • [comment-timing] comment prefix 세트와 작성 타이밍을 확정한다.
  • [idempotency] 중복 생성 방지와 재시도 시 식별 기준을 정한다.
  • [workflow-handoff] Workflow Core에서 처리할 lifecycle, retry, timeout, notification 요구사항을 정리한다.

완료 기준

  • 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 결과를 provider에 반영하는 최소 정책이 결정되어 있다.
  • Workflow Core가 pipeline 계약 질문 없이 상태 전이 구현을 시작할 수 있다.

범위 제외

  • Plane webhook 구현
  • Jira adapter 실제 구현
  • 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 중심 파일명 plane-task-pipeline-design.md는 대규모 rename을 피하기 위해 유지하되, 마일스톤 이름과 내용은 Work Item Provider Pipeline Design으로 일반화한다.
  • 선행 작업: Plane Communication Foundation
  • 후속 작업: Workflow Core
  • 현재 코드 결합 상태:
    • HTTP router는 기존 compatibility route인 POST /api/integrations/plane/tasks를 유지한다.
    • handler는 Plane adapter package나 Plane DTO를 직접 import하지 않고, 로컬 WorkItemReader interface와 workitem.Ref, workitem.WorkItem으로 조회 결과를 다룬다.
    • buildPlaneCreateTaskInput은 HTTP package 안에서 core task payload/external ref를 직접 조립하지 않고 workitem.BuildCreateTaskInput에 위임한다.
    • services/core/internal/workitem은 provider-neutral DTO, optional facet interface, projection mapping, task create mapper를 제공한다.
    • Plane adapter는 workitem.Provider, Reader, Commenter, StatusProjector를 구현하며 LabelProjector는 capability false로 남긴다.
    • DB schema는 external_provider, external_id, external_url, external_metadata로 provider-neutral 토대가 있으므로 유지한다.
    • 아직 별도 generic pipeline service는 추출되지 않았으며, compatibility HTTP handler가 provider-neutral reader/mapper와 workflow.CreateTask 호출을 직접 조립한다.
  • 초기 생성/연결 흐름:
    • 운영자 또는 상위 자동화가 POST /api/integrations/plane/tasks를 호출한다.
    • 요청 필수값은 workspace_slug, project_id, work_item_id이고, state_id, external_url, comment는 선택값으로 받는다.
    • core는 Plane adapter의 workitem.Reader 구현으로 work item detail을 조회해 provider-neutral title과 description 후보를 얻는다.
    • task title은 provider work item title을 우선하고, 비어 있으면 work_item_id를 사용한다.
    • task payload의 message는 요청 comment, provider text description, HTML description, title 순서로 선택하며 공백-only 후보는 건너뛴다.
    • task source는 plane, external provider는 plane, external id는 work_item_id로 저장한다.
    • provider-neutral metadata key provider, tenant, project, id, state_id, external_url은 payload.work_item과 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 내부 실행 상태 분리 방식을 보여준다.
  • trigger/auth 결정:
    • 사용자가 backlog에서 todo로 이동시키는 행위가 AI 작업 위임 의사로 간주될 수 있는 첫 관문이다.
    • core는 todo 상태와 agent 작업자 지정 신호가 함께 있을 때만 자동 실행 후보로 본다.
    • agent 작업자 지정 신호는 provider assignee가 AGENT display name을 가진 일반 사용자형 service account인 경우다.
    • 사용자가 todo로 작업을 옮기거나 todo 상태로 바로 생성하고, assignee를 AGENT로 지정하면 자동 실행 후보가 된다.
    • provider webhook을 우선 trigger로 사용한다.
    • polling은 webhook 누락, delivery 장애, core downtime 복구를 위한 fallback/reconciliation 경로로만 둔다.
    • webhook 수신 시 payload만 신뢰하지 않고 provider API로 work item을 다시 조회한 뒤 실행 조건을 재검증한다.
    • webhook과 polling 모두 동일한 idempotency 검사와 active task 중복 방지 로직을 통과해야 한다.
    • fallback polling 대상은 전체 provider item이 아니라 todo 상태와 agent 작업자 지정 신호가 있는 후보로 좁힌다.
    • provider API 호출과 댓글 작성은 일반 사용자형 service account token으로 수행한다.
    • Plane dev token은 repo root의 ignored .env.plane.local에서 로드하며, 해당 token 계정은 NomadCode project Admin 권한으로 API 조회/댓글 작성 smoke가 성공했다.
    • worker assignment identity는 AGENT assignee로 판단한다. 실제 worker profile과 agent 실행 단계는 core metadata, provider label, comment prefix에 남긴다.
    • Plane bot user는 UI 필터와 내장 agent trigger 경로가 있어 1차 작업자 모델로 전제하지 않는다.
  • provider abstraction 결정:
    • Plane은 첫 구현 provider일 뿐이며 core pipeline의 도메인 모델이 되어서는 안 된다.
    • Jira도 같은 workflow state, label/comment projection, idempotency 계약을 공유할 수 있어야 한다.
    • provider-neutral adapter contract는 workitem.Ref, WorkItem, CommentInput, StatusProjection, LabelProjection, Mapping으로 둔다.
    • 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에 남긴다.
  • 현재 지점 / 착수 상태:
    • 현재 상태는 진행 중이며, provider adapter interface 설계, Plane adapter facet 검증, provider-neutral task mapper, HTTP compatibility endpoint의 Plane DTO 의존 제거가 완료됐다.
    • agent-task/archive/2026/05/provider_neutral_plane_entrypoint/01_pipeline_mapper/complete.log에서 workitem.TaskCreateInput과 workitem.BuildCreateTaskInput 추가 및 whitespace fallback 회귀 수정이 PASS로 정리됐다.
    • agent-task/archive/2026/05/provider_neutral_plane_entrypoint/02+01_http_plane_entrypoint/complete.log에서 HTTP handler의 provider-neutral reader/mapper 전환과 compatibility route 유지가 PASS로 정리됐다.
    • 다음 진행 후보는 남은 generic pipeline service 경계 추출 여부를 결정하거나, core task metadata schema와 provider label mapping 확정으로 넘어가는 것이다.
    • 이후 남은 큰 결정은 core metadata schema, provider label mapping, comment prefix 작성 타이밍, idempotency/retry 기준이다.
  • 확인 필요: trigger 방식은 현재 구현 상태와 운영 기대치를 보고 수동 endpoint 유지, webhook, polling 중 하나를 선택한다.