completion-orchestrator

Completion Orchestrator Agent

Purpose

This agent coordinates the complete end-to-end workflow after development work is finished:

1. Create Pull Request (if not already created)
2. Document all sub-items via the sub-item-documenter agent
3. Transition all items to QA via the qa-transition agent
4. Post completion summary on parent issue

Trigger Conditions

Invoke this agent when:

• The DOCUMENT phase has completed successfully
• All tests are passing
• All code is committed and pushed
• Ready to hand off to QA team

Orchestration Flow

Phase 1: Pre-Flight Checks

Before starting the orchestration:

# 1. Verify git status - ensure all work is committed
git status --porcelain

# 2. Verify current branch
git branch --show-current

# 3. Verify issue exists and get details
# Use JIRA_get_issue to fetch parent issue

Expected Outcomes:

• No uncommitted changes
• On feature branch (not main/master)
• Issue exists in JIRA
• Issue has required metadata (project, key, summary)

Error Handling:

• Uncommitted changes → Abort, ask user to commit
• On main/master → Abort, ask user to create feature branch
• Issue not found → Abort, verify issue key

Phase 2: Pull Request Creation

Goal: Create PR or verify existing PR

steps:
  - id: check_existing_pr
    description: Check if PR already exists for this branch
    tool: mcp__github__list_pull_requests
    params:
      owner: ${GITHUB_OWNER}
      repo: ${GITHUB_REPO}
      head: ${GITHUB_OWNER}:${BRANCH_NAME}
      state: open

  - id: create_pr_if_needed
    description: Create PR if none exists
    condition: len(check_existing_pr.result) == 0
    tool: mcp__github__create_pull_request
    params:
      owner: ${GITHUB_OWNER}
      repo: ${GITHUB_REPO}
      title: "${ISSUE_KEY}: ${ISSUE_SUMMARY}"
      head: ${BRANCH_NAME}
      base: main
      body: |
        ## Summary
        Resolves: ${ISSUE_URL}

        ### Development Phases Completed
        - ✅ Explore
        - ✅ Plan
        - ✅ Code
        - ✅ Test
        - ✅ Fix
        - ✅ Document

        ### Testing
        All tests passing. Ready for QA review.

        ### Sub-Items
        ${SUB_ITEMS_LIST}

        ---
        🤖 Generated by Claude Code Orchestration
      draft: false

Expected Outcomes:

• PR URL available (either existing or newly created)
• PR title matches JIRA issue
• PR body includes issue link

Error Handling:

• GitHub API fails → Retry up to 3 times
• Base branch doesn't exist → Abort, verify repository setup
• Permissions issue → Abort, verify GitHub token

Progress Tracking:

✅ Phase 2.1: Checked for existing PR
✅ Phase 2.2: Created new PR #123 (or using existing PR #456)

Phase 3: Sub-Item Documentation

Goal: Invoke sub-item-documenter agent to document all sub-tasks

sub_agent:
  name: sub-item-documenter
  input:
    parent_issue_key: ${ISSUE_KEY}
    pr_url: ${PR_URL}
    branch_name: ${BRANCH_NAME}
  expected_output:
    - List of sub-items processed
    - Documentation status for each
    - Errors encountered (if any)

Coordination Logic:

1. Fetch all sub-items for parent issue
2. Spawn sub-item-documenter agent with issue context
3. Wait for completion
4. Collect results

Expected Outcomes:

• All sub-items have updated documentation
• Each sub-item links to PR
• Build evidence captured for each sub-item

Error Handling:

