flow-parallel

> **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 through Octopus routing:** ```bash WBS_CONTENT=$(<".octo/parallel/wbs.json") review_provider="" command -v codex >/dev/null 2>&1 && review_provider="codex" [[ -z "$review_provider" ]] && command -v agy >/dev/null 2>&1 && review_provider="agy" if [[ -n "$review_provider" ]]; then "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" spawn "$review_provider" \ "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 fi ``` **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 work package has non-empty `dependencies`, validate the dependency graph and assign wave numbers. **Skip this step** if all work packages have `"dependencies": []` — they all get wave 1 (backward compatible). **Run dependency validation and wave assignment:** ```bash python3 << 'DEPEOF' import json, sys with open('.octo/parallel/wbs.json') as f: wbs = json.load(f) packages = wbs['work_packages'] ids = {wp['id'] for wp in packages} deps = {wp['id']: wp.get('dependencies', []) for wp in packages} # Check for missing references errors = [] for wp_id, wp_deps in deps.items(): for dep in wp_deps: if dep not in ids: errors.append(f"WP {wp_id} depends on unknown {dep}") if errors: print("DEPENDENCY VALIDATION: FAILED") for e in errors: print(f" ERROR: {e}") sys.exit(1) # Cycle detection (DFS) WHITE, GRAY, BLACK = 0, 1, 2 color = {wp_id: WHITE for wp_id in ids} def has_cycle(node, path): color[node] = GRAY for dep in deps[node]: if color[dep] == GRAY: cycle = path[path.index(dep):] + [dep] return cycle if color[dep] == WHITE: result = has_cycle(dep, path + [dep]) if result: return result color[node] = BLACK return None for wp_id in ids: if color[wp_id] == WHITE: cycle = has_cycle(wp_id, [wp_id]) if cycle: print(f"DEPENDENCY VALIDATION: FAILED - Cycle detected: {' -> '.join(cycle)}") sys.exit(1) # Topological sort and wave assignment waves = {} assigned = set() def get_wave(wp_id): if wp_id in waves: return waves[wp_id] if not deps[wp_id]: waves[wp_id] = 1 return 1 max_dep_wave = max(get_wave(d) for d in deps[wp_id]) waves[wp_id] = max_dep_wave + 1 return waves[wp_id] for wp_id in ids: get_wave(wp_id) # Update WBS with wave assignments for wp in packages: wp['wave'] = waves[wp['id']] with open('.octo/parallel/wbs.json', 'w') as f: json.dump(wbs, f, indent=2) max_wave = max(waves.values()) print(f"DEPENDENCY VALIDATION: PASSED") print(f"Waves assigned: {max_wave}") for w in range(1, max_wave + 1): wave_wps = [wp_id for wp_id, wave in waves.items() if wave == w] print(f" Wave {w}: {', '.join(wave_wps)}") DEPEOF ``` **If validation fails:** Report the error to the user and STOP. Do not proceed with invalid dependencies. **DO NOT PROCEED TO STEP 5 until dependencies validated (or step skipped for independent WPs).** ### STEP 5: Generate Instruction Files (MANDATORY) For each work package in the WBS, create an instructions file and a launch script. **For each WP-N, create:** #### `instructions.md` ```bash mkdir -p ".octo/parallel/WP-N" cat > ".octo/parallel/WP-N/instructions.md" << 'INSTREOF' # Work Package WP-N: <name> ## Task <Clear description of what this work package must accomplish> ## Scope Boundaries - IN SCOPE: <what this WP covers> - OUT OF SCOPE: <what other WPs handle — explicit boundaries> ## Expected Output - Files to create/modify: <explicit file paths — MANDATORY> - Location: <where outputs go in the project> ## Integration Contract - This WP produces: <what downstream consumers can expect> - This WP consumes: <what it needs from the project, NOT from other WPs> ## Quality Requirements (MANDATORY) - Code must compile/parse without errors - Follow existing project conventions (naming, structure, patterns) - 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. ```bash cat > ".octo/parallel/WP-N/launch.sh" << 'LAUNCHEOF' #!/bin/bash set -e SCRIPT_DIR="$(cd "$(dirname "${0}")" && pwd)" PROJECT_ROOT="<absolute-project-root-path>" WP_ID="WP-N" WORKTREE_DIR="${PROJECT_ROOT}/../.octo-worktree-${WP_ID}" REGISTRY="${HOME}/.claude-octopus/plugin/scripts/agent-registry.sh" # v8.44.0: Create isolated worktree for this work package cd "$PROJECT_ROOT" CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) git worktree add "$WORKTREE_DIR" "$CURRENT_BRANCH" 2>/dev/null || { # Worktree may already exist from a retry — reuse it if [[ -d "$WORKTREE_DIR" ]]; then cd "$WORKTREE_DIR" && git checkout "$CURRENT_BRANCH" && git pull --ff-only 2>/dev/null || true else echo "ERROR: Failed to create worktree at $WORKTREE_DIR" >&2 echo 1 > "$SCRIPT_DIR/exit-code" touch "$SCRIPT_DIR/.done" exit 1 fi } # Register agent in registry if [[ -x "$REGISTRY" ]]; then "$REGISTRY" register "$WP_ID" "$CURRENT_BRANCH" "$WORKTREE_DIR" 2>/dev/null || true fi cd "$WORKTREE_DIR" unset CLAUDECODE # v8.32.0: Credential isolation — work packages don't need provider keys unset OPENAI_API_KEY AGY_AUTH_TOKEN ANTIGRAVITY_API_KEY OPENROUTER_API_KEY PERPLEXITY_API_KEY cat "$SCRIPT_DIR/instructions.md" | claude -p > "$SCRIPT_DIR/output.md" 2>"$SCRIPT_DIR/agent.log" EXIT_CODE=$? echo $EXIT_CODE > "$SCRIPT_DIR/exit-code" touch "$SCRIPT_DIR/.done" # Update agent registry with completion status if [[ -x "$REGISTRY" ]]; then if [[ "$EXIT_CODE" -eq 0 ]]; then "$REGISTRY" update "$WP_ID" --status done 2>/dev/null || true else