@sienklogic/plan-build-run 2.2.0 → 2.3.0

package/dashboard/public/css/layout.css

@@ -267,6 +267,72 @@ details li {
   background: rgba(255, 255, 255, 0.06);
 }
 
+/* --- Markdown Body (rendered markdown content) --- */
+.markdown-body h1 { font-size: 1.5rem; margin-top: var(--space-xl); margin-bottom: var(--space-sm); }
+.markdown-body h2 { font-size: 1.25rem; margin-top: var(--space-xl); margin-bottom: var(--space-sm); }
+.markdown-body h3 { font-size: 1.05rem; margin-top: var(--space-lg); margin-bottom: var(--space-xs); }
+
+.markdown-body table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: var(--space-md) 0;
+  font-size: 0.875rem;
+}
+
+.markdown-body th,
+.markdown-body td {
+  border: 1px solid var(--border-subtle);
+  padding: var(--space-xs) var(--space-sm);
+  text-align: left;
+}
+
+.markdown-body th {
+  background: rgba(255, 255, 255, 0.04);
+}
+
+.markdown-body pre {
+  background: rgba(0, 0, 0, 0.3);
+  border-radius: var(--radius-sm);
+  padding: var(--space-md);
+  overflow-x: auto;
+  margin: var(--space-md) 0;
+}
+
+.markdown-body pre code {
+  background: none;
+  padding: 0;
+  font-size: 0.85em;
+}
+
+.markdown-body blockquote {
+  border-left: 3px solid var(--pico-primary);
+  background: rgba(255, 255, 255, 0.02);
+  margin: var(--space-md) 0;
+  padding: var(--space-sm) var(--space-md);
+}
+
+.markdown-body ul.contains-task-list {
+  list-style: none;
+  padding-left: var(--space-sm);
+}
+
+.markdown-body ul.contains-task-list li {
+  position: relative;
+  padding-left: var(--space-xs);
+}
+
+.markdown-body img {
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--radius-sm);
+}
+
+.markdown-body hr {
+  border: none;
+  border-top: 1px solid var(--border-subtle);
+  margin: var(--space-lg) 0;
+}
+
 /* --- Back Link --- */
 main > p:first-of-type > a[href="/"] {
   font-size: 0.875rem;

package/dashboard/src/repositories/planning.repository.js

@@ -3,6 +3,8 @@ import { join, resolve, relative, normalize } from 'node:path';
 import matter from 'gray-matter';
 import { marked } from 'marked';
 
+marked.setOptions({ gfm: true, breaks: false });
+
 /**
  * Strip UTF-8 BOM (Byte Order Mark) if present.
  * Windows editors (Notepad, older VS Code) may prepend BOM to UTF-8 files.

package/dashboard/src/routes/pages.routes.js

@@ -3,6 +3,7 @@ import { getPhaseDetail, getPhaseDocument } from '../services/phase.service.js';
 import { getRoadmapData } from '../services/roadmap.service.js';
 import { parseStateFile, derivePhaseStatuses } from '../services/dashboard.service.js';
 import { listPendingTodos, getTodoDetail, createTodo, completeTodo } from '../services/todo.service.js';
+import { getAllMilestones, getMilestoneDetail } from '../services/milestone.service.js';
 
 const router = Router();
 
@@ -225,6 +226,61 @@ router.post('/todos/:id/done', async (req, res) => {
   }
 });
 
+router.get('/milestones', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const milestoneData = await getAllMilestones(projectDir);
+
+  const templateData = {
+    title: 'Milestones',
+    activePage: 'milestones',
+    currentPath: '/milestones',
+    ...milestoneData
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/milestones-content', templateData);
+  } else {
+    res.render('milestones', templateData);
+  }
+});
+
+router.get('/milestones/:version', async (req, res) => {
+  const { version } = req.params;
+
+  // Validate version: alphanumeric with dots and dashes
+  if (!/^[\w.-]+$/.test(version)) {
+    const err = new Error('Invalid milestone version format');
+    err.status = 404;
+    throw err;
+  }
+
+  const projectDir = req.app.locals.projectDir;
+  const detail = await getMilestoneDetail(projectDir, version);
+
+  if (detail.sections.length === 0) {
+    const err = new Error(`No archived files found for milestone v${version}`);
+    err.status = 404;
+    throw err;
+  }
+
+  const templateData = {
+    title: `Milestone v${version}`,
+    activePage: 'milestones',
+    currentPath: '/milestones/' + version,
+    ...detail
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/milestone-detail-content', templateData);
+  } else {
+    res.render('milestone-detail', templateData);
+  }
+});
+
 router.get('/roadmap', async (req, res) => {
   const projectDir = req.app.locals.projectDir;
   const [roadmapData, stateData] = await Promise.all([

package/dashboard/src/services/milestone.service.js

@@ -0,0 +1,103 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readMarkdownFile } from '../repositories/planning.repository.js';
+import { getRoadmapData } from './roadmap.service.js';
+
+/**
+ * Scan .planning/milestones/ for archived milestone files.
+ * Groups files by version prefix (e.g., v1.0-ROADMAP.md, v1.0-STATS.md).
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Promise<Array<{version: string, name: string, date: string, duration: string, files: string[]}>>}
+ */
+export async function listArchivedMilestones(projectDir) {
+  const milestonesDir = join(projectDir, '.planning', 'milestones');
+
+  let entries;
+  try {
+    entries = await readdir(milestonesDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+
+  // Group files by version prefix: v1.0-ROADMAP.md -> version "1.0"
+  const versionMap = new Map();
+  const versionPattern = /^v([\w.-]+)-(\w+)\.md$/;
+
+  for (const file of entries) {
+    const match = file.match(versionPattern);
+    if (!match) continue;
+
+    const version = match[1];
+    if (!versionMap.has(version)) {
+      versionMap.set(version, { version, name: '', date: '', duration: '', files: [] });
+    }
+    versionMap.get(version).files.push(file);
+  }
+
+  // Try to parse STATS.md for each version to get name/date/duration
+  for (const [version, milestone] of versionMap) {
+    const statsFile = `v${version}-STATS.md`;
+    if (milestone.files.includes(statsFile)) {
+      try {
+        const { frontmatter } = await readMarkdownFile(join(milestonesDir, statsFile));
+        milestone.name = frontmatter.milestone || frontmatter.name || `v${version}`;
+        milestone.date = frontmatter.completed || frontmatter.date || '';
+        milestone.duration = frontmatter.duration || '';
+      } catch (_e) {
+        milestone.name = `v${version}`;
+      }
+    } else {
+      milestone.name = `v${version}`;
+    }
+  }
+
+  // Sort by version descending (newest first)
+  return [...versionMap.values()].sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }));
+}
+
+/**
+ * Combine active milestones from ROADMAP.md with archived milestones.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Promise<{active: Array, archived: Array}>}
+ */
+export async function getAllMilestones(projectDir) {
+  const [roadmapData, archived] = await Promise.all([
+    getRoadmapData(projectDir),
+    listArchivedMilestones(projectDir)
+  ]);
+
+  return {
+    active: roadmapData.milestones || [],
+    archived
+  };
+}
+
+/**
+ * Read all archived files for a specific milestone version.
+ * Returns rendered HTML for each file type (ROADMAP, STATS, REQUIREMENTS).
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @param {string} version - Milestone version (e.g., "1.0")
+ * @returns {Promise<{version: string, sections: Array<{type: string, frontmatter: object, html: string}>}>}
+ */
+export async function getMilestoneDetail(projectDir, version) {
+  const milestonesDir = join(projectDir, '.planning', 'milestones');
+  const fileTypes = ['ROADMAP', 'STATS', 'REQUIREMENTS'];
+
+  const sections = [];
+  for (const type of fileTypes) {
+    const filePath = join(milestonesDir, `v${version}-${type}.md`);
+    try {
+      const result = await readMarkdownFile(filePath);
+      sections.push({ type, frontmatter: result.frontmatter, html: result.html });
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      // File doesn't exist for this type — skip
+    }
+  }
+
+  return { version, sections };
+}

