Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/flow-parallel
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Decompose and execute large changes, migrations, or multi-issue fixes in parallel with quality gates
📊 Stats
Stars3,869
Forks362
LanguageShell
LicenseMIT
📦 Ships with octo
</> SKILL.md
flow-parallel.SKILL.md
---name: flow-parallel
effort: high
aliases:
- parallel
- batch
- team
- teams
- team-of-teams
description: "Decompose and execute large changes, migrations, or multi-issue fixes in parallel with quality gates"
execution_mode: enforced
validation_gates:
- wbs_generated
- instructions_written
- processes_launched
- all_work_packages_complete
invocation: human_only
---# STOP - SKILL ALREADY LOADED
**DO NOT call Skill() again. DO NOT load any more skills. Execute directly.**
---## EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)
This skill uses **ENFORCED execution mode**. You MUST follow this exact 7-step sequence.
**Architectural Principle:** Task tool subagents do NOT load plugins. Independent `claude -p` processes DO. This skill spawns independent `claude -p` processes so each work package gets the full Octopus plugin, its own Double Diamond, agents, and quality gates.
---### STEP 1: Clarifying Questions (MANDATORY)
**Ask via AskUserQuestion BEFORE any other action.**
You MUST gather these inputs from the user — without scope, count, and dependency answers, the decomposition will be generic and produce overlapping work packages that cause merge conflicts:
```
AskUserQuestion with these questions:
1. **Compound task**: What compound task should be decomposed?
- Use inline args if provided (e.g., /octo:parallel "build auth system")
- If no args: ask "What compound task should I decompose into parallel work packages?"
2. **Work package count**: How many work packages?
- Options: "3 (Recommended)", "4", "5", "Custom (up to 10)"
- Default: 3-5 is optimal
3. **Dependencies**: Are the work packages independent?
- "Fully independent - no dependencies between packages (Recommended)"
- "Some dependencies - packages may need to share interfaces"
- "Sequential dependencies - packages must complete in order"
```
If user provided a description inline with the command (e.g., `/octo:parallel build a full auth system with OAuth, RBAC, and audit logging`), use that as the task description but STILL ask remaining questions (count, dependencies).
If user says "skip" for any question, use defaults: 3 work packages, fully independent.
**DO NOT PROCEED TO STEP 2 until questions answered.**
- Each WP must be self-contained enough for an independent claude -p process
**Create the coordination directory and WBS:**
```bash
# Create parallel coordination directory
mkdir -p .octo/parallel
# Write wbs.json
cat > .octo/parallel/wbs.json << 'WBSEOF'
{
"task": "<compound task description>",
"created": "<ISO timestamp>",
"work_packages": [
{
"id": "WP-1",
"name": "<work package name>",
"scope": "<what this WP covers>",
"expected_outputs": ["<list of files this WP should produce>"],
"dependencies": [],
"wave": 1,
"status": "pending"
}
]
}
WBSEOF
```
**You MUST write actual WBS content** based on your analysis of the compound task. The JSON above is a template — populate it with real decomposition. Template or placeholder WBS produces vague instructions that agents interpret differently, causing duplicate work or missed scope.
**After generating the WBS but BEFORE dependency validation, cross-check the decomposition with a second model.** Single-model decomposition often produces work packages with hidden dependencies, ambiguous interface contracts, or scope gaps that cause merge conflicts and duplicated work.
**If an external provider is available, dispatch the WBS for adversarial review through Octopus routing:**
- Run any existing tests related to your changes — do NOT skip tests
- Run the project linter if one exists (eslint, ruff, golangci-lint, etc.)
- No `type: ignore`, `@ts-ignore`, `any` casts, or suppression comments unless the existing code already uses them
- No placeholder code — no `TODO`, `FIXME`, or stub implementations
- Verify your changes work by running or testing them before completing
- If you break existing tests, fix them — do not delete or skip them
## Dependency Context
- This WP depends on: <list of dependency WP IDs, or "none">
- Outputs from completed dependencies will be provided below when available
INSTREOF
```
**CRITICAL:** Every instructions.md MUST contain explicit file paths — parallel agents interpret vague scope independently, so without explicit paths two WPs may modify the same file or leave gaps between them. Vague descriptions like "create the auth module" are PROHIBITED — specify exact paths like `src/auth/oauth.ts`.
#### `launch.sh`
**v8.44.0: Each work package runs in its own git worktree** for full file isolation. This prevents write contention when multiple agents modify files simultaneously.
**You MUST replace `<absolute-project-root-path>`** with the actual project root (use `pwd` to determine it).
**Worktree fallback:** If git worktree is unavailable (shallow clone, detached HEAD), the agent falls back to running in the project root. The error is logged but execution continues.
**Validation gate: `instructions_written`** — Verify all instruction files exist:
**Validation gate: `processes_launched`** — Verify PID files exist for all WPs.
**IMPORTANT:** The launch and monitor commands above should be run via the Bash tool. You may need to combine them or run the monitor as a separate polling step. The monitor loop will block until each wave completes or times out.
**DO NOT PROCEED TO STEP 7 until all waves complete.**
---
### STEP 7: Aggregate & Present (MANDATORY)
After all work packages complete (or timeout), aggregate results.
agent.log # Agent stderr log (created by launch.sh)
exit-code # Process exit code (created by launch.sh)
pid # Process ID (created by orchestrator)
.done # Completion marker (created by launch.sh)
WP-2/
...
WP-N/
...
```
---
## Prohibitions (MANDATORY - CANNOT VIOLATE)
- CANNOT use Task tool subagents as substitute — Task subagents run in isolated sandboxes without plugin access, so they get no Octopus quality gates, personas, or provider orchestration
- CANNOT skip WBS decomposition (Step 4) — without decomposition, agents receive the full compound task and produce overlapping, uncoordinated output
- CANNOT launch without instruction files (Step 5 must precede Step 6)
- CANNOT skip 12-second stagger between launches — simultaneous process spawning causes CPU/memory contention that degrades all agents' performance
- CANNOT declare success without checking exit codes
- CANNOT proceed to next step without completing current step
- CANNOT launch more than 10 work packages — beyond 10, resource contention and merge complexity outweigh parallelism gains
- CANNOT skip the monitoring loop — without monitoring, failed or hung agents go undetected and the orchestrator reports false success
- CANNOT launch a wave before its dependency wave completes — later waves consume outputs from earlier waves, so premature launch produces agents working with missing context
- CANNOT skip dependency validation when dependencies exist
---
## Error Handling
**If a work package fails (non-zero exit code):**
1. Read its `agent.log` for error details
2. Present the error to the user
3. Offer to retry the failed WP individually
4. Do NOT re-run succeeded WPs
**If monitoring times out:**
1. Report which WPs completed and which did not
2. Check if timed-out WPs are still running (check PID)
3. Offer to wait longer or kill remaining processes
**If `claude` command is not available:**
1. Check with `command -v claude`
2. Report to user and STOP — cannot proceed without claude CLI
---
## Example Usage
### Example: Authentication System
```
User: /octo:parallel build a full authentication system with OAuth, RBAC, and audit logging
