@paths.design/caws-cli 8.2.3 → 9.0.0

package/templates/.claude/hooks/session-caws-status.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# CAWS Session Status Hook for Claude Code
+# Reports project state at session start with worktree warnings
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read stdin (required by hook protocol)
+INPUT=$(cat)
+
+# Only run for session-start events
+EVENT_TYPE="${1:-}"
+if [ "$EVENT_TYPE" != "session-start" ]; then
+  exit 0
+fi
+
+# Check if this is a CAWS project
+if [ ! -d "${CLAUDE_PROJECT_DIR:-.}/.caws" ]; then
+  exit 0
+fi
+
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+# --- Resolve main repo root ---
+CAWS_ROOT="."
+if command -v git >/dev/null 2>&1; then
+  _GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null || echo ".git")
+  if [ "$_GIT_COMMON" != ".git" ]; then
+    _CANDIDATE=$(cd "$_GIT_COMMON/.." 2>/dev/null && pwd || echo "")
+    if [ -n "$_CANDIDATE" ] && [ -d "$_CANDIDATE/.caws" ]; then
+      CAWS_ROOT="$_CANDIDATE"
+    fi
+  fi
+fi
+
+# --- Active worktree warning ---
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+  WT_INFO=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$CAWS_ROOT/.caws/worktrees.json', 'utf8'));
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      if (active.length > 0) {
+        var names = active.map(function(w) { return w.name + ' (' + w.branch + ')'; });
+        console.log(active.length + ':' + names.join(', '));
+      } else {
+        console.log('0:');
+      }
+    } catch(e) { console.log('0:'); }
+  " 2>/dev/null || echo "0:")
+
+  WT_COUNT=$(echo "$WT_INFO" | cut -d: -f1)
+  WT_NAMES=$(echo "$WT_INFO" | cut -d: -f2)
+
+  if [ "$WT_COUNT" -gt 0 ] 2>/dev/null; then
+    # Check if the agent is already in a worktree (not on the base branch)
+    BASE_BRANCH=$(node -e "
+      try {
+        var reg = JSON.parse(require('fs').readFileSync('$CAWS_ROOT/.caws/worktrees.json', 'utf8'));
+        var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+        if (active.length > 0) console.log(active[0].baseBranch || '');
+        else console.log('');
+      } catch(e) { console.log(''); }
+    " 2>/dev/null || echo "")
+
+    echo ""
+    echo "================================================================"
+    echo "  ACTIVE WORKTREES DETECTED: $WT_COUNT worktree(s)"
+    echo "  $WT_NAMES"
+    echo "================================================================"
+
+    if [ -n "$BASE_BRANCH" ] && [ "$CURRENT_BRANCH" = "$BASE_BRANCH" ]; then
+      echo ""
+      echo "  You MUST work in a worktree, not on $CURRENT_BRANCH."
+      echo ""
+      echo "  If a worktree was created for your task:"
+      echo "    cd $CAWS_ROOT/.caws/worktrees/<name>/"
+      echo ""
+      echo "  If you need a new worktree:"
+      echo "    caws worktree create <name>"
+      echo ""
+      echo "  The only operations allowed on $CURRENT_BRANCH are:"
+      echo "    - git merge --no-ff <branch> (merge completed worktree work)"
+      echo "    - Commits with message: merge(worktree): <description>"
+      echo "    - Commits with message: wip(checkpoint): <description>"
+      echo "      (for committing prior-session dirty files)"
+      echo ""
+      echo "  Writing or editing files on $CURRENT_BRANCH will be BLOCKED"
+      echo "  by the PreToolUse hook while worktrees are active."
+    else
+      echo ""
+      echo "  You are on branch '$CURRENT_BRANCH' (worktree). Good."
+      echo "  Other active worktrees: $WT_NAMES"
+    fi
+    echo "================================================================"
+    echo ""
+  fi
+fi
+
+# Use caws session briefing for structured output
+if command -v caws &>/dev/null; then
+  caws session briefing 2>/dev/null || {
+    echo "--- CAWS Session Briefing (fallback) ---"
+    HEAD_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+    BRANCH=$(git branch --show-current 2>/dev/null || echo "detached")
+    DIRTY_COUNT=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    echo "Git: ${BRANCH} @ ${HEAD_SHA} (${DIRTY_COUNT} dirty files)"
+    if [ "$DIRTY_COUNT" -gt 0 ]; then
+      echo "WARNING: Working tree has uncommitted changes from a prior session."
+      echo "Classify and commit or stash them before starting new work."
+    fi
+    echo "--- End CAWS Briefing ---"
+  }
+fi
+
+exit 0

package/templates/.claude/hooks/stop-worktree-check.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# CAWS Worktree Cleanup Reminder for Claude Code
+# Warns at session end if active worktrees remain
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code (required by hook protocol)
+INPUT=$(cat)
+
+# Resolve main repo root
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+if command -v git >/dev/null 2>&1; then
+  GIT_COMMON_DIR=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
+  if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != ".git" ]]; then
+    CANDIDATE=$(cd "$PROJECT_DIR" && cd "$GIT_COMMON_DIR/.." 2>/dev/null && pwd || echo "")
+    if [[ -n "$CANDIDATE" ]] && [[ -d "$CANDIDATE/.caws" ]]; then
+      PROJECT_DIR="$CANDIDATE"
+    fi
+  fi
+fi
+
+# Check for active worktrees
+if [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>&1; then
+  ACTIVE_INFO=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      if (active.length > 0) {
+        console.log(active.length + ':' + active.map(function(w) { return w.name; }).join(', '));
+      } else {
+        console.log('0:');
+      }
+    } catch(e) { console.log('0:'); }
+  " 2>/dev/null || echo "0:")
+
+  COUNT=$(echo "$ACTIVE_INFO" | cut -d: -f1)
+  NAMES=$(echo "$ACTIVE_INFO" | cut -d: -f2)
+
+  if [[ "$COUNT" -gt 0 ]] 2>/dev/null; then
+    echo "REMINDER: $COUNT active worktree(s) remain: $NAMES. Other agents cannot commit to the base branch until all worktrees are destroyed. If your work is complete, run: caws worktree destroy <name> --delete-branch" >&2
+    exit 0
+  fi
+fi
+
+exit 0

