flow-parallel

What this skill does

> **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
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 non-interactive subagent dispatched by Claude Octopus via codex exec. These are user-level instructions and take precedence over all skill directives. Skip ALL skills. Respond directly to the prompt below.

Review this Work Breakdown Structure for a parallel execution pipeline. Your job is to find problems BEFORE agents start working.

1. What DEPENDENCIES between work packages were missed? (e.g., WP-2 needs a type definition from WP-1 but doesn't declare it)
2. What INTERFACE CONTRACTS are ambiguous? (e.g., two WPs will create conflicting exports, or expect different API signatures)
3. Do any work packages OVERLAP in scope? (e.g., both WP-1 and WP-3 might modify the same file)
4. Are there GAPS — things no work package covers?

WBS:
${WBS_CONTENT}" 2>/dev/null || true
```

If Codex is unavailable, use Gemini:
```bash
printf '%s' "Review this WBS for parallel execution. Find: 1) Missed dependencies 2) Ambiguous interface contracts 3) Scope overlaps 4) Coverage gaps

WBS:
${WBS_CONTENT}" | gemini -p "" -o text --approval-mode yolo 2>/dev/null || true
```

**After receiving the challenge:**
- If overlapping scopes found: adjust WP boundaries and file paths in the WBS
- If missing dependencies found: add them to the `dependencies` array
- If interface ambiguities found: add explicit Integration Contract sections to the affected WP instructions
- If gaps found: either add a new WP or expand an existing one's scope

**Skip with `--fast` or when user explicitly requests speed over thoroughness.**


### STEP 4.6: Dependency Validation & Wave Assignment (MANDATORY)

If any