agileflow 3.0.1 → 3.0.2

package/scripts/ralph-loop.js

@@ -428,15 +428,17 @@ function runCoverage(rootDir) {
 
 // Get screenshots directory from metadata or default
 function getScreenshotsDir(rootDir) {
-  return tryOptional(() => {
-    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
-    if (fs.existsSync(metadataPath)) {
-      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
-      if (metadata.ralph_loop?.screenshots_dir) {
-        return metadata.ralph_loop.screenshots_dir;
+  return (
+    tryOptional(() => {
+      const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+      if (fs.existsSync(metadataPath)) {
+        const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+        if (metadata.ralph_loop?.screenshots_dir) {
+          return metadata.ralph_loop.screenshots_dir;
+        }
       }
-    }
-  }, 'metadata read') || './screenshots';
+    }, 'metadata read') || './screenshots'
+  );
 }
 
 // Run screenshot verification (Visual Mode)

package/scripts/smart-detect.js

@@ -54,7 +54,13 @@ try {
       return { ok: false, error: e.message };
     }
   };
-  tryOptional = (fn, _label) => { try { return fn(); } catch { return undefined; } };
+  tryOptional = (fn, _label) => {
+    try {
+      return fn();
+    } catch {
+      return undefined;
+    }
+  };
 }
 
 // =============================================================================