package/dashboard/src/views/milestone-detail.ejs

@@ -0,0 +1,5 @@
+<%- include('partials/layout-top', { title: 'Milestone v' + version, activePage: 'milestones' }) %>
+
+<%- include('partials/milestone-detail-content') %>
+
+<%- include('partials/layout-bottom') %>

package/dashboard/src/views/milestones.ejs

@@ -0,0 +1,5 @@
+<%- include('partials/layout-top', { title: 'Milestones', activePage: 'milestones' }) %>
+
+<%- include('partials/milestones-content') %>
+
+<%- include('partials/layout-bottom') %>

package/dashboard/src/views/partials/head.ejs

@@ -4,10 +4,16 @@
   <title><%= typeof title !== 'undefined' ? title : 'Plan-Build-Run' %> - Plan-Build-Run</title>
   <link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin>
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-400-normal.min.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-600-normal.min.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-700-normal.min.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/jetbrains-mono@latest/latin-400-normal.min.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-400-normal.min.css" media="print" onload="this.media='all'">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-600-normal.min.css" media="print" onload="this.media='all'">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-700-normal.min.css" media="print" onload="this.media='all'">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/jetbrains-mono@latest/latin-400-normal.min.css" media="print" onload="this.media='all'">
+  <noscript>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-400-normal.min.css">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-600-normal.min.css">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-700-normal.min.css">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/jetbrains-mono@latest/latin-400-normal.min.css">
+  </noscript>
   <link rel="stylesheet" href="/css/layout.css">
   <link rel="stylesheet" href="/css/status-colors.css">
   <script

