shipwright-cli 1.7.0

package/docs/TIPS.md

@@ -0,0 +1,331 @@
+# Power User Tips
+
+Patterns and tricks for getting the most out of Claude Code Agent Teams with tmux.
+
+---
+
+## Team Patterns That Actually Work
+
+Based on [Addy Osmani's research](https://addyosmani.com/blog/claude-code-agent-teams/) and community experience:
+
+### When Teams Add Value
+- **Competing hypotheses** — Multiple agents investigating different theories for a bug
+- **Parallel review** — Security, performance, and test coverage by dedicated reviewers
+- **Cross-layer features** — Frontend, backend, and tests developed simultaneously
+
+### When to Stay Single-Agent
+- Sequential, tightly-coupled work where each step depends on the last
+- Simple bugs or single-file changes
+- Tasks where coordination overhead exceeds the parallel benefit
+
+### The Task Sizing Sweet Spot
+Too small and coordination overhead dominates. Too large and agents work too long without check-ins. Aim for **5-6 focused tasks per agent** with clear deliverables.
+
+### Specification Quality = Output Quality
+Detailed spawn prompts with technical constraints, acceptance criteria, and domain context produce dramatically better results. Don't just say "fix the tests" — say "fix the auth tests in src/auth/__tests__/, ensuring all edge cases for expired tokens are covered, using the existing MockAuthProvider pattern."
+
+---
+
+## Hook Patterns for Teams
+
+### Quality Gates (Most Valuable)
+- **TeammateIdle** — Run typecheck before letting agents idle. Catches errors early.
+- **TaskCompleted** — Run lint + related tests before allowing task completion.
+- **Stop** — Verify all work is complete before Claude stops responding.
+
+### Observability
+- **Notification** — Desktop alerts so you can work on other things.
+- **PostToolUse** on `Bash` — Log all commands agents run to a file.
+- **SubagentStart/SubagentStop** — Track when agents spawn and finish.
+
+### Context Preservation
+- **PreCompact** — Save git status, recent commits, and project reminders before compaction.
+- **SessionStart** on `compact` — Re-inject critical context after compaction.
+
+---
+
+## Team Size & Structure
+
+### Keep teams small
+
+Limit teams to **2-3 agents**. More agents increase the risk of the tmux `send-keys` race condition (#23615) and create more coordination overhead than they save in parallel work.
+
+```
+Good:  2 agents — backend + frontend
+Good:  3 agents — backend + frontend + tests
+Risky: 4+ agents — race conditions, context pressure
+```
+
+### Assign different files to each agent
+
+File conflicts are the #1 source of wasted work in agent teams. If two agents edit the same file, one will overwrite the other. Always partition work by file ownership:
+
+```
+Agent 1 (backend):  src/api/, src/services/
+Agent 2 (frontend): apps/web/src/
+Agent 3 (tests):    src/tests/, *.test.ts
+```
+
+### Use git worktrees for complete isolation
+
+For maximum safety, use [git worktrees](https://git-scm.com/docs/git-worktree) so each agent works in its own copy of the repo:
+
+```bash
+# Create worktrees for each agent
+git worktree add ../project-backend feature/backend
+git worktree add ../project-frontend feature/frontend
+git worktree add ../project-tests feature/tests
+
+# Each agent works in its own directory — zero conflict risk
+```
+
+---
+
+## Agent Configuration
+
+### Use `delegate` mode for maximum autonomy
+
+When you trust the agents to work independently (e.g., they have clear, well-scoped tasks), use `delegate` mode to minimize permission prompts:
+
+```bash
+# In your Claude Code launch or CLAUDE.md
+# "mode": "delegate" gives agents more autonomy
+```
+
+### Use haiku for subagent lookups
+
+Subagents (spawned via the `Task` tool) don't need a powerful model for simple file searches and code lookups. Save money and latency:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
+  }
+}
+```
+
+### Prevent context overflow
+
+Agent teams burn through context faster than solo sessions. Set aggressive auto-compact:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE": "70"
+  }
+}
+```
+
+This compacts the conversation when it hits 70% of the context window (default is 80%).
+
+---
+
+## Monitoring & Management
+
+### Watch all agents at once
+
+Use `shipwright status` (alias: `cct`, `sw`) to see a dashboard of running team sessions:
+
+```bash
+shipwright status
+```
+
+Or press `prefix + Ctrl-t` in tmux to show the dashboard inline.
+
+### Zoom into a single agent
+
+Press `prefix + G` to toggle zoom on the current pane. This makes one agent fill the entire terminal — useful for reading long output. Press again to return to the tiled layout.
+
+### Synchronized input
+
+Press `prefix + Alt-t` to toggle synchronized panes. When enabled, anything you type goes to ALL panes simultaneously. Useful for:
+- Stopping all agents at once (`Ctrl-C` in all panes)
+- Running the same command in all agent directories
+
+**Remember to turn it off** when you're done — otherwise your input goes everywhere.
+
+### Capture pane contents
+
+Press `prefix + Alt-s` to save the current pane's visible content to a file in `/tmp/`. Useful for debugging agent output after the fact.
+
+---
+
+## Hook Patterns
+
+### Quality gates
+
+The included `teammate-idle.sh` hook blocks agents from going idle until TypeScript errors are fixed. You can extend this pattern for other checks:
+
+```bash
+# Example: lint check on idle
+#!/usr/bin/env bash
+cd "$(find_project_root)" || exit 0
+pnpm lint 2>&1 || {
+  echo "::error::Lint errors found. Fix them before going idle."
+  exit 2
+}
+exit 0
+```
+
+### Notification sounds
+
+Play a sound when an agent completes a task (macOS):
+
+```bash
+# task-completed.sh
+#!/usr/bin/env bash
+afplay /System/Library/Sounds/Glass.aiff &
+exit 0
+```
+
+### Auto-format on save
+
+Run a formatter when agents complete work:
+
+```bash
+# task-completed.sh
+#!/usr/bin/env bash
+cd "$(find_project_root)" || exit 0
+pnpm format --write 2>&1
+exit 0
+```
+
+---
+
+## Task Design
+
+### Write focused task descriptions
+
+Vague tasks lead to wasted context and unfocused work. Compare:
+
+```
+Bad:  "Improve the authentication system"
+Good: "Add rate limiting to POST /api/auth/login — max 5 attempts per
+       IP per minute. Add the rate limiter in src/api/middleware/
+       and tests in src/tests/auth-rate-limit.test.ts"
+```
+
+### 5-6 tasks per agent is the sweet spot
+
+Too few tasks = agent finishes early and sits idle. Too many = context pressure and loss of focus.
+
+### Put dependencies first
+
+When creating task lists, order tasks so independent work comes first and dependent tasks come later. The team lead should assign blocked tasks only after their dependencies are complete.
+
+---
+
+## tmux Session Management
+
+### Named sessions
+
+Always use named sessions so you can find them later:
+
+```bash
+tmux new -s my-feature    # Not just "tmux new"
+```
+
+### Detach and reattach
+
+You can detach from a session (`prefix + d`) and agents keep running. Reattach later:
+
+```bash
+tmux attach -t my-feature
+```
+
+### Clean up orphaned sessions
+
+After a team finishes, clean up leftover tmux sessions and panes:
+
+```bash
+shipwright cleanup           # Dry-run: shows what would be killed
+shipwright cleanup --force   # Actually kills orphaned sessions
+```
+
+---
+
+## Environment Variables Reference
+
+| Variable | Default | What it does |
+|----------|---------|--------------|
+| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | — | **Required.** Enables agent teams feature |
+| `CLAUDE_CODE_SUBAGENT_MODEL` | (parent model) | Model for subagent lookups. Set to `"haiku"` to save money |
+| `CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE` | `"80"` | Context compaction threshold. Lower = more aggressive |
+| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | `"3"` | Parallel tool calls per agent. Higher = faster but more API usage |
+| `CLAUDE_CODE_GLOB_HIDDEN` | — | Include dotfiles in glob searches |
+| `CLAUDE_CODE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | — | Keep bash cwd consistent across tool calls |
+| `CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES` | — | Show tool use summaries in output |
+| `CLAUDE_CODE_TST_NAMES_IN_MESSAGES` | — | Show teammate names in messages |
+| `CLAUDE_CODE_EAGER_FLUSH` | — | Flush output eagerly (reduces perceived latency) |
+
+---
+
+## Wave-Style Iteration
+
+For complex, multi-step tasks, use **wave patterns** — iterative cycles of parallel agent work followed by synthesis. See the full pattern guides in [docs/patterns/](patterns/).
+
+### The Wave Cycle
+
+Each wave follows four steps:
+
+1. **Assess** — Read agent outputs from the previous wave. What succeeded? What failed?
+2. **Decompose** — What work remains? What can run in parallel?
+3. **Spawn** — Launch agents in separate tmux panes for each independent task
+4. **Synthesize** — Gather results, update the state file, plan the next wave
+
+Repeat until done. Set a reasonable wave limit (5-10 for most tasks).
+
+### File-Based State
+
+Track progress through a markdown state file instead of keeping everything in agent memory. This survives compactions, context resets, and lets any agent pick up where others left off.
+
+**State file:** `.claude/team-state.local.md`
+
+```markdown
+---
+wave: 2
+status: in_progress
+goal: "Build user auth with JWT"
+started_at: 2026-02-07T10:00:00Z
+---
+
+## Completed
+- [x] Scanned existing auth patterns
+- [x] Built User model
+
+## In Progress
+- [ ] JWT route handlers
+- [ ] React login components
+
+## Blocked
+- Integration tests blocked on route completion
+```
+
+**Agent outputs:** `.claude/team-outputs/*.md`
+
+Each agent writes findings/results to a file in this directory. The team lead reads all outputs between waves.
+
+**Add to `.gitignore`:**
+```
+.claude/team-state.local.md
+.claude/team-outputs/
+```
+
+### When to Use Waves vs. Single-Pass Teams
+
+| Situation | Approach |
+|-----------|----------|
+| Independent tasks with clear file ownership | Single-pass team — spawn agents, collect results |
+| Tasks that require iteration (tests must pass, errors must be fixed) | Wave pattern — iterate until completion criteria met |
+| Exploratory work that builds on previous findings | Wave pattern — each wave goes deeper based on last wave's results |
+| Simple parallel review (code quality + security + tests) | Single-pass team — each reviewer works independently |
+
+### Quick Reference: Five Wave Patterns
+
+| Pattern | Waves | Agents | Best For |
+|---------|-------|--------|----------|
+| [Feature Implementation](patterns/feature-implementation.md) | 3-4 | 2-3 | Multi-component features |
+| [Research & Exploration](patterns/research-exploration.md) | 2-3 | 2-3 | Understanding codebases |
+| [Test Generation](patterns/test-generation.md) | 3-4+ | 2-3 | Coverage campaigns |
+| [Refactoring](patterns/refactoring.md) | 3-4 | 2 | Large-scale transformations |
+| [Bug Hunt](patterns/bug-hunt.md) | 3-4 | 2-3 | Complex, elusive bugs |

package/docs/definition-of-done.example.md

@@ -0,0 +1,16 @@
+# Definition of Done
+
+Use this template with `shipwright loop --definition-of-done <file>` to enforce completion criteria.
+Copy and customize for your project.
+
+## Checklist
+
+- [ ] All specified functionality is implemented
+- [ ] Unit tests exist for new code
+- [ ] All tests pass
+- [ ] No TODO/FIXME markers in new code
+- [ ] Public functions have docstrings/comments
+- [ ] README reflects current state
+- [ ] No hardcoded values that should be configurable
+- [ ] Error handling covers likely failure modes
+- [ ] Code follows existing patterns in the codebase

package/docs/patterns/README.md

@@ -0,0 +1,139 @@
+# Wave-Style Team Patterns
+
+Structured patterns for running Claude Code Agent Teams in tmux using iterative, parallel "waves" of work.
+
+---
+
+## What Are Wave Patterns?
+
+A **wave** is a cycle of parallel work followed by synthesis. Instead of one agent grinding through a task sequentially, you decompose work into independent chunks, assign them to agents in separate tmux panes, and iterate until done.
+
+```
+Wave 1: Research       Wave 2: Build           Wave 3: Integrate
+┌─────┬─────┐          ┌─────┬─────┬─────┐     ┌─────┬─────┐
+│ A1  │ A2  │    →     │ A1  │ A2  │ A3  │  →  │ A1  │ A2  │
+│scan │scan │          │model│routes│ UI  │     │wire │tests│
+└─────┴─────┘          └─────┴─────┴─────┘     └─────┴─────┘
+      ↓ synthesize            ↓ synthesize            ↓ done
+```
+
+Each wave:
+1. **Assess** — What did the previous wave accomplish? What failed?
+2. **Decompose** — What can be done in parallel now?
+3. **Spawn** — Launch agents in tmux panes for each independent task
+4. **Synthesize** — Gather results, update state, plan next wave
+
+---
+
+## Available Patterns
+
+| Pattern | When to Use | Typical Waves | Team Size |
+|---------|-------------|---------------|-----------|
+| [Feature Implementation](feature-implementation.md) | Building multi-component features | 3-4 | 2-3 agents |
+| [Research & Exploration](research-exploration.md) | Understanding a codebase or problem space | 2-3 | 2-3 agents |
+| [Test Generation](test-generation.md) | Comprehensive test coverage campaigns | 3-4+ | 2-3 agents |
+| [Refactoring](refactoring.md) | Large-scale code transformations | 3-4 | 2 agents |
+| [Bug Hunt](bug-hunt.md) | Tracking down complex, elusive bugs | 3-4 | 2-3 agents |
+
+---
+
+## File-Based State
+
+Wave patterns use a **file-based state file** to track progress across iterations. This works everywhere — no special tools required.
+
+**State file:** `.claude/team-state.local.md`
+
+```markdown
+---
+wave: 2
+status: in_progress
+goal: "Build user auth with JWT"
+started_at: 2026-02-07T10:00:00Z
+---
+
+## Completed
+- [x] Scanned existing auth patterns
+- [x] Identified middleware structure
+- [x] Built User model
+
+## In Progress
+- [ ] JWT route handlers
+- [ ] Login/signup React components
+
+## Blocked
+- None
+
+## Agent Outputs
+- wave-1-scan-auth.md — Existing auth analysis
+- wave-1-scan-deps.md — Dependency audit
+- wave-2-model.md — User model implementation notes
+```
+
+**Agent outputs directory:** `.claude/team-outputs/`
+
+Each agent writes its results to a markdown file in this directory. The team lead reads all outputs between waves to synthesize progress.
+
+> **Tip:** Add `.claude/team-state.local.md` and `.claude/team-outputs/` to your `.gitignore`. These are ephemeral working files.
+
+---
+
+## Quick Start
+
+Pick a pattern, then use `shipwright` (alias: `cct`, `sw`) to set up the team:
+
+```bash
+# Start a tmux session
+tmux new -s my-feature
+
+# Create a 3-agent team
+shipwright session my-feature
+
+# In the team lead pane, describe the work using a wave pattern
+# The team lead decomposes into waves and assigns tasks
+```
+
+---
+
+## Key Principles
+
+### 1. Parallel Everything
+If two tasks don't depend on each other, run them at the same time in separate panes. The whole point of waves is maximizing parallel throughput.
+
+### 2. Synthesize Between Waves
+Don't just fire-and-forget. After each wave, the team lead reads all agent outputs, identifies gaps, and adjusts the plan. This is where the real value happens.
+
+### 3. Iterate Until Done
+Waves repeat until the goal is met. Failed tasks get retried with better instructions. Each wave builds on the last. Set a reasonable max (5-10 waves for most tasks).
+
+### 4. File-Based State Is the Source of Truth
+The `.claude/team-state.local.md` file tracks what's done, what's pending, and what's blocked. Agents update their output files; the team lead updates the state file.
+
+### 5. Keep Teams Small
+2-3 agents per team. More agents means more tmux panes, more coordination overhead, and more risk of file conflicts. The sweet spot is 2-3 focused agents.
+
+---
+
+## Anti-Patterns
+
+| Don't | Why | Instead |
+|-------|-----|---------|
+| Spawn 5+ agents per wave | Coordination overhead, race conditions | 2-3 agents per wave |
+| Skip synthesis between waves | You'll lose track of progress and duplicate work | Always read outputs and update state |
+| Give vague task descriptions | Agents waste context figuring out what to do | Be specific: files, functions, acceptance criteria |
+| Let agents touch overlapping files | One will overwrite the other's changes | Partition files by agent |
+| Keep iterating when stuck | Wastes tokens and your time | After 3 failed attempts, rethink the approach |
+| Use waves for trivial tasks | Overhead exceeds benefit | Just do it in a single agent |
+
+---
+
+## Model Selection
+
+Choose the right model for each agent's task:
+
+| Task Type | Model | Why |
+|-----------|-------|-----|
+| File search, simple lookups | `haiku` | Fast, cheap |
+| Implementation, clear requirements | `sonnet` | Balanced speed/quality |
+| Architecture decisions, complex debugging | `opus` | Best reasoning |
+| Test generation | `sonnet` | Good pattern matching |
+| Documentation, reports | `sonnet` | Clear writing |

package/docs/patterns/audit-loop.md

@@ -0,0 +1,149 @@
+# Pattern: Audit Loop
+
+Add self-reflection and quality gates to the continuous agent loop (`shipwright loop`) to prevent premature completion, catch regressions, and enforce project-specific standards.
+
+---
+
+## When to Use
+
+- Running `shipwright loop` on tasks where **correctness matters more than speed** (production features, refactors, data migrations)
+- The agent keeps declaring LOOP_COMPLETE **before the work is actually done**
+- You want **automated quality checks** (tests, linting, type-checking) between iterations
+- Your project has a **Definition of Done** that goes beyond "code compiles"
+
+**Don't use** for quick prototypes, throwaway scripts, or exploration tasks where speed matters more than rigor.
+
+---
+
+## Audit Modes
+
+### `--audit` (Self-Reflection)
+
+The agent pauses after each iteration to review its own work before deciding whether to continue or declare completion.
+
+**Cost:** Minimal — adds ~30 seconds per iteration (one extra prompt to the same agent).
+
+**Best for:** Solo agent work where you want a sanity check without the overhead of a second agent.
+
+```bash
+shipwright loop "Build user auth with JWT" --audit --test-cmd "npm test"
+```
+
+### `--audit-agent` (Separate Auditor)
+
+Spawns a dedicated auditor agent that reviews the work agent's output each iteration. The auditor can reject LOOP_COMPLETE and send the work agent back with specific feedback.
+
+**Cost:** Higher — each iteration runs two agents (worker + auditor). Roughly 2x the API cost.
+
+**Best for:** Complex features, production code, or tasks where you've seen the agent cut corners.
+
+```bash
+shipwright loop "Refactor auth to use refresh tokens" --audit-agent --model sonnet
+```
+
+### `--quality-gates` (Automated Checks)
+
+Runs your test command, linter, or type-checker between iterations. The loop only advances if gates pass.
+
+**Cost:** Depends on your test suite. Adds wall-clock time but no extra API cost.
+
+**Best for:** Projects with existing CI checks you want to enforce locally.
+
+```bash
+shipwright loop "Add pagination to API" --quality-gates --test-cmd "npm test && npm run lint"
+```
+
+### Combining Modes
+
+Modes stack. The most rigorous setup combines all three:
+
+```bash
+shipwright loop "Build payment integration" \
+  --audit-agent \
+  --quality-gates \
+  --test-cmd "npm test" \
+  --definition-of-done dod.md
+```
+
+---
+
+## Writing Effective Definition of Done Files
+
+A good DoD file is the single most effective way to prevent premature LOOP_COMPLETE.
+
+### Template
+
+```bash
+cp ~/.shipwright/templates/definition-of-done.example.md my-dod.md
+```
+
+### Tips
+
+- **Be specific.** "Tests pass" is weak. "Unit tests cover the 3 API endpoints and the auth middleware" is strong.
+- **Include negative checks.** "No hardcoded API keys" or "No TODO markers" catch things agents skip.
+- **Keep it short.** 8-15 items. More than that and the agent loses focus.
+- **Order by importance.** The agent checks items top-to-bottom. Put critical items first.
+
+### Example: Feature DoD
+
+```markdown
+# Definition of Done — Payment Integration
+
+- [ ] Stripe webhook handler processes charge.succeeded and charge.failed
+- [ ] Idempotency keys prevent duplicate charges
+- [ ] Unit tests cover success, failure, and duplicate scenarios
+- [ ] Integration test hits Stripe test mode
+- [ ] All amounts stored as cents (integer), never floats
+- [ ] No Stripe secret keys in source code
+- [ ] Error responses follow existing API error format
+```
+
+---
+
+## Preventing Premature LOOP_COMPLETE
+
+The most common failure mode is the agent declaring victory too early. Countermeasures:
+
+| Technique | How it helps |
+|-----------|-------------|
+| `--audit` | Agent re-reads its own output and catches obvious gaps |
+| `--audit-agent` | Second opinion catches blind spots the worker has |
+| `--definition-of-done` | Explicit checklist the agent must verify before completing |
+| `--quality-gates` | Hard gate — tests must pass or the loop continues |
+| `--test-cmd` | Even without quality gates, a test command gives the agent feedback |
+| `--max-iterations` | Safety net — prevents infinite loops if nothing else works |
+
+**Pro tip:** If the agent still completes too early, make your goal statement more specific. "Build auth" is vague. "Build JWT auth with login, signup, password reset, and refresh token rotation" gives the agent a clear finish line.
+
+---
+
+## Example Commands
+
+```bash
+# Quick audit for a small task
+shipwright loop "Fix the N+1 query in user list" --audit --test-cmd "pytest tests/test_users.py"
+
+# Rigorous audit for production feature
+shipwright loop "Add RBAC to the API" --audit-agent --quality-gates \
+  --test-cmd "npm test" --definition-of-done rbac-dod.md
+
+# Cost-conscious: quality gates only, no extra agent
+shipwright loop "Migrate DB schema" --quality-gates --test-cmd "npm run db:test"
+
+# Maximum rigor: all checks enabled
+shipwright loop "PCI compliance updates" --audit-agent --quality-gates \
+  --test-cmd "npm test && npm run lint && npm run typecheck" \
+  --definition-of-done pci-dod.md --max-iterations 15
+```
+
+---
+
+## Anti-Patterns
+
+| Don't | Why |
+|-------|-----|
+| Use `--audit-agent` for trivial tasks | 2x cost for a one-file fix is wasteful |
+| Write a 30-item DoD | The agent loses focus. Keep it under 15 items |
+| Skip `--test-cmd` with `--quality-gates` | Quality gates with no test command does nothing useful |
+| Set `--max-iterations 1` with `--audit` | The audit has nowhere to send feedback if there's only one iteration |
+| Rely solely on `--audit` for critical work | Self-reflection catches ~60% of issues. Add `--quality-gates` for the rest |