@sienklogic/plan-build-run 2.0.2 → 2.2.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/src/routes/pages.routes.js

@@ -1,19 +1,23 @@
 import { Router } from 'express';
 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';
 
 const router = Router();
 
 router.get('/phases', async (req, res) => {
   const projectDir = req.app.locals.projectDir;
-  const roadmapData = await getRoadmapData(projectDir);
+  const [roadmapData, stateData] = await Promise.all([
+    getRoadmapData(projectDir),
+    parseStateFile(projectDir)
+  ]);
 
   const templateData = {
     title: 'Phases',
     activePage: 'phases',
     currentPath: '/phases',
-    phases: roadmapData.phases,
+    phases: derivePhaseStatuses(roadmapData.phases, stateData.currentPhase),
     milestones: roadmapData.milestones
   };
 
@@ -223,13 +227,16 @@ router.post('/todos/:id/done', async (req, res) => {
 
 router.get('/roadmap', async (req, res) => {
   const projectDir = req.app.locals.projectDir;
-  const roadmapData = await getRoadmapData(projectDir);
+  const [roadmapData, stateData] = await Promise.all([
+    getRoadmapData(projectDir),
+    parseStateFile(projectDir)
+  ]);
 
   const templateData = {
     title: 'Roadmap',
     activePage: 'roadmap',
     currentPath: '/roadmap',
-    phases: roadmapData.phases,
+    phases: derivePhaseStatuses(roadmapData.phases, stateData.currentPhase),
     milestones: roadmapData.milestones
   };
 

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

@@ -24,7 +24,20 @@ export async function parseStateFile(projectDir) {
   try {
     const path = join(projectDir, '.planning', 'STATE.md');
     const raw = await readFile(path, 'utf-8');
-    const content = stripBOM(raw);
+    const content = stripBOM(raw).replace(/\r\n/g, '\n');
+
+    // Parse YAML frontmatter if present (STATE.md v2 format)
+    let frontmatter = {};
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+      for (const line of fmMatch[1].split('\n')) {
+        const kv = line.match(/^(\w+):\s*(.+)/);
+        if (kv) {
+          const val = kv[2].trim().replace(/^"(.*)"$/, '$1');
+          frontmatter[kv[1]] = val;
+        }
+      }
+    }
 
     // Extract project name from **Current focus:** line
     let projectName = 'Unknown Project';
@@ -76,13 +89,23 @@ export async function parseStateFile(projectDir) {
       progress = Math.ceil((currentPhaseId / totalPhases) * 100);
     }
 
+    // Determine phase status from frontmatter or body text
+    // "built", "verified", "complete" all mean the current phase is done
+    const fmStatus = (frontmatter.status || '').toLowerCase();
+    const phaseStatus = ['built', 'verified', 'complete', 'reviewed'].includes(fmStatus)
+      ? 'complete'
+      : ['building', 'planning', 'planned', 'in-progress'].includes(fmStatus)
+        ? 'in-progress'
+        : fmStatus || 'unknown';
+
     return {
       projectName,
       currentPhase: {
         id: currentPhaseId,
         total: totalPhases,
         name: phaseName,
-        planStatus
+        planStatus,
+        status: phaseStatus
       },
       lastActivity: {
         date: activityDate,
@@ -94,7 +117,7 @@ export async function parseStateFile(projectDir) {
     if (error.code === 'ENOENT') {
       return {
         projectName: 'Unknown Project',
-        currentPhase: { id: 0, total: 0, name: 'Not Started', planStatus: 'N/A' },
+        currentPhase: { id: 0, total: 0, name: 'Not Started', planStatus: 'N/A', status: 'unknown' },
         lastActivity: { date: '', description: 'No activity recorded' },
         progress: 0
       };
@@ -132,7 +155,7 @@ export async function parseRoadmapFile(projectDir) {
 
     // 2. Parse descriptions from Phase Details: "### Phase NN: Name\n**Goal**: ..."
     const goalMap = new Map();
-    const goalRegex = /### Phase (\d+):\s*(.+)\n\*\*Goal\*\*:\s*(.+)/g;
+    const goalRegex = /### Phase (\d+):\s*(.+)\n\*\*Goal:?\*\*:?\s*(.+)/g;
     for (const match of content.matchAll(goalRegex)) {
       goalMap.set(parseInt(match[1], 10), match[3].trim());
     }
@@ -158,11 +181,28 @@ export async function parseRoadmapFile(projectDir) {
       progressPhases.push({ id, name, description, status });
     }
 
-    // Use Progress table if available, otherwise fall back to checkbox parsing
+    // 4. Parse H3 Phase Details: "### Phase N: Name\n**Goal:** ..."
+    const h3Phases = [];
+    const h3Regex = /### Phase (\d+):\s*(.+)\n\*\*Goal\*?\*?:?\*?\*?\s*(.+)/g;
+    for (const match of content.matchAll(h3Regex)) {
+      const id = parseInt(match[1], 10);
+      const name = match[2].trim();
+      const description = match[3].trim();
+      // Check checkbox map for status, default to not-started
+      const cbInfo = checkboxMap.get(id);
+      h3Phases.push({
+        id,
+        name,
+        description,
+        status: cbInfo?.status || 'not-started'
+      });
+    }
+
+    // Use Progress table if available, then checkbox list, then H3 headings
     let phases;
     if (progressPhases.length > 0) {
       phases = progressPhases;
-    } else {
+    } else if (checkboxMap.size > 0) {
       phases = [...checkboxMap.entries()]
         .map(([id, info]) => ({
           id,
@@ -171,6 +211,8 @@ export async function parseRoadmapFile(projectDir) {
           status: info.status
         }))
         .sort((a, b) => a.id - b.id);
+    } else {
+      phases = h3Phases.sort((a, b) => a.id - b.id);
     }
 
     const completed = phases.filter(p => p.status === 'complete').length;
@@ -193,23 +235,45 @@ export async function parseRoadmapFile(projectDir) {
  * @param {string} projectDir - Absolute path to the project root
  * @returns {Promise<{projectName: string, currentPhase: object, lastActivity: object, progress: number, phases: Array}>}
  */
+/**
+ * Derive phase statuses by combining roadmap phases with STATE.md context.
+ * Phases before the current phase are marked complete.
+ * The current phase gets its status from STATE.md.
+ * Phases after the current phase keep their roadmap status (typically not-started).
+ *
+ * @param {Array} phases - Raw phases from parseRoadmapFile
+ * @param {{id: number, status: string}} currentPhase - Current phase from parseStateFile
+ * @returns {Array} Phases with derived statuses
+ */
+export function derivePhaseStatuses(phases, currentPhase) {
+  const currentId = currentPhase.id;
+  const currentStatus = currentPhase.status || 'unknown';
+  return phases.map(phase => {
+    // If the roadmap already has explicit status (from progress table/checkboxes), keep it
+    if (phase.status === 'complete') return phase;
+
+    if (phase.id < currentId) {
+      return { ...phase, status: 'complete' };
+    }
+    if (phase.id === currentId) {
+      return { ...phase, status: currentStatus === 'complete' ? 'complete' : 'in-progress' };
+    }
+    return phase;
+  });
+}
+
 export async function getDashboardData(projectDir) {
   const [stateData, roadmapData] = await Promise.all([
     parseStateFile(projectDir),
     parseRoadmapFile(projectDir)
   ]);
 
-  // Derive "in-progress" status for the current phase
-  const phases = roadmapData.phases.map(phase => ({
-    ...phase,
-    status: (phase.id === stateData.currentPhase.id && phase.status !== 'complete')
-      ? 'in-progress'
-      : phase.status
-  }));
-
-  // Prefer roadmap progress if phases exist, otherwise use state progress
-  const progress = roadmapData.phases.length > 0
-    ? roadmapData.progress
+  const phases = derivePhaseStatuses(roadmapData.phases, stateData.currentPhase);
+
+  // Recalculate progress from derived phase statuses
+  const completedPhases = phases.filter(p => p.status === 'complete').length;
+  const progress = phases.length > 0
+    ? Math.ceil((completedPhases / phases.length) * 100)
     : stateData.progress;
 
   return {

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

@@ -109,16 +109,19 @@ export async function getPhaseDetail(projectDir, phaseId) {
   const phaseFiles = await readdir(phaseFullPath);
 
   // Filter and sort PLAN.md files
-  const planRegex = /^\d{2}-\d{2}-PLAN\.md$/;
-  const planIdRegex = /^(\d{2}-\d{2})-PLAN\.md$/;
+  // Supports both naming conventions:
+  //   - NN-NN-PLAN.md (plan ID embedded in filename)
+  //   - PLAN.md (single plan per phase, ID derived from phase directory)
+  const planRegex = /^(?:\d{2}-\d{2}-)?PLAN\.md$/;
   const planFiles = phaseFiles
     .filter(f => planRegex.test(f))
     .sort();
 
   // Build summary paths and read them in parallel
-  const summaryPaths = planFiles.map(planFile => {
-    const match = planFile.match(planIdRegex);
-    const planId = match[1];
+  // Derive planId from filename (NN-NN-PLAN.md) or phase directory (PLAN.md -> NN-01)
+  const summaryPaths = planFiles.map((planFile, index) => {
+    const idMatch = planFile.match(/^(\d{2}-\d{2})-PLAN\.md$/);
+    const planId = idMatch ? idMatch[1] : `${phaseId.padStart(2, '0')}-${String(index + 1).padStart(2, '0')}`;
     return { planId, planFile, summaryPath: join(phaseFullPath, `SUMMARY-${planId}.md`) };
   });
 
@@ -196,25 +199,28 @@ export async function getPhaseDocument(projectDir, phaseId, planId, docType) {
   const phaseName = formatPhaseName(phaseDir.name);
   const phaseFullPath = join(phasesDir, phaseDir.name);
 
-  const fileName = docType === 'plan'
-    ? `${planId}-PLAN.md`
-    : `SUMMARY-${planId}.md`;
+  // Try plan ID-prefixed filename first, then fall back to plain PLAN.md
+  // Supports both "01-01-PLAN.md" and "PLAN.md" naming conventions
+  const fileNames = docType === 'plan'
+    ? [`${planId}-PLAN.md`, 'PLAN.md']
+    : [`SUMMARY-${planId}.md`];
 
-  // Validate the path stays within the phase directory
-  const filePath = validatePath(phaseFullPath, fileName);
-
-  try {
-    const doc = await readMarkdownFile(filePath);
-    return {
-      phaseId,
-      planId,
-      docType,
-      phaseName,
-      frontmatter: doc.frontmatter,
-      html: doc.html
-    };
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    throw error;
+  for (const fileName of fileNames) {
+    const filePath = validatePath(phaseFullPath, fileName);
+    try {
+      const doc = await readMarkdownFile(filePath);
+      return {
+        phaseId,
+        planId,
+        docType,
+        phaseName,
+        frontmatter: doc.frontmatter,
+        html: doc.html
+      };
+    } catch (error) {
+      if (error.code === 'ENOENT') continue;
+      throw error;
+    }
   }
+  return null;
 }

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

@@ -35,7 +35,7 @@ async function countPlansForPhase(projectDir, phaseId) {
     if (!phaseDir) return 0;
 
     const phaseFiles = await readdir(join(phasesDir, phaseDir.name));
-    return phaseFiles.filter(f => /^\d{2}-\d{2}-PLAN\.md$/.test(f)).length;
+    return phaseFiles.filter(f => /^(?:\d{2}-\d{2}-)?PLAN\.md$/.test(f)).length;
   } catch (err) {
     if (err.code === 'ENOENT') return 0;
     throw err;
@@ -52,7 +52,7 @@ function extractAllDependencies(roadmapContent) {
   const dependencyMap = new Map();
 
   // Match Phase Details sections: "### Phase NN: ..." followed by "**Depends on**: ..."
-  const sectionRegex = /### Phase (\d+):[\s\S]*?\*\*Depends on\*\*:\s*([^\n]+)/g;
+  const sectionRegex = /### Phase (\d+):[\s\S]*?\*\*Depends on:?\*\*:?\s*([^\n]+)/g;
   let match;
 
   while ((match = sectionRegex.exec(roadmapContent)) !== null) {
@@ -92,7 +92,7 @@ function extractMilestones(roadmapContent) {
   const projectTitle = titleMatch ? titleMatch[1].trim() : 'Project';
 
   // Parse explicit milestones: "## Milestone: Name\n\n**Goal:** ...\n**Phases:** N - M"
-  const milestoneRegex = /## Milestone:\s*(.+)\n\n\*\*Goal:\*\*\s*(.+)\n\*\*Phases:\*\*\s*(\d+)\s*-\s*(\d+)/g;
+  const milestoneRegex = /## Milestone:\s*(.+)\n+\*\*Goal:?\*\*:?\s*(.+)\n\*\*Phases:?\*\*:?\s*(\d+)\s*-\s*(\d+)/g;
   const explicit = [];
   for (const match of roadmapContent.matchAll(milestoneRegex)) {
     explicit.push({

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

@@ -10,14 +10,15 @@
   </header>
   <%
     // Map verification status to CSS status-badge data-status values
+    var vStatus = verification.status || verification.verdict || 'unknown';
     var verificationCssStatus = 'not-started';
-    if (verification.status === 'passed') verificationCssStatus = 'complete';
-    else if (verification.status === 'failed') verificationCssStatus = 'blocked';
-    else if (verification.status === 'partial') verificationCssStatus = 'in-progress';
+    if (vStatus === 'passed') verificationCssStatus = 'complete';
+    else if (vStatus === 'failed') verificationCssStatus = 'blocked';
+    else if (vStatus === 'partial') verificationCssStatus = 'in-progress';
   %>
   <p>
     <span class="status-badge" data-status="<%= verificationCssStatus %>">
-      <%= verification.status.toUpperCase() %>
+      <%= vStatus.toUpperCase() %>
     </span>
     <% if (verification.verified) { %>
       &nbsp; Verified: <%= new Date(verification.verified).toLocaleString() %>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.0.2",
+  "version": "2.2.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

@@ -11,7 +11,7 @@
   "homepage": "https://github.com/SienkLogic/plan-build-run",
   "repository": "https://github.com/SienkLogic/plan-build-run",
   "license": "MIT",
-  "logo": "assets/logo.png",
+  "logo": "../assets/logo.svg",
   "keywords": ["cursor", "context-engineering", "development-workflow", "subagent-delegation"],
   "category": "developer-tools",
   "tags": ["planning", "workflow", "structured-development", "context-management"],

package/plugins/cursor-pbr/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## v2.0.0 (2026-02-19)
+
+Initial release of Plan-Build-Run for Cursor.
+
+### Features
+
+- 21 skills covering the full development lifecycle: begin, plan, build, review, debug, and more
+- 10 specialized agents with fresh context windows for delegation without context rot
+- Shared hook scripts with the Claude Code plugin for consistent behavior
+- Cross-plugin compatibility: shared `.planning/` state directory works with both Cursor and Claude Code
+- File-based state management with structured planning, execution, and verification phases
+- Atomic commits with deviation handling and self-verification
+- Goal-backward verification ensuring builds match plans

package/plugins/cursor-pbr/README.md

@@ -0,0 +1,118 @@
+# Plan-Build-Run for Cursor
+
+A structured development workflow plugin for Cursor that solves context rot through disciplined subagent delegation, file-based state, and goal-backward verification.
+
+## Installation
+
+### Automated Setup (Recommended)
+
+The setup script creates symlinks from your project's `.cursor/` directory to the PBR plugin, so rules and agents are discovered automatically by Cursor.
+
+**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
+```
+
+This installs:
+- `.cursor/rules/pbr-workflow.mdc` — Workflow rules (auto-loaded when `.planning/` exists)
+- `.cursor/agents/*.md` — 10 specialized agent definitions
+
+### Manual Setup
+
+If you prefer not to use the setup script:
+
+1. Copy or symlink `rules/pbr-workflow.mdc` into your project's `.cursor/rules/` directory
+2. Copy or symlink all files from `agents/` into your project's `.cursor/agents/` directory
+3. Skills (in `skills/`) are prompt templates — paste a skill's `SKILL.md` content into Cursor chat to invoke it, or reference the skill directory if Cursor supports skill discovery
+
+### Uninstall
+
+Remove the symlinks created by setup:
+
+```bash
+rm .cursor/rules/pbr-workflow.mdc
+rm .cursor/agents/*.md    # only PBR agent files
+```
+
+## Quick Start
+
+The core workflow follows four steps per phase:
+
+```
+/pbr:begin     — Define your project: requirements, research, roadmap
+/pbr:plan 1    — Create a detailed plan for phase 1
+/pbr:build 1   — Execute the plan with atomic commits
+/pbr:review 1  — Verify the build matched the plan
+```
+
+Repeat `plan` / `build` / `review` for each phase in your roadmap.
+
+## Skills (21)
+
+| Skill | Description |
+|-------|-------------|
+| begin | Start a new project. Deep questioning, research, requirements, and roadmap. |
+| build | Execute all plans in a phase. Spawns agents to build in parallel, commits atomically. |
+| config | Configure settings: depth, model profiles, features, git, and gates. |
+| continue | Execute the next logical step automatically. No prompts, no decisions. |
+| debug | Systematic debugging with hypothesis testing. Persistent across sessions. |
+| discuss | Talk through a phase before planning. Identifies gray areas and captures decisions. |
+| explore | Explore ideas, think through approaches, and route insights to the right artifacts. |
+| health | Check planning directory integrity. Find and fix corrupted state. |
+| help | Command reference and workflow guide. |
+| import | Import external plans. Validates context, detects conflicts, generates PLAN.md. |
+| milestone | Manage milestones: new, complete, audit, gaps. |
+| note | Zero-friction idea capture. Append, list, or promote notes to todos. |
+| pause | Save your current session state for later resumption. |
+| plan | Create a detailed plan for a phase. Research, plan, and verify before building. |
+| quick | Execute an ad-hoc task with atomic commits. Skips full plan/review. |
+| resume | Pick up where you left off. Restores context and suggests next action. |
+| review | Verify the build matched the plan. Automated checks plus walkthrough. |
+| scan | Analyze an existing codebase. Maps structure, architecture, conventions, and concerns. |
+| setup | Onboarding wizard. Initialize project, select models, verify setup. |
+| status | Show current project status and suggest what to do next. |
+| todo | File-based persistent todos. Add, list, complete — survives sessions. |
+
+Skills live in `skills/{name}/SKILL.md`. Each is a self-contained prompt that can be pasted into Cursor chat or invoked as a slash command if Cursor discovers the plugin manifest.
+
+## Agents (10)
+
+| Agent | Description |
+|-------|-------------|
+| codebase-mapper | Explores codebases and writes structured analysis across four focus areas. |
+| debugger | Systematic debugging using scientific method with hypothesis testing and evidence tracking. |
+| executor | Executes plan tasks with atomic commits, deviation handling, and self-verification. |
+| general | Lightweight agent for ad-hoc tasks that don't fit specialized roles. |
+| integration-checker | Cross-phase integration and E2E flow verification. |
+| plan-checker | Verifies plans will achieve phase goals before execution via goal-backward analysis. |
+| planner | Creates executable phase plans with task breakdown, dependency analysis, and wave assignment. |
+| researcher | Unified research agent for project domains and implementation approaches. |
+| synthesizer | Fast synthesis of multiple research outputs into coherent recommendations. |
+| verifier | Goal-backward phase verification against the real codebase. |
+
+## Configuration
+
+Plan-Build-Run stores all state in a `.planning/` directory at your project root:
+
+- `.planning/config.json` — Workflow settings (~62 properties across 12 keys)
+- `.planning/STATE.md` — Current position and status
+- `.planning/ROADMAP.md` — Phase structure, goals, and dependencies
+- `.planning/phases/NN-slug/` — Per-phase plans, summaries, and verification reports
+
+Run `/pbr:config` to interactively adjust settings like depth, model profiles, and gate behavior.
+
+## Cross-Plugin Compatibility
+
+This plugin works alongside the Claude Code version of Plan-Build-Run. Both plugins share the same `.planning/` directory and file formats, so you can switch between Cursor and Claude Code without losing state. Hook scripts under `plugins/pbr/scripts/` are shared between both plugins via relative paths.
+
+## Links
+
+- Repository: [https://github.com/SienkLogic/plan-build-run](https://github.com/SienkLogic/plan-build-run)
+- License: MIT