beads-orchestration 2.0.0

package/templates/hooks/clarify-vague-request.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+#
+# UserPromptSubmit: Force clarification on vague requests + epic reminder
+#
+# Uses plain text stdout for context injection (per Claude Code docs)
+#
+
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')
+LENGTH=${#PROMPT}
+
+if [[ $LENGTH -lt 50 ]]; then
+  cat << 'EOF'
+<system-reminder>
+STOP. This request is too short to act on safely.
+
+BEFORE doing anything else, you MUST use the AskUserQuestion tool to clarify:
+- What specific outcome does the user want?
+- What files/components are involved?
+- Are there any constraints or preferences?
+
+Do NOT guess. Do NOT start working. Ask first.
+</system-reminder>
+EOF
+elif [[ $LENGTH -lt 200 ]]; then
+  cat << 'EOF'
+<system-reminder>
+This request may be ambiguous. Consider using AskUserQuestion to clarify before proceeding.
+</system-reminder>
+EOF
+fi
+
+# Always remind about epic workflow
+cat << 'EOF'
+<cross-domain-check>
+CRITICAL: If this task spans multiple supervisors, you MUST create an EPIC.
+Cross-domain = Epic. No exceptions.
+</cross-domain-check>
+EOF

package/templates/hooks/enforce-bead-for-supervisor.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+#
+# PreToolUse:Task - Enforce bead exists before supervisor dispatch
+#
+# All supervisors must have BEAD_ID in prompt.
+# This ensures all work is tracked.
+#
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+[[ "$TOOL_NAME" != "Task" ]] && exit 0
+
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty')
+PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty')
+
+# Only enforce for supervisors
+[[ ! "$SUBAGENT_TYPE" =~ supervisor ]] && exit 0
+
+# Exception: merge-supervisor is exempt from bead requirement
+# Merge conflicts are incidental to other work, not tracked separately
+[[ "$SUBAGENT_TYPE" == "merge-supervisor" ]] && exit 0
+
+# Check for BEAD_ID in prompt
+if [[ "$PROMPT" != *"BEAD_ID:"* ]]; then
+  cat << 'EOF'
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"<bead-required>\nAll supervisor work MUST be tracked with a bead.\n\n<action>\nFor standalone tasks:\n  1. bd create \"Task title\" -d \"Description\"\n  2. Dispatch with: BEAD_ID: {id}\n\nFor epic children:\n  1. bd create \"Epic\" -d \"...\" --type epic\n  2. bd create \"Child\" -d \"...\" --parent {EPIC_ID}\n  3. Dispatch with: BEAD_ID: {child_id}, EPIC_ID: {epic_id}\n</action>\n\nEach task creates its own worktree at .worktrees/bd-{BEAD_ID}/\n</bead-required>"}}
+EOF
+  exit 0
+fi
+
+exit 0

