@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/copilot-pbr/templates/research-outputs/ARCHITECTURE.md.tmpl

@@ -0,0 +1,91 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges architecture findings into SUMMARY.md. Needs: component list, pattern names, data flow summary.
+  - Planner agent: uses architecture for phase dependency ordering. Needs: component dependencies, build order implications, API contract shapes.
+  - Build skill: uses architecture patterns during implementation. Needs: specific patterns tied to the chosen stack, anti-patterns to avoid.
+  Breaks if missing: Planner creates phases with wrong dependency order; build agents implement without architectural guidance.
+-->
+# Architecture Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## System Architecture
+
+{High-level overview of the system architecture and its major components.}
+
+## Component Diagram
+
+```
+{text_based_component_diagram}
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Depends On |
+|-----------|----------------|------------|
+| {component} | {responsibility} | {dependencies} |
+
+## Data Flow
+
+### Primary Data Flow
+
+```
+{text_based_data_flow_diagram}
+```
+
+### Key Data Paths
+
+1. **{path_name}:** {description_of_data_flow}
+
+## API Contracts
+
+### {API Endpoint or Interface}
+
+**Request:**
+```
+{request_shape}
+```
+
+**Response:**
+```
+{response_shape}
+```
+
+**Error cases:** {error_description}
+
+## Architecture Patterns
+
+| Pattern | Where Used | Why |
+|---------|-----------|-----|
+| {pattern_name} | {component_or_layer} | {rationale} |
+
+### Pattern Details
+
+#### {Pattern Name}
+
+**What:** {description}
+**When to use:** {conditions}
+**Trade-offs:** {pros_and_cons}
+
+## Anti-Patterns to Avoid
+
+1. **{anti_pattern_name}**
+   - **What people do:** {mistake}
+   - **Why it fails:** {problem}
+   - **Do instead:** {correct_approach}
+
+## Quality Gates
+
+- [ ] Architecture patterns are specific to the chosen stack (not generic advice)
+- [ ] Data flow covers all major paths (happy path, error path, async flows)
+- [ ] API contracts include request shape, response shape, and error cases
+- [ ] Component diagram shows all major components and their connections
+- [ ] At least 2 anti-patterns documented with concrete alternatives
+- [ ] Sources include at least one official documentation or architecture guide reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/copilot-pbr/templates/research-outputs/FEATURES.md.tmpl

@@ -0,0 +1,64 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges feature findings into SUMMARY.md. Needs: categorized feature list with priorities and effort estimates.
+  - Planner agent: uses feature priorities for requirement prioritization and phase scoping. Needs: must-have/should-have/defer categorization, effort estimates.
+  - Begin skill: presents feature inventory to user for scope discussion. Needs: clear feature descriptions with competitive context.
+  Breaks if missing: Planner scopes phases without feature priority data; synthesizer produces SUMMARY with no feature guidance.
+-->
+# Features Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Feature Inventory
+
+| Feature | Category | Priority | Effort | Description |
+|---------|----------|----------|--------|-------------|
+| {feature} | {category} | {must-have/should-have/defer} | {S/M/L/XL} | {brief_description} |
+
+## Competitive Analysis
+
+| Feature | Our Approach | Alternative 1 | Alternative 2 | Tradeoff |
+|---------|-------------|---------------|---------------|----------|
+| {feature} | {our_approach} | {alt_1} | {alt_2} | {tradeoff_analysis} |
+
+## Prioritization Rationale
+
+### Must-Have (table stakes)
+
+{Features users expect as baseline. Without these, the product is not viable.}
+
+- **{feature}:** {why_must_have}
+
+### Should-Have (competitive)
+
+{Features that differentiate from alternatives. Important but not blocking launch.}
+
+- **{feature}:** {why_should_have}
+
+### Defer (v2+)
+
+{Features explicitly excluded from initial scope with rationale.}
+
+- **{feature}:** {why_defer}
+
+## Deferred Features
+
+| Feature | Reason Deferred | Revisit When | Effort if Added Later |
+|---------|----------------|--------------|----------------------|
+| {feature} | {reason} | {trigger} | {effort_estimate} |
+
+## Quality Gates
+
+- [ ] Every feature categorized as must-have, should-have, or defer
+- [ ] Effort estimates present for all features (S/M/L/XL)
+- [ ] Competitive analysis has at least 2 alternatives per major feature
+- [ ] Must-have features have clear rationale for why they are table stakes
+- [ ] Deferred features include revisit triggers
+- [ ] Sources include at least one market or user research reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/copilot-pbr/templates/research-outputs/PITFALLS.md.tmpl

@@ -0,0 +1,50 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges pitfall findings into SUMMARY.md. Needs: numbered pitfalls with severity and avoidance strategies.
+  - Planner agent: reads pitfalls to add defensive verification steps to plans. Needs: specific, actionable avoidance strategies.
+  - Build skill: uses avoidance strategies during implementation. Needs: detection methods to catch pitfalls early.
+  Breaks if missing: Plans lack defensive verification; synthesizer produces SUMMARY with no risk awareness.
+-->
+# Pitfalls Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Critical Pitfalls
+
+{Pitfalls that cause project failure or major rework if not avoided.}
+
+1. **{pitfall_name}** [{source}]
+   - **Impact:** {what_goes_wrong}
+   - **Root cause:** {why_it_happens}
+   - **Avoidance:** {specific_steps_to_prevent}
+   - **Detection:** {how_to_catch_early}
+
+## Common Mistakes
+
+{Mistakes that cause delays but are recoverable.}
+
+1. **{mistake_name}** [{source}]
+   - **Impact:** {what_goes_wrong}
+   - **Avoidance:** {what_to_do_instead}
+
+## Environment-Specific Gotchas
+
+| Environment | Gotcha | Workaround |
+|-------------|--------|------------|
+| {env} | {issue} | {fix} |
+
+## Quality Gates
+
+- [ ] At least 3 critical pitfalls identified with source attribution
+- [ ] Each critical pitfall has a concrete avoidance strategy (not "be careful")
+- [ ] Each critical pitfall has a detection method
+- [ ] Environment-specific gotchas checked for target platform
+- [ ] Common mistakes section has at least 2 entries
+- [ ] Sources include at least one official documentation reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/copilot-pbr/templates/research-outputs/STACK.md.tmpl

@@ -0,0 +1,63 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges stack findings into SUMMARY.md. Needs: technology table with versions and rationale, confidence levels per recommendation.
+  - Planner agent: uses stack decisions for phase planning and dependency ordering. Needs: prescriptive technology choices (not "consider X or Y"), version numbers, package manager.
+  - Dashboard ResearchTab: displays research confidence. Needs: frontmatter confidence field.
+  Breaks if missing: Synthesizer produces SUMMARY with vague stack section; planner makes technology decisions without research backing.
+-->
+# Stack Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Core Stack
+
+| Technology | Version | Purpose | Why Standard |
+|------------|---------|---------|--------------|
+| {technology} | {version} | {purpose} | {rationale} |
+
+## Supporting Tools
+
+| Tool | Version | Purpose | When to Use |
+|------|---------|---------|-------------|
+| {tool} | {version} | {purpose} | {use_case} |
+
+## Package Manager
+
+**Recommended:** {package_manager}
+**Why:** {rationale}
+
+## Deployment Target
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Platform | {platform} | {notes} |
+| Hosting | {hosting} | {notes} |
+| CI/CD | {ci_cd} | {notes} |
+
+## Alternatives Considered
+
+| Recommended | Alternative | Why Not |
+|-------------|-------------|---------|
+| {our_choice} | {alternative} | {rejection_reason} |
+
+## Version Compatibility
+
+| Package A | Compatible With | Notes |
+|-----------|-----------------|-------|
+| {package_a} | {package_b} | {compatibility_notes} |
+
+## Quality Gates
+
+- [ ] All technology recommendations are prescriptive ("Use X") not exploratory ("Consider X or Y")
+- [ ] Every technology entry has a specific version number (not "latest")
+- [ ] Core stack table has at least 3 entries
+- [ ] Alternatives Considered table documents at least 2 rejected alternatives with rationale
+- [ ] Package manager recommendation includes rationale
+- [ ] Sources include at least one official documentation reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/copilot-pbr/templates/research-outputs/SUMMARY.md.tmpl

@@ -0,0 +1,98 @@
+<!-- Downstream consumers:
+  - Planner agent (primary consumer): reads SUMMARY.md for all phase planning decisions. Needs: stack recommendation, architecture recommendation, key risks, feature priorities, confidence assessment.
+  - Begin skill: presents synthesis to user for approval before roadmap creation. Needs: executive summary, consolidated recommendations.
+  - Dashboard ResearchTab: displays synthesis with confidence levels. Needs: confidence assessment table, research coverage.
+  Breaks if missing: Planner makes phase decisions without research backing; user approves roadmap without seeing synthesis; dashboard shows empty research card.
+-->
+# Research Synthesis
+
+**Synthesized:** {date}
+**Input documents:** {count}
+**Confidence:** {overall_confidence}
+
+## Executive Summary
+
+{Unified findings across all research dimensions in under 200 words. State: what was researched, key conclusions, primary recommendation, and confidence level.}
+
+## Stack Recommendation
+
+**Recommended stack:** {one_line_summary}
+
+{Key technology choices with rationale, sourced from STACK research.}
+
+- **{technology}:** {version} -- {why_chosen}
+
+## Architecture Recommendation
+
+**Recommended pattern:** {pattern_name}
+
+{Architecture approach with component overview, sourced from ARCHITECTURE research.}
+
+- **{component}:** {responsibility}
+
+## Key Risks
+
+{Top risks from PITFALLS research, ordered by impact.}
+
+1. **{risk}** -- {mitigation}
+2. **{risk}** -- {mitigation}
+3. **{risk}** -- {mitigation}
+
+## Feature Priorities
+
+{Prioritized feature summary from FEATURES research.}
+
+**Must-have:** {must_have_features}
+**Should-have:** {should_have_features}
+**Deferred:** {deferred_features}
+
+## Consolidated Recommendations
+
+{Actionable recommendations that integrate findings across all dimensions.}
+
+1. {recommendation}
+2. {recommendation}
+3. {recommendation}
+
+## Confidence Assessment
+
+| Dimension | Confidence | Gaps |
+|-----------|------------|------|
+| Stack | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Features | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Architecture | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Pitfalls | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+
+**Overall confidence:** {confidence}
+
+## Research Coverage
+
+| Dimension | Status | Notes |
+|-----------|--------|-------|
+| Stack | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Features | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Architecture | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Pitfalls | {COMPLETE/PARTIAL/MISSING} | {notes} |
+
+**Dimensions researched:** {count}/4
+**Gaps requiring attention:** {list_or_none}
+
+## Quality Gates
+
+- [ ] Executive summary is under 200 words
+- [ ] All 4 research dimensions referenced (Stack, Features, Architecture, Pitfalls)
+- [ ] Confidence gaps explicitly listed for each dimension
+- [ ] Recommendations are prescriptive and actionable (not "consider" or "evaluate")
+- [ ] Partial failure handled -- missing dimensions noted, not silently omitted
+- [ ] Sources consolidated from all input documents
+
+## Sources
+
+### Primary (HIGH confidence)
+- {source}
+
+### Secondary (MEDIUM confidence)
+- {source}
+
+### Tertiary (LOW confidence)
+- {source}

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

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.0.0",
+  "version": "2.1.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",
@@ -12,9 +12,19 @@
   "repository": "https://github.com/SienkLogic/plan-build-run",
   "license": "MIT",
   "logo": "../assets/logo.svg",
-  "keywords": ["cursor", "context-engineering", "development-workflow", "subagent-delegation"],
+  "keywords": [
+    "cursor",
+    "context-engineering",
+    "development-workflow",
+    "subagent-delegation"
+  ],
   "category": "developer-tools",
-  "tags": ["planning", "workflow", "structured-development", "context-management"],
+  "tags": [
+    "planning",
+    "workflow",
+    "structured-development",
+    "context-management"
+  ],
   "skills": "./skills/",
   "agents": "./agents/",
   "rules": "./rules/",

package/plugins/cursor-pbr/README.md

@@ -46,24 +46,27 @@ rm .cursor/agents/*.md    # only PBR agent files
 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
+/pbr:new-project     — Define your project: requirements, research, roadmap
+/pbr:plan-phase 1    — Create a detailed plan for phase 1
+/pbr:execute-phase 1   — Execute the plan with atomic commits
+/pbr:verify-work 1  — Verify the build matched the plan
 ```
 
 Repeat `plan` / `build` / `review` for each phase in your roadmap.
 