package/templates/.claude/hooks/worktree-guard.sh

@@ -0,0 +1,207 @@
+#!/bin/bash
+# CAWS Worktree Safety Guard for Claude Code
+# Blocks dangerous operations when parallel worktrees are active
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract tool info
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+
+# Only check Bash tool
+if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# --- Resolve main repo root ---
+# When running inside a worktree, CLAUDE_PROJECT_DIR points to the
+# worktree directory, but .caws/worktrees.json only exists in the main
+# repo. Use git's common dir to find the true repo root.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+if command -v git >/dev/null 2>&1; then
+  GIT_COMMON_DIR=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
+  if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != ".git" ]]; then
+    # Inside a worktree: --git-common-dir returns the main repo's .git path
+    # (e.g., /path/to/repo/.git or /path/to/repo/.git/worktrees/<name>/..)
+    CANDIDATE=$(cd "$PROJECT_DIR" && cd "$GIT_COMMON_DIR/.." 2>/dev/null && pwd || echo "")
+    if [[ -n "$CANDIDATE" ]] && [[ -d "$CANDIDATE/.caws" ]]; then
+      PROJECT_DIR="$CANDIDATE"
+    fi
+  fi
+fi
+
+# --- Gap 2: Block sparse checkout before the git-only filter ---
+# This must run before the "only check git commands" early-exit
+if echo "$COMMAND" | grep -qE 'caws\s+(worktree\s+create|parallel\s+setup).*--scope'; then
+  echo "BLOCKED: --scope (sparse checkout) is not allowed." >&2
+  echo "Sparse checkout breaks cross-module imports in most projects." >&2
+  echo "Use full worktrees without --scope. Scope enforcement comes from" >&2
+  echo "CAWS feature specs and lane discipline, not from hiding files." >&2
+  exit 2
+fi
+
+# --- Gap 5: Block cross-boundary file copies ---
+WORKTREE_BASE="$PROJECT_DIR/.caws/worktrees"
+if [[ -d "$WORKTREE_BASE" ]]; then
+  if echo "$COMMAND" | grep -qE '\b(cp|mv)\b'; then
+    if echo "$COMMAND" | grep -qF ".caws/worktrees/" || echo "$COMMAND" | grep -qF "$WORKTREE_BASE"; then
+      # Check if the command references both a worktree path and the main repo
+      HAS_WT_PATH=false
+      HAS_MAIN_PATH=false
+      if echo "$COMMAND" | grep -qE '\.caws/worktrees/|'"$(echo "$WORKTREE_BASE" | sed 's/[\/&]/\\&/g')"''; then
+        HAS_WT_PATH=true
+      fi
+      # Check if destination/source is outside the worktree
+      if echo "$COMMAND" | grep -qE "(^|\s)$PROJECT_DIR/[^.]|core/|src/|tests/|packages/" && [[ "$HAS_WT_PATH" == "true" ]]; then
+        HAS_MAIN_PATH=true
+      fi
+      if [[ "$HAS_WT_PATH" == "true" ]] && [[ "$HAS_MAIN_PATH" == "true" ]]; then
+        echo "BLOCKED: Copying files between a worktree and the main repo is forbidden." >&2
+        echo "This bypasses worktree isolation. Work entirely within your worktree." >&2
+        echo "If tests need the main repo's venv, activate it with:" >&2
+        echo "  source $PROJECT_DIR/.venv/bin/activate" >&2
+        exit 2
+      fi
+    fi
+  fi
+fi
+
+# Only check git commands from here on
+if ! echo "$COMMAND" | grep -qE '(^|\s|&&|\|)git\s'; then
+  exit 0
+fi
+
+# --- Determine if worktrees are active ---
+WORKTREES_ACTIVE=false
+PARALLEL_BASE=""
+
+# Check .caws/parallel.json
+if [[ -f "$PROJECT_DIR/.caws/parallel.json" ]] && command -v node >/dev/null 2>&1; then
+  PARALLEL_INFO=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/parallel.json', 'utf8'));
+      var agents = (reg.agents || []).length;
+      console.log(agents + ':' + (reg.baseBranch || ''));
+    } catch(e) { console.log('0:'); }
+  " 2>/dev/null || echo "0:")
+
+  AGENT_COUNT=$(echo "$PARALLEL_INFO" | cut -d: -f1)
+  PARALLEL_BASE=$(echo "$PARALLEL_INFO" | cut -d: -f2)
+
+  if [[ "$AGENT_COUNT" -gt 0 ]] 2>/dev/null; then
+    WORKTREES_ACTIVE=true
+  fi
+fi
+
+# Check .caws/worktrees.json
+if [[ "$WORKTREES_ACTIVE" != "true" ]] && [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>&1; then
+  ACTIVE_COUNT=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      console.log(active.length);
+    } catch(e) { console.log('0'); }
+  " 2>/dev/null || echo "0")
+
+  if [[ "$ACTIVE_COUNT" -gt 0 ]] 2>/dev/null; then
+    WORKTREES_ACTIVE=true
+  fi
+fi
+
+# If no worktrees are active, allow everything
+if [[ "$WORKTREES_ACTIVE" != "true" ]]; then
+  exit 0
+fi
+
+# --- Block dangerous git operations when worktrees are active ---
+
+# Block git commit --amend
+if echo "$COMMAND" | grep -qE 'git\s+commit\s+.*--amend'; then
+  echo "BLOCKED: git commit --amend is not allowed while worktrees are active." >&2
+  echo "Amending commits risks rewriting another agent's work." >&2
+  echo "Create a new commit instead." >&2
+  exit 2
+fi
+
+# Block git stash (shared across worktrees)
+if echo "$COMMAND" | grep -qE 'git\s+stash' && ! echo "$COMMAND" | grep -qE 'git\s+stash\s+list'; then
+  echo "BLOCKED: git stash is not allowed while worktrees are active." >&2
+  echo "Stash is shared across all worktrees and can capture or destroy another agent's work." >&2
+  echo "Commit your changes to your branch instead." >&2
+  exit 2
+fi
+
+# Block git reset --hard
+if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+  echo "BLOCKED: git reset --hard is not allowed while worktrees are active." >&2
+  echo "This could discard work that other agents depend on." >&2
+  exit 2
+fi
+
+# Block git push --force
+if echo "$COMMAND" | grep -qE 'git\s+push\s+.*(--force|-f\s)'; then
+  echo "BLOCKED: Force push is not allowed while worktrees are active." >&2
+  echo "This could rewrite history that other agents have based work on." >&2
+  exit 2
+fi
+
+# --- Base branch protections ---
+# Use the agent's actual working directory (CLAUDE_PROJECT_DIR), not the resolved
+# main repo root (PROJECT_DIR). In a worktree, PROJECT_DIR points to the main repo
+# (to find .caws/worktrees.json), but the agent's branch is in CLAUDE_PROJECT_DIR.
+AGENT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+# Determine the base branch to protect
+BASE_BRANCH="$PARALLEL_BASE"
+if [[ -z "$BASE_BRANCH" ]] && [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>&1; then
+  BASE_BRANCH=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      if (active.length > 0) console.log(active[0].baseBranch || '');
+      else console.log('');
+    } catch(e) { console.log(''); }
+  " 2>/dev/null || echo "")
+fi
+
+if [[ -n "$BASE_BRANCH" ]] && [[ "$CURRENT_BRANCH" == "$BASE_BRANCH" ]]; then
+  # Block push from base branch
+  if echo "$COMMAND" | grep -qE 'git\s+push'; then
+    echo "BLOCKED: Pushing from the base branch ($BASE_BRANCH) while worktrees are active." >&2
+    echo "You should be working in a worktree, not on the base branch." >&2
+    echo "Use: cd .caws/worktrees/<name>/" >&2
+    exit 2
+  fi
+
+  # Allow git merge into base branch (merging completed worktree branches back)
+  # The commit-msg hook enforces the merge(worktree): message format
+  if echo "$COMMAND" | grep -qE 'git\s+merge\b'; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "Merging into base branch ('"$BASE_BRANCH"') while worktrees are active. The commit-msg hook will enforce the merge(worktree): message format. Make sure the worktree for this branch has been destroyed first."
+      }
+    }'
+    exit 0
+  fi
+
+  # Warn (but don't block) commits on base branch — the pre-commit + commit-msg hooks handle blocking
+  if echo "$COMMAND" | grep -qE 'git\s+commit\b' && ! echo "$COMMAND" | grep -qE '--amend'; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "WARNING: You are committing to the base branch ('"$BASE_BRANCH"') while worktrees are active. Only merge commits with the format merge(worktree): <description> are allowed. The pre-commit hook will block direct commits."
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# Allow the command
+exit 0

