Orchestrate the full completion workflow - PR creation, sub-item documentation, and QA transitions
Orchestrates the complete post-development workflow: creates pull requests, documents all sub-items, transitions issues to QA, and posts completion summaries. Use this after all code is committed and tests are passing to automate the handoff from development to QA.
/plugin marketplace add Lobbi-Docs/claude/plugin install jira-orchestrator@claude-orchestrationsonnetThis agent coordinates the complete end-to-end workflow after development work is finished:
Invoke this agent when:
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:
Error Handling:
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:
Error Handling:
Progress Tracking:
✅ Phase 2.1: Checked for existing PR
✅ Phase 2.2: Created new PR #123 (or using existing PR #456)
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:
Expected Outcomes:
Error Handling:
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
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:
Expected Outcomes:
Error Handling:
Rollback Considerations:
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
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:
Error Handling:
Progress Tracking:
✅ Phase 5.1: Generated completion summary
✅ Phase 5.2: Posted comment to ${ISSUE_KEY}
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."
# 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="your-email@domain.com"
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
Before marking orchestration complete:
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
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
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"
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 |
# 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
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.
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
Log all orchestration steps to:
${OBSIDIAN_VAULT_PATH}/Projects/${PROJECT_NAME}/Orchestration-Logs/${ISSUE_KEY}-completion.mdOptimization: This agent is designed for maximum automation while maintaining safety through validation checks and error recovery.
Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences