@sienklogic/plan-build-run 2.4.1 → 2.6.0

package/plugins/cursor-pbr/skills/statusline/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: statusline
+description: "Install or configure the PBR status line in Claude Code."
+argument-hint: "[install | uninstall | preview]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~3,000 tokens. Begin executing Step 0 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► STATUS LINE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
+# /pbr:statusline — Status Line Setup
+
+The PBR status line displays live project state (phase, plan, status, git branch, context usage) in the Claude Code terminal status bar.
+
+---
+
+## Subcommand Parsing
+
+Parse `$ARGUMENTS`:
+
+| Argument | Action |
+|----------|--------|
+| `install` or empty | Install/enable the status line |
+| `uninstall` or `remove` | Remove the status line configuration |
+| `preview` | Show what the status line looks like without installing |
+
+---
+
+## Subcommand: install (default)
+
+### Step 1: Locate the status-line script
+
+**CRITICAL: You must resolve the correct absolute path to `status-line.js`. Do NOT hardcode paths.**
+
+1. The script lives at `${PLUGIN_ROOT}/scripts/status-line.js`
+2. Resolve `${PLUGIN_ROOT}` to its absolute path using `pwd` or by checking the plugin root
+3. If running from a local plugin dir (`claude --plugin-dir .`), the path is the local repo's `plugins/pbr/scripts/status-line.js`
+4. If running from the installed plugin cache (`~/.claude/plugins/cache/`), use that path
+5. **Verify the script exists** with `ls` before proceeding. If it doesn't exist, show an error and stop.
+
+Store the resolved absolute path as `SCRIPT_PATH`.
+
+### Step 2: Read current settings
+
+Read `~/.claude/settings.json` (or `$HOME/.claude/settings.json`).
+
+- If the file doesn't exist: start with an empty object `{}`
+- If it exists: parse the JSON content
+- Check if `statusLine` key already exists:
+  - If yes and points to the same script: inform user "PBR status line is already installed." and stop (unless they want to reconfigure)
+  - If yes but points to a different command: warn user and ask if they want to replace it
+
+### Step 3: Configure settings.json
+
+Use AskUserQuestion:
+  question: "Install the PBR status line? This adds a `statusLine` entry to ~/.claude/settings.json."
+  header: "Install?"
+  options:
+    - label: "Install"  description: "Enable the PBR status line in Claude Code"
+    - label: "Preview first"  description: "Show a preview before installing"
+    - label: "Cancel"  description: "Don't install"
+  multiSelect: false
+
+If "Preview first": run the preview subcommand (show sample output), then ask again.
+If "Cancel": stop.
+If "Install":
+
+**CRITICAL: Use Read tool to read the file, then Write to update it. Do NOT use sed or other text manipulation on JSON files.**
+
+1. Read `~/.claude/settings.json`
+2. Parse the JSON
+3. Set `statusLine` to:
+   ```json
+   {
+     "type": "command",
+     "command": "node \"SCRIPT_PATH\""
+   }
+   ```
+   Where `SCRIPT_PATH` is the resolved absolute path from Step 1. Use forward slashes even on Windows.
+4. Write the updated JSON back (preserve all other settings, use 2-space indentation)
+
+### Step 4: Verify and confirm
+
+Display:
+```
+✓ PBR status line installed
+
+  Script: {SCRIPT_PATH}
+  Config: ~/.claude/settings.json
+
+The status line will appear on your next Claude Code session.
+Restart Claude Code or run `/clear` to activate it now.
+
+Customize per-project via .planning/config.json:
+  "status_line": {
+    "sections": ["phase", "plan", "status", "git", "context"],
+    "brand_text": "PBR"
+  }
+```
+
+---
+
+## Subcommand: uninstall
+
+1. Read `~/.claude/settings.json`
+2. If no `statusLine` key: inform user "No status line configured." and stop
+3. Remove the `statusLine` key from the JSON
+4. Write the updated file
+5. Display: `✓ PBR status line removed. Restart Claude Code to take effect.`
+
+---
+
+## Subcommand: preview
+
+1. Locate and run the status-line script: `node {SCRIPT_PATH}`
+   - Pass sample stdin JSON: `{"context_window": {"used_percentage": 35}, "model": {"display_name": "Claude Opus 4.6"}, "cost": {"total_cost_usd": 0.42}}`
+2. Display the raw output to the user
+3. Also show a description of each section:
+   - **Phase**: Current phase number and name from STATE.md
+   - **Plan**: Plan progress (N of M)
+   - **Status**: Phase status keyword (planning, building, built, etc.)
+   - **Git**: Current branch + dirty indicator
+   - **Context**: Unicode bar showing context window usage (green/yellow/red)
+
+---
+
+## Edge Cases
+
+### No .planning/ directory
+The status line works even without `.planning/` — it will show only git and context sections. Installation doesn't require a PBR project.
+
+### Plugin installed from npm vs local
+The script path differs between `~/.claude/plugins/cache/plan-build-run/pbr/{version}/scripts/status-line.js` and a local `plugins/pbr/scripts/status-line.js`. The install command must resolve the actual path at install time.
+
+### Existing non-PBR status line
+If `statusLine` already exists with a different command, warn the user and confirm before replacing.

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/commands/statusline.md

