@sienklogic/plan-build-run 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-02-19
+
+### Added
+- Milestone integration into workflow lifecycle — milestones are now created automatically during `/pbr:begin` roadmap generation
+- Planner agent generates milestone-grouped roadmaps (single milestone for standard projects, multiple for 8+ phase comprehensive projects)
+- Milestone-aware boundary detection in `/pbr:build` and `/pbr:review` — reads ROADMAP.md phase ranges instead of just "last phase overall"
+- Between-milestones state handling in `/pbr:continue`
+- Audit report detection in `/pbr:status` — suggests the correct next action based on whether an audit exists and its result
+
+### Fixed
+- "Skip audit" option in build/review completion banners now correctly says "archive milestone after audit passes" (consistent with milestone anti-pattern rules)
+- `auto_advance` hard-stop message at milestone boundaries now explains why it paused
+
+## [2.1.0] - 2026-02-19
+
+### Added
+- **Cursor IDE plugin** (`plugins/cursor-pbr/`) — complete port with 21 skills, 10 agents, and `.mdc` workflow rules
+- Cross-plugin compatibility: shared `.planning/` state between Claude Code and Cursor plugins
+- Setup scripts (`setup.sh` for macOS/Linux, `setup.ps1` for Windows) for easy Cursor plugin installation
+- Summary gate hook (`check-summary-gate.js`) — enforces SUMMARY file before phase state can advance
+- Cross-plugin compatibility test suite (7 tests)
+- Cursor plugin validation test suite (92 tests)
+- Companion web dashboard improvements: service and route enhancements
+
+### Changed
+- Agent definitions optimized — 48% average size reduction across all 10 agents
+- Hook scripts improved with better error handling and dispatch logic
+- Test count increased from 758 to 1008 across 42 suites
+- Removed `.gitkeep` placeholder files from `cursor-pbr/` (replaced by real content)
+
 ## [2.0.0] - 2026-02-17
 
 ### Added

package/README.md

@@ -3,11 +3,11 @@
 </p>
 
 <p align="center">
-  <strong>Context-engineered development workflow for Claude Code.</strong>
+  <strong>Context-engineered development workflow for Claude Code and Cursor.</strong>
   <br />
   Build ambitious multi-phase software without quality degradation.
   <br />
-  Works with any Claude Code plan. Shines on Max.
+  Works with any Claude Code plan. Shines on Max. Now available for Cursor IDE.
   <br />
   <br />
   <a href="#why-plan-build-run">Why Plan-Build-Run?</a> &bull;
@@ -21,10 +21,11 @@
 <p align="center">
   <a href="https://github.com/SienkLogic/plan-build-run/actions"><img src="https://img.shields.io/github/actions/workflow/status/SienkLogic/plan-build-run/ci.yml?style=for-the-badge&label=CI&logo=github" alt="CI Status" /></a>
   <img src="https://img.shields.io/badge/Claude_Code-Plugin-7C3AED?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code Plugin" />
+  <img src="https://img.shields.io/badge/Cursor-Plugin-00A67E?style=for-the-badge&logo=cursor&logoColor=white" alt="Cursor Plugin" />
   <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
   <a href="LICENSE"><img src="https://img.shields.io/github/license/SienkLogic/plan-build-run?style=for-the-badge" alt="License" /></a>
   <a href="https://www.npmjs.com/package/@sienklogic/plan-build-run"><img src="https://img.shields.io/npm/v/@sienklogic/plan-build-run?style=for-the-badge&logo=npm&logoColor=white" alt="npm" /></a>
-  <img src="https://img.shields.io/badge/Tests-780_passing-brightgreen?style=for-the-badge" alt="780 Tests" />
+  <img src="https://img.shields.io/badge/Tests-1008_passing-brightgreen?style=for-the-badge" alt="1008 Tests" />
 </p>
 
 ---
@@ -87,6 +88,24 @@ All `/pbr:*` commands are now available globally.
 
 </details>
 