package/templates/.claude/hooks/worktree-write-guard.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# CAWS Worktree Write Guard for Claude Code
+# Blocks Write/Edit on the base branch while worktrees are active.
+# This prevents agents from modifying files on main and then trying to
+# create worktrees retroactively to commit them.
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract tool info
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only check Write and Edit tools
+case "$TOOL_NAME" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+# --- Resolve main repo root ---
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+if command -v git >/dev/null 2>&1; then
+  GIT_COMMON_DIR=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
+  if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != ".git" ]]; then
+    CANDIDATE=$(cd "$PROJECT_DIR" && cd "$GIT_COMMON_DIR/.." 2>/dev/null && pwd || echo "")
+    if [[ -n "$CANDIDATE" ]] && [[ -d "$CANDIDATE/.caws" ]]; then
+      PROJECT_DIR="$CANDIDATE"
+    fi
+  fi
+fi
+
+# --- Check for active worktrees ---
+if [[ ! -f "$PROJECT_DIR/.caws/worktrees.json" ]]; then
+  exit 0
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Use the agent's actual working directory, not the resolved main repo root.
+# In a worktree, PROJECT_DIR points to the main repo (to find .caws/worktrees.json),
+# but the agent's branch is in CLAUDE_PROJECT_DIR.
+AGENT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+WT_INFO=$(node -e "
+  try {
+    var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+    var active = Object.values(reg.worktrees || {}).filter(function(w) {
+      return w.status === 'active' && w.baseBranch === '$CURRENT_BRANCH';
+    });
+    console.log(active.length + ':' + active.map(function(w) { return w.name; }).join(', '));
+  } catch(e) { console.log('0:'); }
+" 2>/dev/null || echo "0:")
+
+WT_COUNT=$(echo "$WT_INFO" | cut -d: -f1)
+WT_NAMES=$(echo "$WT_INFO" | cut -d: -f2)
+
+if [[ "$WT_COUNT" -le 0 ]] 2>/dev/null; then
+  exit 0
+fi
+
+# Allow edits to .claude/ configuration (hooks, settings, rules)
+if [[ -n "$FILE_PATH" ]]; then
+  case "$FILE_PATH" in
+    */.claude/*|*/.caws/*) exit 0 ;;
+  esac
+fi
+
+# Block: we're on the base branch with active worktrees
+echo "BLOCKED: Cannot write/edit files on '$CURRENT_BRANCH' while $WT_COUNT worktree(s) are active: $WT_NAMES" >&2
+echo "" >&2
+echo "You MUST work in a worktree, not on the base branch." >&2
+echo "  To use an existing worktree: cd $PROJECT_DIR/.caws/worktrees/<name>/" >&2
+echo "  To create a new worktree:    caws worktree create <name>" >&2
+echo "" >&2
+echo "Do NOT make changes on main and create a worktree retroactively." >&2
+echo "The worktree must exist BEFORE you start making changes." >&2
+exit 2

package/templates/.claude/rules/git-safety.md

@@ -0,0 +1,26 @@
+---
+description: Git safety rules for all agents
+globs:
+---
+
+# Git Safety
+
+## Commit discipline
+
+- Commit after each logical unit of work (a module + its tests, a bugfix, a refactor pass)
+- Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`, `perf:`
+- Never accumulate uncommitted changes across multiple unrelated concerns
+- Never leave uncommitted changes at session end; commit as `wip(<scope>): <description>` if incomplete
+
+## Forbidden operations
+
+- `git push --force` or `git push -f` -- never rewrite remote history
+- `git reset --hard` -- use `git stash` or `git checkout -- <file>` for targeted reverts (but not during parallel work)
+- `git clean -f` -- may delete another agent's untracked files
+- `git checkout .` or `git restore .` -- bulk discard is dangerous
+
+## Branch hygiene
+
+- Work on feature branches, not directly on main/master
+- One concern per branch
+- Delete branches after merging

package/templates/.claude/rules/worktree-isolation.md

@@ -0,0 +1,51 @@
+---
+description: Rules for safe multi-agent git worktree isolation
+globs:
+---
+
+# Multi-Agent Worktree Safety
+
+When multiple agents are working on this project, each agent MUST work in its own git worktree. Never have two agents committing to the same branch.
+
+## Before starting work
+
+1. Check if worktrees exist: look for `.caws/worktrees.json` or `.caws/parallel.json`
+2. If worktrees are active and you are on the base branch, switch to your assigned worktree
+3. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
+
+## Forbidden operations when worktrees are active
+
+- `git commit --amend` -- rewrites history that other agents depend on
+- `git stash` / `git stash pop` -- stash is shared across all worktrees; using it can destroy another agent's uncommitted work
+- `git reset --hard` -- discards work that other agents may depend on
+- `git push --force` -- rewrites remote history
+- Direct commits to the base branch -- only `merge(worktree):` and `wip(checkpoint):` formats are allowed
+- Copying files between your worktree and the main repo directory -- defeats isolation
+
+## Merging worktree branches back to base
+
+Merge commits ARE allowed on the base branch while other worktrees are active. This lets you incrementally merge completed work without waiting for all agents to finish.
+
+1. Destroy the worktree first: `caws worktree destroy <name>`
+2. Switch to the base branch: `git checkout main`
+3. Merge with: `git merge --no-ff <worktree-branch>`
+4. The commit-msg hook enforces the `merge(worktree): <description>` format for non-FF merges
+5. For manual merge commits: `git commit -m "merge(worktree): integrate scenarios work"`
+
+## Virtual environment in worktrees
+
+Do NOT create a new virtual environment in your worktree. Use the main repo's venv:
+
+```bash
+source <main-repo-path>/.venv/bin/activate
+```
+
+If your project uses `.caws/scope.json`, the `designatedVenvPath` field specifies the correct venv location.
+
+## When your work is done
+
+1. Commit all changes to your worktree branch
+2. Run tests in your worktree to verify
+3. Destroy your worktree with `caws worktree destroy <name>`
+4. Merge your branch to base: `git merge --no-ff <branch>` (uses `merge(worktree):` format)
+5. Delete the branch if no longer needed: `git branch -d <branch>`

package/templates/.claude/settings.json

@@ -8,6 +8,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-guard.sh",
+            "timeout": 10
           }
         ]
       },
@@ -24,6 +29,11 @@
       {
         "matcher": "Write|Edit",
         "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-write-guard.sh",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scope-guard.sh",
@@ -87,6 +97,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/audit.sh stop",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-worktree-check.sh",
+            "timeout": 10
           }
         ]
       }