@sienklogic/plan-build-run 2.18.1 → 2.19.1

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

@@ -1,112 +0,0 @@
-<!-- Source: agents/researcher.md | Purpose: Output format for research project SUMMARY.md (executive overview with roadmap implications) -->
-# Project Research Summary
-
-**Project:** {project_name}
-**Domain:** {domain}
-**Researched:** {date}
-**Confidence:** {confidence}
-
-## Executive Summary
-
-{executive_summary}
-
-## Key Findings
-
-### Recommended Stack
-
-{stack_summary}
-
-**Core technologies:**
-- {technology}: {purpose} -- {rationale}
-
-### Expected Features
-
-{features_summary}
-
-**Must have (table stakes):**
-- {feature} -- users expect this
-
-**Should have (competitive):**
-- {feature} -- differentiator
-
-**Defer (v2+):**
-- {feature} -- not essential for launch
-
-### Architecture Approach
-
-{architecture_summary}
-
-**Major components:**
-1. {component} -- {responsibility}
-2. {component} -- {responsibility}
-3. {component} -- {responsibility}
-
-### Critical Pitfalls
-
-{pitfalls_summary}
-
-1. **{pitfall}** -- {avoidance}
-2. **{pitfall}** -- {avoidance}
-3. **{pitfall}** -- {avoidance}
-
-## Implications for Roadmap
-
-Based on research, suggested phase structure:
-
-### Phase 1: {phase_name}
-**Rationale:** {why_first}
-**Delivers:** {deliverables}
-**Addresses:** {features}
-**Avoids:** {pitfall}
-
-### Phase 2: {phase_name}
-**Rationale:** {why_this_order}
-**Delivers:** {deliverables}
-**Uses:** {stack_elements}
-**Implements:** {architecture_component}
-
-### Phase 3: {phase_name}
-**Rationale:** {why_this_order}
-**Delivers:** {deliverables}
-
-### Phase Ordering Rationale
-
-- {ordering_rationale}
-
-### Research Flags
-
-Phases likely needing deeper research during planning:
-- **Phase {x}:** {reason}
-
-Phases with standard patterns (skip research-phase):
-- **Phase {x}:** {reason}
-
-## Confidence Assessment
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | {confidence} | {notes} |
-| Features | {confidence} | {notes} |
-| Architecture | {confidence} | {notes} |
-| Pitfalls | {confidence} | {notes} |
-
-**Overall confidence:** {confidence}
-
-### Gaps to Address
-
-- {gap}: {handling}
-
-## Sources
-
-### Primary (HIGH confidence)
-- {source}
-
-### Secondary (MEDIUM confidence)
-- {source}
-
-### Tertiary (LOW confidence)
-- {source}
-
----
-*Research completed: {date}*
-*Ready for roadmap: yes*

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

@@ -1,81 +0,0 @@
-# Phase Research: {Phase Name}
-
-> Research conducted: {date}
-> Research date: {ISO date}
-> Mode: phase-research
-> Phase: {NN}-{phase-name}
-> Confidence: {overall HIGH/MEDIUM/LOW}
-> Coverage: {COMPLETE/PARTIAL/INSUFFICIENT}
-> Retrieval cycles: {1-3}
-
-## User Constraints
-
-{Copied verbatim from CONTEXT.md}
-
-## Phase Goal
-
-{What this phase aims to achieve, extracted from the phase definition}
-
-## Implementation Approach
-
-### Recommended Approach
-
-{Detailed implementation strategy with source attribution}
-
-**Steps**:
-1. {Step with [S{n}] attribution}
-2. ...
-
-**Key decisions**:
-- {Decision with rationale and source}
-
-### Configuration Details
-
-{Specific configuration values, environment variables, file paths}
-
-```{language}
-// Source: [S{n}]
-{configuration example}
-```
-
-### API Patterns
-
-{Relevant API signatures, request/response formats, authentication patterns}
-
-### Data Models
-
-{Database schemas, type definitions, data flow}
-
-## Dependencies
-
-{What needs to be installed, configured, or available}
-
-| Dependency | Version | Purpose | Required By |
-|-----------|---------|---------|-------------|
-| ... | ... | ... | ... |
-
-## Pitfalls for This Phase
-
-{Phase-specific things that can go wrong}
-
-1. **{Pitfall}** [S{n}]: {Description}
-
-## Testing Strategy
-
-{How to verify this phase works correctly}
-
-## Coverage Assessment
-
-| Question | Status | Confidence | Cycle Resolved |
-|----------|--------|------------|----------------|
-| {Implementation question 1} | ANSWERED | HIGH | 1 |
-| {Implementation question 2} | GAP | — | — |
-
-**Overall coverage**: {COMPLETE/PARTIAL/INSUFFICIENT}
-**Gaps remaining**: {List any unresolved questions}
-
-## Sources
-
-| # | Type | URL/Description | Confidence |
-|---|------|----------------|------------|
-| ... | ... | ... | ... |

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

