hool-cli 0.4.0 → 0.5.0

package/hooks/agent-checklist.sh

@@ -1,17 +1,25 @@
 #!/bin/bash
 # Hook: Post-agent operational checklist reminder
 # Type: Stop and SubagentStop
-# Injects a reminder asking if the agent completed its operational duties
+# Outputs JSON with additionalContext so the agent actually sees and acts on it
+# (plain text to stdout was often ignored — JSON injection ensures visibility)
 
-echo "OPERATIONAL CHECKLIST — Did you complete these before finishing?"
-echo "[ ] Updated memory/cold.md with work log entries"
-echo "[ ] Rebuilt memory/hot.md from cold log"
-echo "[ ] Moved [GOTCHA]/[PATTERN] entries to best-practices.md"
-echo "[ ] Logged any issues to operations/issues.md"
-echo "[ ] Logged any inconsistencies to operations/inconsistencies.md"
-echo "[ ] Marked task complete on operations/task-board.md"
-echo "[ ] Verified no governor-feedback.md violations in your output"
-echo ""
-echo "If any items are incomplete, address them now before returning."
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo '.')"
+HOOL_DIR="$PROJECT_ROOT/.hool"
+
+# Check if task-board was recently updated (within last 5 minutes)
+STALE_WARNING=""
+if [ -f "$HOOL_DIR/operations/task-board.md" ]; then
+  TASK_BOARD_MOD=$(stat -f %m "$HOOL_DIR/operations/task-board.md" 2>/dev/null || stat -c %Y "$HOOL_DIR/operations/task-board.md" 2>/dev/null || echo "0")
+  NOW=$(date +%s)
+  AGE=$((NOW - TASK_BOARD_MOD))
+  if [ "$AGE" -gt 300 ]; then
+    STALE_WARNING=" WARNING: task-board.md not updated in ${AGE}s."
+  fi
+fi
+
+CHECKLIST="OPERATIONAL CHECKLIST — Before finishing, verify: (1) Updated .hool/memory/<agent>/cold.md with work log entries (2) Rebuilt .hool/memory/<agent>/hot.md from cold log (3) Moved [GOTCHA]/[PATTERN] entries to best-practices.md (4) Logged issues to .hool/operations/issues.md (5) Logged inconsistencies to .hool/operations/inconsistencies.md (6) Marked task complete on .hool/operations/task-board.md (7) Verified no governor-feedback.md violations in output.${STALE_WARNING} If any items are incomplete, address them now."
+
+printf '{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":"%s"}}\n' "$CHECKLIST"
 
 exit 0

package/hooks/inject-pl-context.sh

@@ -23,8 +23,75 @@ if [ -f "$PROJECT_ROOT/.hool/operations/needs-human-review.md" ]; then
   REVIEW_ITEMS=$(grep -c '^##\|^- ' "$PROJECT_ROOT/.hool/operations/needs-human-review.md" 2>/dev/null | tr -d '\n' || echo "0")
 fi
 
