@sienklogic/plan-build-run 2.2.0 → 2.3.1

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.1",
   "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.1",
   "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/do/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: do
+description: "Route freeform text to the right PBR skill automatically."
+argument-hint: "<freeform description of what you want to do>"
+---
+
+# /pbr:do — Freeform Task Router
+
+You are running the **do** skill. Your job is to analyze freeform text from the user and route it to the most appropriate PBR skill. You are a dispatcher, not an executor — you never do the work yourself.
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► ROUTING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
+## Step 1 — Validate Input
+
+If `$ARGUMENTS` is empty, ask the user what they want to do via AskUserQuestion:
+```
+What would you like to do? Describe the task, bug, or idea and I'll route it to the right skill.
+```
+
+## Step 2 — Analyze and Route
+
+Evaluate `$ARGUMENTS` against these routing criteria. Apply the **first matching** rule:
+
+| If the text describes... | Route to | Why |
+|--------------------------|----------|-----|
+| A bug, error, crash, failure, or something broken | `/pbr:debug` | Needs systematic investigation |
+| Exploration, research, comparison, or "how does X work" | `/pbr:explore` | Open-ended investigation |
+| A complex task: refactoring, migration, multi-file architecture, system redesign | `/pbr:plan add` | Needs a full phase with research/plan/build cycle |
+| A review or quality concern about existing work | `/pbr:review` | Needs verification against plan |
+| A note, idea, or "remember to..." | `/pbr:note` | Capture for later |
+| A specific, actionable task (add feature, fix typo, update config, write test) | `/pbr:quick` | Self-contained, single executor |
+
+**Ambiguity handling**: If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example:
+
+```
+"Refactor the authentication system" could be:
+- /pbr:plan add — Full planning cycle (recommended for multi-file refactors)
+- /pbr:quick — Quick execution (if scope is small and clear)
+```
+
+## Step 3 — Confirm and Dispatch
+
+Display the routing decision:
+
+```
+**Input:** {first 80 chars of arguments}
+**Routing to:** {chosen skill}
+**Reason:** {one-line explanation}
+```
+
+Then invoke the chosen skill via the Skill tool, passing `$ARGUMENTS` as the args.
+
+**Special case for `/pbr:plan add`**: When routing to plan, check if `.planning/ROADMAP.md` exists first (via Read). If it doesn't, suggest `/pbr:begin` instead — the user needs to set up the project before they can add phases.
+
+## Step 4 — No Follow-Up
+
+After invoking the skill, your job is done. The dispatched skill handles everything from here (execution, commits, state updates). Do not add any additional output after the Skill tool call.

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,68 @@ 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. **Assess complexity** to choose the right skill. Evaluate the todo content against these criteria:
+
+| Signal | Route to |
+|--------|----------|
+| Single file change, small fix, simple addition | `/pbr:quick` |
+| Multiple acceptance criteria, multi-file scope, architectural decisions, needs research | `/pbr:plan` (requires an active phase) |
+| Investigation needed, unclear root cause | `/pbr:debug` |
+| Open-ended exploration, no clear deliverable | `/pbr:explore` |
+
+If unsure, ask the user via AskUserQuestion:
+```
+Todo {NNN} could be handled as a quick task or may need full planning.
+
+Which approach?
+- Quick task (/pbr:quick) — single executor, atomic commit
+- Full planning (/pbr:plan) — research, plan, build cycle
+- Debug (/pbr:debug) — systematic investigation
+- Explore (/pbr:explore) — open-ended investigation
+```
+
+6. Display branded output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Todo {NNN}:** {title}
+**Routing to:** /pbr:{chosen-skill}
+```
+
+7. Invoke the chosen skill via the Skill tool, passing the todo title and body as args:
+
+```
+{title}
+
+Context from todo {NNN}:
+{body content — Goal, Scope, Acceptance Criteria sections}
+```
+
+For `/pbr:plan`, if no phase exists for this work yet, suggest the user run `/pbr:plan add` first to create one, then re-run `/pbr:todo work {NNN}`.
+
+8. When the skill 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.1",
   "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,150 @@
+#!/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).
+ *
+ * When freeform text is detected, analyzes it to suggest the most
+ * appropriate skill (quick, debug, explore, todo, plan).
+ *
+ * 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;
+
+/**
+ * Keyword patterns for routing freeform text to the right skill.
+ * Order matters — first match wins.
+ */
+const ROUTE_PATTERNS = [
+  {
+    pattern: /\b(bugs?|fix(es|ing)?|errors?|crash(es|ing)?|fails?|failing|broken|issues?|debug(ging)?|diagnos(e|ing)|stack\s*trace|exceptions?|regress(ion|ing)?)\b/i,
+    skill: '/pbr:debug',
+    reason: 'Looks like a bug or debugging task'
+  },
+  {
+    pattern: /\b(explore|research|understand|how does|what is|analy[zs]e|evaluate|compare|pros and cons|trade-?offs?|approach(es)?)\b/i,
+    skill: '/pbr:explore',
+    reason: 'Looks like exploration or research'
+  },
+  {
+    pattern: /\b(refactor|redesign|architect|migrate|restructure|overhaul|rewrite|multi-?phase|complex|system|infrastructure)\b/i,
+    skill: '/pbr:plan add',
+    reason: 'Looks like a complex task that needs full planning'
+  },
+  {
+    // Default: anything actionable goes to quick
+    pattern: /./,
+    skill: '/pbr:quick',
+    reason: 'Looks like a straightforward task'
+  }
+];
+
+/**
+ * Suggest the best skill for freeform text.
+ * Returns { skill, reason }.
+ */
+function suggestSkill(text) {
+  for (const route of ROUTE_PATTERNS) {
+    if (route.pattern.test(text)) {
+      return { skill: route.skill, reason: route.reason };
+    }
+  }
+  return { skill: '/pbr:quick', reason: 'Default routing' };
+}
+
+/**
+ * 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 — suggest the right skill
+  const suggestion = suggestSkill(args);
+
+  logHook('validate-skill-args', 'PreToolUse', 'blocked', {
+    skill,
+    args: args.substring(0, 100),
+    reason: 'freeform-text',
+    suggested: suggestion.skill
+  });
+
+  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 /pbr:plan 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',
+        '',
+        'Suggested skill for this text:',
+        '  ' + suggestion.skill + ' — ' + suggestion.reason,
+        '',
+        'Or use /pbr:do to auto-route freeform text to the right skill.'
+      ].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, suggestSkill, PLAN_VALID_PATTERN, ROUTE_PATTERNS };
+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/do/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: do
+description: "Route freeform text to the right PBR skill automatically."
+allowed-tools: Read, Skill, AskUserQuestion
+argument-hint: "<freeform description of what you want to do>"
+---
+
+**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 1 immediately.**
+
+# /pbr:do — Freeform Task Router
+
+You are running the **do** skill. Your job is to analyze freeform text from the user and route it to the most appropriate PBR skill. You are a dispatcher, not an executor — you never do the work yourself.
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► ROUTING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
+## Step 1 — Validate Input
+
+If `$ARGUMENTS` is empty, ask the user what they want to do via AskUserQuestion:
+```
+What would you like to do? Describe the task, bug, or idea and I'll route it to the right skill.
+```
+
+## Step 2 — Analyze and Route
+
+Evaluate `$ARGUMENTS` against these routing criteria. Apply the **first matching** rule:
+
+| If the text describes... | Route to | Why |
+|--------------------------|----------|-----|
+| A bug, error, crash, failure, or something broken | `/pbr:debug` | Needs systematic investigation |
+| Exploration, research, comparison, or "how does X work" | `/pbr:explore` | Open-ended investigation |
+| A complex task: refactoring, migration, multi-file architecture, system redesign | `/pbr:plan add` | Needs a full phase with research/plan/build cycle |
+| A review or quality concern about existing work | `/pbr:review` | Needs verification against plan |
+| A note, idea, or "remember to..." | `/pbr:note` | Capture for later |
+| A specific, actionable task (add feature, fix typo, update config, write test) | `/pbr:quick` | Self-contained, single executor |
+
+**Ambiguity handling**: If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example:
+
+```
+"Refactor the authentication system" could be:
+- /pbr:plan add — Full planning cycle (recommended for multi-file refactors)
+- /pbr:quick — Quick execution (if scope is small and clear)
+```
+
+## Step 3 — Confirm and Dispatch
+
+Display the routing decision:
+
+```
+**Input:** {first 80 chars of arguments}
+**Routing to:** {chosen skill}
+**Reason:** {one-line explanation}
+```
+
+Then invoke the chosen skill via the Skill tool, passing `$ARGUMENTS` as the args.
+
+**Special case for `/pbr:plan add`**: When routing to plan, check if `.planning/ROADMAP.md` exists first (via Read). If it doesn't, suggest `/pbr:begin` instead — the user needs to set up the project before they can add phases.
+
+## Step 4 — No Follow-Up
+
+After invoking the skill, your job is done. The dispatched skill handles everything from here (execution, commits, state updates). Do not add any additional output after the Skill tool call.

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, AskUserQuestion
+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,68 @@ 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. **Assess complexity** to choose the right skill. Evaluate the todo content against these criteria:
+
+| Signal | Route to |
+|--------|----------|
+| Single file change, small fix, simple addition | `/pbr:quick` |
+| Multiple acceptance criteria, multi-file scope, architectural decisions, needs research | `/pbr:plan` (requires an active phase) |
+| Investigation needed, unclear root cause | `/pbr:debug` |
+| Open-ended exploration, no clear deliverable | `/pbr:explore` |
+
+If unsure, ask the user via AskUserQuestion:
+```
+Todo {NNN} could be handled as a quick task or may need full planning.
+
+Which approach?
+- Quick task (/pbr:quick) — single executor, atomic commit
+- Full planning (/pbr:plan) — research, plan, build cycle
+- Debug (/pbr:debug) — systematic investigation
+- Explore (/pbr:explore) — open-ended investigation
+```
+
+6. Display branded output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Todo {NNN}:** {title}
+**Routing to:** /pbr:{chosen-skill}
+```
+
+7. Invoke the chosen skill via the Skill tool, passing the todo title and body as args:
+
+```
+{title}
+
+Context from todo {NNN}:
+{body content — Goal, Scope, Acceptance Criteria sections}
+```
+
+For `/pbr:plan`, if no phase exists for this work yet, suggest the user run `/pbr:plan add` first to create one, then re-run `/pbr:todo work {NNN}`.
+
+8. When the skill 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.