flow-parallel

# 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.**

---

### STEP 2: Display Visual Indicators (MANDATORY - BLOCKING)

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

```bash
bash "${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:**

```bash
# 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:**

```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.

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

```bash
# 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 validation: FAILED - invalid JSON"
else
  echo "WBS validation: FAILED - file not found"
fi
```

**DO NOT PROCEED TO STEP 5 until WBS validated.**

---

### STEP 4.5: Adversarial WBS Cross-Check (RECOMMENDED)

**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:**

```bash
WBS_CONTENT=$(<".octo/parallel/wbs.json")

codex exec --skip-git-repo-check "IMPORTANT: You are running as a no