Orchestrate

Orchestrate: Full Task Pipeline

Run the complete agent pipeline for a task: branch setup, implement, test, CI validate, review, push, and create PR.

Usage

/orchestrate <asana-task-id-or-url>

Accepts either:

• Asana task ID: 1213560067347874
• Asana URL: https://app.asana.com/0/1234567890/1213560067347874

Pipeline

Phase 0: Setup

1. Parse the Asana task ID from the argument:

   • If it's a URL, extract the last numeric segment as the task ID
   • If it's already a numeric ID, use it directly

2. Read the Asana task to get:

   • Task title
   • Task description and acceptance criteria
   • Any tags or custom fields (e.g., package name, ticket number)

3. Create a feature branch from main:

   • Pull latest main: git checkout main && git pull origin main
   • Generate branch name from task: feat/<ticket>-<slug>
     • Extract ticket number from task name or custom field (e.g., QVAC-123)
     • Slugify the task title (lowercase, hyphens, max 50 chars)
     • Example: feat/QVAC-123-add-rag-support-for-lancedb
   • If no ticket number found: feat/<task-title-slug>
   • Create and switch to branch: git checkout -b <branch-name>

4. Inform the user of the setup:

   Task: <task-title>
   Branch: <branch-name>
   

Phase 0.5: Plan

Before any implementation, create a plan for the user to approve:

1. Read the relevant source files mentioned in the task description or likely affected by the changes
2. Draft an implementation plan that includes:
   • Summary of what will be changed and why
   • Files to create or modify (with brief description of changes per file)
   • Approach and key design decisions
   • Dependencies or packages to add (if any)
   • How it will be verified (build commands, test commands)
3. Present the plan to the user and wait for approval
   • If the user requests changes, update the plan and ask again
   • Do NOT proceed until the user explicitly approves
4. Comment on the Asana task with the approved plan

Phase 1: Implement

Launch the implementer agent with the Asana task ID and the approved plan.

Implement Asana task <task-id>. Follow this approved plan:

<paste the approved plan here>

Write code within scope of the plan, verify build/tests pass, and commit working changes.

Wait for completion. If the implementer reports failure (e.g., ambiguous requirements, build failures after 3 retries), stop the pipeline and report to the user.

Phase 1.5: Determine test and CI requirements

After implementation, analyze the changed files and the Asana task to decide what's needed next.

Run git diff --name-only main...HEAD and apply these rules:

1. Native addon packages — if changed files match a package in the CI Package Mapping table in .agent/knowledge/ci-validation.md, CI is needed. Use the short name from that table. If multiple addon packages changed, run CI for each.

2. SDK / TS packages (packages/sdk/**, packages/rag/**, packages/cli/**) — SDK CI runs automatically via pr-checks-sdk-pod on PR creation. No manual trigger needed.

3. Everything else (simple libraries, docs, workflows, config, markdown) — no CI needed.

If CI is needed, inform the user which packages will be validated and why.

Determine if new tests are needed by checking:

Read the Asana task acceptance criteria. If they describe specific behaviors or scenarios, those should become tests.

Phase 1.75: Write Tests

If Phase 1.5 determined tests are needed, launch the test-writer agent:

Write automated tests for the changes on the current branch. Task ID: <task-id>. Focus on new public APIs, new behavior, and edge cases. Match existing test patterns.

Wait for completion. If the test-writer discovers code bugs, launch the implementer again with the bug details before proceeding.

If tests are not needed, skip to Phase 2.

Phase 2: CI Validation

If Phase 1.5 determined CI is needed:

1. Push the current branch: git push -u origin HEAD
2. Launch the ci-validator agent for each affected package
3. If CI fails with code errors: go back to Phase 1 — launch implementer again with the error details
4. If CI fails with infra errors: let ci-validator handle retries
5. Maximum 2 implement→CI loops before stopping

If CI is not needed, skip to Phase 3.

Phase 3: Review

Launch the code-reviewer agent:

Review all changes on the current branch against main. Task ID: <task-id>. Check requirements match, bugs, conventions, security, scope, and test coverage. Fix issues directly and commit fixes.

Wait for completion. Collect the review summary.

Phase 4: Re-validate (if reviewer made fixes)

If the reviewer committed any fixes AND Phase 1.5 determined CI was needed:

1. Re-run CI validation for the affected packages
2. If CI passes, proceed to reporting

If no CI needed or no reviewer fixes, proceed to reporting.

Phase 5: Push and Create PR

1. Push the branch to origin:

   git push -u origin HEAD
   

2. Determine PR type from the changed files:

   • If changes are in packages/sdk/ or other TS packages → SDK PR
   • If changes are in native addon packages → Addon PR
   • If mixed → use addon format (more detailed)

3. Create the PR using gh pr create:

   • Title: <ticket> <prefix>[tags]: <task-title-summary> (following commit format from CLAUDE.md)
   • Body: Generate based on PR type:
     • For addon packages: follow the format from /qv-addon-pr-create
     • For SDK packages: follow the format from /qv-sdk-pr-create
     • Include: what changed, why, test plan, link to Asana task
   • Base: main
   • Example:

     gh pr create --base main --title "QVAC-123 feat: add RAG support" --body "..."
     

4. Link the PR to the Asana task: comment on the task with the PR URL.

Phase 6: Report

Produce a final summary:

Pipeline complete for task <task-id>:

Branch: <branch-name>
PR: <pr-url>

Implementation:
  - [summary from implementer]
  - Files changed: [list]

Tests:
  - [added/skipped, with reason]
  - Tests added: [count and brief descriptions]
  - Code bugs found by tests: [count or none]

CI Validation:
  - [pass/fail/skipped]
  - Packages tested: [list or "n/a — no native addon changes"]
  - Platforms: [list]

Review:
  - Issues found and fixed: [count]
  - Issues flagged but not fixed: [count, with details]

Status: [ready for human review / needs attention]

Update the Asana task:

• Add the final summary as a comment
• If all phases passed, mark the task as complete

Error handling

• If implementer fails: report what went wrong and stop
• If CI fails after 2 implement→CI loops: report the persistent failure and stop
• If reviewer finds architectural concerns: report them and stop
• If PR creation fails: report the error, the branch is still pushed
• At any stop point, comment on the Asana task with current status

Important notes

• Phase 0 creates the branch automatically — user does not need to set up anything
• The skill asks for confirmation before marking the Asana task complete
• Each agent runs in isolation with fresh context
• The pipeline can be resumed manually if interrupted — just re-run from the failed phase