+# Phase-specific guidance — different advice depending on where we are
+PHASE_LOWER=$(echo "$PHASE" | tr '[:upper:]' '[:lower:]')
+PHASE_GUIDANCE=""
+case "$PHASE_LOWER" in
+  *onboard*)
+    PHASE_GUIDANCE="ONBOARDING: Complete ALL onboarding tasks immediately. Reverse-engineer docs from code. Do not wait for explicit instruction."
+    ;;
+  *phase*0*|*init*)
+    PHASE_GUIDANCE="PHASE 0: Ask what we're building, determine project type and mode, capture preferences."
+    ;;
+  *phase*1*|*brainstorm*)
+    PHASE_GUIDANCE="PHASE 1: Interactive brainstorm with user. Explore ideas, constraints, scope. Get explicit sign-off."
+    ;;
+  *phase*2*|*spec*)
+    PHASE_GUIDANCE="PHASE 2: Define user stories and acceptance criteria. Get sign-off (interactive) or advance (full-hool)."
+    ;;
+  *phase*3*|*design*)
+    PHASE_GUIDANCE="PHASE 3: Design screens, components, visual language. Get sign-off (interactive) or advance (full-hool)."
+    ;;
+  *phase*4*|*arch*)
+    PHASE_GUIDANCE="PHASE 4: FINAL HUMAN GATE. Define tech stack, contracts, schema, flows. Get sign-off before autonomous."
+    ;;
+  *phase*5*|*fe*scaffold*|*fe*lld*)
+    PHASE_GUIDANCE="PHASE 5: Autonomous. Dispatch FE Tech Lead for scaffold + LLD. Verify output."
+    ;;
+  *phase*6*|*be*scaffold*|*be*lld*)
+    PHASE_GUIDANCE="PHASE 6: Autonomous. Dispatch BE Tech Lead for scaffold + LLD. Verify output."
+    ;;
+  *phase*7*|*test*plan*)
+    PHASE_GUIDANCE="PHASE 7: Autonomous. Dispatch QA for test plan. Verify coverage of all spec criteria."
+    ;;
+  *phase*8*|*impl*)
+    PHASE_GUIDANCE="PHASE 8: Autonomous. Dispatch FE/BE Devs per task. Check output, route issues."
+    ;;
+  *phase*9*|*review*)
+    PHASE_GUIDANCE="PHASE 9: Autonomous. Dispatch Tech Leads for code review. Route inconsistencies."
+    ;;
+  *phase*10*|*test*)
+    PHASE_GUIDANCE="PHASE 10: Autonomous. Dispatch QA for testing. Route bugs to Forensic."
+    ;;
+  *phase*11*|*forensic*)
+    PHASE_GUIDANCE="PHASE 11: Autonomous. Dispatch Forensic for root cause. Route fixes to Devs."
+    ;;
+  *phase*12*|*retro*)
+    PHASE_GUIDANCE="PHASE 12: Run retrospective. Read all agents' memory. Write findings to needs-human-review.md."
+    ;;
+  *standby*)
+    PHASE_GUIDANCE="STANDBY: Wait for user request. Route to appropriate phase/agent based on request type."
+    ;;
+esac
+
+# Check for unresolved inconsistencies
+INCONSISTENCIES=0
+if [ -f "$PROJECT_ROOT/.hool/operations/inconsistencies.md" ]; then
+  INCONSISTENCIES=$(grep -c '^- ' "$PROJECT_ROOT/.hool/operations/inconsistencies.md" 2>/dev/null | tr -d '\n' || echo "0")
+fi
+
+# Check governor dispatch count
+DISPATCH_COUNT=0
+if [ -f "$PROJECT_ROOT/.hool/metrics/dispatch-count.txt" ]; then
+  DISPATCH_COUNT=$(cat "$PROJECT_ROOT/.hool/metrics/dispatch-count.txt" 2>/dev/null | tr -d '\n' || echo "0")
+fi
+GOVERNOR_DUE=""
+if [ "$DISPATCH_COUNT" -gt 0 ] && [ $(( DISPATCH_COUNT % 3 )) -ge 2 ]; then
+  GOVERNOR_DUE=" Governor audit due after next dispatch."
+fi
+
 # Build context as a single line (JSON-safe)
