shipwright-cli 1.7.0

package/claude-code/CLAUDE.md.shipwright

@@ -0,0 +1,125 @@
+# Shipwright — Agent Instructions
+
+This project uses [Shipwright](https://github.com/sethdford/shipwright) for autonomous Claude Code agent teams.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `shipwright pipeline start --issue <N>` | Run full delivery pipeline for an issue |
+| `shipwright pipeline start --issue <N> --worktree` | Pipeline in isolated git worktree (parallel-safe) |
+| `shipwright pipeline start --goal "..." --worktree=name` | Pipeline with named worktree |
+| `shipwright session <name> --template <tpl>` | Create a team session with agent panes |
+| `shipwright daemon start` | Watch repo for labeled issues, auto-process |
+| `shipwright fleet start` | Orchestrate daemons across multiple repos |
+| `shipwright fix "<goal>" --repos <paths>` | Apply the same fix across repos in parallel |
+| `shipwright prep` | Analyze repo and generate preparation report |
+| `shipwright loop` | Continuous improvement loop |
+| `shipwright status` | Show team dashboard |
+| `shipwright cost show` | Token usage and spending dashboard |
+| `shipwright cost budget set <amount>` | Set daily budget limit |
+| `shipwright cost remaining-budget` | Check remaining daily budget (used by auto-scaler) |
+| `shipwright memory list` | View captured failure patterns |
+
+## Pipeline Stages
+
+```
+intake → plan → design → build → test → review → compound_quality → pr → deploy → validate → monitor
+```
+
+## Parallel Pipelines
+
+Use `--worktree` to run multiple pipelines concurrently on the same repo:
+
+```bash
+# Each runs in its own git worktree — no conflicts
+shipwright pipeline start --issue 42 --worktree
+shipwright pipeline start --issue 43 --worktree
+shipwright pipeline start --goal "Refactor auth" --worktree=auth-refactor
+```
+
+The daemon uses worktrees automatically. Use `--worktree` for ad-hoc parallel runs.
+
+## Auto-Scaling (Daemon)
+
+The daemon can dynamically adjust worker count based on system resources:
+
+```json
+{
+  "auto_scale": true,
+  "auto_scale_interval": 5,
+  "max_workers": 8,
+  "min_workers": 1,
+  "worker_mem_gb": 4,
+  "estimated_cost_per_job_usd": 5.0
+}
+```
+
+Scaling factors (takes the minimum):
+- **CPU**: 75% of cores (e.g., 8-core → max 6 workers)
+- **Memory**: available GB / `worker_mem_gb`
+- **Budget**: remaining daily budget / `estimated_cost_per_job_usd`
+- **Queue**: current demand (active + queued issues)
+
+## Fleet Worker Pool
+
+Distribute a total worker budget across repos proportionally to demand:
+
+```json
+{
+  "worker_pool": {
+    "enabled": true,
+    "total_workers": 12,
+    "rebalance_interval_seconds": 120
+  }
+}
+```
+
+When enabled, the fleet rebalancer runs in the background and redistributes workers every N seconds. Repos with more queued issues get more workers. Each repo always gets at least 1 worker.
+
+## tmux Conventions
+
+- Team windows are named `claude-<team-name>` (get the lambda icon in the status bar)
+- Pane titles: `<team>-<role>` (visible in pane borders)
+- Set pane title: `printf '\033]2;agent-name\033\\'`
+- Prefix key: **Ctrl-a**
+- Layouts: `prefix + M-1` (horizontal), `M-2` (vertical), `M-3` (tiled)
+- Zoom: `prefix + G` (toggle focus on one pane)
+- Capture output: `prefix + M-s` (current pane), `prefix + M-a` (all panes)
+
+## Team Patterns
+
+- Assign each agent **different files** to avoid merge conflicts
+- Use `--worktree` for file isolation between agents
+- Keep tasks self-contained (5-6 focused tasks per agent)
+- Use the task list for coordination, not direct messaging
+
+## Memory System
+
+Failure patterns are automatically captured after each pipeline run and injected into future builds. Agents receive relevant context from previous runs — fixes, root causes, and codebase conventions — so they don't repeat mistakes.
+
+## Pipeline Templates
+
+| Template | Use Case |
+|----------|----------|
+| `fast` | Simple changes (score >= 70) — skip review |
+| `standard` | Medium complexity — full pipeline |
+| `full` | Complex changes — extra review cycles |
+| `hotfix` | Urgent fixes — minimal stages |
+| `autonomous` | Daemon-driven — all stages enabled |
+| `cost-aware` | Budget-conscious — model routing by stage |
+
+## Daemon Configuration
+
+Generate with `shipwright daemon init`, then edit `.claude/daemon-config.json`:
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `max_parallel` | `2` | Static worker limit (overridden by auto_scale) |
+| `auto_scale` | `false` | Enable resource-aware dynamic scaling |
+| `max_workers` | `8` | Ceiling for auto-scaler |
+| `min_workers` | `1` | Floor for auto-scaler |
+| `self_optimize` | `false` | Auto-tune based on DORA metrics |
+| `auto_template` | `false` | Pick pipeline template by issue complexity |
+| `max_retries` | `2` | Retry failed pipelines with escalation |
+| `priority_lane` | `false` | Reserve a slot for urgent/hotfix issues |

package/claude-code/hooks/notify-idle.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════════════════
+# notify-idle.sh — Desktop notification when Claude needs your attention
+# ═══════════════════════════════════════════════════════════════════════
+#
+# Works on macOS (osascript) and Linux (notify-send).
+#
+# Install:
+#   1. Copy this file to ~/.claude/hooks/notify-idle.sh
+#   2. chmod +x ~/.claude/hooks/notify-idle.sh
+#   3. Add to ~/.claude/settings.json:
+#      "hooks": {
+#        "Notification": [
+#          {
+#            "hooks": [
+#              {
+#                "type": "command",
+#                "command": "~/.claude/hooks/notify-idle.sh",
+#                "async": true
+#              }
+#            ]
+#          }
+#        ]
+#      }
+# ═══════════════════════════════════════════════════════════════════════
+
+set -euo pipefail
+
+if [[ "$(uname)" == "Darwin" ]]; then
+  osascript -e 'display notification "An agent needs your attention" with title "Claude Code Teams" sound name "Ping"'
+elif command -v notify-send &>/dev/null; then
+  notify-send "Claude Code Teams" "An agent needs your attention" --urgency=normal
+fi
+
+exit 0

package/claude-code/hooks/pre-compact-save.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════════════════
+# pre-compact-save.sh — Save important context before compaction
+# ═══════════════════════════════════════════════════════════════════════
+#
+# Outputs text to stdout that gets injected into Claude's context after
+# compaction. Helps Claude remember project state across compaction events.
+#
+# Install:
+#   1. Copy this file to ~/.claude/hooks/pre-compact-save.sh
+#   2. chmod +x ~/.claude/hooks/pre-compact-save.sh
+#   3. Add to ~/.claude/settings.json:
+#      "hooks": {
+#        "PreCompact": [
+#          {
+#            "matcher": "auto",
+#            "hooks": [
+#              {
+#                "type": "command",
+#                "command": "~/.claude/hooks/pre-compact-save.sh",
+#                "statusMessage": "Saving context before compaction..."
+#              }
+#            ]
+#          }
+#        ]
+#      }
+# ═══════════════════════════════════════════════════════════════════════
+
+set -euo pipefail
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+
+if [[ -n "$CWD" ]] && [[ -d "$CWD" ]]; then
+  cd "$CWD"
+fi
+
+# Remind Claude of project context after compaction
+echo "Post-compaction context refresh:"
+
+# Show recent git activity
+if git rev-parse --is-inside-work-tree &>/dev/null 2>&1; then
+  echo ""
+  echo "Recent commits:"
+  git log --oneline -5 2>/dev/null || true
+  echo ""
+  echo "Current branch: $(git branch --show-current 2>/dev/null || echo 'unknown')"
+  echo "Changed files: $(git diff --name-only 2>/dev/null | head -10 || true)"
+fi
+
+# Show CLAUDE.md reminder if present
+if [[ -f "CLAUDE.md" ]]; then
+  echo ""
+  echo "Project has CLAUDE.md — re-read it for project conventions."
+fi
+
+exit 0

package/claude-code/hooks/task-completed.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════════════════
+# task-completed.sh — Quality gate: block task completion if quality fails
+# ═══════════════════════════════════════════════════════════════════════
+#
+# Runs when a Claude Code agent marks a task as completed. Checks lint
+# and tests on changed files. If any check fails, exit code 2 tells
+# Claude the task isn't really done yet.
+#
+# Install:
+#   1. Copy this file to ~/.claude/hooks/task-completed.sh
+#   2. chmod +x ~/.claude/hooks/task-completed.sh
+#   3. Add to ~/.claude/settings.json:
+#      "hooks": {
+#        "TaskCompleted": [
+#          {
+#            "hooks": [
+#              {
+#                "type": "command",
+#                "command": "~/.claude/hooks/task-completed.sh",
+#                "timeout": 60
+#              }
+#            ]
+#          }
+#        ]
+#      }
+#
+# Exit codes:
+#   0 = allow completion (all checks passed)
+#   2 = block completion (fix issues first)
+# ═══════════════════════════════════════════════════════════════════════
+
+set -euo pipefail
+
+# Read hook input (JSON on stdin) — contains session_id, cwd, etc.
+INPUT=$(cat)
+HOOK_CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+if [[ -n "$HOOK_CWD" ]]; then
+  cd "$HOOK_CWD"
+fi
+
+FAILED=0
+
+# Find the project root (walk up from cwd looking for package.json)
+find_project_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+PROJECT_ROOT="$(find_project_root)" || {
+  # No package.json found — not a JS/TS project, allow completion
+  exit 0
+}
+
+cd "$PROJECT_ROOT"
+
+# ─── Step 1: Lint changed files ──────────────────────────────────────
+
+# Get files changed relative to HEAD (staged + unstaged)
+CHANGED_FILES=$(git diff --name-only HEAD 2>/dev/null || true)
+if [[ -z "$CHANGED_FILES" ]]; then
+  # Also check staged files not yet committed
+  CHANGED_FILES=$(git diff --cached --name-only 2>/dev/null || true)
+fi
+
+# Filter to lintable files (ts, tsx, js, jsx)
+LINT_FILES=$(echo "$CHANGED_FILES" | grep -E '\.(ts|tsx|js|jsx)$' || true)
+
+if [[ -n "$LINT_FILES" ]]; then
+  echo "Linting $(echo "$LINT_FILES" | wc -l | tr -d ' ') changed file(s)..."
+
+  # Build file list as arguments (handle spaces in filenames)
+  LINT_ARGS=()
+  while IFS= read -r file; do
+    [[ -f "$file" ]] && LINT_ARGS+=("$file")
+  done <<< "$LINT_FILES"
+
+  if [[ ${#LINT_ARGS[@]} -gt 0 ]]; then
+    if command -v pnpm &>/dev/null && [[ -f "pnpm-lock.yaml" ]]; then
+      pnpm eslint --no-error-on-unmatched-pattern "${LINT_ARGS[@]}" 2>&1 || {
+        echo "::error::Lint errors in changed files."
+        FAILED=1
+      }
+    elif npx --no-install eslint --version &>/dev/null 2>&1; then
+      npx eslint --no-error-on-unmatched-pattern "${LINT_ARGS[@]}" 2>&1 || {
+        echo "::error::Lint errors in changed files."
+        FAILED=1
+      }
+    else
+      echo "ESLint not available — skipping lint check."
+    fi
+  fi
+else
+  echo "No lintable files changed — skipping lint."
+fi
+
+# ─── Step 2: Run related tests ───────────────────────────────────────
+
+# Find test files related to changed source files
+TEST_FILES=()
+while IFS= read -r file; do
+  [[ -z "$file" ]] && continue
+
+  # Skip if file is itself a test
+  if [[ "$file" =~ \.(test|spec)\.(ts|tsx|js|jsx)$ ]]; then
+    [[ -f "$file" ]] && TEST_FILES+=("$file")
+    continue
+  fi
+
+  # Look for corresponding test file
+  base="${file%.*}"
+  ext="${file##*.}"
+  for pattern in "${base}.test.${ext}" "${base}.spec.${ext}"; do
+    [[ -f "$pattern" ]] && TEST_FILES+=("$pattern")
+  done
+
+  # Also check __tests__ directory
+  dir="$(dirname "$file")"
+  name="$(basename "$file")"
+  namebase="${name%.*}"
+  for pattern in "${dir}/__tests__/${namebase}.test.${ext}" "${dir}/__tests__/${namebase}.spec.${ext}"; do
+    [[ -f "$pattern" ]] && TEST_FILES+=("$pattern")
+  done
+done <<< "$CHANGED_FILES"
+
+if [[ ${#TEST_FILES[@]} -gt 0 ]]; then
+  # Deduplicate
+  readarray -t TEST_FILES < <(printf '%s\n' "${TEST_FILES[@]}" | sort -u)
+
+  echo "Running ${#TEST_FILES[@]} related test file(s)..."
+
+  if command -v pnpm &>/dev/null && [[ -f "pnpm-lock.yaml" ]]; then
+    pnpm vitest run --reporter=verbose "${TEST_FILES[@]}" 2>&1 || {
+      echo "::error::Tests failed for changed files."
+      FAILED=1
+    }
+  elif npx --no-install vitest --version &>/dev/null 2>&1; then
+    npx vitest run --reporter=verbose "${TEST_FILES[@]}" 2>&1 || {
+      echo "::error::Tests failed for changed files."
+      FAILED=1
+    }
+  elif npx --no-install jest --version &>/dev/null 2>&1; then
+    npx jest --bail "${TEST_FILES[@]}" 2>&1 || {
+      echo "::error::Tests failed for changed files."
+      FAILED=1
+    }
+  else
+    echo "No test runner (vitest/jest) available — skipping tests."
+  fi
+else
+  echo "No related test files found — skipping tests."
+fi
+
+# ─── Result ───────────────────────────────────────────────────────────
+
+if [[ "$FAILED" -ne 0 ]]; then
+  echo ""
+  echo "Task completion blocked — fix the issues above first."
+  exit 2
+fi
+
+echo "All quality checks passed."
+exit 0

package/claude-code/hooks/teammate-idle.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════════════════
+# teammate-idle.sh — Quality gate: block idle if typecheck fails
+# ═══════════════════════════════════════════════════════════════════════
+#
+# Runs when a Claude Code teammate goes idle. If there are TypeScript
+# errors, exit code 2 tells Claude to keep working and fix them first.
+#
+# Install:
+#   1. Copy this file to ~/.claude/hooks/teammate-idle.sh
+#   2. chmod +x ~/.claude/hooks/teammate-idle.sh
+#   3. Add to ~/.claude/settings.json:
+#      "hooks": {
+#        "teammate-idle": {
+#          "command": "~/.claude/hooks/teammate-idle.sh",
+#          "timeout": 30000
+#        }
+#      }
+#
+# Exit codes:
+#   0 = allow idle (typecheck passed)
+#   2 = keep working (typecheck failed — fix errors first)
+# ═══════════════════════════════════════════════════════════════════════
+
+set -euo pipefail
+
+# Find the project root (walk up from cwd looking for package.json)
+find_project_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+PROJECT_ROOT="$(find_project_root)" || {
+  # No package.json found — not a TypeScript project, allow idle
+  exit 0
+}
+
+cd "$PROJECT_ROOT"
+
+# Check if this project uses TypeScript
+if [[ ! -f "tsconfig.json" ]]; then
+  exit 0
+fi
+
+# Run typecheck — try pnpm first, fall back to npx
+if command -v pnpm &>/dev/null && [[ -f "pnpm-lock.yaml" ]]; then
+  pnpm typecheck 2>&1 || {
+    echo "::error::TypeScript errors found. Fix them before going idle."
+    exit 2
+  }
+elif command -v npm &>/dev/null; then
+  npx tsc --noEmit 2>&1 || {
+    echo "::error::TypeScript errors found. Fix them before going idle."
+    exit 2
+  }
+else
+  # No package manager available — skip check, allow idle
+  exit 0
+fi
+
+exit 0

package/claude-code/settings.json.template

@@ -0,0 +1,184 @@
+{
+  // ═══════════════════════════════════════════════════════════════════════
+  // Claude Code Settings — Agent Teams + tmux Configuration
+  // ═══════════════════════════════════════════════════════════════════════
+  //
+  // Copy this to ~/.claude/settings.json and customize for your project.
+  //
+  // NOTE: Standard JSON does not support comments. This file uses JSONC
+  // (JSON with Comments) syntax for documentation purposes. Before using
+  // as your actual settings.json, either:
+  //   1. Use an editor that supports JSONC (VS Code, Zed, etc.)
+  //   2. Strip comments: sed '/^\s*\/\//d' settings.json.template > settings.json
+  //
+  // Docs: https://docs.anthropic.com/en/docs/claude-code/settings
+
+  // ─── Teammate Mode ────────────────────────────────────────────────────
+  // Agent teams auto-detect tmux: when you launch Claude Code inside a
+  // tmux session, teammates automatically get their own split panes.
+  // No explicit setting needed — just run inside tmux!
+  //
+  // TIP: Use `new-window` (not `split-window`) when spawning 4+ agents
+  // to avoid the tmux send-keys race condition. See KNOWN-ISSUES.md.
+
+  // ─── Hooks ─────────────────────────────────────────────────────────────
+  // Shell commands that run on lifecycle events.
+  // See claude-code/hooks/ for the scripts referenced below.
+  // Docs: https://code.claude.com/docs/en/hooks-guide
+  //
+  // Event reference:
+  //   TeammateIdle   — when an agent teammate is about to go idle
+  //   TaskCompleted  — when a task is being marked as completed
+  //   Notification   — when Claude needs your attention
+  //   Stop           — when Claude finishes responding
+  //   PreCompact     — before context window compaction
+  //   PostToolUse    — after a tool call succeeds (e.g., auto-format)
+  //   SessionStart   — when a session begins or resumes
+  //
+  // Exit codes: 0 = allow, 2 = block action (agent gets feedback to fix)
+  "hooks": {
+    // Quality gate: block idle if typecheck fails
+    "TeammateIdle": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/teammate-idle.sh",
+            "timeout": 30,
+            "statusMessage": "Running typecheck before idle..."
+          }
+        ]
+      }
+    ],
+    // Quality gate: block task completion if lint/tests fail
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/task-completed.sh",
+            "timeout": 60,
+            "statusMessage": "Running quality checks..."
+          }
+        ]
+      }
+    ],
+    // Desktop notification when Claude needs attention
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/notify-idle.sh",
+            "async": true
+          }
+        ]
+      }
+    ],
+    // Save context before compaction
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/pre-compact-save.sh",
+            "statusMessage": "Saving context before compaction..."
+          }
+        ]
+      }
+    ],
+    // Auto-format files after Claude edits them
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  },
+
+  // ─── Status Line ──────────────────────────────────────────────────────
+  // Custom status line shown at the bottom of Claude Code.
+  //   "type": "command" — runs a shell script and displays its stdout
+  //   "type": "static"  — shows fixed text
+  //
+  // Uncomment to enable:
+  // "statusLine": {
+  //   "type": "command",
+  //   "command": "echo \"$(git branch --show-current) | $(date +%H:%M)\""
+  // },
+
+  // ─── Plugins ──────────────────────────────────────────────────────────
+  // Enable/disable official and community plugins.
+  // Browse available plugins: claude plugins list
+  "enabledPlugins": {
+    // Code quality & review
+    "typescript-lsp@claude-plugins-official": true,
+    "feature-dev@claude-plugins-official": true,
+    "code-review@claude-plugins-official": true,
+    "pr-review-toolkit@claude-plugins-official": true,
+    "commit-commands@claude-plugins-official": true,
+
+    // Integrations — enable the ones you use
+    "github@claude-plugins-official": true,
+    "linear@claude-plugins-official": false,
+    "firebase@claude-plugins-official": false,
+    "slack@claude-plugins-official": false,
+
+    // Documentation & context
+    "context7@claude-plugins-official": true,
+    "frontend-design@claude-plugins-official": false,
+
+    // Workflow & output styles
+    "hookify@claude-plugins-official": true,
+    "learning-output-style@claude-plugins-official": false,
+    "explanatory-output-style@claude-plugins-official": false
+  },
+
+  // ─── Extended Thinking ────────────────────────────────────────────────
+  // When true, Claude thinks through complex problems step-by-step.
+  // Recommended for agent teams doing multi-file coordinated work.
+  "alwaysThinkingEnabled": true,
+
+  // ─── Environment Variables ────────────────────────────────────────────
+  // These env vars configure Claude Code's runtime behavior.
+  "env": {
+    // REQUIRED: Enable agent teams feature
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
+
+    // Performance: max concurrent tool calls per agent (default: 3)
+    // Higher = faster parallel work, but more API usage
+    "CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY": "5",
+
+    // Auto-compact conversation when context usage hits this % (default: 80)
+    // Lower = more aggressive compaction, less risk of hitting limits
+    "CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE": "70",
+
+    // Use haiku for subagent tasks (cheaper + faster for simple lookups)
+    // Remove to use the same model as the parent agent
+    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
+
+    // Include hidden files (dotfiles) in glob searches
+    "CLAUDE_CODE_GLOB_HIDDEN": "1",
+
+    // Keep bash working directory consistent across tool calls
+    "CLAUDE_CODE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1",
+
+    // Show tool use summaries in output (helpful for debugging agent behavior)
+    "CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES": "1",
+
+    // Show teammate names in messages (makes multi-agent output readable)
+    "CLAUDE_CODE_TST_NAMES_IN_MESSAGES": "1",
+
+    // Flush output eagerly (better for streaming, reduces perceived latency)
+    "CLAUDE_CODE_EAGER_FLUSH": "1",
+
+    // Enable prompt suggestions after idle
+    "CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION": "1"
+  }
+}