@@ -1,99 +0,0 @@
-# Research: {Topic Title}
-
-> Research conducted: {date}
-> Research date: {ISO date}
-> Mode: project-research
-> Confidence: {overall HIGH/MEDIUM/LOW}
-> Coverage: {COMPLETE/PARTIAL/INSUFFICIENT}
-> Retrieval cycles: {1-3}
-> Sources consulted: {count}
-
-## User Constraints
-
-{Copied verbatim from CONTEXT.md if it exists. Otherwise: "No CONTEXT.md found."}
-
-## Executive Summary
-
-{2-3 paragraph overview of findings. What is this technology/domain? Why does it matter for this project? What is the recommended approach?}
-
-## Standard Stack
-
-{The conventional/recommended technology stack for this domain}
-
-| Layer | Technology | Version | Confidence | Source |
-|-------|-----------|---------|------------|--------|
-| Runtime | Node.js | 20.x LTS | HIGH | [S2] |
-| Framework | Next.js | 14.x | HIGH | [S2] |
-| ... | ... | ... | ... | ... |
-
-### Stack Rationale
-
-{Why this combination? What alternatives were considered and why they were rejected?}
-
-### Stack Risks
-
-{Known issues, upcoming deprecations, migration concerns}
-
-## Architecture Patterns
-
-### Recommended Pattern: {Name}
-
-{Description with source attribution}
-
-**When to use**: ...
-**When to avoid**: ...
-**Example structure**:
-```
-project/
-  src/
-    ...
-```
-
-### Alternative Pattern: {Name}
-
-{Only include if CONTEXT.md doesn't lock the architecture}
-
-## Common Pitfalls
-
-{Numbered list of things that commonly go wrong}
-
-1. **{Pitfall name}** [S{n}]: {Description and how to avoid}
-2. ...
-
-## Code Examples
-
-{Working code snippets for key patterns. Every snippet must include source attribution.}
-
-### {Pattern Name}
-
-```{language}
-// Source: [S{n}] {url or description}
-{code}
-```
-
-## Integration Points
-
-{How this technology connects with other systems. API patterns, data flow, authentication.}
-
-## Coverage Assessment
-
-| Question | Status | Confidence | Cycle Resolved |
-|----------|--------|------------|----------------|
-| {Core question 1} | ANSWERED | HIGH | 1 |
-| {Core question 2} | ANSWERED | MEDIUM | 2 |
-| {Core question 3} | GAP | — | — |
-
-**Overall coverage**: {COMPLETE/PARTIAL/INSUFFICIENT}
-**Gaps remaining**: {List any unresolved questions and why they couldn't be answered}
-
-## Open Questions
-
-{Things the research could not definitively answer. These need human input or further investigation.}
-
-## Sources
-
-| # | Type | URL/Description | Confidence |
-|---|------|----------------|------------|
-| S1 | Official Docs | {url} | HIGH |
-| S2 | GitHub | {url} | HIGH |
-| ... | ... | ... | ... |

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

@@ -1,36 +0,0 @@
-# Research Synthesis: {Topic}
-
-> Synthesized: {date}
-> Mode: synthesis
-> Input documents: {count}
-> Confidence: {overall}
-
-## Executive Summary
-
-{Unified findings across all input documents}
-
-## Key Findings
-
-{Numbered list of the most important findings, with source document attribution}
-
-## Contradictions Resolved
-
-{Where input documents disagreed and how it was resolved}
-
-| Topic | Document A Says | Document B Says | Resolution | Basis |
-|-------|----------------|----------------|------------|-------|
-| ... | ... | ... | ... | ... |
-
-## Recommended Approach
-
-{The synthesized recommendation}
-
-## Risks and Mitigations
-
-| Risk | Likelihood | Impact | Mitigation |
-|------|-----------|--------|------------|
-| ... | ... | ... | ... |
-
-## Sources
-
-{Consolidated source list from all input documents}

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

@@ -1,32 +0,0 @@
-{
-  "name": "pbr",
-  "displayName": "Plan-Build-Run",
-  "version": "2.18.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",
-    "email": "dave@sienklogic.com"
-  },
-  "publisher": "SienkLogic",
-  "homepage": "https://github.com/SienkLogic/plan-build-run",
-  "repository": "https://github.com/SienkLogic/plan-build-run",
-  "license": "MIT",
-  "logo": "../assets/logo.svg",
-  "keywords": [
-    "cursor",
-    "context-engineering",
-    "development-workflow",
-    "subagent-delegation"
-  ],
-  "category": "developer-tools",
-  "tags": [
-    "planning",
-    "workflow",
-    "structured-development",
-    "context-management"
-  ],
-  "skills": "./skills/",
-  "agents": "./agents/",
-  "rules": "./rules/",
-  "hooks": "./hooks/hooks.json"
-}

package/plugins/cursor-pbr/CHANGELOG.md

@@ -1,15 +0,0 @@
-# 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

@@ -1,123 +0,0 @@
-# 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 (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. |
-| 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. |
-| 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 (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. |
-| 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

package/plugins/cursor-pbr/agents/audit.md

@@ -1,178 +0,0 @@
----
-name: audit
-description: "Analyzes Claude Code session logs for PBR workflow compliance, hook firing, state file hygiene, and user experience quality."
-model: sonnet
-readonly: true
----
-
-# Plan-Build-Run Session Auditor
-
-You are **audit**, the session analysis agent for the Plan-Build-Run development system. You analyze Claude Code session JSONL logs to evaluate PBR workflow compliance, hook firing, state management, commit discipline, and user experience quality.
-
-## Core Principle
-
-**Evidence over assumption.** Every finding must cite specific JSONL line numbers, timestamps, or tool call IDs. Never infer hook behavior without evidence — absent evidence means "no evidence found," not "hooks didn't fire."
-
----
-
-## Input
-
-You receive a prompt containing:
-- **Session JSONL path**: Absolute path to the session log file
-- **Subagent paths**: Optional paths to subagent logs in the `subagents/` subdirectory
-- **Audit mode**: `compliance` (workflow correctness) or `ux` (user experience) or `full` (both)
-- **Output path**: Where to write findings
-
----
-
-## JSONL Format
-
-Session logs are newline-delimited JSON. Key entry types:
-
-| Field | Values | Meaning |
-|-------|--------|---------|
-| `type` | `user`, `assistant`, `progress` | Entry type |
-| `message.role` | `human`, `assistant` | Who sent it |
-| `data.type` | `hook_progress` | Hook execution evidence |
-| `data.hookEvent` | `SessionStart`, `PreToolUse`, `PostToolUse`, etc. | Which hook event |
-| `timestamp` | ISO 8601 | When it occurred |
-| `sessionId` | UUID | Session identifier |
-
-User messages contain the actual commands (`/pbr:build`, `/pbr:quick`, etc.) and freeform instructions.
-
----
-
-## Compliance Audit Checklist
-
-For each session, check:
-
-### 1. PBR Commands Used
-- Extract all `/pbr:*` command invocations from user messages
-- Was the command sequence logical? (e.g., plan before build, build before review)
-- Were there commands that SHOULD have been used but weren't?
-
-### 2. STATE.md Lifecycle
-- Was STATE.md read before starting work?
-- Was STATE.md updated at phase transitions?
-- After context compaction/continuation, was STATE.md re-read?
-
-### 3. ROADMAP.md Consultation
-- Was ROADMAP.md read during build, plan, or milestone operations?
-
-### 4. SUMMARY.md Creation
-- After any build or quick task, was SUMMARY.md created?
-- Does it contain required frontmatter fields (`requires`, `key_files`, `deferred`)?
-
-### 5. Hook Evidence
-- Are there `hook_progress` entries in the log?
-- Which hooks fired and how many times?
-- Were any hooks missing that should have fired?
-- If NO hook evidence exists, flag as HIGH severity
-
-### 6. Commit Format
-- Extract all `git commit` commands from Bash tool calls
-- Verify format: `{type}({scope}): {description}`
-- Check for forbidden `Co-Authored-By` lines
-
-### 7. Subagent Delegation
-- Was implementation work delegated to executor subagents?
-- Or was it done directly in main context (anti-pattern)?
-- Count tool calls in main context vs subagents
-
-### 8. Active Skill Management
-- Was `.active-skill` written when skills were invoked?
-- Was it cleaned up when skills completed?
-
----
-
-## UX Audit Checklist
-
-For each session, evaluate:
-
-### 1. User Intent vs Assistant Behavior
-- What did the user ask for? (Extract exact user messages)
-- Did the assistant deliver what was asked?
-- Did the user have to repeat instructions? (Escalation = frustration)
-- Count the number of course-corrections
-
-### 2. Flow Choice Quality
-- Was the chosen PBR command the best fit for the task?
-- Would a different command have been more efficient?
-- Was the ceremony proportionate to the task scope?
-
-### 3. Feedback and Progress
-- Were there progress updates during long operations?
-- Were CI results communicated clearly?
-- Were there silent gaps with no user feedback?
-
-### 4. Handoff Quality
-- After skill completion, was the next step suggested?
-- Did the user know what to do next?
-
-### 5. Context Efficiency
-- Did the session approach or hit context limits?
-- Was work delegated to subagents appropriately?
-- Were there unnecessary file reads burning context?
-
----
-
-## Output Format
-
-Return findings as structured markdown (inline in your response):
-
-```markdown
-# PBR Session Audit
-
-## Session Metadata
-- **Session ID**: {id}
-- **Time Range**: {start} to {end}
-- **Duration**: {duration}
-
-## PBR Commands Invoked
-| # | Command | Arguments | Timestamp |
-|---|---------|-----------|-----------|
-
-## Compliance Score
-| Category | Status | Details |
-|----------|--------|---------|
-
-## UX Score (if audit mode includes UX)
-| Dimension | Rating | Details |
-|-----------|--------|---------|
-
-## Hook Firing Report
-| Hook Event | Count | Notes |
-|------------|-------|-------|
-
-## Commits Made
-| Hash | Message | Format Valid? |
-|------|---------|---------------|
-
-## Issues Found
-### Critical
-### High
-### Medium
-### Low
-
-## Recommendations
-```
-
----
-
-## Context Budget
-
-- **Maximum**: 50% of context for reading logs, 50% for analysis and output
-- Large JSONL files (>1MB): Read in chunks using `offset` and `limit` on Read tool, or use Bash with `wc -l` to assess size first, then sample key sections
-- Focus on user messages (`"role": "human"`), tool calls, and hook progress entries
-- Skip verbose tool output content — focus on tool names and results
-
----
-
-## Anti-Patterns
-
-1. DO NOT guess what hooks did — only report what the log evidence shows
-2. DO NOT read the entire JSONL if it exceeds 2000 lines — sample strategically
-3. DO NOT judge workflow violations without understanding the skill type (explore is read-only, doesn't need STATE.md updates)
-4. DO NOT fabricate timestamps or session IDs
-5. DO NOT include raw JSONL content in the output — summarize findings
-6. DO NOT over-report informational items as critical — use appropriate severity