@@ -0,0 +1,5 @@
+---
+description: "Install or configure the PBR status line in Claude Code."
+---
+
+This command is provided by the `dev:statusline` skill.

package/plugins/pbr/scripts/auto-continue.js

@@ -49,6 +49,20 @@ function main() {
 
     // Check for signal file
     if (!fs.existsSync(signalPath)) {
+      // No auto-continue signal — check for pending todos as a reminder
+      const todoPendingDir = path.join(planningDir, 'todos', 'pending');
+      try {
+        if (fs.existsSync(todoPendingDir)) {
+          const pending = fs.readdirSync(todoPendingDir).filter(f => f.endsWith('.md'));
+          if (pending.length > 0) {
+            logHook('auto-continue', 'Stop', 'pending-todos', { count: pending.length });
+            // Non-blocking reminder — write to stderr so it shows in hook output
+            process.stderr.write(`[pbr] ${pending.length} pending todo(s) in .planning/todos/pending/ — run /pbr:todo list to review\n`);
+          }
+        }
+      } catch (_todoErr) {
+        // Ignore errors scanning todos
+      }
       logHook('auto-continue', 'Stop', 'no-signal', {});
       process.exit(0);
     }

package/plugins/pbr/scripts/check-dangerous-commands.js

@@ -19,6 +19,8 @@
  *   2 = blocked (destructive command detected)
  */
 
+const fs = require('fs');
+const path = require('path');
 const { logHook } = require('./hook-logger');
 
 // Commands that are outright blocked
@@ -107,10 +109,52 @@ function checkDangerous(data) {
     }
   }
 
+  // Skill-specific checks
+  const skillResult = checkSkillSpecificBash(command);
+  if (skillResult) return skillResult;
+
   // No match — allow
   return null;
 }
 
+/**
+ * Skill-specific bash command checks.
+ * Currently: statusline skill cannot use sed/awk/perl on JSON files.
+ */
+function checkSkillSpecificBash(command) {
+  const planningDir = path.join(process.cwd(), '.planning');
+  const skillFile = path.join(planningDir, '.active-skill');
+
+  let activeSkill = null;
+  try {
+    activeSkill = fs.readFileSync(skillFile, 'utf8').trim();
+  } catch (_e) {
+    return null;
+  }
+
+  if (activeSkill !== 'statusline') return null;
+
+  // Block sed/awk/perl targeting .json files
+  const jsonManipPattern = /\b(sed|awk|perl)\b.*\.json/;
+  const echoRedirectPattern = /echo\s.*>\s*.*\.json/;
+
+  if (jsonManipPattern.test(command) || echoRedirectPattern.test(command)) {
+    logHook('check-dangerous-commands', 'PreToolUse', 'block', {
+      command: command.substring(0, 200),
+      reason: 'JSON shell manipulation during statusline'
+    });
+    return {
+      output: {
+        decision: 'block',
+        reason: 'CRITICAL: Use Read + Write tools for JSON files, not shell text manipulation. Shell tools can corrupt JSON structure.'
+      },
+      exitCode: 2
+    };
+  }
+
+  return null;
+}
+
 function main() {
   let input = '';
 

package/plugins/pbr/scripts/check-skill-workflow.js

@@ -114,6 +114,12 @@ function checkSkillRules(skill, filePath, planningDir) {
     return checkQuickRules(filePath, isInPlanning, planningDir);
   case 'build':
     return checkBuildRules(filePath, isInPlanning, planningDir);
+  case 'statusline':
+    return checkStatuslineRules(filePath, isInPlanning, planningDir);
+  case 'review':
+  case 'discuss':
+  case 'begin':
+    return checkReadOnlySkillRules(skill, filePath, isInPlanning);
   default:
     return null;
   }
@@ -205,6 +211,63 @@ function checkBuildRules(filePath, isInPlanning, planningDir) {
   }
 }
 