@@ -121,11 +127,17 @@ function extractSignals(prefetched, sessionState, metadata) {
   // File existence checks
   const files = {
     tsconfig: fs.existsSync('tsconfig.json'),
-    eslintrc: fs.existsSync('.eslintrc.js') || fs.existsSync('.eslintrc.json') || fs.existsSync('.eslintrc.yml'),
+    eslintrc:
+      fs.existsSync('.eslintrc.js') ||
+      fs.existsSync('.eslintrc.json') ||
+      fs.existsSync('.eslintrc.yml'),
     coverage: fs.existsSync('coverage/coverage-summary.json'),
     playwright: fs.existsSync('playwright.config.ts') || fs.existsSync('playwright.config.js'),
     screenshots: fs.existsSync('screenshots'),
-    ciConfig: fs.existsSync('.github/workflows') || fs.existsSync('.gitlab-ci.yml') || fs.existsSync('Jenkinsfile'),
+    ciConfig:
+      fs.existsSync('.github/workflows') ||
+      fs.existsSync('.gitlab-ci.yml') ||
+      fs.existsSync('Jenkinsfile'),
     expertiseDir: fs.existsSync('.agileflow/expertise'),
   };
 
@@ -255,7 +267,11 @@ function analyze(prefetched, sessionState, metadata) {
   const rawRecommendations = runDetectorsForPhases(relevantPhases, signals);
 
   // Filter and categorize
-  const { immediate, available } = filterRecommendations(rawRecommendations, metadata, sessionState);
+  const { immediate, available } = filterRecommendations(
+    rawRecommendations,
+    metadata,
+    sessionState
+  );
 
   // Auto-enabled features (existing babysit modes)
   const autoEnabled = detectAutoModes(signals);
@@ -304,7 +320,7 @@ function detectAutoModes(signals) {
     const readyInEpic = Object.entries(statusJson.stories).filter(
       ([, s]) => s.epic === story.epic && s.status === 'ready'
     ).length;
-    loopMode = readyInEpic >= 3 && !!(packageJson?.scripts?.test);
+    loopMode = readyInEpic >= 3 && !!packageJson?.scripts?.test;
   }
 
   // Visual mode: UI-related story or visual e2e setup
@@ -342,10 +358,9 @@ function writeRecommendations(results, outputPath) {
 
 if (require.main === module) {
   // Run standalone - gather our own data
-  const statusJsonResult = safeReadJSON(
-    path.join(process.cwd(), 'docs/09-agents/status.json'),
-    { defaultValue: {} }
-  );
+  const statusJsonResult = safeReadJSON(path.join(process.cwd(), 'docs/09-agents/status.json'), {
+    defaultValue: {},
+  });
   const sessionStateResult = safeReadJSON(
     path.join(process.cwd(), 'docs/09-agents/session-state.json'),
     { defaultValue: {} }
@@ -357,8 +372,14 @@ if (require.main === module) {
 
   // Build minimal prefetched structure
   const { execSync } = require('child_process');
-  const gitBranch = tryOptional(() => execSync('git branch --show-current', { encoding: 'utf8' }).trim(), 'git branch') || '';
-  const gitStatus = tryOptional(() => execSync('git status --short', { encoding: 'utf8' }).trim(), 'git status') || '';
+  const gitBranch =
+    tryOptional(
+      () => execSync('git branch --show-current', { encoding: 'utf8' }).trim(),
+      'git branch'
+    ) || '';
+  const gitStatus =
+    tryOptional(() => execSync('git status --short', { encoding: 'utf8' }).trim(), 'git status') ||
+    '';
 
   const prefetched = {
     json: {

package/scripts/team-manager.js

@@ -204,7 +204,7 @@ function startTeam(rootDir, templateName) {
     const sessionStatePath = paths.getSessionStatePath(rootDir);
     const fileLock = getFileLock();
 
-    const updateState = (state) => {
+    const updateState = state => {
       state.active_team = {
         template: templateName,
         mode,

package/scripts/tmux-task-name.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# tmux-task-name.sh - Rename current tmux window based on task/work description
+#
+# Called by Claude Code when starting work on a task (via TaskCreate/TaskUpdate).
+# Reads the task subject from ~/.claude/tasks/ or accepts it as an argument.
+#
+# Usage:
+#   tmux-task-name.sh "Fix auth middleware"    # Rename to task subject
+#   tmux-task-name.sh --scan                   # Auto-detect from task files
+#   tmux-task-name.sh --reset                  # Reset to default "claude-N"
+#
+# The script is best-effort: silently exits if not inside tmux.
+
+set -euo pipefail
+
+# Exit silently if not in tmux
+[ -n "${TMUX:-}" ] || exit 0
+
+MAX_LEN=30
+
+truncate_name() {
+  local name="$1"
+  if [ ${#name} -gt $MAX_LEN ]; then
+    echo "${name:0:$((MAX_LEN - 1))}…"
+  else
+    echo "$name"
+  fi
+}
+
+# Mode: reset to default sequential name
+if [ "${1:-}" = "--reset" ]; then
+  N=$(( $(tmux list-windows -F '#{window_name}' 2>/dev/null | grep -c '^claude') ))
+  [ "$N" -eq 0 ] && N=1
+  tmux rename-window "claude-$N" 2>/dev/null || true
+  exit 0
+fi
+
+# Mode: scan ~/.claude/tasks/ for most recently modified in-progress task
+if [ "${1:-}" = "--scan" ]; then
+  TASKS_DIR="${HOME}/.claude/tasks"
+  [ -d "$TASKS_DIR" ] || exit 0
+
+  BEST_SUBJECT=""
+  BEST_MTIME=0
+
+  for dir in "$TASKS_DIR"/*/; do
+    [ -d "$dir" ] || continue
+    for f in "$dir"*.json; do
+      [ -f "$f" ] || continue
+      # Check if task is in_progress and get subject
+      status=$(python3 -c "import json,sys; d=json.load(open('$f')); print(d.get('status',''))" 2>/dev/null || echo "")
+      if [ "$status" = "in_progress" ]; then
+        mtime=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f" 2>/dev/null || echo "0")
+        if [ "$mtime" -gt "$BEST_MTIME" ]; then
+          BEST_MTIME=$mtime
+          BEST_SUBJECT=$(python3 -c "import json; d=json.load(open('$f')); print(d.get('subject',''))" 2>/dev/null || echo "")
+        fi
+      fi
+    done
+  done
+
+  if [ -n "$BEST_SUBJECT" ]; then
+    tmux rename-window "$(truncate_name "$BEST_SUBJECT")" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Mode: direct - rename to provided argument
+if [ -n "${1:-}" ]; then
+  tmux rename-window "$(truncate_name "$1")" 2>/dev/null || true
+  exit 0
+fi
+
+echo "Usage: tmux-task-name.sh <task-subject> | --scan | --reset" >&2
+exit 1

package/scripts/tmux-task-watcher.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# tmux-task-watcher.sh - Auto-rename tmux window based on Claude Code tasks
+#
+# Launched automatically by SessionStart hook. Self-backgrounds immediately.
+# Polls ~/.claude/tasks/<session-id>/ for in-progress tasks every few seconds.
+# Renames the tmux window to match the active task subject.
+#
+# Usage:
+#   tmux-task-watcher.sh           # Start watcher (backgrounds itself)
+#   tmux-task-watcher.sh stop      # Stop watcher for current pane
+#
+# Requirements:
+#   - Must be inside tmux ($TMUX set)
+#   - Node.js available (for JSON parsing)
+#   - Claude Code session active ($CLAUDECODE=1)
+
+set -euo pipefail
+
+# Only run inside tmux
+[ -n "${TMUX:-}" ] || exit 0
+
+MODE="${1:-start}"
+MAX_LEN=30
+
+# Get current pane ID for per-pane tracking
+PANE_ID=$(tmux display-message -p '#{pane_id}' 2>/dev/null || true)
+[ -n "$PANE_ID" ] || exit 0
+
+# PID file keyed by pane to allow multiple watchers (one per window)
+SAFE_PANE_ID="${PANE_ID//[^a-zA-Z0-9]/_}"
+PID_FILE="/tmp/tmux-task-watcher-${SAFE_PANE_ID}.pid"
+
+# --- Stop mode ---
+if [ "$MODE" = "stop" ]; then
+  if [ -f "$PID_FILE" ]; then
+    kill "$(cat "$PID_FILE")" 2>/dev/null || true
+    rm "$PID_FILE" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# --- Start mode ---
+if [ "$MODE" = "start" ]; then
+  # Kill any existing watcher for this pane first
+  if [ -f "$PID_FILE" ]; then
+    kill "$(cat "$PID_FILE")" 2>/dev/null || true
+    rm "$PID_FILE" 2>/dev/null || true
+  fi
+
+  # Self-background: parent exits immediately so hook completes fast
+  _WATCHER_BG=1 nohup "$0" "_run" >/dev/null 2>&1 &
+  echo $! > "$PID_FILE"
+  exit 0
+fi
+
+# --- _run mode: skip to background worker below ---
+
+# ============================================================
+# Background watcher logic (runs in forked process)
+# ============================================================
+
+# Disable strict mode for background worker - we handle errors ourselves
+set +eu
+
+# Derive Claude Code project dir from PWD
+CLAUDE_PROJECT_DIR="${HOME}/.claude/projects/$(pwd | sed 's|/|-|g')"
+
+# Find current session ID: most recently CREATED JSONL in project dir
+# Uses birth time (stat %W) to avoid picking up other sessions' modified files
+find_session_id() {
+  [ -d "$CLAUDE_PROJECT_DIR" ] || return 1
+  local best_file="" best_birth=0
+  for f in "$CLAUDE_PROJECT_DIR"/*.jsonl; do
+    [ -f "$f" ] || continue
+    local birth
+    birth=$(stat -c '%W' "$f" 2>/dev/null || echo "0")
+    if [ "$birth" -gt "$best_birth" ] 2>/dev/null; then
+      best_birth=$birth
+      best_file=$f
+    fi
+  done
+  [ -n "$best_file" ] || return 1
+  basename "$best_file" .jsonl
+}
+
+# Wait briefly for session file to be created/updated
+sleep 2
+
+SESSION_ID=$(find_session_id || true)
+if [ -z "$SESSION_ID" ]; then
+  # Retry after a longer wait
+  sleep 5
+  SESSION_ID=$(find_session_id || true)
+fi
+
+# Store session ID as tmux pane option (for debugging/other scripts)
+if [ -n "$SESSION_ID" ]; then
+  tmux set-option -p @claude_session_id "$SESSION_ID" 2>/dev/null || true
+fi
+
+TASKS_DIR="${HOME}/.claude/tasks/${SESSION_ID}"
+LAST_WINDOW_NAME=""
+POLL_INTERVAL=5
+MAX_RUNTIME=$((12 * 3600))  # 12 hours safety limit
+START_TIME=$(date +%s)
+
+# Parse task files and find the most recent in-progress task subject
+get_active_task() {
+  [ -d "$TASKS_DIR" ] || return
+  node -e "
+    const fs = require('fs'), path = require('path');
+    const dir = process.argv[1];
+    let best = { mtime: 0, subject: '' };
+    try {
+      for (const f of fs.readdirSync(dir)) {
+        if (!f.endsWith('.json') || f === '.lock') continue;
+        const fp = path.join(dir, f);
+        const data = JSON.parse(fs.readFileSync(fp, 'utf8'));
+        if (data.status === 'in_progress') {
+          const mt = fs.statSync(fp).mtimeMs;
+          if (mt > best.mtime) {
+            best = { mtime: mt, subject: data.subject || data.activeForm || '' };
+          }
+        }
+      }
+    } catch(e) {}
+    if (best.subject) process.stdout.write(best.subject);
+  " "$TASKS_DIR" 2>/dev/null || true
+}
+
+truncate_name() {
+  local name="$1"
+  if [ ${#name} -gt $MAX_LEN ]; then
+    printf '%s' "${name:0:$((MAX_LEN - 1))}"
+  else
+    printf '%s' "$name"
+  fi
+}
+
+# Main polling loop
+while true; do
+  # Safety timeout
+  NOW=$(date +%s)
+  if [ $((NOW - START_TIME)) -gt $MAX_RUNTIME ]; then
+    break
+  fi
+
+  # Check if our pane is still alive
+  if ! tmux list-panes -a -F '#{pane_id}' 2>/dev/null | grep -qF "$PANE_ID"; then
+    break
+  fi
+
+  # If we don't have a session ID yet, retry finding it
+  if [ -z "$SESSION_ID" ]; then
+    SESSION_ID=$(find_session_id || true)
+    if [ -n "$SESSION_ID" ]; then
+      tmux set-option -p @claude_session_id "$SESSION_ID" 2>/dev/null || true
+      TASKS_DIR="${HOME}/.claude/tasks/${SESSION_ID}"
+    fi
+  fi
+
+  # Get active task subject
+  ACTIVE_TASK=$(get_active_task 2>/dev/null || true)
+
+  if [ -n "$ACTIVE_TASK" ]; then
+    NEW_NAME=$(truncate_name "$ACTIVE_TASK")
+    if [ "$NEW_NAME" != "$LAST_WINDOW_NAME" ]; then
+      tmux rename-window -t "$PANE_ID" "$NEW_NAME" 2>/dev/null || true
+      LAST_WINDOW_NAME="$NEW_NAME"
+    fi
+  fi
+
+  sleep "$POLL_INTERVAL"
+done
+
+# Cleanup
+rm -f "$PID_FILE"

package/src/core/commands/babysit.md

@@ -13,7 +13,7 @@ compact_context:
     - "STUCK DETECTION: If same error 2+ times, suggest /agileflow:research:ask with detailed prompt"
     - "PLAN FILE CONTEXT: BEFORE ExitPlanMode, EDIT plan file to add babysit rules header at TOP - rules survive context clear"
     - "STORY CLAIMING: claim after selection, release after completion, check others before suggesting"
-    - "LOGIC AUDIT: After implementation, offer '🔍 Run logic audit' option via AskUserQuestion (not automatic)"
+    - "LOGIC AUDIT: ALWAYS suggest '🔍 Run logic audit' after ANY implementation (plan or direct) - it's a standard post-impl step, not optional"
   state_fields:
     - current_story
     - current_epic
@@ -382,8 +382,9 @@ If you end your response without calling AskUserQuestion, you have violated thes
 |-------|-------------------|-----|
 | After context gathering | The most impactful ready story | Based on epic progress, blockers, dependencies |
 | After plan approval | "Start implementing now" | Don't ask permission, suggest action |
-| After code is written | "Run tests to verify (Recommended)" | Always verify before committing |
-| After tests pass | "Commit and continue to next story" | Keep momentum |
+| After code is written | "Run tests to verify (Recommended)" + logic audit option | Always verify before committing |
+| After tests pass | "🔍 Run logic audit (Recommended)" or "Commit" | Logic audit catches what tests miss |
+| After logic audit | "Commit: '[type]: [summary]' (Recommended)" | All checks done, ready to commit |
 | After error | "Try [specific alternative approach]" | Don't just say "fix it" |
 | After expert returns | "Review and apply changes" or "Run tests" | Based on expert output quality |
 
@@ -421,7 +422,7 @@ If you end your response without calling AskUserQuestion, you have violated thes
 | User gave detailed instructions | Skip plan mode, follow them |
 | Everything else | **USE PLAN MODE** |
 
-**Plan mode flow:** EnterPlanMode → Explore with Glob/Grep/Read → Design approach → ExitPlanMode → Implement
+**Plan mode flow:** EnterPlanMode → Explore with Glob/Grep/Read → Design approach → Add smart babysit header to plan → ExitPlanMode → Implement → Smart AskUserQuestion (with logic audit)
 
 ---
 
@@ -512,17 +513,21 @@ if(ready.length)console.log('🔔 Validators ready:',ready.map(t=>t.id).join(','
 ## ⚠️ MANDATORY IMPLEMENTATION RULES (from /babysit)
 
 These rules MUST be followed during implementation:
-1. **ALWAYS end your final response with AskUserQuestion tool** offering next steps
+1. **ALWAYS end your final response with SMART AskUserQuestion tool** - specific, contextual options with (Recommended) label
 2. **Use EnterPlanMode** if any NEW non-trivial tasks arise during implementation
 3. **Delegate complex work** to domain experts via Task tool
 4. **Track progress** with TaskCreate/TaskUpdate for multi-step work
 
-After implementation completes, you MUST call AskUserQuestion with options like:
-- "Run tests to verify"
-- "🔍 Run logic audit" (for complex code - uses /agileflow:logic:audit)
-- "Continue to next task"
-- "Review changes"
-- "Pause here"
+**Smart AskUserQuestion format** (NEVER generic - always contextual):
+- Options must reference specific files, test commands, story IDs, and change counts
+- Always mark the best next step with "(Recommended)"
+- Include descriptions with concrete context (e.g., "3 files changed in scripts/")
+
+After implementation completes, you MUST call AskUserQuestion. **ALWAYS include logic audit**:
+- "Run `npm test` in packages/cli/ (Recommended)" + description with file count
+- "🔍 Run logic audit on [N] modified files" + "5 analyzers check for edge cases, race conditions, type bugs"
+- "Commit: '[type]: [summary]'" + "All tests pass, ready to commit"
+- "Pause here" + "Changes saved, not committed"
 
 ---
 ```
@@ -534,7 +539,7 @@ After implementation completes, you MUST call AskUserQuestion with options like:
 # Plan: Add User Profile Feature
 
 ## ⚠️ MANDATORY IMPLEMENTATION RULES (from /babysit)
-[rules as above]
+[rules as above - with SMART AskUserQuestion and logic audit]
 
 ---
 
@@ -594,22 +599,22 @@ After implementation completes, you MUST call AskUserQuestion with options like:
 13. Delegate to experts based on scope
 14. Collect results if async (TaskOutput)
 15. Verify tests pass
-16. AskUserQuestion with specific test results: "All tests pass - commit changes? (Recommended)"
+16. **ALWAYS offer logic audit** via smart AskUserQuestion with specific file counts and test results
 
 **Phase 4: Completion**
-15. Update status.json (mark story done)
-16. **RELEASE THE STORY claim:**
+17. Update status.json (mark story done)
+18. **RELEASE THE STORY claim:**
     ```bash
     node .agileflow/scripts/lib/story-claiming.js release <story-id>
     ```
-17. Present next steps via AskUserQuestion **(including Logic Audit option)**
+19. Present next steps via smart AskUserQuestion
 
-**Post-Implementation Options** (offer via AskUserQuestion):
-- "Run tests to verify" - Standard verification
-- "🔍 Run logic audit" - Multi-agent analysis for logic bugs (recommended for complex code)
-- "Continue to next story" - Move on
-- "Review changes" - Manual review
-- "Pause here" - Stop for now
+**Post-Implementation Options** (ALWAYS offer via smart AskUserQuestion):
+- "Run tests to verify (Recommended)" - with specific test command and file count
+- "🔍 Run logic audit on N modified files" - **ALWAYS include this** - 5 analyzers check edge cases, race conditions, type bugs
+- "Commit: '[type]: [summary]'" - with specific commit message suggestion
+- "Continue to next story" - with story ID and epic progress
+- "Pause here" - with summary of what's saved/uncommitted
 
 ---
 
@@ -673,19 +678,37 @@ Present top 3-5 via AskUserQuestion, always include "Other" option.
 
 ### LOGIC AUDIT INTEGRATION
 
-After completing an implementation, offer logic audit as an **optional quality check**:
+**ALWAYS suggest logic audit after ANY implementation** - whether from a plan, direct coding, or expert delegation. This is a standard post-implementation step, not optional.
 
+**Smart AskUserQuestion after implementation:**
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Implementation complete. What would you like to do?",
+  "question": "Implementation complete (3 files changed, 85 lines added). What's next?",
   "header": "Next step",
   "multiSelect": false,
   "options": [
-    {"label": "Run tests (Recommended)", "description": "Verify with test suite"},
-    {"label": "🔍 Run logic audit", "description": "Multi-agent analysis for edge cases, race conditions, type bugs"},
-    {"label": "Continue to next story", "description": "Move on without additional checks"},
-    {"label": "Pause here", "description": "Stop for now"}
+    {"label": "Run npm test in packages/cli/ (Recommended)", "description": "3 files changed in scripts/ - verify before committing"},
+    {"label": "🔍 Run logic audit on 3 modified files", "description": "5 analyzers check for edge cases, race conditions, type bugs - catches issues tests miss"},
+    {"label": "Commit: 'feat: add session tracking'", "description": "Skip verification - only if changes are trivial"},
+    {"label": "Pause here", "description": "Changes saved, not committed"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**After tests pass, suggest logic audit again if not yet run:**
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "All 4373 tests pass. Ready to finalize?",
+  "header": "Next step",
+  "multiSelect": false,
+  "options": [
+    {"label": "🔍 Run logic audit on 3 modified files (Recommended)", "description": "5 analyzers catch edge cases tests miss - quick check before commit"},
+    {"label": "Commit: 'feat: add session tracking'", "description": "All tests pass, skip logic audit"},
+    {"label": "Continue to US-0044", "description": "EP-0018 is 85% done - 2 stories left"},
+    {"label": "Pause here", "description": "Tests pass, changes not committed"}
   ]
 }]</parameter>
 </invoke>
@@ -696,19 +719,25 @@ After completing an implementation, offer logic audit as an **optional quality c
 2. Run: `/agileflow:logic:audit <modified-files> DEPTH=quick`
 3. Review findings with user
 4. Offer to fix any P0/P1 issues immediately
-5. Then present next steps again
+5. Then present next steps again with smart AskUserQuestion
 
 ---
 
 ### SMART ASKUSERQUESTION EXAMPLES
 
 After implementation:
-- "Run `npm test` in packages/cli/ (Recommended)" + "3 files changed, verify before commit"
-- "🔍 Run logic audit on modified files" + "5 analyzers check for edge cases"
+- "Run `npm test` in packages/cli/ (Recommended)" + "3 files changed in scripts/ - verify before committing"
+- "🔍 Run logic audit on 3 modified files" + "5 analyzers check edge cases, race conditions, type bugs"
+- "Pause here" + "Changes saved, not committed"
 
-After tests pass:
-- "Commit: 'fix: resolve tmux socket path' (Recommended)" + "All tests pass"
-- "Review diff before committing" + "14 files touched"
+After tests pass (logic audit NOT yet run):
+- "🔍 Run logic audit on 3 modified files (Recommended)" + "Quick check catches what tests miss - edge cases, race conditions"
+- "Commit: 'fix: resolve tmux socket path'" + "All 4373 tests pass, skip audit"
+- "Continue to US-0044" + "EP-0018 is 85% done"
+
+After tests pass (logic audit already done):
+- "Commit: 'fix: resolve tmux socket path' (Recommended)" + "All tests pass, logic audit clean"
+- "Review diff before committing" + "14 files touched across 3 directories"
 
 After error:
 - "Try alternative: use execFileSync instead (Recommended)" + "Current approach has shell injection risk"
@@ -726,14 +755,14 @@ After error:
 - Delegate complex work to experts
 - If stuck 2+ times → research prompt
 - Use state narration markers (📍🔀🔄⚠️✅) for visibility
+- **LOGIC AUDIT - ALWAYS SUGGEST**: After ANY implementation (plan or direct), ALWAYS include "🔍 Run logic audit" as an option. After tests pass but before commit, make it (Recommended).
 - **PLAN FILE CONTEXT - CRITICAL:**
-  BEFORE ExitPlanMode, EDIT the plan file to add babysit rules header at TOP
+  BEFORE ExitPlanMode, EDIT the plan file to add babysit rules header at TOP (with smart AskUserQuestion format and logic audit)
   This ensures rules survive "Clear context and bypass permissions"
 - **STORY CLAIMING - CRITICAL:**
   1. BEFORE suggesting: `node .agileflow/scripts/lib/story-claiming.js others` → exclude 🔒
   2. AFTER user selects: `node .agileflow/scripts/lib/story-claiming.js claim <id>`
   3. WHEN done: `node .agileflow/scripts/lib/story-claiming.js release <id>`
-
 ---
 
 ## 🛑 FINAL ACTION REQUIRED - DO NOT SKIP
@@ -1175,12 +1204,16 @@ When stuck detection triggers:
    ## ⚠️ MANDATORY IMPLEMENTATION RULES (from /babysit)
 
    These rules MUST be followed during implementation:
-   1. ALWAYS end your final response with AskUserQuestion tool
-   2. Use EnterPlanMode if new non-trivial tasks arise
-   3. Delegate complex work to domain experts
-   4. Track progress with TaskCreate/TaskUpdate
-
-   After implementation, call AskUserQuestion with next step options.
+   1. **ALWAYS end with SMART AskUserQuestion** - specific options with (Recommended), contextual descriptions, file counts
+   2. **Use EnterPlanMode** if new non-trivial tasks arise
+   3. **Delegate complex work** to domain experts via Task tool
+   4. **Track progress** with TaskCreate/TaskUpdate for multi-step work
+
+   After implementation, ALWAYS call AskUserQuestion with:
+   - "Run tests (Recommended)" with specific command and file count
+   - "🔍 Run logic audit on N modified files" - ALWAYS include this
+   - "Commit: '[type]: [summary]'" with suggested message
+   - "Pause here" with save state summary
 
    ---
    ```

package/src/core/commands/blockers.md

@@ -156,18 +156,18 @@ DETAILED=true        # Show extended details (dependencies, ADRs, research)
 
 ## Confirmation & Integration
 
-After displaying blockers:
+After displaying blockers (use actual counts and data from analysis):
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "What would you like to do?",
-  "header": "Blocker Actions",
+  "question": "[N] blockers found ([critical] critical, [stale] stale >14d). What next?",
+  "header": "Resolve",
   "multiSelect": false,
   "options": [
-    {"label": "Update blocker status", "description": "Mark blocker as resolved"},
-    {"label": "Create unblocking story", "description": "Create story to unblock"},
-    {"label": "View ADR details", "description": "See related architecture decisions"},
-    {"label": "Escalate blocker", "description": "Escalate for decision"}
+    {"label": "Resolve [top_blocker_id]: [reason] (Recommended)", "description": "[category] blocker, [age] days old - [resolution_hint]"},
+    {"label": "Create unblocking story for [blocker_id]", "description": "[blocker_summary] - needs [effort] to unblock [N] downstream stories"},
+    {"label": "View [N] related ADRs/research", "description": "Found [adr_count] ADRs and [research_count] research notes matching blockers"},
+    {"label": "Done - report only", "description": "[N] blockers documented, no action needed now"}
   ]
 }]</parameter>
 </invoke>