-CONTEXT="HOOL PRODUCT LEAD CONTEXT | Current: ${PHASE} | Pending tasks: ${PENDING} | Human review items: ${REVIEW_ITEMS} | RULES: (1) NEVER edit src/ or tests/ - dispatch agents via .claude/agents/{name}.md (2) Read .hool/operations/current-phase.md and task-board.md FIRST (3) All state in .hool/ (memory/, phases/, operations/) (4) After every 3 agent dispatches, run the governor (5) No task too small for dispatch (6) If pending tasks exist, tell user and ask if you should proceed"
+CONTEXT="HOOL PRODUCT LEAD CONTEXT | Current: ${PHASE} | Pending tasks: ${PENDING} | Human review: ${REVIEW_ITEMS} | Inconsistencies: ${INCONSISTENCIES} | Dispatches: ${DISPATCH_COUNT}${GOVERNOR_DUE} | ${PHASE_GUIDANCE} | RULES: (1) NEVER edit src/ or tests/ - dispatch agents (2) Read .hool/operations/current-phase.md and task-board.md FIRST (3) All state in .hool/ (4) After every 3 dispatches, run governor (5) No task too small for dispatch (6) If pending tasks, tell user and ask to proceed"
 
 # Output valid JSON
 printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"%s"}}\n' "$CONTEXT"

package/hooks/pre-compact.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Hook: Save HOOL state snapshot before context compaction
+# Type: PreCompact
+# Why: Context compaction can lose critical phase/task state.
+#       This hook preserves a snapshot so the agent can recover on resume.
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo '.')"
+HOOL_DIR="$PROJECT_ROOT/.hool"
+SNAPSHOTS_DIR="$HOOL_DIR/metrics/snapshots"
+mkdir -p "$SNAPSHOTS_DIR"
+
+TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
+SNAPSHOT_FILE="$SNAPSHOTS_DIR/pre-compact-$TIMESTAMP.md"
+
+# Capture current phase
+PHASE="unknown"
+if [ -f "$HOOL_DIR/operations/current-phase.md" ]; then
+  PHASE=$(head -10 "$HOOL_DIR/operations/current-phase.md")
+fi
+
+# Capture pending task count and first 5 pending tasks
+PENDING_TASKS=""
+if [ -f "$HOOL_DIR/operations/task-board.md" ]; then
+  PENDING_TASKS=$(grep '^\- \[ \]' "$HOOL_DIR/operations/task-board.md" 2>/dev/null | head -5)
+fi
+
+# Capture last 10 entries from PL cold log
+RECENT_LOG=""
+if [ -f "$HOOL_DIR/memory/product-lead/cold.md" ]; then
+  RECENT_LOG=$(tail -10 "$HOOL_DIR/memory/product-lead/cold.md")
+fi
+
+# Capture items needing human review
+REVIEW_COUNT=0
+if [ -f "$HOOL_DIR/operations/needs-human-review.md" ]; then
+  REVIEW_COUNT=$(grep -c '^##\|^- ' "$HOOL_DIR/operations/needs-human-review.md" 2>/dev/null | tr -d '\n' || echo "0")
+fi
+
+# Capture dispatch count
+DISPATCH_COUNT=0
+if [ -f "$HOOL_DIR/metrics/dispatch-count.txt" ]; then
+  DISPATCH_COUNT=$(cat "$HOOL_DIR/metrics/dispatch-count.txt" 2>/dev/null | tr -d '\n' || echo "0")
+fi
+
+# Write snapshot
+cat > "$SNAPSHOT_FILE" << SNAPSHOT
+# HOOL Pre-Compaction Snapshot
+**Timestamp:** $TIMESTAMP
+**Dispatch count:** $DISPATCH_COUNT
+**Human review items:** $REVIEW_COUNT
+
+## Current Phase
+$PHASE
+
+## Pending Tasks (first 5)
+$PENDING_TASKS
+
+## Recent Activity (last 10 cold log entries)
+$RECENT_LOG
+SNAPSHOT
+
+# Also inject context into the conversation so the agent doesn't lose state
+PHASE_ONELINER=$(echo "$PHASE" | head -1 | tr -d '\n')
+TASK_COUNT=$(echo "$PENDING_TASKS" | grep -c '.' 2>/dev/null | tr -d '\n' || echo "0")
+
+cat << JSONEOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreCompact",
+    "additionalContext": "HOOL STATE SNAPSHOT (pre-compaction): Phase: ${PHASE_ONELINER} | Pending tasks: ${TASK_COUNT} | Dispatches: ${DISPATCH_COUNT} | Review items: ${REVIEW_COUNT} | IMPORTANT: After compaction, re-read .hool/operations/current-phase.md and .hool/operations/task-board.md to restore full context. Snapshot saved to ${SNAPSHOT_FILE}"
+  }
+}
+JSONEOF
+
+exit 0