-## Skills (21)
+## Skills (25)
 
 | Skill | Description |
 |-------|-------------|
+| audit | Review past Claude Code sessions for PBR workflow compliance and UX quality. |
 | 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. |
+| dashboard | Launch the PBR web dashboard for the current project. |
 | debug | Systematic debugging with hypothesis testing. Persistent across sessions. |
 | discuss | Talk through a phase before planning. Identifies gray areas and captures decisions. |
+| do | Route freeform text to the right PBR skill automatically. |
 | 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. |
@@ -78,14 +81,16 @@ Repeat `plan` / `build` / `review` for each phase in your roadmap.
 | 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. |
+| statusline | Install or configure the PBR status line in Claude Code. |
 | 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)
+## Agents (11)
 
 | Agent | Description |
 |-------|-------------|
+| audit | Analyzes Claude Code session logs for PBR workflow compliance and UX quality. |
 | 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. |
@@ -106,7 +111,27 @@ Plan-Build-Run stores all state in a `.planning/` directory at your project root
 - `.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.
+Run `/pbr:settings` to interactively adjust settings like depth, model profiles, and gate behavior.
+
+## Hook Compatibility
+
+Cursor's plugin hooks.json is configured with all 14 hook events matching Claude Code. However, **whether Cursor IDE actually fires these hooks is unverified** — no integration testing has confirmed hook execution in real Cursor sessions.
+
+**If hooks DO fire**, Cursor gets the full hook experience identical to Claude Code:
+- Commit format enforcement (PreToolUse)
+- PLAN/SUMMARY quality classification via local LLM (PostToolUse)
+- Test failure triage (PostToolUse)
+- Context budget tracking (PostToolUse)
+- Auto-continue between skills (Stop)
+
+**If hooks do NOT fire**, the following are unavailable:
+- Commit format enforcement — commits won't be validated automatically
+- Automatic local LLM classification on writes — but skills include explicit `pbr-tools.js llm` fallback calls for plan quality (build Step 6a), task validation (quick Step 6b), and verification quality (review Step 3b)
+- Context budget tracking — no automatic warnings when context is filling up
+- Auto-continue — you must manually run the next command
+- Subagent lifecycle logging — agent spawn/completion events aren't tracked
+
+**Local LLM via CLI (always works):** Regardless of hook support, skills and agents can call `pbr-tools.js llm` commands directly via Bash. The `/pbr:progress` skill displays local LLM metrics, and agents (debugger, researcher, synthesizer) use CLI commands for error classification, source scoring, and summarization.
 
 ## Cross-Plugin Compatibility