+### Install for Cursor IDE
+
+Plan-Build-Run also works in Cursor. The setup script symlinks rules and agents into your project's `.cursor/` directory.
+
+**macOS / Linux:**
+```bash
+cd /path/to/your/project
+bash /path/to/plan-build-run/plugins/cursor-pbr/setup.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+cd C:\path\to\your\project
+powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\cursor-pbr\setup.ps1
+```
+
+Both plugins share the same `.planning/` directory — start a project in Claude Code, continue in Cursor, or vice versa. See [`plugins/cursor-pbr/README.md`](plugins/cursor-pbr/README.md) for full details.
+
 ### Dashboard (Optional)
 
 Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser. To set it up:
@@ -212,7 +231,7 @@ git clone https://github.com/SienkLogic/plan-build-run.git
 cd plan-build-run
 npm install
 
-# Run tests (758 tests, 36 suites)
+# Run tests (1008 tests, 42 suites)
 npm test
 
 # Lint
@@ -236,8 +255,8 @@ CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md]
 | Skills (slash commands) | 21 |
 | Specialized agents | 10 |
 | Hook scripts | 28 |
-| Tests | 758 |
-| Test suites | 36 |
+| Tests | 1008 |
+| Test suites | 42 |
 | Config toggles | 12 top-level keys |
 
 ---

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.1.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/agents/planner.md

@@ -38,6 +38,8 @@ Invoked with plan-checker feedback containing issues. Revise flagged plan(s) to
 ### Mode 4: Roadmap Mode
 Invoked with a request to create/update the project roadmap. Produce `.planning/ROADMAP.md` using the template at `${CLAUDE_PLUGIN_ROOT}/templates/ROADMAP.md.tmpl`.
 
+**Milestone grouping:** All phases in the initial roadmap MUST be wrapped in a `## Milestone: {project name} v1.0` section. This section includes `**Goal:**` and `**Phases:** 1 - {N}`, followed by the `### Phase NN:` details. For comprehensive-depth projects (8+ phases), consider splitting into multiple milestones if there are natural delivery boundaries (e.g., "Core Platform" phases 1-5, "Advanced Features" phases 6-10). Each milestone section follows the format defined in the roadmap template.
+
 ---
 
 ## Goal-Backward Methodology

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/references/ui-formatting.md

@@ -387,7 +387,7 @@ All phase goals verified ✓
 
 **Also available:**
 - /pbr:review — manual acceptance testing
-- /pbr:milestone complete — skip audit, archive directly
+- /pbr:milestone complete — archive milestone after audit passes
 
 ───────────────────────────────────────────────────────────────
 ```

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/begin/SKILL.md

@@ -379,10 +379,11 @@ Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 
 **After the planner completes:**
 - Read `.planning/ROADMAP.md`
-- Count the phases and milestones from the roadmap content
+- Count the phases from the roadmap content
+- Verify the roadmap contains a `## Milestone:` section wrapping the phases (the planner should generate this). If not, the initial set of phases constitutes the first milestone — add the section header yourself.
 - Display:
   ```
-  ✓ Roadmap created — {N} phases across {M} milestones
+  ✓ Roadmap created — {N} phases in milestone "{name}"
   ```
 - If `gates.confirm_roadmap` is true in config, use the **approve-revise-abort** pattern from `skills/shared/gate-prompts.md`:
   question: "Approve this roadmap?"
@@ -544,6 +545,7 @@ Then use the "Next Up" routing block:
 **Also available:**
 - `/pbr:explore` — open-ended exploration before planning
 - `/pbr:plan 1` — jump straight to planning Phase 1
+- `/pbr:milestone new` — add a second milestone with new phases
 - `/pbr:config` — adjust workflow settings
 
 ───────────────────────────────────────────────────────────────

package/plugins/pbr/skills/begin/templates/roadmap-prompt.md.tmpl

@@ -24,6 +24,8 @@ Each phase should:
 3. Build on prior phases logically
 4. Be independently verifiable
 