package/hooks/run-if-profile.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Hook Profile Wrapper — conditionally runs a hook based on HOOL_HOOK_PROFILE
+# Usage: run-if-profile.sh <required-profiles-csv> <actual-hook-script>
+# Example: run-if-profile.sh "standard,strict" ".hool/hooks/suggest-compact.sh"
+#
+# Profile levels:
+#   minimal  — only safety-critical hooks (block-pl-src-write, pre-compact)
+#   standard — default: safety + operational (all hooks except strict-only)
+#   strict   — maximum guardrails: all hooks active
+#
+# Set via: export HOOL_HOOK_PROFILE=minimal|standard|strict
+# Default: standard
+
+REQUIRED_PROFILES="$1"
+HOOK_SCRIPT="$2"
+
+if [ -z "$HOOK_SCRIPT" ]; then
+  echo "Usage: run-if-profile.sh <profiles-csv> <hook-script>" >&2
+  exit 0
+fi
+
+# Default profile
+CURRENT_PROFILE="${HOOL_HOOK_PROFILE:-standard}"
+
+# Check if current profile is in the required list
+ENABLED=false
+IFS=',' read -ra PROFILES <<< "$REQUIRED_PROFILES"
+for profile in "${PROFILES[@]}"; do
+  profile=$(echo "$profile" | tr -d ' ')
+  if [ "$profile" = "$CURRENT_PROFILE" ]; then
+    ENABLED=true
+    break
+  fi
+done
+
+if [ "$ENABLED" = false ]; then
+  # Pass through stdin unchanged
+  cat
+  exit 0
+fi
+
+# Profile matches — run the actual hook, passing stdin through
+exec bash "$HOOK_SCRIPT"

package/hooks/session-start.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Hook: Load HOOL state on new session start
+# Type: PreToolUse (first invocation) or UserPromptSubmit
+# Why: When a new session begins, the agent needs to know where it left off.
+#       This hook injects the most recent pre-compact snapshot + current state.
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo '.')"
+HOOL_DIR="$PROJECT_ROOT/.hool"
+SNAPSHOTS_DIR="$HOOL_DIR/metrics/snapshots"
+SESSION_MARKER="$HOOL_DIR/metrics/session-active.txt"
+
+# Only run once per session — check if we already injected
+if [ -f "$SESSION_MARKER" ]; then
+  MARKER_AGE=$(( $(date +%s) - $(stat -f %m "$SESSION_MARKER" 2>/dev/null || stat -c %Y "$SESSION_MARKER" 2>/dev/null || echo "0") ))
+  # If marker is less than 60 seconds old, skip (already ran this session)
+  if [ "$MARKER_AGE" -lt 60 ]; then
+    exit 0
+  fi
+fi
+
+# Mark session as active
+date +%s > "$SESSION_MARKER" 2>/dev/null
+
+# Find the most recent snapshot
+LATEST_SNAPSHOT=""
+if [ -d "$SNAPSHOTS_DIR" ]; then
+  LATEST_SNAPSHOT=$(ls -t "$SNAPSHOTS_DIR"/pre-compact-*.md 2>/dev/null | head -1)
+fi
+
+# Build session context
+PHASE="unknown"
+if [ -f "$HOOL_DIR/operations/current-phase.md" ]; then
+  PHASE=$(head -3 "$HOOL_DIR/operations/current-phase.md" | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+fi
+
+PENDING=0
+if [ -f "$HOOL_DIR/operations/task-board.md" ]; then
+  PENDING=$(grep -c '^\- \[ \]' "$HOOL_DIR/operations/task-board.md" 2>/dev/null | tr -d '\n' || echo "0")
+fi
+
+SNAPSHOT_INFO=""
+if [ -n "$LATEST_SNAPSHOT" ]; then
+  SNAPSHOT_INFO=" | Last snapshot: $(basename "$LATEST_SNAPSHOT")"
+fi
+
+CONTEXT="HOOL SESSION RESUMED | Phase: ${PHASE} | Pending tasks: ${PENDING}${SNAPSHOT_INFO} | ACTION: Read .hool/operations/current-phase.md and .hool/operations/task-board.md immediately. If there are pending tasks, tell the user and ask if you should proceed."
+
+printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"%s"}}\n' "$CONTEXT"
+
+exit 0