package/templates/hooks/enforce-branch-before-edit.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+#
+# PreToolUse: Block Edit/Write on main branch outside worktrees
+#
+# Supervisors must work in .worktrees/bd-{BEAD_ID}/ directories, not main.
+# This prevents accidental commits to main directory.
+#
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+# Only check Edit and Write tools
+[[ "$TOOL_NAME" != "Edit" ]] && [[ "$TOOL_NAME" != "Write" ]] && exit 0
+
+# Get the file path being edited
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Allow if editing within .worktrees/ directory
+if [[ "$FILE_PATH" == *"/.worktrees/"* ]] || [[ "$FILE_PATH" == *"\.worktrees\"* ]]; then
+  exit 0
+fi
+
+# Get current working directory
+CWD=$(pwd)
+
+# Allow if currently inside a .worktrees/ directory
+if [[ "$CWD" == *"/.worktrees/"* ]] || [[ "$CWD" == *"\.worktrees\"* ]]; then
+  exit 0
+fi
+
+# Check current branch (if we're in a git repo outside worktrees)
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null)
+
+# Block if on main or master (and not in a worktree)
+if [[ "$CURRENT_BRANCH" == "main" ]] || [[ "$CURRENT_BRANCH" == "master" ]]; then
+  cat << EOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Cannot edit files on $CURRENT_BRANCH branch. Supervisors must work in worktrees.
+
+Create a worktree first using the API:
+  POST /api/git/worktree { repo_path, bead_id }
+
+Then cd into .worktrees/bd-{BEAD_ID}/ to make changes."}}
+EOF
+  exit 0
+fi
+
+exit 0

package/templates/hooks/enforce-concise-response.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+#
+# PostToolUse: Enforce concise responses from subagents
+#
+# Subagents should return concise reports (max 10 lines, ~500 chars)
+# This reduces context usage and keeps orchestrator focused.
+#
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+# Only check Task tool responses
+[[ "$TOOL_NAME" != "Task" ]] && exit 0
+
+# Get the tool response
+RESPONSE=$(echo "$INPUT" | jq -r '.tool_result // empty')
+[[ -z "$RESPONSE" ]] && exit 0
+
+# Count lines and characters
+LINE_COUNT=$(echo "$RESPONSE" | wc -l | tr -d ' ')
+CHAR_COUNT=$(echo "$RESPONSE" | wc -c | tr -d ' ')
+
+# Limits
+MAX_LINES=10
+MAX_CHARS=500
+
+# Check limits (warn but don't block - agent already completed)
+if [[ "$LINE_COUNT" -gt "$MAX_LINES" ]] || [[ "$CHAR_COUNT" -gt "$MAX_CHARS" ]]; then
+  # Log warning (PostToolUse can't deny, only add context)
+  cat << EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "warning": "Subagent response exceeded limits (${LINE_COUNT} lines, ${CHAR_COUNT} chars). Target: ${MAX_LINES} lines, ${MAX_CHARS} chars. Consider asking agents for more concise reports."
+  }
+}
+EOF
+  exit 0
+fi
+
+exit 0

package/templates/hooks/enforce-sequential-dispatch.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+#
+# PreToolUse:Task - Enforce sequential dispatch and design doc existence
+#
+# For epic child tasks:
+# 1. Blocks dispatch if task has unresolved blockers
+# 2. Blocks dispatch if epic has design path but file doesn't exist
+#
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+[[ "$TOOL_NAME" != "Task" ]] && exit 0
+
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty')
+PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty')
+
+# Only check for supervisors (not architect, scout, etc.)
+[[ ! "$SUBAGENT_TYPE" =~ supervisor ]] && exit 0
+
+# Worker-supervisor is exempt
+[[ "$SUBAGENT_TYPE" == *"worker"* ]] && exit 0
+
+# Extract BEAD_ID
+BEAD_ID=$(echo "$PROMPT" | grep -oE "BEAD_ID: [A-Za-z0-9._-]+" | head -1 | sed 's/BEAD_ID: //')
+[[ -z "$BEAD_ID" ]] && exit 0
+
+# Block dispatch to closed/done beads - create a new bead instead
+BEAD_STATUS=$(bd show "$BEAD_ID" --json 2>/dev/null | jq -r '.[0].status // empty')
+if [[ "$BEAD_STATUS" == "closed" || "$BEAD_STATUS" == "done" ]]; then
+  cat << EOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"<closed-bead>\nBead ${BEAD_ID} is already ${BEAD_STATUS}. Do not reopen closed beads.\n\nCreate a new bead for follow-up work and relate it:\n\n  bd create \"Fix: [description]\" -d \"Follow-up to ${BEAD_ID}: [details]\"\n  # Returns: {NEW_ID}\n  bd dep relate {NEW_ID} ${BEAD_ID}\n\nThen dispatch with the NEW bead ID.\n</closed-bead>"}}
+EOF
+  exit 0
+fi
+
+# Check if this is an epic child (contains dot)
+if [[ "$BEAD_ID" == *"."* ]]; then
+  # Extract EPIC_ID (everything before last dot)
+  EPIC_ID=$(echo "$BEAD_ID" | sed 's/\.[0-9]*$//')
+
+  # Check for unresolved blockers (exclude parent epic - it's not a real blocker)
+  BLOCKERS=$(bd dep list "$BEAD_ID" --json 2>/dev/null | jq -r --arg epic "$EPIC_ID" '.[] | select(.id != $epic and .status != "done" and .status != "closed") | .id' 2>/dev/null | tr '\n' ', ' | sed 's/,$//')
+
+  if [[ -n "$BLOCKERS" ]]; then
+    cat << EOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"<blocked-task>\nCannot dispatch ${BEAD_ID} - unresolved blockers: ${BLOCKERS}\n\nComplete blocking tasks first, then dispatch this one.\n\nUse: bd ready --json to see tasks with no blockers.\n</blocked-task>"}}
+EOF
+    exit 0
+  fi
+
+  # Check design doc exists (if epic has design field)
+  DESIGN_PATH=$(bd show "$EPIC_ID" --json 2>/dev/null | jq -r '.[0].design // empty')
+
+  if [[ -n "$DESIGN_PATH" ]] && [[ ! -f "$DESIGN_PATH" ]]; then
+    cat << EOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"<design-doc-missing>\nEpic ${EPIC_ID} has design path '${DESIGN_PATH}' but file doesn't exist.\n\n<stop-and-think>\nBefore dispatching architect, verify you fully understand the epic:\n\n1. Are the requirements clear and unambiguous?\n2. Do you know the expected inputs/outputs?\n3. Are there edge cases or constraints to consider?\n4. Do you understand how this integrates with existing code?\n\nIf ANY ambiguity exists -> Use AskUserQuestion to clarify FIRST.\nDo NOT dispatch architect with vague requirements.\n</stop-and-think>\n\n<next-steps>\nIf requirements are CLEAR:\n  Task(\n    subagent_type=\"architect\",\n    prompt=\"Create design doc for EPIC_ID: ${EPIC_ID}\n           Output: ${DESIGN_PATH}\n           \n           [Provide clear, specific requirements]\"\n  )\n\nIf requirements are UNCLEAR:\n  AskUserQuestion(\n    questions=[{\n      \"question\": \"[Your specific clarifying question]\",\n      \"header\": \"Clarify\",\n      \"options\": [...],\n      \"multiSelect\": false\n    }]\n  )\n</next-steps>\n</design-doc-missing>"}}
+EOF
+    exit 0
+  fi
+fi
+
+exit 0

