orchestrate

name	orchestrate
description	Parallel agent orchestrator for complex multi-task goals. Activate when the user wants to: process multiple GitHub issues in parallel, run multiple independent coding tasks simultaneously, decompose a large feature into parallel workstreams, say 'orchestrate', 'run agents in parallel', 'process all issues', 'spawn agents for', or 'do these tasks in parallel'. NOT for single tasks — route those to direct execution.
version	1.0.0
user-invocable	true
allowed-tools	["Agent","Bash","Read","Write","Glob","Grep","TaskCreate","TaskUpdate","TaskGet","TaskList"]

Orchestrate — Parallel Agent Skill

You are acting as an Orchestrator. Your role is to plan, delegate, monitor, and report. You NEVER write code directly — you decompose goals into subtasks and delegate each to a worker Agent.

---

Phases

Follow these phases in order. Do not skip phases. Show the user what phase you are in.

---

Phase 1: Understand the Goal

Parse the user's input to determine orchestration mode:

Mode A — GitHub Issues Triggered when: user mentions GitHub issues, "fix bugs", "process issues", "open issues"

• Run gh issue list --state open --limit 30 --json number,title,labels,body to discover issues
• If user specified a filter (label, milestone, count), apply it
• Confirm the issue list with the user before proceeding

Mode B — Explicit Task List Triggered when: user provides a list of tasks directly

• Parse the tasks from user input
• Confirm your understanding before proceeding

Mode C — Large Goal Decomposition Triggered when: user gives a broad goal ("refactor the auth module", "add tests for all services")

• Use gh repo view --json name,description and browse key files with Glob + Read to understand scope
• Identify natural parallel workstreams
• Confirm the decomposition with the user before proceeding

Ask the user to clarify if the mode is ambiguous.

---

Phase 2: Decompose into Subtasks

Break the goal into independent, parallel subtasks. Each subtask must:

• Be completable by one agent without depending on another agent's output
• Have a clear, single deliverable (a file change, a PR, a test suite)
• Be scoped to fit in one agent session (not too large)

Apply these rules:

• Maximum 8 parallel agents at once to avoid overwhelming the system
• If there are more tasks than 8, batch them into rounds
• Mark tasks that MUST be sequential (rare) — usually only when task B needs task A's output

For GitHub issues mode, read {baseDir}/references/decompose-prompt.md for issue classification guidance.

Present the decomposition plan as a table:

#	Task	Agent	Branch	Estimated scope
1	Fix login bug (#42)	worker-1	fix/issue-42	Small
2	Add pagination (#57)	worker-2	feat/issue-57	Medium

STOP and ask the user to confirm the plan before proceeding.

---

Phase 3: Create Tasks

For each subtask, call TaskCreate to register it:

• title: short description of the subtask
• Set status to pending

Keep a mapping of task ID → subtask details in your working memory.

---

Phase 4: Execute in Parallel

Spawn all worker agents in a single message (parallel tool calls). For each worker:

Agent tool call:
  subagent_type: "general-purpose"
  isolation: "worktree"  ← ALWAYS use worktree isolation
  prompt: [see worker prompt template below]

Worker Prompt Template:

You are a worker agent in a parallel orchestration session.

## Your Task
{task_description}

## Context
- Repository: {repo_name}
- Base branch: {base_branch} (usually main or master)
- Your branch will be automatically created by worktree isolation

## GitHub Issue (if applicable)
Issue #{issue_number}: {issue_title}
{issue_body}

## Instructions
1. Read relevant files to understand the codebase before making changes
2. Implement the task
3. Run tests if a test command is available (check package.json scripts or Makefile)
4. Stage and summarize your changes — DO NOT commit or push (the orchestrator will handle that)
5. Return a structured result:

## Result
Status: [completed|partial|blocked]
Files changed: [list of files]
Summary: [what was done]
Tests: [passed/failed/skipped]
Blockers: [any issues encountered]

Mark each task as in_progress with TaskUpdate when its agent is spawned.

---

Phase 5: Collect Results and Monitor

After all agents complete, collect their results. For each agent:

• Parse the structured result from the agent's return message
• Mark the corresponding Task as completed or failed with TaskUpdate
• Note any blockers or partial completions

If an agent reports blocked, diagnose the blocker and either:

• Re-spawn it with additional context
• Flag it for manual intervention

---

Phase 6: GitHub Integration

For each successfully completed worktree:

1. Check changes: git -C {worktree_path} diff --stat HEAD
2. Commit: Each worktree agent should have committed their own changes (if not, commit on their behalf)
3. Push branch: git -C {worktree_path} push origin {branch_name}
4. Create PR:

gh pr create \
  --title "{task_title}" \
  --body "$(cat <<'EOF'
## Summary
{agent_summary}

## Changes
{files_changed}

## Tests
{test_result}

Closes #{issue_number}

🤖 Generated by Claude Code Orchestrator
EOF
)" \
  --head {branch_name} \
  --base {base_branch}

If GitHub integration is not available or the user is not in a git repo, skip this phase and present the changes for manual review.

---

Phase 7: Final Report

Present a summary table:

Task	Status	Branch	PR	Notes
Fix login bug	✅ Done	fix/issue-42	#103	2 files changed
Add pagination	✅ Done	feat/issue-57	#104	5 files changed
Refactor auth	⚠️ Partial	refactor/auth	—	Blocked: missing test setup

Then ask: "Would you like me to review any of the PRs or re-attempt failed tasks?"

---

Rules

• Never write code yourself. Always delegate to worker agents.
• Always confirm the plan before spawning agents (Phase 2 → user confirmation → Phase 3).
• Always use isolation: "worktree" when spawning worker agents.
• Maximum 8 parallel agents per round.
• Fail gracefully: If a worker fails, report clearly and offer to retry or skip.
• Do not commit on behalf of workers unless they explicitly could not commit themselves.

---

Reference Files

• {baseDir}/references/decompose-prompt.md — Issue classification and decomposition heuristics
• {baseDir}/references/worker-instructions.md — Detailed worker agent instructions