package/hooks/suggest-compact.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Hook: Suggest strategic /compact at logical intervals
+# Type: PreToolUse on Edit|Write
+# Why: Auto-compact happens at arbitrary points, often mid-task.
+#       Strategic compaction between phases preserves better context.
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo '.')"
+METRICS_DIR="$PROJECT_ROOT/.hool/metrics"
+mkdir -p "$METRICS_DIR"
+
+COUNTER_FILE="$METRICS_DIR/tool-call-count.txt"
+THRESHOLD="${HOOL_COMPACT_THRESHOLD:-50}"
+
+# Read and increment counter
+CURRENT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+NEXT=$((CURRENT + 1))
+echo "$NEXT" > "$COUNTER_FILE"
+
+# Suggest at threshold
+if [ "$NEXT" -eq "$THRESHOLD" ]; then
+  echo "HOOL: ${THRESHOLD} tool calls reached. Consider running /compact if you're between phases or tasks." >&2
+fi
+
+# Suggest every 25 calls after threshold
+if [ "$NEXT" -gt "$THRESHOLD" ]; then
+  OVER=$((NEXT - THRESHOLD))
+  if [ $((OVER % 25)) -eq 0 ]; then
+    echo "HOOL: ${NEXT} tool calls. Good checkpoint for /compact if context feels stale." >&2
+  fi
+fi
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hool-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agent-Driven SDLC — scaffold and configure HOOL for any project",
   "bin": {
     "hool": "./dist/index.js"

package/settings/claude-settings.json

@@ -9,7 +9,19 @@
             "command": ".hool/hooks/block-pl-src-write.sh",
             "timeout": 5
           }
-        ]
+        ],
+        "description": "Block Product Lead from editing src/ or tests/ directly"
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".hool/hooks/suggest-compact.sh",
+            "timeout": 3
+          }
+        ],
+        "description": "Suggest strategic /compact at logical intervals"
       }
     ],
     "PostToolUse": [
@@ -21,7 +33,8 @@
             "command": ".hool/hooks/track-prompt-count.sh",
             "timeout": 5
           }
-        ]
+        ],
+        "description": "Track dispatch count, trigger governor every 3 dispatches"
       }
     ],
     "UserPromptSubmit": [
@@ -33,7 +46,21 @@
             "command": ".hool/hooks/inject-pl-context.sh",
             "timeout": 5
           }
-        ]
+        ],
+        "description": "Inject phase-aware PL context on every user prompt"
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".hool/hooks/pre-compact.sh",
+            "timeout": 10
+          }
+        ],
+        "description": "Save HOOL state snapshot before context compaction"
       }
     ],
     "Stop": [
@@ -45,7 +72,8 @@
             "command": ".hool/hooks/agent-checklist.sh",
             "timeout": 5
           }
-        ]
+        ],
+        "description": "Operational checklist reminder after each response"
       }
     ],
     "SubagentStop": [
@@ -57,7 +85,8 @@
             "command": ".hool/hooks/agent-checklist.sh",
             "timeout": 5
           }
-        ]
+        ],
+        "description": "Operational checklist reminder after subagent completes"
       }
     ]
   }