shipwright-cli 3.1.0 → 3.3.0

package/docs/plans/2026-03-01-capabilities-cleanup-plan.md

@@ -0,0 +1,658 @@
+# Stream 3: Capabilities + Cleanup Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Read plan format notes at the bottom before starting.
+
+**Goal:** Decompose 2 bash god-files (6,591 lines total), adopt shared test harness, add Claude Code MCP server + 4 skills + 1 enhanced hook.
+
+**Architecture:**
+
+- **Bash Decomposition:** Modular source pattern (source sub-files from main, export all functions). No behavior change, pure structural reorganization.
+- **Test Harness:** Central `test-helpers.sh` exists (100+ lines). Standardize all 128 test scripts to source it instead of defining helpers locally.
+- **MCP Server:** Lightweight HTTP wrapper around Skipper API at `http://127.0.0.1:4200/mcp`. Register in `.claude/settings.json` as MCP server.
+- **Skills:** Four new markdown files in `.claude/skills/` implementing /pipeline-monitor, /fleet-overview, /agent-debug, /cost-report (inline Claude Code calls).
+- **Hooks:** New hook fires on Skipper agent crash, captures diagnostics to memory system.
+
+**Tech Stack:** Bash 3.2, Claude Code skills/hooks, MCP protocol, Shipper API
+
+**Estimated Scope:** 22 tasks, ~3-4 days parallel execution with small team (2-3 agents)
+
+---
+
+## Phase 1: Bash Cleanup Foundation (6 tasks)
+
+### Task 1.1: Decompose pipeline-stages.sh — Part A (intake, plan, design)
+
+**Objective:** Extract `stage_intake()`, `stage_plan()`, `stage_design()` (first 950 lines) into new file.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages-intake.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages.sh`
+
+**Steps:**
+
+1. Read pipeline-stages.sh lines 1-950 (headers, helpers, first 3 stage functions)
+2. Extract lines 1-163 (file header + helper functions: `prune_context_section()`, `guard_prompt_size()`, `_safe_base_log()`, `_safe_base_diff()`, `show_stage_preview()`) to new file with module guard
+3. Extract lines 164-730 (stage_intake function) to new file
+4. Extract lines 731-951 (stage_plan, stage_design functions) to new file
+5. In original pipeline-stages.sh, replace extracted content with: `source "${SCRIPT_DIR}/lib/pipeline-stages-intake.sh"`
+6. Add guard at top: `[[ -n "${_PIPELINE_STAGES_INTAKE_LOADED:-}" ]] && return 0; _PIPELINE_STAGES_INTAKE_LOADED=1`
+7. Run: `bash -n scripts/lib/pipeline-stages-intake.sh` (syntax check)
+8. Commit: `git add scripts/lib/pipeline-stages-intake.sh scripts/lib/pipeline-stages.sh && git commit -m "refactor(pipeline): decompose intake, plan, design stages into pipeline-stages-intake.sh"`
+
+**Notes:**
+
+- Don't remove from original yet—we'll update the main file in a separate task
+- Extract helpers as well (they're shared but we'll consolidate later)
+- Module guard pattern: `[[ -n "${_PIPELINE_STAGES_INTAKE_LOADED:-}" ]] && return 0; _PIPELINE_STAGES_INTAKE_LOADED=1`
+
+---
+
+### Task 1.2: Decompose pipeline-stages.sh — Part B (build, test)
+
+**Objective:** Extract `stage_test_first()`, `stage_build()`, `stage_test()` (~800 lines) into new file.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages-build.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages.sh`
+
+**Steps:**
+
+1. Read pipeline-stages.sh lines 952-1458 (stage_test_first, stage_build, stage_test)
+2. Create new file with module guard
+3. Copy only the three stage functions (no duplicate helpers)
+4. Source helper functions from pipeline-stages-intake.sh at top: `source "${SCRIPT_DIR}/lib/pipeline-stages-intake.sh"`
+5. Update main pipeline-stages.sh to source this file
+6. Run syntax check
+7. Commit: `git add scripts/lib/pipeline-stages-build.sh scripts/lib/pipeline-stages.sh && git commit -m "refactor(pipeline): decompose build, test stages into pipeline-stages-build.sh"`
+
+---
+
+### Task 1.3: Decompose pipeline-stages.sh — Part C (review, compound_quality)
+
+**Objective:** Extract `stage_review()`, `stage_compound_quality()`, `stage_audit()` (~400 lines) into new file.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages-review.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages.sh`
+
+**Steps:**
+
+1. Read pipeline-stages.sh lines 1459-1961 (stage_review, stage_compound_quality, stage_audit)
+2. Create new file with module guard
+3. Copy the three stage functions
+4. Source helpers from intake file
+5. Update main pipeline-stages.sh to source this file
+6. Run syntax check
+7. Commit: `git add scripts/lib/pipeline-stages-review.sh scripts/lib/pipeline-stages.sh && git commit -m "refactor(pipeline): decompose review, compound_quality, audit stages into pipeline-stages-review.sh"`
+
+---
+
+### Task 1.4: Decompose pipeline-stages.sh — Part D (pr, merge, deploy)
+
+**Objective:** Extract `stage_pr()`, `stage_merge()`, `stage_deploy()` (~1,100 lines) into new file.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages-delivery.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages.sh`
+
+**Steps:**
+
+1. Read pipeline-stages.sh lines 1962-2853 (stage_pr, stage_merge, stage_deploy)
+2. Create new file with module guard
+3. Copy the three stage functions
+4. Source helpers from intake file
+5. Update main pipeline-stages.sh to source this file
+6. Run syntax check
+7. Commit: `git add scripts/lib/pipeline-stages-delivery.sh scripts/lib/pipeline-stages.sh && git commit -m "refactor(pipeline): decompose pr, merge, deploy stages into pipeline-stages-delivery.sh"`
+
+---
+
+### Task 1.5: Decompose pipeline-stages.sh — Part E (validate, monitor)
+
+**Objective:** Extract `stage_validate()`, `stage_monitor()` (~300 lines) into new file.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages-monitor.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages.sh`
+
+**Steps:**
+
+1. Read pipeline-stages.sh lines 2854-end (stage_validate, stage_monitor)
+2. Create new file with module guard
+3. Copy the two stage functions
+4. Source helpers from intake file
+5. Update main pipeline-stages.sh to source this file
+6. Run syntax check
+7. Commit: `git add scripts/lib/pipeline-stages-monitor.sh scripts/lib/pipeline-stages.sh && git commit -m "refactor(pipeline): decompose validate, monitor stages into pipeline-stages-monitor.sh"`
+
+---
+
+### Task 1.6: Finalize pipeline-stages.sh
+
+**Objective:** Reduce pipeline-stages.sh to ~100 lines (loader + exports).
+
+**Files:**
+
+- Edit: `/Users/sethford/Documents/shipwright/scripts/lib/pipeline-stages.sh`
+
+**Steps:**
+
+1. Read current pipeline-stages.sh
+2. Keep file header, module guard, defaults section
+3. Delete all duplicated helpers (keep only in intake sub-file)
+4. Add five source statements at bottom (for the five stage files)
+5. Add final section exporting stage function list:
+   ```bash
+   # Export all available stages
+   export PIPELINE_STAGES="intake plan design test_first build test review compound_quality audit pr merge deploy validate monitor"
+   ```
+6. Final file should be ~100-120 lines
+7. Run: `bash -n scripts/lib/pipeline-stages.sh` (syntax check)
+8. Verify by running sw-pipeline-test.sh (should pass without changes)
+9. Commit: `git add scripts/lib/pipeline-stages.sh && git commit -m "refactor(pipeline): consolidate pipeline-stages.sh to loader (100 lines)"`
+
+---
+
+## Phase 2: Loop Decomposition (4 tasks)
+
+### Task 2.1: Decompose sw-loop.sh — Part A (loop-iteration.sh)
+
+**Objective:** Extract single-iteration logic (~600 lines).
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/loop-iteration.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/sw-loop.sh`
+
+**Steps:**
+
+1. Read sw-loop.sh, identify functions for single iteration:
+   - `select_adaptive_model()`
+   - `select_audit_model()`
+   - `accumulate_loop_tokens()`
+   - `write_loop_tokens()`
+   - `validate_claude_output()`
+   - `check_fatal_error()`
+   - `check_progress()`
+   - `check_completion()`
+   - `run_test_gate()`
+   - `write_error_summary()`
+   - `run_audit_agent()`
+   - `run_quality_gates()`
+   - `compose_prompt()`
+   - Full iteration loop logic from main function
+2. Create new file with module guard `_LOOP_ITERATION_LOADED`
+3. Copy listed functions to new file
+4. Source helpers in sw-loop.sh: `source "${SCRIPT_DIR}/lib/loop-iteration.sh"`
+5. Replace iteration logic in sw-loop.sh main loop with call to extracted function
+6. Syntax check both files
+7. Commit: `git add scripts/lib/loop-iteration.sh scripts/sw-loop.sh && git commit -m "refactor(loop): extract single-iteration logic into loop-iteration.sh"`
+
+---
+
+### Task 2.2: Decompose sw-loop.sh — Part B (loop-convergence.sh)
+
+**Objective:** Extract convergence detection logic (~400 lines).
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/loop-convergence.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/sw-loop.sh`
+
+**Steps:**
+
+1. Extract convergence-related functions:
+   - `check_circuit_breaker()`
+   - `check_max_iterations()`
+   - `diagnose_failure()`
+   - `detect_stuckness()`
+   - `record_iteration_stuckness_data()`
+   - `compose_audit_section()`
+   - `check_definition_of_done()`
+   - `track_iteration_velocity()`
+   - `compute_velocity_avg()`
+2. Create new file with module guard `_LOOP_CONVERGENCE_LOADED`
+3. Copy functions
+4. Source in sw-loop.sh
+5. Syntax check
+6. Commit: `git add scripts/lib/loop-convergence.sh scripts/sw-loop.sh && git commit -m "refactor(loop): extract convergence detection into loop-convergence.sh"`
+
+---
+
+### Task 2.3: Decompose sw-loop.sh — Part C (loop-restart.sh)
+
+**Objective:** Extract session restart logic (~300 lines).
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/loop-restart.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/sw-loop.sh`
+
+**Steps:**
+
+1. Extract session restart functions:
+   - `initialize_state()`
+   - `resume_state()`
+   - `write_state()`
+   - `append_log_entry()`
+   - Logic for session restart after exhaustion
+2. Create new file with module guard `_LOOP_RESTART_LOADED`
+3. Copy functions
+4. Source in sw-loop.sh
+5. Syntax check
+6. Commit: `git add scripts/lib/loop-restart.sh scripts/sw-loop.sh && git commit -m "refactor(loop): extract session restart logic into loop-restart.sh"`
+
+---
+
+### Task 2.4: Decompose sw-loop.sh — Part D (loop-progress.sh)
+
+**Objective:** Extract progress.md management (~200 lines).
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/scripts/lib/loop-progress.sh`
+- Edit: `/Users/sethford/Documents/shipwright/scripts/sw-loop.sh`
+
+**Steps:**
+
+1. Extract progress tracking functions:
+   - `write_progress()`
+   - `manage_context_window()`
+   - `git_commit_count()`, `git_recent_log()`, `git_diff_stat()`, `git_auto_commit()`
+   - Progress file write logic
+2. Create new file with module guard `_LOOP_PROGRESS_LOADED`
+3. Copy functions
+4. Source in sw-loop.sh
+5. Syntax check
+6. Commit: `git add scripts/lib/loop-progress.sh scripts/sw-loop.sh && git commit -m "refactor(loop): extract progress tracking into loop-progress.sh"`
+
+---
+
+## Phase 3: Test Harness Adoption (1 task + 3 parallel)
+
+### Task 3.1: Verify test-helpers.sh completeness
+
+**Objective:** Ensure test-helpers.sh has all common assertion/setup patterns.
+
+**Files:**
+
+- Read: `/Users/sethford/Documents/shipwright/scripts/lib/test-helpers.sh`
+
+**Steps:**
+
+1. Read full test-helpers.sh to see what's exported
+2. Verify it has: colors, counters, assert_pass/fail/eq/contains/contains_regex/gt/json_key, setup_test_env, cleanup_test_env, print_test_header, print_test_results, mock helpers
+3. If any missing patterns found, add them to test-helpers.sh
+4. Commit if changes: `git add scripts/lib/test-helpers.sh && git commit -m "refactor(tests): ensure test-helpers.sh has all common patterns"`
+
+---
+
+### Task 3.2: Adopt test harness — Batch A (scripts/\*-test.sh [A-H])
+
+**Objective:** Update first 32 test scripts to source test-helpers.sh.
+
+**Files:**
+
+- Edit: All test scripts matching pattern `scripts/sw-*-test.sh` where name starts with A-H (32 files)
+
+**Steps:**
+
+1. For each test script:
+   a. Read first 50 lines
+   b. If it defines its own `assert_pass()`, `assert_fail()`, etc., mark for replacement
+   c. Add at top (after shebang and after `SCRIPT_DIR=...`): `source "$SCRIPT_DIR/lib/test-helpers.sh"`
+   d. Remove duplicate helper function definitions (keep custom ones if unique)
+   e. Syntax check: `bash -n <file>`
+2. Bulk commit: `git add scripts/sw-*-test.sh && git commit -m "refactor(tests): adopt test-helpers.sh in batch A (32 scripts)"`
+
+**Note:** Can be done in parallel with next batches. Each batch can be a separate agent.
+
+---
+
+### Task 3.3: Adopt test harness — Batch B (scripts/\*-test.sh [I-P])
+
+**Objective:** Update next 32 test scripts to source test-helpers.sh.
+
+**Files:**
+
+- Edit: All test scripts starting with I-P (32 files)
+
+**Steps:**
+
+1. Same as Task 3.2
+2. Bulk commit: `git add scripts/sw-*-test.sh && git commit -m "refactor(tests): adopt test-helpers.sh in batch B (32 scripts)"`
+
+---
+
+### Task 3.4: Adopt test harness — Batch C (scripts/\*-test.sh [Q-Z])
+
+**Objective:** Update remaining test scripts to source test-helpers.sh.
+
+**Files:**
+
+- Edit: All remaining test scripts (64 files)
+
+**Steps:**
+
+1. Same as Task 3.2
+2. Bulk commit: `git add scripts/sw-*-test.sh && git commit -m "refactor(tests): adopt test-helpers.sh in batch C (64 scripts)"`
+
+---
+
+## Phase 4: Claude Code Capabilities (7 tasks)
+
+### Task 4.1: Create MCP server wrapper
+
+**Objective:** Register Skipper API as MCP server for Claude Code.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/.claude/mcp/skipper-server.sh`
+- Edit: `/Users/sethford/Documents/shipwright/.claude/settings.json`
+
+**Steps:**
+
+1. Create wrapper script that:
+   - Checks if `http://127.0.0.1:4200` is reachable
+   - Translates MCP tool calls to HTTP POST to `/mcp` endpoint
+   - Returns tool responses
+2. Add minimal bash script that acts as MCP bridge (see MCP protocol docs for format)
+3. In settings.json, add under `mcpServers`:
+   ```json
+   "skipper": {
+     "command": "bash",
+     "args": [".claude/mcp/skipper-server.sh"],
+     "description": "Skipper Agent OS API"
+   }
+   ```
+4. Test: Try calling a tool from Claude Code terminal
+5. Commit: `git add .claude/mcp/skipper-server.sh .claude/settings.json && git commit -m "feat(mcp): register Skipper API as MCP server for Claude Code"`
+
+**Notes:**
+
+- If Skipper is not running, server should gracefully fail with helpful message
+- See MCP protocol in Skipper docs for exact message format
+
+---
+
+### Task 4.2: Create pipeline-monitor skill
+
+**Objective:** /pipeline-monitor — check pipeline progress, surface blockers.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/.claude/skills/pipeline-monitor.md`
+
+**Steps:**
+
+1. Create skill file with:
+   - Heading: `# Pipeline Monitor`
+   - Description: "Real-time pipeline progress tracking and blocker detection"
+   - Implementation that:
+     - Calls `shipwright status --json` to get current pipeline state
+     - Reads `.claude/pipeline-state.md` for detailed stage info
+     - Checks for blockers (failed stages, hung iterations)
+     - Displays in user-friendly format with progress bars
+2. Include inline Claude Code that uses bash to run shipwright commands
+3. Commit: `git add .claude/skills/pipeline-monitor.md && git commit -m "feat(skills): add pipeline-monitor skill"`
+
+---
+
+### Task 4.3: Create fleet-overview skill
+
+**Objective:** /fleet-overview — multi-repo fleet status.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/.claude/skills/fleet-overview.md`
+
+**Steps:**
+
+1. Create skill file with:
+   - Heading: `# Fleet Overview`
+   - Description: "Multi-repo fleet status, worker pool, per-repo queue"
+   - Implementation that:
+     - Reads fleet-config.json
+     - Calls `shipwright fleet` status command
+     - Shows per-repo pipeline queue depth
+     - Shows worker pool utilization
+2. Commit: `git add .claude/skills/fleet-overview.md && git commit -m "feat(skills): add fleet-overview skill"`
+
+---
+
+### Task 4.4: Create agent-debug skill
+
+**Objective:** /agent-debug — debug stuck/failing Skipper agent.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/.claude/skills/agent-debug.md`
+
+**Steps:**
+
+1. Create skill file with:
+   - Heading: `# Agent Debug`
+   - Description: "Diagnose stuck or failing Skipper agents"
+   - Implementation that:
+     - Takes agent ID as input
+     - Calls Skipper API to fetch agent logs
+     - Reads memory system for failure patterns
+     - Checks heartbeat status
+     - Suggests recovery steps
+2. Commit: `git add .claude/skills/agent-debug.md && git commit -m "feat(skills): add agent-debug skill"`
+
+---
+
+### Task 4.5: Create cost-report skill
+
+**Objective:** /cost-report — token usage and cost analysis.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/.claude/skills/cost-report.md`
+
+**Steps:**
+
+1. Create skill file with:
+   - Heading: `# Cost Report`
+   - Description: "Token usage and cost analysis for pipelines"
+   - Implementation that:
+     - Calls `shipwright cost show` for current state
+     - Reads cost tracking files
+     - Shows breakdown by pipeline/stage
+     - Alerts if approaching budget
+2. Commit: `git add .claude/skills/cost-report.md && git commit -m "feat(skills): add cost-report skill"`
+
+---
+
+### Task 4.6: Create agent-crash detection hook
+
+**Objective:** Auto-capture diagnostics when Skipper agent crashes.
+
+**Files:**
+
+- Create: `/Users/sethford/Documents/shipwright/.claude/hooks/agent-crash-capture.sh`
+- Edit: `/Users/sethford/Documents/shipwright/.claude/settings.json`
+
+**Steps:**
+
+1. Create hook script that:
+   - Monitors heartbeat files in `~/.shipwright/heartbeats/`
+   - Detects when an agent heartbeat file goes stale (>2 minutes old)
+   - Captures:
+     - Agent logs (last 50 lines)
+     - Last iteration output
+     - Error summary
+     - System state (memory, CPU)
+   - Writes diagnostic bundle to memory system: `~/.shipwright/memory/<repo>/<agent-id>.crash-dump.json`
+   - Emits event: `agent_crash` with agent_id, reason
+2. In settings.json, register hook for new event type or use periodic check
+3. Test: Kill an agent, verify diagnostics captured
+4. Commit: `git add .claude/hooks/agent-crash-capture.sh .claude/settings.json && git commit -m "feat(hooks): add agent-crash-capture diagnostics hook"`
+
+**Notes:**
+
+- Graceful fallback if heartbeat files not found
+- Don't block agent execution, run async
+- Compress old crash dumps to avoid disk bloat
+
+---
+
+### Task 4.7: Wire Refined Depths brand implementation
+
+**Objective:** Execute Refined Depths plan (dashboard + docs styling).
+
+**Files:**
+
+- Edit: All dashboard HTML/CSS files (in `dashboard/public/`)
+- Edit: All documentation files (in `docs/`)
+
+**Steps:**
+
+1. Read: `docs/plans/2026-03-01-refined-depths-implementation.md` (separate doc)
+2. Apply color scheme changes to dashboard CSS/HTML
+3. Apply typography and spacing updates
+4. Update documentation site styling
+5. Commit all changes: `git add dashboard/ docs/ && git commit -m "brand: apply Refined Depths design system"`
+
+---
+
+## Phase 5: Verification & Integration (4 tasks)
+
+### Task 5.1: Run full test suite on decomposed pipeline-stages
+
+**Objective:** Verify all 19 stages work correctly after decomposition.
+
+**Files:**
+
+- Run: `bash scripts/sw-lib-pipeline-stages-test.sh`
+- Run: `bash scripts/sw-pipeline-test.sh`
+
+**Steps:**
+
+1. Run existing stage test suite: `bash scripts/sw-lib-pipeline-stages-test.sh`
+2. Run full pipeline e2e test: `bash scripts/sw-pipeline-test.sh`
+3. If failures, debug and fix (likely just import issues)
+4. Commit any fixes: `git add ... && git commit -m "fix(pipeline): correct stage decomposition imports"`
+
+---
+
+### Task 5.2: Run full test suite on decomposed loop
+
+**Objective:** Verify loop iteration, convergence, restart, progress all work.
+
+**Files:**
+
+- Run: `bash scripts/sw-loop-test.sh`
+
+**Steps:**
+
+1. Run loop test suite: `bash scripts/sw-loop-test.sh`
+2. If failures, fix imports/sourcing
+3. Commit fixes if needed
+
+---
+
+### Task 5.3: Run full test suite on test-harness adoption
+
+**Objective:** Verify all 128 test scripts still pass with shared harness.
+
+**Files:**
+
+- Run: `npm test` (runs all test suites)
+
+**Steps:**
+
+1. Run full test suite: `npm test`
+2. Should see ~95+ tests pass
+3. If failures, likely missing helpers — add to test-helpers.sh
+4. Commit fixes
+
+---
+
+### Task 5.4: Integration test — MCP server + skills
+
+**Objective:** Verify new Claude Code features work end-to-end.
+
+**Files:**
+
+- Manual: Test in Claude Code terminal
+
+**Steps:**
+
+1. Start Skipper locally: `skipper start` (if available)
+2. In Claude Code, try invoking skill: `/pipeline-monitor`
+3. Verify skill executes and returns output
+4. Try other skills: `/fleet-overview`, `/agent-debug`, `/cost-report`
+5. If issues, debug hook/skill implementations
+6. Document any limitations in .claude/CLAUDE.md
+
+---
+
+## Phase 6: Documentation & Final (1 task)
+
+### Task 6.1: Update .claude/CLAUDE.md with new capabilities
+
+**Objective:** Document new skills, hooks, and MCP server.
+
+**Files:**
+
+- Edit: `/Users/sethford/Documents/shipwright/.claude/CLAUDE.md`
+
+**Steps:**
+
+1. Add section "Claude Code Skills" listing new skills: pipeline-monitor, fleet-overview, agent-debug, cost-report
+2. Add MCP server info: "Skipper API available via MCP server at 127.0.0.1:4200"
+3. Add Hook info: "Agent crash detection hook auto-captures diagnostics"
+4. Update architecture table if pipeline-stages decomposition changes line counts
+5. Commit: `git add .claude/CLAUDE.md && git commit -m "docs: add Stream 3 capabilities to CLAUDE.md"`
+
+---
+
+## Parallel Execution Strategy
+
+**Recommended team composition:** 3 agents
+
+- **Agent 1 (Pipeline Decomposer):** Tasks 1.1–1.6 (bash cleanup for pipeline-stages)
+- **Agent 2 (Loop Decomposer):** Tasks 2.1–2.4 (bash cleanup for sw-loop)
+- **Agent 3 (Capabilities):** Tasks 3.1–4.7 (test harness + MCP + skills + hooks in parallel with Agents 1–2)
+
+**Merge safety:** Each phase uses different files, no conflicts expected.
+
+**Verification order:**
+
+1. Phases 1–2 complete → Run Task 5.1–5.2
+2. Phase 3 complete → Run Task 5.3
+3. Phase 4 complete → Run Task 5.4
+4. All phases complete → Run Task 6.1
+
+---
+
+## Success Criteria
+
+- [ ] pipeline-stages.sh reduced to ~100 lines (loader only)
+- [ ] 5 new stage sub-files created and working (pipeline-stages-intake/build/review/delivery/monitor.sh)
+- [ ] sw-loop.sh reduced by ~50% (4 sub-files handling iteration/convergence/restart/progress)
+- [ ] All 128 test scripts source test-helpers.sh
+- [ ] MCP server registered and functional
+- [ ] 4 new skills created and callable from Claude Code
+- [ ] Agent crash hook implemented and tested
+- [ ] All existing tests pass (no regression)
+- [ ] Refined Depths brand applied to dashboard + docs
+
+---
+
+## Plan Format Notes
+
+- **File paths:** All absolute paths (`/Users/sethford/Documents/shipwright/...`)
+- **Commits:** One per logical chunk, frequent (every task or subtask)
+- **Testing:** After each phase, run relevant test suite
+- **Bash 3.2:** No bashisms in new files (no `declare -A`, no `readarray`, etc.)
+- **Sourcing pattern:** Use `source "${SCRIPT_DIR}/lib/file.sh"` with guard `[[ -n "${_FILE_LOADED:-}" ]] && return 0; _FILE_LOADED=1`
+- **No new behavior:** Decomposition is pure structural, all tests should pass unchanged
+- **Tasks can run in parallel:** Phases 1, 2, 3 touch different files. Use `--worktree` if needed for true isolation.