/flow-parallel

name: flow-parallel
description: "Decompose and execute large changes, migrations, or multi-issue fixes in parallel with quality gates"
disable-model-invocation: true

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.

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:** host subagent 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.**

STEP 2: Display Visual Indicators (MANDATORY - BLOCKING)

**MANDATORY: You MUST use the native shell command tool to run this provider check BEFORE displaying the banner. Do NOT skip it. Do NOT assume availability.**

bash "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}}/scripts/helpers/check-providers.sh"

**Use the ACTUAL results below. PROHIBITED: Showing only "🔵 Claude: Available ✓" without listing all providers.**

**Display this banner with real provider status BEFORE any decomposition:**

🐙 CLAUDE OCTOPUS ACTIVATED - Team of Teams Mode
Parallel Phase: Decomposing compound task into N independent work packages

Architecture:
  Main (this session) - Orchestrator: decompose, launch, monitor, aggregate
  WP-1..WP-N (claude -p) - Independent workers with full plugin capabilities

Each worker:
  - Runs as independent claude -p process in its own git worktree
  - Loads full Octopus plugin
  - Has own context, tools, and quality gates
  - Produces output.md + exit-code
  - Tracked in agent registry (~/.claude-octopus/agents/registry.json)

Estimated Time: 5-15 minutes (depending on task complexity)

**DO NOT PROCEED TO STEP 3 until banner displayed.**

STEP 3: Read Prior State (MANDATORY - State Management)

**Before decomposing, read any prior context:**

# Initialize state if needed
if [[ -d ".octo" ]]; then
  echo "Found existing .octo/ state directory"
else
  echo "No prior .octo/ state found - starting fresh"
fi

# Check for prior discover/spec context
if [[ -f ".octo/STATE.md" ]]; then
  echo "Prior state found:"
  cat .octo/STATE.md
fi

if [[ -f ".octo/PROJECT.md" ]]; then
  echo "Prior project context found:"
  cat .octo/PROJECT.md
fi

Use any prior context (discover findings, spec definitions, project state) to inform the WBS decomposition.

**DO NOT PROCEED TO STEP 4 until state read.**

STEP 4: Decompose into WBS (MANDATORY)

Claude analyzes the compound task and produces a Work Breakdown Structure.

**Decomposition rules:**

• Break into 3-5 independent work packages (WP-1 through WP-N, max 10)
• Each WP gets: name, scope description, expected output files, dependencies
• Validate: non-overlapping scopes, collectively exhaustive
• Each WP must be self-contained enough for an independent claude -p process

**Create the coordination directory and WBS:**

# 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,
      "branch": "<a branch name unique to this work package>",
      "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.

**Validation gate: `wbs_generated`** — Verify `.octo/parallel/wbs.json` exists and contains valid JSON:

# Validate WBS was created
if [[ -f ".octo/parallel/wbs.json" ]]; then
  python3 -c "import json; json.load(open('.octo/parallel/wbs.json')); print('WBS validation: PASSED')" 2>/dev/null || echo "WBS valid