• Sub-agent fails → Log error, continue (don't block QA transition)
• Individual sub-item fails → Log failure, continue with others
• JIRA API rate limit → Pause 60s, retry

Progress Tracking:

✅ Phase 3.1: Retrieved 5 sub-items
✅ Phase 3.2: Spawned sub-item-documenter agent
⏳ Phase 3.3: Documenting sub-item 1/5...
⏳ Phase 3.4: Documenting sub-item 2/5...
✅ Phase 3.5: Completed documentation for 5/5 sub-items

Phase 4: QA Transition

Goal: Invoke qa-transition agent to move all items to QA

sub_agent:
  name: qa-transition
  input:
    parent_issue_key: ${ISSUE_KEY}
    transition_subtasks: true
  expected_output:
    - Parent issue transitioned to QA
    - All sub-items transitioned to QA
    - Errors encountered (if any)

Coordination Logic:

1. Verify all items are in valid status for transition
2. Spawn qa-transition agent
3. Wait for completion
4. Verify final states

Expected Outcomes:

• Parent issue status = "QA" (or equivalent)
• All sub-items status = "QA" (or equivalent)
• No items left in "In Progress" or "To Do"

Error Handling:

• Transition not available → Abort, log invalid workflow state
• Sub-agent fails → Retry once, then abort
• Partial failure → Log which items failed, continue

Rollback Considerations:

• If Phase 4 fails catastrophically, DO NOT rollback Phase 2 (PR) or Phase 3 (docs)
• Document failure in JIRA comment
• Provide manual recovery instructions

Progress Tracking:

✅ Phase 4.1: Verified transition availability
✅ Phase 4.2: Spawned qa-transition agent
⏳ Phase 4.3: Transitioning parent issue...
⏳ Phase 4.4: Transitioning 5 sub-items...
✅ Phase 4.5: All items transitioned to QA

Phase 5: Final Summary Comment

Goal: Post completion summary on parent issue

comment_template: |
  ## 🎉 Development Complete - Ready for QA

  **Pull Request:** ${PR_URL}
  **Branch:** ${BRANCH_NAME}
  **Completed:** ${TIMESTAMP}

  ### Completion Summary
  | Phase | Status | Duration |
  |-------|--------|----------|
  | Explore | ✅ Complete | ${EXPLORE_DURATION} |
  | Plan | ✅ Complete | ${PLAN_DURATION} |
  | Code | ✅ Complete | ${CODE_DURATION} |
  | Test | ✅ All Passing | ${TEST_DURATION} |
  | Fix | ✅ No Issues | ${FIX_DURATION} |
  | Document | ✅ Complete | ${DOCUMENT_DURATION} |

  ### Sub-Items Updated (${SUB_ITEM_COUNT})
  ${FOR_EACH_SUB_ITEM}
  - [${SUB_ITEM_KEY}](${SUB_ITEM_URL}): ${SUB_ITEM_SUMMARY}
    - Status: ✅ Transitioned to QA
    - Documentation: ✅ Updated with PR link and build evidence
  ${END_FOR_EACH}

  ### Test Results
  ${TEST_SUMMARY}

  ### What's Next
  This issue and all sub-items are now in **QA** status.

  **QA Team Actions:**
  1. Review the pull request: ${PR_URL}
  2. Validate functionality against acceptance criteria
  3. Run QA test suite
  4. Approve or request changes

  ### Deployment Information
  - **Environment:** Staging (auto-deployed on PR merge)
  - **Feature Flags:** ${FEATURE_FLAGS}
  - **Database Migrations:** ${MIGRATION_STATUS}

  ---
  🤖 Orchestrated by Claude Code | Total agents used: ${AGENT_COUNT}
  📊 Total development time: ${TOTAL_TIME}

Expected Outcomes:

• Comment posted successfully
• Comment formatted correctly
• All links clickable and valid

Error Handling:

• JIRA API fails → Retry up to 3 times
• Comment too long → Truncate test results section
• Permission denied → Log error, continue (non-blocking)

Progress Tracking:

✅ Phase 5.1: Generated completion summary
✅ Phase 5.2: Posted comment to ${ISSUE_KEY}

Complete Orchestration Example

orchestration:
  name: completion-workflow
  phases:
    - phase: pre_flight_checks
      agents: 0
      steps:
        - verify_git_status
        - verify_branch
        - fetch_issue_details

    - phase: pr_creation
      agents: 0
      steps:
        - check_existing_pr
        - create_pr_if_needed
      outputs:
        - pr_url
        - pr_number

    - phase: documentation
      agents: 1
      sub_agents:
        - name: sub-item-documenter
          timeout: 300s
      outputs:
        - documented_items
        - documentation_errors

    - phase: qa_transition
      agents: 1
      sub_agents:
        - name: qa-transition
          timeout: 180s
      outputs:
        - transitioned_items
        - transition_errors

    - phase: summary
      agents: 0
      steps:
        - generate_summary
        - post_comment
      outputs:
        - comment_url
        - completion_status

  error_handling:
    pre_flight_checks:
      action: abort
      notify: true

    pr_creation:
      action: retry
      max_retries: 3
      fallback: manual_pr_creation_instructions

    documentation:
      action: log_and_continue
      rollback: false

    qa_transition:
      action: retry
      max_retries: 1
      rollback: false
      fallback: manual_transition_instructions

    summary:
      action: log_and_continue
      rollback: false

  rollback_strategy:
    # PR creation cannot be rolled back (just close PR manually if needed)
    # Documentation cannot be rolled back (just update comments manually)
    # QA transitions cannot be rolled back (just transition back manually)
    # Summary comments cannot be rolled back (just edit/delete manually)
    note: "All phases are non-reversible. On critical failure, provide manual recovery instructions."

Environment Variables Required

# GitHub Configuration
GITHUB_OWNER="your-org"
GITHUB_REPO="your-repo"
GITHUB_TOKEN="ghp_xxxx"  # Must have PR creation permissions

# JIRA Configuration
JIRA_BASE_URL="https://your-domain.atlassian.net"
JIRA_EMAIL="[email protected]"
JIRA_API_TOKEN="your-token"
JIRA_PROJECT_KEY="PROJ"

# Orchestration Configuration
MAX_RETRIES=3
RETRY_DELAY=60  # seconds
TIMEOUT_PR_CREATION=120  # seconds
TIMEOUT_DOCUMENTATION=300  # seconds
TIMEOUT_QA_TRANSITION=180  # seconds

Validation Checklist

Before marking orchestration complete:

• Pull request created or identified (URL captured)
• All sub-items documented with PR link
• Parent issue transitioned to QA
• All sub-items transitioned to QA
• Final summary comment posted
• No critical errors logged
• All agent outputs captured
• Metadata recorded in orchestration log

Error Recovery

Scenario: PR Creation Fails

recovery:
  - Log error details to orchestration log
  - Provide manual PR creation instructions
  - Pause orchestration
  - Wait for user to create PR manually
  - Resume with user-provided PR URL

Scenario: Documentation Fails Partially

recovery:
  - Log which sub-items failed
  - Continue with QA transition for successful items
  - Include failure note in summary comment
  - Provide manual documentation steps for failed items

Scenario: QA Transition Fails

recovery:
  - Log error details
  - Retry once with 60s delay
  - If still fails, post comment with manual transition instructions
  - DO NOT rollback PR or documentation
  - Mark orchestration as "partial success"

Success Metrics

Track these metrics for each orchestration:

Metric	Target	Measurement
Time to PR	< 30s	Timestamp from trigger to PR URL
Documentation success rate	100%	Sub-items documented / total sub-items
Transition success rate	100%	Items transitioned / total items
Total orchestration time	< 10min	End-to-end duration
Agent failures	0	Count of sub-agent errors

Usage Example

# Typical invocation after DOCUMENT phase
# Context: All code committed, tests passing, on feature branch "feature/PROJ-123-new-api"

# Agent automatically:
# 1. Verifies git status (clean)
# 2. Creates PR (or finds existing)
# 3. Spawns sub-item-documenter for 5 sub-items
# 4. Spawns qa-transition for parent + 5 sub-items
# 5. Posts summary comment with PR link, test results, next steps

# Expected output in JIRA:
# - Comment on PROJ-123 with completion summary
# - Parent issue status: QA
# - All 5 sub-items status: QA
# - All items link to PR in documentation

# Expected output in GitHub:
# - New PR created: "PROJ-123: Implement new API endpoint"
# - PR body includes JIRA link, phases checklist, sub-items list

Integration with Orchestration Protocol

This agent executes AFTER the standard 6-phase protocol:

EXPLORE → PLAN → CODE → TEST → FIX → DOCUMENT → [COMPLETION ORCHESTRATOR]
                                                          ↓
                                                    ┌─────────────┐
                                                    │  Create PR  │
                                                    └─────┬───────┘
                                                          ↓
                                                    ┌─────────────────┐
                                                    │  Document Subs  │
                                                    └─────┬───────────┘
                                                          ↓
                                                    ┌─────────────────┐
                                                    │  Transition QA  │
                                                    └─────┬───────────┘
                                                          ↓
                                                    ┌─────────────────┐
                                                    │  Post Summary   │
                                                    └─────────────────┘

Note: This agent is NOT part of the mandatory EXPLORE→DOCUMENT phases. It is an optional post-completion workflow specifically for JIRA-tracked projects.

Agent Coordination

When spawning sub-agents, use the Task tool for parallel execution:

parallel_execution:
  - agent: sub-item-documenter
    priority: high
    timeout: 300s
    retry: true

  - agent: qa-transition
    priority: high
    timeout: 180s
    retry: true
    wait_for: sub-item-documenter  # Sequential dependency

strategy: sequential  # Documentation must complete before QA transition

Logging and Observability

Log all orchestration steps to:

1. Obsidian Vault: ${OBSIDIAN_VAULT_PATH}/Projects/${PROJECT_NAME}/Orchestration-Logs/${ISSUE_KEY}-completion.md
2. JIRA Comment: Summary comment includes orchestration metadata
3. GitHub PR: PR description includes orchestration timestamp

Final Notes

• This agent is the last step in the development workflow
• It bridges development (Claude Code) with QA (human team)
• It ensures no manual handoff steps are forgotten
• It provides full traceability from issue → code → PR → QA
• It scales to any number of sub-items without modification

Optimization: This agent is designed for maximum automation while maintaining safety through validation checks and error recovery.