Flow Parallel

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"

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

🐙 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)

# 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

# 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

# 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

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

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

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

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
        "$REGISTRY" update "$WP_ID" --status failed --error "Exit code $EXIT_CODE" 2>/dev/null || true
    fi
fi

# Clean up worktree (agent finished, changes are in output.md not the worktree)
cd "$PROJECT_ROOT"
git worktree remove "$WORKTREE_DIR" --force 2>/dev/null || true
LAUNCHEOF

chmod +x ".octo/parallel/WP-N/launch.sh"

# Count WPs from wbs.json
wp_count=$(python3 -c "import json; print(len(json.load(open('.octo/parallel/wbs.json'))['work_packages']))")

# Verify each WP has instructions.md and launch.sh
missing=0
for i in $(seq 1 "$wp_count"); do
  if [[ ! -f ".octo/parallel/WP-$i/instructions.md" ]]; then
    echo "MISSING: .octo/parallel/WP-$i/instructions.md"
    missing=$((missing + 1))
  fi
  if [[ ! -f ".octo/parallel/WP-$i/launch.sh" ]]; then
    echo "MISSING: .octo/parallel/WP-$i/launch.sh"
    missing=$((missing + 1))
  fi
done

if [[ "$missing" -eq 0 ]]; then
  echo "Instruction files validation: PASSED ($wp_count work packages)"
else
  echo "Instruction files validation: FAILED ($missing files missing)"
fi