package/templates/hooks/inject-discipline-reminder.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+#
+# PreToolUse: Inject discipline skill reminder for supervisor dispatches
+#
+# When orchestrator dispatches a supervisor via Task(), remind them to
+# invoke the subagents-discipline skill at the start of implementation.
+#
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+# Only check Task tool
+[[ "$TOOL_NAME" != "Task" ]] && exit 0
+
+# Check if dispatching a supervisor
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty')
+
+# Only inject for supervisors (not code-reviewer, architect, etc.)
+if [[ "$SUBAGENT_TYPE" == *"-supervisor"* ]]; then
+  cat << 'EOF'
+<system-reminder>
+SUPERVISOR DISPATCH: Before implementing, invoke `/subagents-discipline` skill.
+This ensures verification-first development with DEMO blocks.
+</system-reminder>
+EOF
+fi
+
+exit 0

package/templates/hooks/log-dispatch-prompt.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+#
+# PostToolUse:Task (async) - Auto-log dispatch prompts to bead comments
+#
+# When orchestrator dispatches a supervisor via Task(), capture the prompt
+# and log it as a DISPATCH comment on the bead. This replaces manual
+# INVESTIGATION logging — the dispatch prompt IS the investigation record.
+#
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+# Only process Task tool
+[[ "$TOOL_NAME" != "Task" ]] && exit 0
+
+# Extract subagent_type
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty')
+
+# Only log supervisor dispatches
+[[ "$SUBAGENT_TYPE" != *"supervisor"* ]] && exit 0
+
+# Extract prompt
+PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty')
+[[ -z "$PROMPT" ]] && exit 0
+
+# Extract BEAD_ID from prompt
+BEAD_ID=$(echo "$PROMPT" | grep -oE 'BEAD_ID: [A-Za-z0-9._-]+' | head -1 | sed 's/BEAD_ID: //')
+[[ -z "$BEAD_ID" ]] && exit 0
+
+# Truncate prompt at 2048 chars
+TRUNCATED_PROMPT=$(echo "$PROMPT" | head -c 2048)
+
+# Log dispatch to bead (fail silently)
+# Prefix: DISPATCH_PROMPT — UI renders as collapsible "Prompt Used" entry
+bd comment "$BEAD_ID" "DISPATCH_PROMPT [$SUBAGENT_TYPE]:
+
+$TRUNCATED_PROMPT" 2>/dev/null || true
+
+exit 0

