Swarm

Team Plan

Design a multi-agent team plan for an implementation task. Enters plan mode, explores the codebase, selects agent roles, writes task breakdowns with prompts, and exits for user approval.

Input

• $ARGUMENTS — Task description (e.g., "build phase 4 of user-vaults", "implement auth middleware")

Agent Roster

Available agent types for teammates. Choose based on what each task requires:

| Agent Type | Tools | Best For | |-----------|-------|----------| | orc:orc-executor | Read, Write, Edit, Bash, Glob, Grep, Task, Skill, SendMessage, TaskCreate, TaskUpdate, TaskList | Sequential task implementation with per-task commits | | orc:orc-impl-verifier | Read, Write, Glob, Grep, Bash, Task, Skill, SendMessage, TaskCreate, TaskUpdate, TaskList | Verifying must_haves, running tsc/build, code review | | orc:frontend-verifier | All tools | Browser testing (Agent Browser), visual QA, UI polish, CSS fixes | | general-purpose | All tools | Flexible — anything that doesn't fit a specialized type | | orc:build-error-resolver | Read, Write, Edit, Bash, Grep, Glob | Fixing tsc/build errors with minimal diffs |

Selection heuristics:

• Implementation work → orc:orc-executor (commits per task, follows PLAN.md)
• Verification gate → orc:orc-impl-verifier (3-level checks against spec)
• Frontend with UI → add orc:frontend-verifier after verification passes
• Default model: opus for all teammates (strongest reasoning)

Execution

Step 1: Enter Plan Mode

Call EnterPlanMode. All subsequent work happens in plan mode (read-only except the plan file).

Step 2: Explore

Launch 1-3 Explore agents in parallel to understand:

1. Scope: What files exist, what needs to be created, what needs to be modified
2. Patterns: Existing code to mirror (find the closest analog for each new file)
3. Spec: Read any existing plan/spec docs referenced in the task description
4. Constraints: ABI signatures, type definitions, pitfall docs, test patterns

Each Explore agent should return:

• File inventory (exists vs. needs creation)
• Mirror patterns (existing file → new file mapping)
• Key constraints and gotchas
• Data flow (what hooks/components already provide)

Step 3: Design Team

Based on exploration results, decide:

1. How many executor+verifier pairs?

Parse PLAN.md tasks and their depends_on attributes. Build dependency DAG: each task is a node, depends_on edges point to prerequisites. Find independent chains: tasks connected by dependency edges form one chain (one executor). Tasks with no shared dependencies are independent chains (run in parallel).

Example:

• Tasks: 1.1, 1.2(→1.1), 1.3, 1.4(→1.2,1.3)
• Chains: [1.1→1.2→1.4], [1.3→1.4] — but 1.4 deps on both, so merge: [1.1→1.2], [1.3], both feed [1.4]

Wave model (simpler):

• Wave 1: tasks with no depends_on → spawn all in parallel (one executor each, or group if tiny)
• Wave 2: tasks whose deps are all in wave 1 → spawn after wave 1 verifiers pass
• Repeat until all tasks assigned

Minimum viable team (no parallelism):

• If all tasks are sequential (one chain): 1 executor + 1 verifier (same as before)
• If independent tasks exist: N executors + N verifiers (one pair per chain)

Cap at 4 executor+verifier pairs. Beyond 4, group small independent tasks together into one executor.

Also add:

• 1 ui-tester (orc:frontend-verifier) — only if frontend work involved
• Add more only if tasks are truly parallelizable

1. How many tasks per executor? Group by dependency chain, then cap:

• Tasks within a chain are sequential (executor does them in order)
• Independent chains get separate executors
• Max 3 tasks per executor. If a chain exceeds 3, split it: executor A takes the first 3, executor B takes the rest (depends_on: executor-A's verifier passes first)
• Verification is a separate task (verifier runs after executor tasks)
• UAT is a separate task (ui-tester runs after verification passes)

1. What prompts? Each teammate needs:

• Working directory (absolute path)
• Files to read first (spec, contracts, pitfalls — absolute paths)
• Files to mirror (existing patterns → new files)
• Hard rules (constraints that MUST be followed)
• Task IDs for executor (which tasks to execute)
• Wave number for executor (which wave this runs in)
• Executor dependencies (which executors must complete before this one starts)
• executor_name for executor (e.g., executor-1) — used for PROGRESS/SUMMARY/VERIFIED file names
• verifier_name for executor (e.g., verifier-1) — used as SendMessage recipient
• paired_executor for verifier (e.g., executor-1) — used as SendMessage recipient and VERIFIED file name
• verifier_name for verifier (e.g., verifier-1) — used in sentinel file content and internal messaging

Step 4: Write Plan

Write the team plan to the plan file using the template structure from [templates/TEAM-PLAN.md](templates/TEAM-PLAN.md).

Plan file sections (all required):

1. Context — Why, what, current state, scope summary
2. Team Structure — Table: role, agent type, model, purpose, wave if applicable
3. Task Breakdown — Per executor: assigned task_ids, wave, dependencies, detailed spec per task
4. Workflow — Numbered execution steps with decision points (PASS/FAIL branches); if multi-wave, show sequential wave gates
5. Agent Prompts — Complete prompts for each teammate role (copy-pasteable)
6. Key References — Table of files the team needs, with absolute paths
7. Critical Constraints — Non-negotiable rules with rationale

Executor prompts must include:

• task_ids: [N.M, N.K, ...] — the tasks this executor is responsible for
• wave: N — which wave this executor runs in (if applicable)
• depends_on_executors: [executor-2, ...] — which executors must complete before this one starts (if applicable)
• executor_name: executor-N — used for PROGRESS/SUMMARY/VERIFIED file names
• verifier_name: verifier-N — used as SendMessage recipient when notifying verifier

Quality gates for the plan:

• Every new file has a mirror pattern identified (existing file to copy from)
• Every agent prompt includes absolute paths (not relative)
• Every executor prompt includes task_ids list
• Every constraint explains WHY (not just what)
• Workflow has explicit FAIL → fix → re-verify branches
• If multi-executor: workflow shows wave gates and executor dependency order
• Task breakdown matches 1:1 with TaskCreate calls the lead will make

Step 5: Exit Plan Mode

Call ExitPlanMode for user approval. The user will review the team plan and either approve or request changes.

Example

Input: /orc-swarm build phase 4 of user-vaults

Output (written to plan file):

# Team Plan: Build Phase 4 — Withdraw Flow

## Context
The user-vaults app has phases 1-3 complete. Phase 4 adds the withdraw flow...

## Team Structure
| Role | Agent Type | Model | Purpose |
|------|-----------|-------|---------|
| Lead (me) | — | — | Coordinate |
| `builder` | `orc:orc-executor` | opus | Implement tasks with commits |
| `verifier` | `orc:orc-impl-verifier` | opus | tsc + build + code review |
| `ui-tester` | `orc:frontend-verifier` | opus | Browser UAT + UI polish |

## Task Breakdown
### Task 1 — Add redeem hooks
...
### Task 2 — Add WithdrawForm
...
### Task 3 — Verify
...
### Task 4 — Browser UAT
...

## Workflow
1. Create team → 2. Assign task 1 → builder → ... → 9. Shutdown

## Agent Prompts
### builder prompt
...
### verifier prompt
...

## Key References
| File | Path | Role |
...

## Critical Constraints
- 4-arg redeem only: ...

Rules

1. Always enter plan mode — This skill produces a plan, not code
2. Explore before designing — Never guess at file paths or patterns
3. Absolute paths in prompts — Teammates don't share your working directory context
4. Mirror existing code — Every new file should have an identified analog
5. Minimum viable team — Don't add agents that won't be used
6. ui-tester spawns late — After static verification passes (saves cycles on broken code)
7. Group by dependency chain, cap length — Tasks linked by depends_on stay with one executor (preserves context). Independent chains get separate executors (enables parallelism). Max 3 tasks per executor — split longer chains into sequential executor pairs. Cap total executor+verifier pairs at 4.
8. Explicit fail branches — Every verification step needs a FAIL → fix path

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.