package/dashboard/src/views/partials/milestone-detail-content.ejs

@@ -0,0 +1,19 @@
+<h1>Milestone v<%= version %></h1>
+
+<p>
+  <a href="/milestones"
+     hx-get="/milestones"
+     hx-target="#main-content"
+     hx-push-url="true">&larr; Back to Milestones</a>
+</p>
+
+<% sections.forEach(function(section) { %>
+<article>
+  <header>
+    <strong><%= section.type %></strong>
+  </header>
+  <div class="markdown-body">
+    <%- section.html %>
+  </div>
+</article>
+<% }); %>

package/dashboard/src/views/partials/milestones-content.ejs

@@ -0,0 +1,44 @@
+<h1>Milestones</h1>
+
+<% if (active.length > 0) { %>
+<h2>Active</h2>
+<% active.forEach(function(m) { %>
+<article>
+  <header>
+    <strong><%= m.name %></strong>
+    <% if (m.goal) { %><small> &mdash; <%= m.goal %></small><% } %>
+  </header>
+  <p>
+    Phases <%= m.startPhase %> &ndash; <%= m.endPhase %>
+  </p>
+</article>
+<% }); %>
+<% } %>
+
+<% if (archived.length > 0) { %>
+<h2>Archived</h2>
+<% archived.forEach(function(m) { %>
+<article>
+  <header>
+    <strong>
+      <a href="/milestones/<%= m.version %>"
+         hx-get="/milestones/<%= m.version %>"
+         hx-target="#main-content"
+         hx-push-url="true">
+        v<%= m.version %> &mdash; <%= m.name %>
+      </a>
+    </strong>
+  </header>
+  <p>
+    <% if (m.date) { %><small>Completed: <%= m.date %></small><% } %>
+    <% if (m.duration) { %><small> &bull; Duration: <%= m.duration %></small><% } %>
+    <br>
+    <small><%= m.files.length %> archived file<%= m.files.length !== 1 ? 's' : '' %></small>
+  </p>
+</article>
+<% }); %>
+<% } %>
+
+<% if (active.length === 0 && archived.length === 0) { %>
+<p>No milestones found. Use <code>/pbr:milestone new</code> to create one.</p>
+<% } %>

