shipwright-cli 1.7.0

package/docs/patterns/bug-hunt.md

@@ -0,0 +1,183 @@
+# Pattern: Bug Hunt
+
+Track down complex bugs using parallel hypothesis testing with tmux teams.
+
+---
+
+## When to Use
+
+- **Intermittent failures** — the bug doesn't reproduce reliably and you're not sure where to look
+- **Complex root cause** — multiple possible explanations (race condition? state corruption? edge case?)
+- **Large blast radius** — the symptom is far from the cause and you need to search broadly
+- **Time-sensitive** — parallel investigation is faster than sequential hypothesis testing
+
+**Don't use** for obvious bugs with clear stack traces, or when you already know the root cause and just need to fix it.
+
+---
+
+## Recommended Team Composition
+
+| Role | Agent Name | Focus |
+|------|-----------|-------|
+| **Team Lead** | `lead` | Hypothesis formation, synthesis, fix verification |
+| **Investigator 1** | `investigator-1` | Tests hypothesis A |
+| **Investigator 2** | `investigator-2` | Tests hypothesis B |
+| **Investigator 3** *(optional)* | `investigator-3` | Tests hypothesis C |
+
+> **Tip:** Start with 2 investigators. Add a third only if Wave 1 produces 3+ viable hypotheses.
+
+---
+
+## Wave Breakdown
+
+### Wave 1: Gather Evidence
+
+**Goal:** Collect data from multiple angles simultaneously.
+
+```
+┌──────────────────┬──────────────────┬──────────────────┐
+│  Agent: logs       │  Agent: code      │  Agent: history   │
+│  Search error      │  Find related     │  Check git log    │
+│  logs, stack       │  code paths,      │  for recent       │
+│  traces, recent    │  identify         │  changes to       │
+│  failures           │  suspects         │  affected area    │
+└──────────────────┴──────────────────┴──────────────────┘
+         ↓ Team lead forms hypotheses from evidence
+```
+
+**Agent instructions should be narrow:**
+- Logs agent: "Search for error messages matching [pattern] in logs. Find the 5 most recent occurrences. Extract timestamps, stack traces, and request context."
+- Code agent: "Read the code path for [affected operation]. Identify all places where [symptom] could originate. Check for missing error handling, race conditions, or state mutations."
+- History agent: "Run `git log --since='2 weeks ago'` on [affected files]. Identify changes that could have introduced the bug. Check if the bug timing correlates with any deploy."
+
+### Wave 2: Test Hypotheses (Parallel)
+
+**Goal:** Each agent tests a different hypothesis simultaneously.
+
+```
+┌──────────────────┬──────────────────┬──────────────────┐
+│  Agent: hypo-A     │  Agent: hypo-B    │  Agent: hypo-C    │
+│  Test: race        │  Test: state      │  Test: edge case  │
+│  condition in      │  corruption in    │  in input         │
+│  auth middleware   │  session store    │  validation       │
+└──────────────────┴──────────────────┴──────────────────┘
+         ↓ Team lead evaluates which hypothesis has evidence
+```
+
+**Each agent should:**
+1. Add targeted logging or assertions to test their hypothesis
+2. Attempt to reproduce the bug under their hypothesis's conditions
+3. Write a clear "confirmed/rejected/inconclusive" verdict with evidence
+
+### Wave 3: Fix
+
+**Goal:** Implement the fix based on confirmed hypothesis.
+
+```
+┌──────────────────┐
+│  Agent: fixer      │
+│  Implement fix     │
+│  based on          │
+│  confirmed         │
+│  hypothesis        │
+└──────────────────┘
+         ↓ Team lead reviews fix
+```
+
+Usually a single agent. The team lead provides the confirmed root cause from Wave 2.
+
+### Wave 4: Verify
+
+**Goal:** Prove the fix works and prevent regression.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: regression │  Agent: verify    │
+│  Write regression  │  Test that the    │
+│  test that fails   │  original bug     │
+│  without fix       │  no longer        │
+│  passes with it    │  reproduces       │
+└──────────────────┴──────────────────┘
+         ↓ Team lead confirms: bug fixed, regression test in place
+```
+
+---
+
+## File-Based State Example
+
+`.claude/team-state.local.md`:
+
+```markdown
+---
+wave: 2
+status: in_progress
+goal: "Find and fix intermittent 401 errors on /api/dashboard after session refresh"
+started_at: 2026-02-07T16:00:00Z
+---
+
+## Bug Description
+Users intermittently get 401 Unauthorized on /api/dashboard. Happens ~5% of the time,
+mostly after browser has been idle for 10+ minutes. Session refresh should be transparent.
+
+## Evidence (Wave 1)
+- Error logs show 401s with valid-looking JWT signatures (wave-1-logs.md)
+- Session refresh endpoint returns 200 but sometimes the new token isn't persisted (wave-1-code.md)
+- git log shows refresh token rotation was added 3 weeks ago (wave-1-history.md)
+
+## Hypotheses
+- **A: Race condition** — refresh fires twice, second request uses revoked token
+- **B: Cookie timing** — httpOnly cookie isn't set before the next API call fires
+- **C: Clock skew** — JWT "not before" time is in the future on some requests
+
+## In Progress (Wave 2)
+- [ ] Testing hypothesis A: Add mutex/dedup to refresh logic
+- [ ] Testing hypothesis B: Add cookie write logging, check timing
+- [ ] Testing hypothesis C: Add clock skew tolerance, check JWT nbf
+
+## Agent Outputs
+- wave-1-logs.md
+- wave-1-code.md
+- wave-1-history.md
+```
+
+---
+
+## Example Commands
+
+```bash
+# Create a 3-agent bug hunt team
+shipwright session bug-hunt-401
+
+# Watch all three investigators work in parallel panes
+# Each pane shows a different hypothesis being tested
+
+# Use prefix + G to zoom into the most promising investigator
+# Use prefix + Alt-s to capture pane output for later review
+
+# Monitor
+shipwright status
+```
+
+---
+
+## Tips
+
+- **Wave 1 is about breadth, Wave 2 is about depth.** Cast a wide net first, then drill into the most promising leads.
+- **Give each investigator ONE hypothesis.** Don't let agents explore multiple theories — focus produces better results.
+- **Include reproduction steps in agent prompts.** If you know how to trigger the bug (even intermittently), include those exact steps.
+- **The team lead forms hypotheses, not agents.** Agents gather evidence and test hypotheses. The team lead synthesizes evidence into hypotheses and decides which to pursue.
+- **Add logging generously in Wave 2.** Hypothesis testing often requires instrumentation. Let agents add `console.log` or debug assertions freely — you can clean them up after.
+- **Commit the fix AND the regression test together.** A fix without a regression test is a bug waiting to come back.
+
+---
+
+## Anti-Patterns
+
+| Don't | Why |
+|-------|-----|
+| Skip evidence gathering (Wave 1) | You'll test the wrong hypotheses |
+| Let agents form their own hypotheses | They lack the full picture — the team lead should synthesize |
+| Test only one hypothesis at a time | That's sequential — the whole point is parallel hypothesis testing |
+| Test more than 3 hypotheses per wave | Agents won't go deep enough on any of them |
+| Implement a fix before confirming the root cause | You'll fix a symptom, not the cause |
+| Skip the regression test (Wave 4) | The bug WILL come back |

package/docs/patterns/feature-implementation.md

@@ -0,0 +1,159 @@
+# Pattern: Feature Implementation
+
+Build multi-component features using iterative parallel waves with tmux teams.
+
+---
+
+## When to Use
+
+- Building a feature that spans **2+ layers** (frontend + backend, API + tests, etc.)
+- Work can be **decomposed into independent modules** that different agents can build simultaneously
+- You want **faster delivery** than sequential single-agent work
+
+**Don't use** for single-file changes, tightly sequential work, or features small enough for one agent.
+
+---
+
+## Recommended Team Composition
+
+| Role | Agent Name | Focus | Example Files |
+|------|-----------|-------|---------------|
+| **Team Lead** | `lead` | Orchestration, synthesis, integration | State file, final wiring |
+| **Backend** | `backend` | Data models, API routes, services | `src/api/`, `src/services/`, `src/models/` |
+| **Frontend** | `frontend` | UI components, state management | `apps/web/src/`, `*.tsx` |
+| **Tests** *(optional)* | `tests` | Unit + integration tests | `src/tests/`, `*.test.ts` |
+
+> **Tip:** For smaller features, combine frontend + tests into one agent (2-agent team).
+
+---
+
+## Wave Breakdown
+
+### Wave 1: Research & Plan
+
+**Goal:** Understand existing patterns before writing code.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: backend   │  Agent: frontend  │
+│  Scan existing    │  Scan existing    │
+│  API patterns,    │  component        │
+│  data models,     │  patterns, state  │
+│  middleware        │  management       │
+└──────────────────┴──────────────────┘
+         ↓ Team lead synthesizes findings
+```
+
+**Each agent writes:** `.claude/team-outputs/wave-1-{name}.md`
+
+**Team lead then:** Reads both outputs, identifies the implementation approach, updates the state file with a plan.
+
+### Wave 2: Parallel Implementation
+
+**Goal:** Build independent components simultaneously.
+
+```
+┌──────────────────┬──────────────────┬──────────────────┐
+│  Agent: backend   │  Agent: frontend  │  Agent: tests     │
+│  Build data       │  Build UI         │  Set up test       │
+│  model + API      │  components +     │  fixtures +        │
+│  routes            │  state hooks      │  unit tests        │
+└──────────────────┴──────────────────┴──────────────────┘
+         ↓ Team lead reviews outputs, checks for errors
+```
+
+**Each agent writes:** `.claude/team-outputs/wave-2-{name}.md`
+
+**Team lead then:** Reads outputs, runs a quick build/typecheck, identifies integration points.
+
+### Wave 3: Integration & Validation
+
+**Goal:** Wire components together, run tests, fix issues.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: backend   │  Agent: tests     │
+│  Wire routes to   │  Run full test    │
+│  frontend calls,  │  suite, write     │
+│  fix type errors  │  integration tests│
+└──────────────────┴──────────────────┘
+         ↓ Team lead verifies everything passes
+```
+
+### Wave 4: Polish *(if needed)*
+
+**Goal:** Fix remaining issues, documentation.
+
+Usually a single agent handles the remaining fixes.
+
+---
+
+## File-Based State Example
+
+`.claude/team-state.local.md`:
+
+```markdown
+---
+wave: 2
+status: in_progress
+goal: "Build user authentication with JWT — login, signup, password reset"
+started_at: 2026-02-07T10:00:00Z
+---
+
+## Completed
+- [x] Scanned existing Express route patterns (wave-1-backend.md)
+- [x] Scanned existing React component patterns (wave-1-frontend.md)
+- [x] Decided: JWT with httpOnly cookies, Zod validation, React Hook Form
+
+## In Progress (Wave 2)
+- [ ] User model + auth routes (backend)
+- [ ] Login/Signup/Reset components (frontend)
+- [ ] Auth test fixtures + unit tests (tests)
+
+## Blocked
+- Integration tests blocked on Wave 2 completion
+
+## Agent Outputs
+- wave-1-backend.md — Express patterns, middleware chain analysis
+- wave-1-frontend.md — React component patterns, existing form handling
+```
+
+---
+
+## Example Commands
+
+```bash
+# Create the team session with 3 panes
+shipwright session auth-feature
+
+# In the team lead pane, describe the feature goal and wave plan
+# The team lead spawns workers and tracks state in .claude/team-state.local.md
+
+# Monitor progress from any terminal
+shipwright status
+
+# Clean up when done
+shipwright cleanup --force
+```
+
+---
+
+## Tips
+
+- **Partition files strictly.** Before Wave 2, explicitly tell each agent which directories they own. File conflicts are the #1 failure mode.
+- **Run typecheck between waves.** The quality gate hooks help here — `teammate-idle.sh` catches type errors before agents go idle.
+- **Don't over-decompose Wave 1.** Two research agents are usually enough. More than 3 researchers creates redundant analysis.
+- **Wave 3 is where things break.** Integration is inherently serial. Be ready to have the team lead handle wiring personally if agents struggle with cross-module connections.
+- **Use `sonnet` for implementation, `haiku` for lookups.** Save the expensive models for the architecture decisions in Wave 1.
+
+---
+
+## Anti-Patterns
+
+| Don't | Why |
+|-------|-----|
+| Let two agents edit the same file | One overwrites the other |
+| Skip Wave 1 research | Agents will re-invent existing patterns instead of following them |
+| Give agents the full feature spec | They lose focus. Give each agent only their slice |
+| Run Wave 3 without checking Wave 2 outputs | You'll integrate broken code |
+| Use 4+ agents for a single feature | Coordination cost exceeds the parallel benefit |

package/docs/patterns/refactoring.md

@@ -0,0 +1,183 @@
+# Pattern: Refactoring
+
+Perform large-scale code transformations safely using a 2-agent team with strict file ownership and iterative validation.
+
+---
+
+## When to Use
+
+- **Pattern migration** — converting callbacks to async/await, class components to hooks, etc.
+- **Architecture changes** — extracting modules, reorganizing directories, splitting monoliths
+- **API redesign** — changing function signatures, renaming across the codebase
+- **Dependency replacement** — swapping one library for another throughout the project
+
+**Don't use** for small renames in 1-2 files, or cosmetic changes like formatting.
+
+---
+
+## Recommended Team Composition
+
+| Role | Agent Name | Focus | Owns |
+|------|-----------|-------|------|
+| **Team Lead** | `lead` | Orchestration, runs tests between waves | State file |
+| **Refactorer** | `refactor` | Source code transformations | Production source files |
+| **Consumers** | `consumers` | Updates tests, imports, dependents | Test files, config files, docs |
+
+> This is intentionally a **2-agent** pattern. Refactoring requires tight coordination — more agents means more conflict risk. The team lead runs tests.
+
+---
+
+## Wave Breakdown
+
+### Wave 1: Map
+
+**Goal:** Find all instances of the old pattern and understand the dependency graph.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: refactor   │  Agent: consumers │
+│  Find all          │  Find all tests,  │
+│  instances of old  │  imports, and     │
+│  pattern in source │  dependents of    │
+│  code               │  affected modules │
+└──────────────────┴──────────────────┘
+         ↓ Team lead builds the transformation plan
+```
+
+**This wave is critical.** The team lead uses both outputs to:
+1. Identify the full blast radius of the change
+2. Order the transformation (leaf nodes first)
+3. Assign specific files to each agent
+
+### Wave 2: Transform (Leaf Nodes First)
+
+**Goal:** Change the code, starting with modules that nothing else depends on.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: refactor   │  Agent: consumers │
+│  Transform leaf    │  Update tests for │
+│  modules — files   │  leaf modules,    │
+│  with zero         │  fix imports      │
+│  dependents        │                    │
+└──────────────────┴──────────────────┘
+         ↓ Team lead runs tests — should still pass
+```
+
+**Why leaf nodes first?** If you change a core module first, everything that depends on it breaks simultaneously. By starting with leaf nodes, you keep the test suite green between waves.
+
+### Wave 3: Transform Core
+
+**Goal:** Transform the remaining core modules, now that leaf nodes are done.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: refactor   │  Agent: consumers │
+│  Transform core    │  Update remaining │
+│  modules           │  tests, fix type  │
+│                    │  errors           │
+└──────────────────┴──────────────────┘
+         ↓ Team lead runs full test suite
+```
+
+### Wave 4+: Fix Breakage
+
+**Goal:** Iteratively fix test failures and type errors until green.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: refactor   │  Agent: consumers │
+│  Fix source code   │  Fix test         │
+│  issues from test  │  failures,        │
+│  failures           │  update snapshots │
+└──────────────────┴──────────────────┘
+         ↓ Team lead verifies: all tests pass, no type errors
+```
+
+---
+
+## File-Based State Example
+
+`.claude/team-state.local.md`:
+
+```markdown
+---
+wave: 3
+status: in_progress
+goal: "Convert all callback-based code in src/services/ to async/await"
+started_at: 2026-02-07T11:00:00Z
+---
+
+## Transformation Map (from Wave 1)
+Leaf nodes (no dependents):
+- src/services/email.ts (5 callbacks)
+- src/services/logger.ts (2 callbacks)
+
+Core modules (have dependents):
+- src/services/db.ts (12 callbacks) → used by 8 other files
+- src/services/auth.ts (7 callbacks) → used by 4 other files
+
+## Completed
+- [x] Mapped all 26 callback instances across 4 files (wave-1-refactor.md)
+- [x] Found 14 test files and 6 other dependents (wave-1-consumers.md)
+- [x] Converted email.ts and logger.ts to async/await (wave-2)
+- [x] Updated tests for email.ts and logger.ts (wave-2)
+
+## In Progress (Wave 3)
+- [ ] Convert db.ts (12 callbacks → async/await)
+- [ ] Convert auth.ts (7 callbacks → async/await)
+- [ ] Update 14 test files for new signatures
+- [ ] Fix imports in 6 dependent modules
+
+## Test Status
+- After Wave 2: 142/142 passing
+- After Wave 3: TBD
+
+## Agent Outputs
+- wave-1-refactor.md — Full callback inventory with file:line
+- wave-1-consumers.md — Dependency map of affected modules
+```
+
+---
+
+## Example Commands
+
+```bash
+# Create a 2-agent refactoring team
+shipwright session refactor-async
+
+# In the lead pane, describe the refactoring goal
+# Team lead assigns specific files to each agent per wave
+
+# Run tests between waves from the lead pane:
+#   pnpm test
+
+# Monitor agents in their panes
+shipwright status
+
+# Clean up
+shipwright cleanup --force
+```
+
+---
+
+## Tips
+
+- **Always map before transforming.** Wave 1 is non-negotiable. Skipping it leads to missed instances and cascading breakage.
+- **Transform leaf nodes first.** This keeps the test suite green through intermediate waves, which gives you confidence that each wave's changes are correct.
+- **The team lead must run tests between every wave.** This is the safety net. If tests break, you know which wave caused it.
+- **Strict file ownership.** The refactorer owns production files. The consumers agent owns test files and config. Never overlap.
+- **Use git commits between waves.** After each successful wave (tests pass), commit. This gives you rollback points if a later wave goes wrong.
+
+---
+
+## Anti-Patterns
+
+| Don't | Why |
+|-------|-----|
+| Transform everything at once | If it breaks, you won't know which change caused it |
+| Let both agents edit the same file | Write conflicts |
+| Skip running tests between waves | You lose the ability to isolate which wave broke things |
+| Start with core modules | Everything that depends on them breaks simultaneously |
+| Use 3+ agents for refactoring | The file ownership partition becomes too fragmented |
+| Refactor and add features simultaneously | One change at a time — refactoring should be behavior-preserving |

package/docs/patterns/research-exploration.md

@@ -0,0 +1,144 @@
+# Pattern: Research & Exploration
+
+Understand a codebase, problem space, or architecture using parallel exploration agents in tmux.
+
+---
+
+## When to Use
+
+- **Onboarding** onto an unfamiliar codebase — need to map architecture, patterns, and conventions
+- **Pre-implementation research** — need to understand existing code before building something new
+- **Architecture review** — need a comprehensive understanding of how the system fits together
+- **Dependency audits** — need to survey what's used and where
+
+**Don't use** when you already know the codebase well, or for narrow questions where a single `grep` suffices.
+
+---
+
+## Recommended Team Composition
+
+| Role | Agent Name | Focus |
+|------|-----------|-------|
+| **Team Lead** | `lead` | Synthesis, asks follow-up questions, produces final report |
+| **Explorer 1** | `structure` | Directory layout, entry points, build system, configuration |
+| **Explorer 2** | `patterns` | Code patterns, abstractions, data flow, key types |
+| **Explorer 3** *(optional)* | `deps` | Dependencies, external integrations, API surface |
+
+> **Tip:** For smaller codebases, 2 agents (structure + patterns) is enough.
+
+---
+
+## Wave Breakdown
+
+### Wave 1: Broad Scan
+
+**Goal:** Map the territory. Each agent scans a different dimension of the codebase.
+
+```
+┌──────────────────┬──────────────────┬──────────────────┐
+│  Agent: structure │  Agent: patterns  │  Agent: deps      │
+│  Map directories  │  Find key         │  Catalog external  │
+│  Find entry       │  abstractions,    │  dependencies,     │
+│  points, configs  │  patterns, types  │  API boundaries    │
+└──────────────────┴──────────────────┴──────────────────┘
+         ↓ Team lead synthesizes initial map
+```
+
+**Agent prompts should be specific:**
+- Structure agent: "Map the directory tree, identify entry points (main files, index files), find config files (tsconfig, package.json, .env), and document the build pipeline."
+- Patterns agent: "Find recurring code patterns — how are routes defined? How is state managed? What abstraction layers exist? Document with specific file:line references."
+- Deps agent: "Catalog all external dependencies from package.json/go.mod/requirements.txt. Map which modules use which deps. Identify external API calls."
+
+### Wave 2: Deep Dives
+
+**Goal:** Based on Wave 1 findings, investigate specific areas in depth.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: deep-1    │  Agent: deep-2    │
+│  Trace the auth   │  Trace the data   │
+│  flow end-to-end  │  layer end-to-end │
+│  (from HTTP to DB)│  (models → API)   │
+└──────────────────┴──────────────────┘
+         ↓ Team lead synthesizes into architecture doc
+```
+
+The team lead picks the 2-3 most important areas from Wave 1 findings and sends agents to trace them in detail.
+
+### Wave 3: Synthesis *(team lead only)*
+
+**Goal:** Combine all findings into a coherent report.
+
+The team lead reads all agent output files and produces a final architecture document or research summary.
+
+---
+
+## File-Based State Example
+
+`.claude/team-state.local.md`:
+
+```markdown
+---
+wave: 2
+status: in_progress
+goal: "Map architecture of the payments service for migration planning"
+started_at: 2026-02-07T09:00:00Z
+---
+
+## Completed
+- [x] Directory structure mapped (wave-1-structure.md)
+- [x] Key patterns identified: repository pattern, event sourcing (wave-1-patterns.md)
+- [x] External deps cataloged: Stripe SDK, Redis, PostgreSQL (wave-1-deps.md)
+
+## In Progress (Wave 2)
+- [ ] Deep dive: payment processing flow (Stripe integration → event store → ledger)
+- [ ] Deep dive: subscription lifecycle (create → renew → cancel → webhook handling)
+
+## Key Findings So Far
+- Entry point: src/server.ts → src/routes/index.ts
+- All mutations go through event store before updating read models
+- Stripe webhook handler is in src/webhooks/stripe.ts — 800 lines, needs refactoring
+- No test coverage for subscription renewal edge cases
+
+## Agent Outputs
+- wave-1-structure.md
+- wave-1-patterns.md
+- wave-1-deps.md
+```
+
+---
+
+## Example Commands
+
+```bash
+# Create a 2-agent exploration team
+shipwright session codebase-explore
+
+# Agents run in parallel panes — you can watch both scanning at once
+# Team lead pane synthesizes results between waves
+
+# Use tmux zoom (prefix + G) to focus on one agent's output
+# Use synchronized input (prefix + S) to stop all agents at once if needed
+```
+
+---
+
+## Tips
+
+- **Use `haiku` for Wave 1 agents.** Broad scanning is simple work — haiku is fast and cheap for file discovery and pattern matching.
+- **Use `sonnet` or `opus` for Wave 2 deep dives.** Tracing execution paths and understanding architecture requires stronger reasoning.
+- **Give agents specific questions, not vague goals.** Instead of "explore the frontend," ask "How does the React app manage authentication state? Trace from login button click through to authenticated API calls."
+- **Wave 1 should produce file:line references.** Agents should cite specific locations, not just describe patterns abstractly. This makes Wave 2 much more efficient.
+- **The team lead's synthesis is the real deliverable.** Individual agent outputs are raw data. The team lead turns them into actionable understanding.
+
+---
+
+## Anti-Patterns
+
+| Don't | Why |
+|-------|-----|
+| Send all agents to explore the same directories | Redundant work, wasted tokens |
+| Skip Wave 1 and go straight to deep dives | You won't know which areas are worth diving into |
+| Have agents write a "report" instead of citing specifics | Abstract summaries are useless — you need file:line references |
+| Use more than 3 exploration agents | Diminishing returns — 3 agents cover most codebases in one wave |
+| Run exploration waves beyond 3 | If you don't understand the codebase after 3 waves, the problem is prompt quality, not wave count |