package/templates/hooks/memory-capture.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+#
+# PostToolUse:Bash (async) - Capture knowledge from bd comment commands
+#
+# Detects: bd comment {BEAD_ID} "LEARNED: ..."
+# Extracts knowledge entries into .beads/memory/knowledge.jsonl
+#
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+# Only process Bash tool
+[[ "$TOOL_NAME" != "Bash" ]] && exit 0
+
+# Extract the command that was executed
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+[[ -z "$COMMAND" ]] && exit 0
+
+# Only process bd comment commands containing knowledge markers
+echo "$COMMAND" | grep -qE 'bd\s+comment\s+' || exit 0
+echo "$COMMAND" | grep -qE 'LEARNED:' || exit 0
+
+# Extract BEAD_ID (argument after "bd comment")
+BEAD_ID=$(echo "$COMMAND" | sed -E 's/.*bd[[:space:]]+comment[[:space:]]+([A-Za-z0-9._-]+)[[:space:]]+.*/\1/')
+[[ -z "$BEAD_ID" || "$BEAD_ID" == "$COMMAND" ]] && exit 0
+
+# Extract the comment body (content inside quotes after bead ID)
+COMMENT_BODY=$(echo "$COMMAND" | sed -E 's/.*bd[[:space:]]+comment[[:space:]]+[A-Za-z0-9._-]+[[:space:]]+["'\'']//' | sed -E 's/["'\''][[:space:]]*$//' | head -c 4096)
+[[ -z "$COMMENT_BODY" ]] && exit 0
+
+# Determine type and extract content (voluntary LEARNED only)
+TYPE=""
+CONTENT=""
+if echo "$COMMENT_BODY" | grep -q "LEARNED:"; then
+  TYPE="learned"
+  CONTENT=$(echo "$COMMENT_BODY" | sed 's/.*LEARNED:[[:space:]]*//' | head -c 2048)
+fi
+
+[[ -z "$TYPE" || -z "$CONTENT" ]] && exit 0
+
+# Generate key from content (type + slugified first 60 chars)
+SLUG=$(echo "$CONTENT" | head -c 60 | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//')
+KEY="${TYPE}-${SLUG}"
+
+# Detect source agent from CWD or transcript context
+SOURCE="orchestrator"
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+if echo "$CWD" | grep -q '\.worktrees/'; then
+  # Inside a worktree = supervisor is running
+  SOURCE="supervisor"
+fi
+
+# Build tags array - start with type tag
+TAGS_ARRAY=("$TYPE")
+
+# Scan content for known tech keywords and add matching tags
+for tag in swift swiftui appkit menubar api security test database \
+           networking ui layout performance crash bug fix workaround \
+           gotcha pattern convention architecture auth middleware \
+           async concurrency model protocol adapter scanner engine; do
+  if echo "$CONTENT" | grep -qi "$tag"; then
+    TAGS_ARRAY+=("$tag")
+  fi
+done
+
+# Convert tags array to JSON
+TAGS_JSON=$(printf '%s\n' "${TAGS_ARRAY[@]}" | jq -R . | jq -s .)
+
+# Get timestamp
+TS=$(date +%s)
+
+# Build JSON entry with proper escaping
+ENTRY=$(jq -cn \
+  --arg key "$KEY" \
+  --arg type "$TYPE" \
+  --arg content "$CONTENT" \
+  --arg source "$SOURCE" \
+  --argjson tags "$TAGS_JSON" \
+  --argjson ts "$TS" \
+  --arg bead "$BEAD_ID" \
+  '{key: $key, type: $type, content: $content, source: $source, tags: $tags, ts: $ts, bead: $bead}')
+
+# Validate JSON
+[[ -z "$ENTRY" ]] && exit 0
+echo "$ENTRY" | jq . >/dev/null 2>&1 || exit 0
+
+# Resolve memory directory
+MEMORY_DIR="${CLAUDE_PROJECT_DIR:-.}/.beads/memory"
+mkdir -p "$MEMORY_DIR"
+KNOWLEDGE_FILE="$MEMORY_DIR/knowledge.jsonl"
+
+# Append entry
+echo "$ENTRY" >> "$KNOWLEDGE_FILE"
+
+# Rotation: archive oldest 500 when file exceeds 1000 lines
+LINE_COUNT=$(wc -l < "$KNOWLEDGE_FILE" 2>/dev/null | tr -d ' ')
+if [[ "$LINE_COUNT" -gt 1000 ]]; then
+  ARCHIVE_FILE="$MEMORY_DIR/knowledge.archive.jsonl"
+  head -500 "$KNOWLEDGE_FILE" >> "$ARCHIVE_FILE"
+  tail -n +501 "$KNOWLEDGE_FILE" > "$KNOWLEDGE_FILE.tmp"
+  mv "$KNOWLEDGE_FILE.tmp" "$KNOWLEDGE_FILE"
+fi
+
+exit 0

package/templates/hooks/remind-inprogress.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+#
+# PreToolUse:Task - Soft reminder to set bead status before dispatch
+#
+
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty')
+
+# Only remind if dispatching a bead task (prompt contains BEAD_ID)
+if [[ "$PROMPT" == *"BEAD_ID:"* ]]; then
+  echo "IMPORTANT: Before dispatching, ensure bead is in_progress: bd update {BEAD_ID} --status in_progress"
+fi
+
+exit 0

package/templates/hooks/session-start.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+#
+# SessionStart: Show full task context for orchestrator
+#
+
+BEADS_DIR="$CLAUDE_PROJECT_DIR/.beads"
+
+if [[ ! -d "$BEADS_DIR" ]]; then
+  echo "No .beads directory found. Run 'bd init' to initialize."
+  exit 0
+fi
+
+# Check if bd is available
+if ! command -v bd &>/dev/null; then
+  echo "beads CLI (bd) not found. Install from: https://github.com/steveyegge/beads"
+  exit 0
+fi
+
+# ============================================================
+# Dirty Parent Check - Warn if main directory has uncommitted changes
+# ============================================================
+REPO_ROOT=$(git -C "$CLAUDE_PROJECT_DIR" rev-parse --show-toplevel 2>/dev/null)
+if [[ -n "$REPO_ROOT" ]]; then
+  DIRTY=$(git -C "$REPO_ROOT" status --porcelain 2>/dev/null)
+  if [[ -n "$DIRTY" ]]; then
+    echo "⚠️  WARNING: Main directory has uncommitted changes."
+    echo "   Agents should only work in .worktrees/"
+    echo ""
+  fi
+fi
+
+# ============================================================
+# Auto-cleanup: Detect merged PRs and cleanup worktrees
+# ============================================================
+WORKTREES_DIR="$CLAUDE_PROJECT_DIR/.worktrees"
+if [[ -d "$WORKTREES_DIR" ]]; then
+  for worktree in $(git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | grep "^worktree.*\.worktrees/bd-" | awk '{print $2}'); do
+    BEAD_ID=$(basename "$worktree" | sed 's/bd-//')
+    BRANCH=$(basename "$worktree")
+    
+    # Check if branch was merged to main
+    if git -C "$REPO_ROOT" branch --merged main 2>/dev/null | grep -q "$BRANCH"; then
+      echo "✓ $BRANCH was merged - consider cleaning up"
+      echo "   Run: git worktree remove \"$worktree\" && bd close \"$BEAD_ID\""
+      echo ""
+    fi
+  done
+fi
+
+# ============================================================
+# Open PR Reminder
+# ============================================================
+if command -v gh &>/dev/null; then
+  OPEN_PRS=$(gh pr list --author "@me" --state open --json number,title,headRefName 2>/dev/null)
+  if [[ -n "$OPEN_PRS" && "$OPEN_PRS" != "[]" ]]; then
+    echo "📋 You have open PRs:"
+    echo "$OPEN_PRS" | jq -r '.[] | "  #\(.number) \(.title) (\(.headRefName))"' 2>/dev/null
+    echo ""
+  fi
+fi
+
+echo ""
+echo "## Task Status"
+echo ""
+
+# Show in-progress beads first (highest priority)
+IN_PROGRESS=$(bd list --status in_progress 2>/dev/null | head -5)
+if [[ -n "$IN_PROGRESS" ]]; then
+  echo "### In Progress (resume these):"
+  echo "$IN_PROGRESS"
+  echo ""
+fi
+
+# Show ready (unblocked) beads
+READY=$(bd ready 2>/dev/null | head -5)
+if [[ -n "$READY" ]]; then
+  echo "### Ready (no blockers):"
+  echo "$READY"
+  echo ""
+fi
+
+# Show blocked beads
+BLOCKED=$(bd blocked 2>/dev/null | head -3)
+if [[ -n "$BLOCKED" ]]; then
+  echo "### Blocked:"
+  echo "$BLOCKED"
+  echo ""
+fi
+
+# Show stale beads (no activity in 3 days)
+STALE=$(bd stale --days 3 2>/dev/null | head -3)
+if [[ -n "$STALE" ]]; then
+  echo "### Stale (no activity in 3 days):"
+  echo "$STALE"
+  echo ""
+fi
+
+# If nothing found
+if [[ -z "$IN_PROGRESS" && -z "$READY" && -z "$BLOCKED" && -z "$STALE" ]]; then
+  echo "No active beads. Create one with: bd create \"Task title\" -d \"Description\""
+fi
+
+# ============================================================
+# Knowledge Base - Surface recent learnings
+# ============================================================
+KNOWLEDGE_FILE="$BEADS_DIR/memory/knowledge.jsonl"
+if [[ -f "$KNOWLEDGE_FILE" && -s "$KNOWLEDGE_FILE" ]]; then
+  TOTAL_ENTRIES=$(wc -l < "$KNOWLEDGE_FILE" | tr -d ' ')
+  echo ""
+  echo "## Recent Knowledge ($TOTAL_ENTRIES entries)"
+  echo ""
+  # Show 5 most recent, deduplicated by key (latest wins)
+  tail -20 "$KNOWLEDGE_FILE" | jq -s '
+    group_by(.key) | map(max_by(.ts)) | sort_by(-.ts) | .[0:5] | .[] |
+    "  [\(.type | ascii_upcase | .[0:5])] \(.content | .[0:100])  (\(.source))"
+  ' -r 2>/dev/null
+  echo ""
+  echo "  Search: .beads/memory/recall.sh \"keyword\""
+fi
+
+echo ""

package/templates/hooks/validate-completion.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+#
+# SubagentStop: Enforce bead lifecycle - work verification
+#
+
+INPUT=$(cat)
+AGENT_TRANSCRIPT=$(echo "$INPUT" | jq -r '.agent_transcript_path // empty')
+MAIN_TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+
+[[ -z "$AGENT_TRANSCRIPT" || ! -f "$AGENT_TRANSCRIPT" ]] && echo '{"decision":"approve"}' && exit 0
+
+# Extract last assistant text response
+LAST_RESPONSE=$(tail -200 "$AGENT_TRANSCRIPT" | jq -rs '
+  [.[] | select(.message?.role == "assistant" and .message?.content != null)
+   | .message.content[] | select(.text != null) | .text] | last // ""
+' 2>/dev/null || echo "")
+
+# === LAYER 1: Extract subagent_type from transcript (fail open) ===
+SUBAGENT_TYPE=""
+if [[ -n "$AGENT_ID" && -n "$MAIN_TRANSCRIPT" && -f "$MAIN_TRANSCRIPT" ]]; then
+  PARENT_TOOL_USE_ID=$(grep "\"agentId\":\"$AGENT_ID\"" "$MAIN_TRANSCRIPT" 2>/dev/null | head -1 | jq -r '.parentToolUseID // empty' 2>/dev/null)
+  if [[ -n "$PARENT_TOOL_USE_ID" ]]; then
+    SUBAGENT_TYPE=$(grep "\"id\":\"$PARENT_TOOL_USE_ID\"" "$MAIN_TRANSCRIPT" 2>/dev/null | \
+      grep '"name":"Task"' | \
+      jq -r '.message.content[]? | select(.type == "tool_use" and .id == "'"$PARENT_TOOL_USE_ID"'") | .input.subagent_type // empty' 2>/dev/null | \
+      head -1)
+  fi
+fi
+
+# === LAYER 2: Check completion format (backup detection) ===
+HAS_BEAD_COMPLETE=$(echo "$LAST_RESPONSE" | grep -cE "BEAD.*COMPLETE" 2>/dev/null || true)
+HAS_WORKTREE_OR_BRANCH=$(echo "$LAST_RESPONSE" | grep -cE "(Worktree:|Branch:).*bd-" 2>/dev/null || true)
+[[ -z "$HAS_BEAD_COMPLETE" ]] && HAS_BEAD_COMPLETE=0
+[[ -z "$HAS_WORKTREE_OR_BRANCH" ]] && HAS_WORKTREE_OR_BRANCH=0
+
+# Determine if this is a supervisor (Layer 1) or has completion format (Layer 2)
+IS_SUPERVISOR="false"
+[[ "$SUBAGENT_TYPE" == *"supervisor"* ]] && IS_SUPERVISOR="true"
+
+NEEDS_VERIFICATION="false"
+[[ "$IS_SUPERVISOR" == "true" ]] && NEEDS_VERIFICATION="true"
+[[ "$HAS_BEAD_COMPLETE" -ge 1 && "$HAS_WORKTREE_OR_BRANCH" -ge 1 ]] && NEEDS_VERIFICATION="true"
+
+# Skip verification if not needed
+[[ "$NEEDS_VERIFICATION" == "false" ]] && echo '{"decision":"approve"}' && exit 0
+
+# Worker supervisor is exempt
+[[ "$SUBAGENT_TYPE" == *"worker"* ]] && echo '{"decision":"approve"}' && exit 0
+
+# === VERIFICATION CHECKS ===
+
+# Check 1: Completion format required for supervisors
+if [[ "$IS_SUPERVISOR" == "true" ]] && [[ "$HAS_BEAD_COMPLETE" -lt 1 || "$HAS_WORKTREE_OR_BRANCH" -lt 1 ]]; then
+  cat << 'EOF'
+{"decision":"block","reason":"Work verification failed: completion report missing.\n\nRequired format:\nBEAD {BEAD_ID} COMPLETE\nWorktree: .worktrees/bd-{BEAD_ID}\nFiles: [list]\nTests: pass\nSummary: [1 sentence]"}
+EOF
+  exit 0
+fi
+
+# Extract BEAD_ID from response
+BEAD_ID_FROM_RESPONSE=$(echo "$LAST_RESPONSE" | grep -oE "BEAD [A-Za-z0-9._-]+" | head -1 | awk '{print $2}')
+IS_EPIC_CHILD="false"
+[[ "$BEAD_ID_FROM_RESPONSE" == *"."* ]] && IS_EPIC_CHILD="true"
+
+# Check 2: Comment required
+HAS_COMMENT=$(grep -c '"bd comment\|"command":"bd comment' "$AGENT_TRANSCRIPT" 2>/dev/null) || HAS_COMMENT=0
+if [[ "$HAS_COMMENT" -lt 1 ]]; then
+  cat << 'EOF'
+{"decision":"block","reason":"Work verification failed: no comment on bead.\n\nRun: bd comment {BEAD_ID} \"Completed: [summary]\""}
+EOF
+  exit 0
+fi
+
+# Check 3: Worktree verification
+REPO_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." 2>/dev/null && pwd)
+WORKTREE_PATH="$REPO_ROOT/.worktrees/bd-${BEAD_ID_FROM_RESPONSE}"
+
+if [[ ! -d "$WORKTREE_PATH" ]]; then
+  cat << 'EOF'
+{"decision":"block","reason":"Work verification failed: worktree not found.\n\nCreate worktree first via API."}
+EOF
+  exit 0
+fi
+
+# Check 4: Uncommitted changes
+UNCOMMITTED=$(git -C "$WORKTREE_PATH" status --porcelain 2>/dev/null)
+if [[ -n "$UNCOMMITTED" ]]; then
+  cat << 'EOF'
+{"decision":"block","reason":"Work verification failed: uncommitted changes.\n\nRun in worktree:\n  git add -A && git commit -m \"...\""}
+EOF
+  exit 0
+fi
+
+# Check 5: Remote push
+HAS_REMOTE=$(git -C "$WORKTREE_PATH" remote get-url origin 2>/dev/null)
+if [[ -n "$HAS_REMOTE" ]]; then
+  BRANCH="bd-${BEAD_ID_FROM_RESPONSE}"
+  REMOTE_EXISTS=$(git -C "$WORKTREE_PATH" ls-remote --heads origin "$BRANCH" 2>/dev/null)
+  if [[ -z "$REMOTE_EXISTS" ]]; then
+    cat << 'EOF'
+{"decision":"block","reason":"Work verification failed: branch not pushed.\n\nRun: git push -u origin bd-{BEAD_ID}"}
+EOF
+    exit 0
+  fi
+fi
+
+# Check 6: Bead status
+BEAD_STATUS=$(bd show "$BEAD_ID_FROM_RESPONSE" --json 2>/dev/null | jq -r '.[0].status // "unknown"')
+EXPECTED_STATUS="inreview"
+# Epic children also use inreview (done status not supported in bd)
+if [[ "$BEAD_STATUS" != "$EXPECTED_STATUS" ]]; then
+  cat << EOF
+{"decision":"block","reason":"Work verification failed: bead status is '${BEAD_STATUS}'.\n\nRun: bd update ${BEAD_ID_FROM_RESPONSE} --status ${EXPECTED_STATUS}"}
+EOF
+  exit 0
+fi
+
+# Check 7: Verbosity limit
+DECODED_RESPONSE=$(printf '%b' "$LAST_RESPONSE")
+LINE_COUNT=$(echo "$DECODED_RESPONSE" | wc -l | tr -d ' ')
+CHAR_COUNT=${#DECODED_RESPONSE}
+
+if [[ "$LINE_COUNT" -gt 15 ]] || [[ "$CHAR_COUNT" -gt 800 ]]; then
+  cat << EOF
+{"decision":"block","reason":"Work verification failed: response too verbose (${LINE_COUNT} lines, ${CHAR_COUNT} chars). Max: 15 lines, 800 chars."}
+EOF
+  exit 0
+fi
+
+echo '{"decision":"approve"}'