+/**
+ * /pbr:statusline rules:
+ * - Warn when writing settings.json with hardcoded home directory paths
+ */
+function checkStatuslineRules(filePath, _isInPlanning, _planningDir) {
+  const normalizedPath = filePath.replace(/\\/g, '/');
+
+  // Only check settings.json writes
+  if (!normalizedPath.endsWith('settings.json')) return null;
+
+  // Check tool_input content isn't available here — we only have filePath.
+  // The hardcoded path check needs content, which we get from the hook data.
+  // This function is called from checkSkillRules which only passes filePath.
+  // We'll check in the wrapper instead. For now, return null (pass).
+  return null;
+}
+
+/**
+ * Extended statusline check that includes content inspection.
+ * Called from checkWorkflow/main where we have access to full hook data.
+ */
+function checkStatuslineContent(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  const normalizedPath = filePath.replace(/\\/g, '/');
+
+  if (!normalizedPath.endsWith('settings.json')) return null;
+
+  // Check new_string (Edit) or content (Write) for hardcoded home paths
+  const content = data.tool_input?.new_string || data.tool_input?.content || '';
+  const oldString = data.tool_input?.old_string || '';
+  const textToCheck = content + ' ' + oldString;
+
+  // Hardcoded home directory paths — warn, don't block (may be legitimately resolved)
+  const hardcodedPathPattern = /(\/home\/|C:\\Users\\|\/Users\/)[^"'\s]*\.claude/i;
+  if (hardcodedPathPattern.test(textToCheck)) {
+    return {
+      rule: 'statusline-hardcoded-path',
+      message: `Warning: settings.json write appears to contain a hardcoded home directory path.\n\nFile: ${filePath}\n\nCRITICAL: Do NOT hardcode paths. Use dynamic path resolution to find the correct plugin installation directory.`
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Read-only skill rules (review, discuss, begin):
+ * - Cannot write files outside .planning/
+ */
+function checkReadOnlySkillRules(skill, filePath, isInPlanning) {
+  if (isInPlanning) return null;
+
+  return {
+    rule: `${skill}-readonly`,
+    message: `Workflow violation: /pbr:${skill} should only write to .planning/ files.\n\nBlocked: ${filePath}\n\nThe ${skill} skill is not intended to modify source code.`
+  };
+}
+
 /**
  * Check if any PLAN.md file exists in a directory (recursive one level).
  */
@@ -214,10 +277,10 @@ function hasPlanFile(dir) {
   try {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith('PLAN.md')) return true;
+      if (entry.isFile() && /^PLAN.*\.md$/i.test(entry.name)) return true;
       if (entry.isDirectory()) {
         const subEntries = fs.readdirSync(path.join(dir, entry.name));
-        if (subEntries.some(f => f.endsWith('PLAN.md'))) return true;
+        if (subEntries.some(f => /^PLAN.*\.md$/i.test(f))) return true;
       }
     }
   } catch (_e) {
@@ -255,8 +318,22 @@ function checkWorkflow(data) {
     };
   }
 
+  // Statusline content check (needs full data for content inspection)
+  if (activeSkill === 'statusline') {
+    const contentViolation = checkStatuslineContent(data);
+    if (contentViolation) {
+      logHook('check-skill-workflow', 'PreToolUse', 'warn', {
+        skill: activeSkill, file: path.basename(filePath), rule: contentViolation.rule
+      });
+      return {
+        exitCode: 0,
+        output: { additionalContext: contentViolation.message }
+      };
+    }
+  }
+
   return null;
 }
 
-module.exports = { readActiveSkill, checkSkillRules, hasPlanFile, checkWorkflow };
+module.exports = { readActiveSkill, checkSkillRules, hasPlanFile, checkWorkflow, checkStatuslineContent, checkReadOnlySkillRules };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/check-subagent-output.js

@@ -24,8 +24,13 @@ const { logHook } = require('./hook-logger');
 // Agent type → expected output patterns
 const AGENT_OUTPUTS = {
   'pbr:executor': {
-    description: 'SUMMARY.md in the phase directory',
-    check: (planningDir) => findInPhaseDir(planningDir, /^SUMMARY.*\.md$/i)
+    description: 'SUMMARY.md in the phase or quick directory',
+    check: (planningDir) => {
+      // Check phase directory first, then quick directory
+      const phaseMatches = findInPhaseDir(planningDir, /^SUMMARY.*\.md$/i);
+      if (phaseMatches.length > 0) return phaseMatches;
+      return findInQuickDir(planningDir, /^SUMMARY.*\.md$/i);
+    }
   },
   'pbr:planner': {
     description: 'PLAN.md in the phase directory',
@@ -48,6 +53,69 @@ const AGENT_OUTPUTS = {
         return [];
       }
     }
+  },
+  'pbr:synthesizer': {
+    description: 'synthesis file in .planning/research/ or CONTEXT.md update',
+    check: (planningDir) => {
+      const researchDir = path.join(planningDir, 'research');
+      if (fs.existsSync(researchDir)) {
+        try {
+          const files = fs.readdirSync(researchDir).filter(f => f.endsWith('.md'));
+          if (files.length > 0) return files.map(f => path.join('research', f));
+        } catch (_e) { /* best-effort */ }
+      }
+      const contextFile = path.join(planningDir, 'CONTEXT.md');
+      if (fs.existsSync(contextFile)) {
+        try {
+          const stat = fs.statSync(contextFile);
+          if (stat.size > 0) return ['CONTEXT.md'];
+        } catch (_e) { /* best-effort */ }
+      }
+      return [];
+    }
+  },
+  'pbr:plan-checker': {
+    description: 'advisory output (no file expected)',
+    noFileExpected: true,
+    check: () => []
+  },
+  'pbr:integration-checker': {
+    description: 'advisory output (no file expected)',
+    noFileExpected: true,
+    check: () => []
+  },
+  'pbr:debugger': {
+    description: 'debug file in .planning/debug/',
+    check: (planningDir) => {
+      const debugDir = path.join(planningDir, 'debug');
+      if (!fs.existsSync(debugDir)) return [];
+      try {
+        return fs.readdirSync(debugDir)
+          .filter(f => f.endsWith('.md'))
+          .map(f => path.join('debug', f));
+      } catch (_e) {
+        return [];
+      }
+    }
+  },
+  'pbr:codebase-mapper': {
+    description: 'codebase map in .planning/codebase/',
+    check: (planningDir) => {
+      const codebaseDir = path.join(planningDir, 'codebase');
+      if (!fs.existsSync(codebaseDir)) return [];
+      try {
+        return fs.readdirSync(codebaseDir)
+          .filter(f => f.endsWith('.md'))
+          .map(f => path.join('codebase', f));
+      } catch (_e) {
+        return [];
+      }
+    }
+  },
+  'pbr:general': {
+    description: 'advisory output (no file expected)',
+    noFileExpected: true,
+    check: () => []
   }
 };
 
@@ -87,6 +155,39 @@ function findInPhaseDir(planningDir, pattern) {
   return matches;
 }
 
+function findInQuickDir(planningDir, pattern) {
+  const matches = [];
+  const quickDir = path.join(planningDir, 'quick');
+  if (!fs.existsSync(quickDir)) return matches;
+
+  try {
+    // Find the most recent quick task directory (highest NNN)
+    const dirs = fs.readdirSync(quickDir)
+      .filter(d => /^\d{3}-/.test(d))
+      .sort()
+      .reverse();
+    if (dirs.length === 0) return matches;
+
+    const latestDir = path.join(quickDir, dirs[0]);
+    const stat = fs.statSync(latestDir);
+    if (!stat.isDirectory()) return matches;
+
+    const files = fs.readdirSync(latestDir);
+    for (const file of files) {
+      if (pattern.test(file)) {
+        const filePath = path.join(latestDir, file);
+        const fileStat = fs.statSync(filePath);
+        if (fileStat.size > 0) {
+          matches.push(path.join('quick', dirs[0], file));
+        }
+      }
+    }
+  } catch (_e) {
+    // best-effort
+  }
+  return matches;
+}
+
 function readStdin() {
   try {
     const input = fs.readFileSync(0, 'utf8').trim();
@@ -119,7 +220,7 @@ function main() {
   // Check for expected outputs
   const found = outputSpec.check(planningDir);
 
-  if (found.length === 0) {
+  if (found.length === 0 && !outputSpec.noFileExpected) {
     logHook('check-subagent-output', 'PostToolUse', 'warning', {
       agent_type: agentType,
       expected: outputSpec.description,
@@ -140,5 +241,5 @@ function main() {
   process.exit(0);
 }
 
-module.exports = { AGENT_OUTPUTS, findInPhaseDir };
+module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir };
 if (require.main === module || process.argv[1] === __filename) { main(); }