@sienklogic/plan-build-run 2.1.0 → 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/package.json

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

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/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/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/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/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