+**Milestone structure:** Wrap all phases in a `## Milestone:` section. For comprehensive-depth projects with 8+ phases, consider splitting into multiple milestones at natural delivery boundaries. Use the milestone section format from the roadmap template (`## Milestone: {name}` with `**Goal:**` and `**Phases:** start - end`).
+
 Write the roadmap to .planning/ROADMAP.md using the roadmap format from your agent definition.
 </roadmap_instructions>
 

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

@@ -744,7 +744,7 @@ Chain to the next skill directly within this session. This eliminates manual pha
 | Verification passed, more phases | Plan next phase | `Skill({ skill: "pbr:plan", args: "{N+1}" })` |
 | Verification skipped | Run review | `Skill({ skill: "pbr:review", args: "{N}" })` |
 | Verification gaps found | **HARD STOP** — present gaps to user | Do NOT auto-advance past failures |
-| Last phase complete | **HARD STOP** — milestone boundary | Suggest `/pbr:milestone audit` |
+| Last phase in current milestone | **HARD STOP** — milestone boundary | Suggest `/pbr:milestone audit`. Explain: "auto_advance pauses at milestone boundaries — your sign-off is required." |
 | Build errors occurred | **HARD STOP** — errors need human review | Do NOT auto-advance past errors |
 
 After invoking the chained skill, it runs within the same session. When it completes, the chained skill may itself chain further (review→plan, plan→build) if auto_advance remains true. This creates the full cycle: build→review→plan→build→...
@@ -759,8 +759,10 @@ Use the branded output templates from `references/ui-formatting.md`. Route based
 
 | Status | Template |
 |--------|----------|
-| `passed` + more phases | "Phase Complete" template |
-| `passed` + last phase | "Milestone Complete" template |
+| `passed` + more phases in current milestone | "Phase Complete" template |
+| `passed` + last phase in current milestone | "Milestone Complete" template |
+
+**Milestone boundary detection:** To determine "last phase in current milestone", read ROADMAP.md and find the `## Milestone:` section containing the current phase. Check its `**Phases:** start - end` range. If the current phase equals `end`, this is the last phase in the milestone. For projects with a single milestone or no explicit milestone sections, "last phase in ROADMAP" is equivalent.
 | `gaps_found` | "Gaps Found" template |
 
 Before the branded banner, include the results table:
@@ -838,7 +840,7 @@ All phase goals verified ✓
 
 **Also available:**
 - `/pbr:review` — manual acceptance testing
-- `/pbr:milestone complete` — skip audit, archive directly
+- `/pbr:milestone complete` — archive milestone after audit passes
 
 ───────────────────────────────────────────────────────────────
 ```

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

@@ -95,7 +95,8 @@ Check the resumption priority hierarchy (same as /pbr:resume):
 4. **Incomplete build**: PLAN.md files without SUMMARY.md → Execute `/pbr:build {N}`
 5. **Unverified phase**: All plans complete, no VERIFICATION.md → Execute `/pbr:review {N}`
 6. **Phase complete, more phases exist**: Verification passed → Execute `/pbr:plan {N+1}`
-7. **All phases complete**: Verification passed on final phase, no more phases in ROADMAP.md → Stop. Display: "All phases are complete. Run `/pbr:milestone audit` to verify cross-phase integration, or `/pbr:milestone complete` to archive this milestone."
+7. **Last phase in current milestone complete**: Verification passed on the last phase of the current milestone's phase range → Stop. Display: "Milestone complete! Run `/pbr:milestone audit` to verify cross-phase integration, then `/pbr:milestone complete` to archive."
+8. **Between milestones**: Current milestone is marked complete in STATE.md, but more milestones exist or user needs to create the next one → Stop. Display: "Current milestone is complete. Run `/pbr:milestone new` to start the next milestone, or `/pbr:milestone audit` if not yet audited."
 
 ### Step 3: Execute
 

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/review/SKILL.md

@@ -340,7 +340,8 @@ If all automated checks and UAT items passed:
 
 Use the branded output from `references/ui-formatting.md`:
 - If more phases remain: use the "Phase Complete" banner template
-- If this was the last phase: use the "Milestone Complete" banner template
+- If this was the last phase in the current milestone: use the "Milestone Complete" banner template
+- **Milestone boundary detection:** Read ROADMAP.md and find the `## Milestone:` section containing the current phase. Check its `**Phases:** start - end` range. If the current phase equals `end`, this is the last phase in the milestone.
 - Always include the "Next Up" routing block
 
 4. If `gates.confirm_transition` is true in config AND `features.auto_advance` is NOT true:
@@ -356,7 +357,7 @@ Use the branded output from `references/ui-formatting.md`:
 5. **If `features.auto_advance` is `true` AND `mode` is `autonomous` AND more phases remain:**
    - Chain directly to plan: `Skill({ skill: "pbr:plan", args: "{N+1}" })`
    - This continues the build→review→plan cycle automatically
-   - **If this is the last phase:** HARD STOP — do NOT auto-advance past milestone boundaries
+   - **If this is the last phase in the current milestone:** HARD STOP — do NOT auto-advance past milestone boundaries. Display: "auto_advance pauses at milestone boundaries — your sign-off is required."
 
 #### Gaps Found WITH `--auto-fix`
 
@@ -666,7 +667,7 @@ Then:
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
-- `/pbr:milestone complete` — archive this milestone and tag it
+- `/pbr:milestone complete` — archive milestone after audit passes
 - `/pbr:milestone new` — start planning next features
 - `/pbr:status` — see final project status
 

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

@@ -251,7 +251,7 @@ Based on the project state, suggest the single most logical next action:
          YES → "Re-plan with updated context: `/pbr:plan {N+1}`"
          NO → "Build the next phase: `/pbr:build {N+1}`"
        NO → "Plan the next phase: `/pbr:plan {N+1}`"
-     NO → "All phases complete! Your next steps:\n       -> /pbr:milestone audit — verify cross-phase integration (recommended)\n       -> /pbr:milestone complete — archive this milestone and create a git tag\n       -> /pbr:milestone new — start planning the next set of features"
+     NO → Check for existing `*-MILESTONE-AUDIT.md` in `.planning/`:\n       IF audit passed → "All phases complete and audited! `/pbr:milestone complete` to archive and tag."\n       IF audit has gaps → "Audit found gaps. `/pbr:milestone gaps` to address them."\n       IF no audit → "All phases complete! `/pbr:milestone audit` to verify cross-phase integration (recommended), then `/pbr:milestone complete`."
 
 6. Is the current phase not started?
    YES → Has it been discussed?
@@ -317,7 +317,10 @@ Build options dynamically from the decision tree results. Always include "Someth
 
 ### All phases complete
 - Celebrate briefly: "All phases complete!"
-- Suggest: `/pbr:milestone audit` to verify cross-phase integration (recommended first)
+- Check for existing audit report: look for `*-MILESTONE-AUDIT.md` in `.planning/`
+  - **If audit exists and passed:** Suggest `/pbr:milestone complete` to archive (audit already done)
+  - **If audit exists with gaps:** Suggest `/pbr:milestone gaps` to address issues
+  - **If no audit exists:** Suggest `/pbr:milestone audit` to verify cross-phase integration (recommended first)
 - Then: `/pbr:milestone complete` to archive the milestone and tag it
 - Or: `/pbr:milestone new` to start the next set of features
 

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.

package/plugins/pbr/templates/ROADMAP.md.tmpl

@@ -21,7 +21,12 @@ Phase 01 ──→ Phase 02 ──→ Phase 04
                        └──→ Phase 04
 ```
 
-## Phase Details
+---
+
+## Milestone: {project name} v1.0
+
+**Goal:** {overall project goal from requirements}
+**Phases:** 1 - {n}
 
 ### Phase 01: Project Setup