package/dashboard/src/views/partials/sidebar.ejs

@@ -33,6 +33,14 @@
           Roadmap
         </a>
       </li>
+      <li>
+        <a href="/milestones"
+           hx-get="/milestones"
+           hx-target="#main-content"
+           hx-push-url="true"<%= typeof activePage !== 'undefined' && activePage === 'milestones' ? ' aria-current="page"' : '' %>>
+          Milestones
+        </a>
+      </li>
     </ul>
   </nav>
 </aside>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

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

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/hooks/hooks.json

@@ -106,6 +106,16 @@
             "statusMessage": "Validating Task() call..."
           }
         ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" validate-skill-args.js",
+            "statusMessage": "Validating skill arguments..."
+          }
+        ]
       }
     ],
     "PreCompact": [

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

@@ -0,0 +1,22 @@
+---
+name: dashboard
+description: "Launch the PBR web dashboard for the current project."
+argument-hint: "[--port N]"
+---
+
+## Behavior
+
+1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.
+
+2. **Check dependencies**: Check if the dashboard `node_modules/` exists in the plugin's dashboard directory. If not, run `npm install` in that directory.
+
+3. **Launch dashboard**: Run in background:
+   ```
+   node <plugin-root>/dashboard/bin/cli.js --dir <cwd> --port <port> &
+   ```
+
+4. **Output to user**:
+   ```
+   Dashboard running at http://localhost:<port>
+   Open this URL in your browser to view your project's planning state.
+   ```

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

@@ -63,9 +63,9 @@ Parse the phase number and optional flags:
 | `insert <N>` | Insert a new phase at position N (uses decimal numbering) |
 | `remove <N>` | Remove phase N from the roadmap |
 
-### Freeform Text Guard
+### Freeform Text Guard — CRITICAL
 
-**Before any context loading**, check whether `$ARGUMENTS` looks like freeform text rather than a valid invocation. Valid patterns are:
+**STOP. Before ANY context loading or Step 1 work**, you MUST check whether `$ARGUMENTS` looks like freeform text rather than a valid invocation. This check is non-negotiable. Valid patterns are:
 
 - Empty (no arguments)
 - A phase number: integer (`3`, `03`) or decimal (`3.1`)
@@ -97,6 +97,8 @@ Then suggest the appropriate skill based on the text content:
 
 Do NOT proceed with planning. The user needs to use the correct skill.
 
+**Self-check**: If you reach Step 1 without having matched a valid argument pattern above, you have a bug. Stop immediately and show the usage block.
+
 ---
 
 ## Orchestration Flow: Standard Planning

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

@@ -1,7 +1,7 @@
 ---
 name: todo
 description: "File-based persistent todos. Add, list, complete — survives sessions."
-argument-hint: "add <description> | list [theme] | done <NNN>"
+argument-hint: "add <description> | list [theme] | done <NNN> | work <NNN>"
 ---
 
 ## Step 0 — Immediate Output
@@ -121,12 +121,12 @@ Pending Todos:
 
 **Pick a todo** — mark one done or start working
 
-`/pbr:todo done <NNN>`
+`/pbr:todo work <NNN>` — start working on a todo
+`/pbr:todo done <NNN>` — mark a todo as complete
 
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
-- `/pbr:quick` — work on one now
 - `/pbr:status` — see project status
 
 ───────────────────────────────────────────────────────────────
@@ -178,6 +178,45 @@ Todo {NNN} not found in pending todos.
 ───────────────────────────────────────────────────────────────
 ```
 
+### `work <NNN>`
+
+1. Find `.planning/todos/pending/{NNN}-*.md` (match by number prefix)
+2. If not found, display the same error block as `done` — suggest `/pbr:todo list`
+3. Read the todo file content (frontmatter + body)
+4. Extract the `title` from frontmatter and the full body (Goal, Scope, Acceptance Criteria sections)
+5. Display branded output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Todo {NNN}:** {title}
+
+Launching /pbr:quick with todo context...
+```
+6. Invoke the Skill tool: `skill: "pbr:quick"` with `args` set to the todo title followed by the body content. Format the args as:
+
+```
+{title}
+
+Context from todo {NNN}:
+{body content — Goal, Scope, Acceptance Criteria sections}
+```
+
+This hands off execution to `/pbr:quick`, which will spawn an executor agent, make atomic commits, and track the work. When quick completes, remind the user:
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Mark this todo as done if the work is complete**
+
+`/pbr:todo done {NNN}`
+
+───────────────────────────────────────────────────────────────
+```
+
 ### No arguments
 
 Show a brief summary: count of pending todos, grouped by theme, plus usage hint.

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.0.0",
+  "version": "2.3.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/dashboard.md

@@ -0,0 +1,5 @@
+---
+description: "Launch the PBR web dashboard for the current project."
+---
+
+This command is provided by the `dev:dashboard` skill.

package/plugins/pbr/hooks/hooks.json

@@ -106,6 +106,16 @@
             "statusMessage": "Validating Task() call..."
           }
         ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" validate-skill-args.js",
+            "statusMessage": "Validating skill arguments..."
+          }
+        ]
       }
     ],
     "PreCompact": [

package/plugins/pbr/scripts/config-schema.json

@@ -211,6 +211,14 @@
       },
       "additionalProperties": false
     },
+    "dashboard": {
+      "type": "object",
+      "properties": {
+        "auto_launch": { "type": "boolean" },
+        "port": { "type": "integer", "minimum": 1024, "maximum": 65535 }
+      },
+      "additionalProperties": false
+    },
     "status_line": {
       "type": "object",
       "properties": {

package/plugins/pbr/scripts/progress-tracker.js

@@ -32,6 +32,12 @@ function main() {
 
   const context = buildContext(planningDir, stateFile);
 
+  // Auto-launch dashboard if configured
+  const config = configLoad(planningDir);
+  if (config && config.dashboard && config.dashboard.auto_launch) {
+    tryLaunchDashboard(config.dashboard.port || 3000, planningDir, cwd);
+  }
+
   if (context) {
     const output = {
       additionalContext: context
@@ -275,7 +281,46 @@ function getHookHealthSummary(planningDir) {
   }
 }
 
+/**
+ * Attempt to launch the dashboard in a detached background process.
+ * Checks if the port is already in use before spawning.
+ */
+function tryLaunchDashboard(port, _planningDir, projectDir) {
+  const net = require('net');
+  const { spawn } = require('child_process');
+
+  // Quick port probe — if something is already listening, skip launch
+  const probe = net.createConnection({ port, host: '127.0.0.1' });
+  probe.on('connect', () => {
+    probe.destroy();
+    logHook('progress-tracker', 'SessionStart', 'dashboard-already-running', { port });
+  });
+  probe.on('error', () => {
+    // Port is free — launch dashboard
+    const cliPath = path.join(__dirname, '..', 'dashboard', 'bin', 'cli.js');
+    if (!fs.existsSync(cliPath)) {
+      logHook('progress-tracker', 'SessionStart', 'dashboard-cli-missing', { cliPath });
+      return;
+    }
+
+    try {
+      const child = spawn(process.execPath, [cliPath, '--dir', projectDir, '--port', String(port)], {
+        detached: true,
+        stdio: 'ignore',
+        cwd: projectDir
+      });
+      child.unref();
+      logHook('progress-tracker', 'SessionStart', 'dashboard-launched', { port, pid: child.pid });
+    } catch (e) {
+      logHook('progress-tracker', 'SessionStart', 'dashboard-launch-error', { error: e.message });
+    }
+  });
+
+  // Don't let the probe keep the process alive
+  probe.unref();
+}
+
 // Exported for testing
-module.exports = { getHookHealthSummary, FAILURE_DECISIONS, HOOK_HEALTH_MAX_ENTRIES };
+module.exports = { getHookHealthSummary, FAILURE_DECISIONS, HOOK_HEALTH_MAX_ENTRIES, tryLaunchDashboard };
 
 main();

package/plugins/pbr/scripts/validate-skill-args.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Validates Skill tool arguments before execution.
+ *
+ * Currently validates:
+ *   - /pbr:plan — blocks freeform text arguments that don't match
+ *     valid patterns (phase number, subcommand, flags).
+ *
+ * This provides structural enforcement that catches cases where the
+ * LLM ignores the prompt-based freeform text guard in SKILL.md.
+ *
+ * Exit codes:
+ *   0 = allowed (valid args or non-plan skill)
+ *   2 = blocked (freeform text detected for /pbr:plan)
+ */
+
+const { logHook } = require('./hook-logger');
+
+/**
+ * Valid argument patterns for /pbr:plan.
+ *
+ * Matches:
+ *   - Empty / whitespace only
+ *   - Phase number: "3", "03", "3.1"
+ *   - Phase number + flags: "3 --skip-research", "3 --assumptions", "3 --gaps", "3 --teams"
+ *   - Subcommands: "add", "insert 3", "remove 3"
+ *   - Legacy: "check"
+ */
+const PLAN_VALID_PATTERN = /^\s*$|^\s*\d+(\.\d+)?\s*(--(?:skip-research|assumptions|gaps|teams)\s*)*$|^\s*(?:add|check)\s*$|^\s*(?:insert|remove)\s+\d+(\.\d+)?\s*$/i;
+
+/**
+ * Check whether a Skill tool call has valid arguments.
+ * Returns null if valid, or { output, exitCode } if blocked.
+ */
+function checkSkillArgs(data) {
+  const toolInput = data.tool_input || {};
+  const skill = toolInput.skill || '';
+  const args = toolInput.args || '';
+
+  // Only validate /pbr:plan for now
+  if (skill !== 'pbr:plan') {
+    return null;
+  }
+
+  // Test against valid patterns
+  if (PLAN_VALID_PATTERN.test(args)) {
+    return null;
+  }
+
+  // Freeform text detected — block
+  logHook('validate-skill-args', 'PreToolUse', 'blocked', {
+    skill,
+    args: args.substring(0, 100),
+    reason: 'freeform-text'
+  });
+
+  return {
+    output: {
+      additionalContext: [
+        'BLOCKED: /pbr:plan received freeform text instead of a phase number.',
+        '',
+        'The arguments "' + args.substring(0, 80) + (args.length > 80 ? '...' : '') + '" do not match any valid pattern.',
+        '',
+        'Valid usage:',
+        '  /pbr:plan <N>              Plan phase N',
+        '  /pbr:plan <N> --gaps       Create gap-closure plans',
+        '  /pbr:plan add              Add a new phase',
+        '  /pbr:plan insert <N>       Insert a phase at position N',
+        '  /pbr:plan remove <N>       Remove phase N',
+        '',
+        'For freeform tasks, use:',
+        '  /pbr:todo add <description>   Capture as a todo',
+        '  /pbr:quick <description>      Execute immediately',
+        '  /pbr:explore <topic>          Investigate an idea'
+      ].join('\n')
+    },
+    exitCode: 2
+  };
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      const result = checkSkillArgs(data);
+
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+        process.exit(result.exitCode);
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkSkillArgs, PLAN_VALID_PATTERN };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/skills/dashboard/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: dashboard
+description: "Launch the PBR web dashboard for the current project."
+allowed-tools: Bash, Read
+argument-hint: "[--port N]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing immediately.**
+
+## Behavior
+
+1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.
+
+2. **Check dependencies**: Check if `${CLAUDE_PLUGIN_ROOT}/dashboard/node_modules/` exists. If not, run:
+   ```
+   npm install --prefix ${CLAUDE_PLUGIN_ROOT}/dashboard
+   ```
+
+3. **Launch dashboard**: Run in background via Bash:
+   ```
+   node ${CLAUDE_PLUGIN_ROOT}/dashboard/bin/cli.js --dir <cwd> --port <port> &
+   ```
+   Use `&` to background the process so it doesn't block the session.
+
+4. **Output to user**:
+   ```
+   Dashboard running at http://localhost:<port>
+   Open this URL in your browser to view your project's planning state.
+   ```
+
+## Notes
+
+- If the port is already in use, the dashboard will fail to start — suggest the user try a different port with `--port`.
+- The dashboard watches `.planning/` for live updates via SSE.

package/plugins/pbr/skills/plan/SKILL.md

@@ -66,9 +66,9 @@ Parse the phase number and optional flags:
 | `insert <N>` | Insert a new phase at position N (uses decimal numbering) |
 | `remove <N>` | Remove phase N from the roadmap |
 
-### Freeform Text Guard
+### Freeform Text Guard — CRITICAL
 
-**Before any context loading**, check whether `$ARGUMENTS` looks like freeform text rather than a valid invocation. Valid patterns are:
+**STOP. Before ANY context loading or Step 1 work**, you MUST check whether `$ARGUMENTS` looks like freeform text rather than a valid invocation. This check is non-negotiable. Valid patterns are:
 
 - Empty (no arguments)
 - A phase number: integer (`3`, `03`) or decimal (`3.1`)
@@ -100,6 +100,8 @@ Then suggest the appropriate skill based on the text content:
 
 Do NOT proceed with planning. The user needs to use the correct skill.
 
+**Self-check**: If you reach Step 1 without having matched a valid argument pattern above, you have a bug. Stop immediately and show the usage block.
+
 ---
 
 ## Orchestration Flow: Standard Planning

package/plugins/pbr/skills/todo/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: todo
 description: "File-based persistent todos. Add, list, complete — survives sessions."
-allowed-tools: Read, Write, Bash, Glob, Grep
-argument-hint: "add <description> | list [theme] | done <NNN>"
+allowed-tools: Read, Write, Bash, Glob, Grep, Skill
+argument-hint: "add <description> | list [theme] | done <NNN> | work <NNN>"
 ---
 
 **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 ~7,600 tokens. Begin executing Step 1 immediately.**
@@ -124,12 +124,12 @@ Pending Todos:
 
 **Pick a todo** — mark one done or start working
 
-`/pbr:todo done <NNN>`
+`/pbr:todo work <NNN>` — start working on a todo
+`/pbr:todo done <NNN>` — mark a todo as complete
 
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
-- `/pbr:quick` — work on one now
 - `/pbr:status` — see project status
 
 ───────────────────────────────────────────────────────────────
@@ -181,6 +181,45 @@ Todo {NNN} not found in pending todos.
 ───────────────────────────────────────────────────────────────
 ```
 
+### `work <NNN>`
+
+1. Find `.planning/todos/pending/{NNN}-*.md` (match by number prefix)
+2. If not found, display the same error block as `done` — suggest `/pbr:todo list`
+3. Read the todo file content (frontmatter + body)
+4. Extract the `title` from frontmatter and the full body (Goal, Scope, Acceptance Criteria sections)
+5. Display branded output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Todo {NNN}:** {title}
+
+Launching /pbr:quick with todo context...
+```
+6. Invoke the Skill tool: `skill: "pbr:quick"` with `args` set to the todo title followed by the body content. Format the args as:
+
+```
+{title}
+
+Context from todo {NNN}:
+{body content — Goal, Scope, Acceptance Criteria sections}
+```
+
+This hands off execution to `/pbr:quick`, which will spawn an executor agent, make atomic commits, and track the work. When quick completes, remind the user:
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Mark this todo as done if the work is complete**
+
+`/pbr:todo done {NNN}`
+
+───────────────────────────────────────────────────────────────
+```
+
 ### No arguments
 
 Show a brief summary: count of pending todos, grouped by theme, plus usage hint.