@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/cursor-pbr/references/wave-execution.md

@@ -1,96 +0,0 @@
-<!-- canonical: ../../pbr/references/wave-execution.md -->
-# Wave-Based Execution
-
-How Plan-Build-Run parallelizes plan execution within a phase while respecting dependencies.
-
----
-
-## What Are Waves?
-
-Waves are dependency-based groupings of plans within a phase. Plans in the same wave have no dependencies on each other and can execute in parallel. Plans in later waves depend on earlier waves completing first.
-
-```
-Wave 1: [plan-01, plan-02]      (no dependencies, can run in parallel)
-Wave 2: [plan-03]               (depends on wave 1 plans)
-Wave 3: [plan-04, plan-05]      (depends on wave 2)
-```
-
-## How Wave Numbers Are Assigned
-
-Wave numbers come from the `depends_on` field in each plan's YAML frontmatter:
-
-```yaml
----
-plan: "03-01"
-wave: 1
-depends_on: []          # No dependencies → Wave 1
----
-```
-
-```yaml
----
-plan: "03-03"
-wave: 2
-depends_on: [03-01]     # Depends on Wave 1 plan → Wave 2
----
-```
-
-**Rules**:
-- Wave 1 plans must have `depends_on: []`
-- Wave 2+ plans must depend only on plans from earlier waves
-- No plan depends on a plan in the same wave (that would require sequential execution within the wave)
-
-## Execution Order
-
-1. All Wave 1 plans execute (in parallel if enabled)
-2. Wait for all Wave 1 plans to complete
-3. All Wave 2 plans execute (in parallel if enabled)
-4. Repeat until all waves complete
-
-## Parallelization Config
-
-Controlled by `config.json`:
-
-```json
-{
-  "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "max_concurrent_agents": 3
-  }
-}
-```
-
-| Setting | Effect |
-|---------|--------|
-| `enabled: false` | All plans execute sequentially, regardless of wave |
-| `plan_level: true` | Plans within a wave run in parallel |
-| `max_concurrent_agents` | Cap on simultaneous executor agents (default: 3) |
-
-When `enabled: false` or `plan_level: false`, plans execute one at a time within each wave, in plan ID order.
-
-## Git Lock Handling
-
-When multiple executors run in parallel, git lock conflicts can occur. Executors handle this with a retry pattern:
-
-```bash
-git commit -m "message" || (sleep 2 && git commit -m "message") || (sleep 2 && git commit -m "message")
-```
-
-Maximum 3 attempts with 2-second delays between retries.
-
-## Checkpoint Manifest
-
-The build skill tracks wave progress in `.checkpoint-manifest.json`:
-
-```json
-{
-  "plans": ["03-01", "03-02", "03-03"],
-  "checkpoints_resolved": ["03-01", "03-02"],
-  "wave": 2,
-  "commit_log": [...],
-  "last_good_commit": "abc1234"
-}
-```
-
-On crash/resume, the manifest tells the build skill which plans are complete and which wave to resume from.

package/plugins/cursor-pbr/rules/pbr-workflow.mdc

@@ -1,48 +0,0 @@
----
-description: "Plan-Build-Run workflow rules for .planning/ managed projects"
-globs: ".planning/**"
-alwaysApply: false
----
-
-# Plan-Build-Run Workflow Rules
-
-When a `.planning/` directory exists, this is a Plan-Build-Run-managed project. Follow these rules:
-
-## Context Awareness
-
-- Check `.planning/STATE.md` for current project context before starting work
-- Read `.planning/config.json` for workflow preferences
-- Respect phase boundaries — don't work on Phase 4 code when Phase 2 is in progress
-
-## Context Budget Management
-
-Context is your scarcest resource. Protect it:
-
-- **Delegate heavy work** to agent invocations — never analyze, research, or build in the main context
-- **Never read agent definitions** (agents/*.md) — agent invocation auto-loads them
-- **Read summaries, not full files** — when checking agent results, read only frontmatter or first 20 lines
-- **Proactive session boundaries**: When you sense context is getting heavy (long conversation, many tool calls, large file reads), proactively tell the user:
-  - "Context is getting full. I recommend running `/pbr:pause` now so we can resume fresh."
-  - Do this BEFORE hitting the limit — once context is compacted, details are lost
-- **After compaction**: If the conversation was auto-compacted, immediately read STATE.md to reorient
-- **One phase per session** is a good rule of thumb for complex work
-
-## Commit Discipline
-
-- Prefer atomic commits per logical change
-- Follow the commit format: `{type}({phase}-{plan}): {description}`
-- Valid types: feat, fix, refactor, test, docs, chore
-
-## Workflow Discipline
-
-- When asked to implement multi-step changes, suggest `/pbr:plan` before diving in
-- When asked to fix bugs, suggest `/pbr:debug` for systematic investigation
-- When asked about project status, suggest `/pbr:status`
-- When starting a new session, suggest `/pbr:resume` if paused work exists
-
-## Planning Integrity
-
-- Do not modify files in `.planning/phases/` directly — use `/pbr:plan` and `/pbr:build`
-- Do not skip verification — use `/pbr:review` after building
-- Respect locked decisions in CONTEXT.md files
-- Do not implement deferred ideas from CONTEXT.md

package/plugins/cursor-pbr/setup.ps1

@@ -1,78 +0,0 @@
-#
-# Plan-Build-Run for Cursor — Setup Script (Windows)
-#
-# Usage:
-#   cd C:\path\to\your\project
-#   powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\cursor-pbr\setup.ps1
-#
-# Creates symlinks in your project's .cursor\ directory so Cursor
-# can discover PBR rules and agents. Requires admin privileges for
-# symlinks on older Windows versions, or Developer Mode enabled.
-
-$ErrorActionPreference = "Stop"
-
-$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
-$PluginDir = $ScriptDir
-$ProjectDir = Get-Location
-
-Write-Host "Plan-Build-Run for Cursor - Setup" -ForegroundColor Cyan
-Write-Host "=================================" -ForegroundColor Cyan
-Write-Host ""
-Write-Host "Plugin source: $PluginDir"
-Write-Host "Target project: $ProjectDir"
-Write-Host ""
-
-# Sanity check
-if (Test-Path (Join-Path $ProjectDir "plugins\cursor-pbr\setup.ps1")) {
-    Write-Host "Error: You appear to be inside the plan-build-run repo itself." -ForegroundColor Red
-    Write-Host "Run this script from your target project directory instead:" -ForegroundColor Red
-    Write-Host ""
-    Write-Host "  cd C:\path\to\your\project"
-    Write-Host "  powershell -ExecutionPolicy Bypass -File $($MyInvocation.MyCommand.Path)"
-    exit 1
-}
-
-# Create .cursor directories
-$rulesDir = Join-Path $ProjectDir ".cursor\rules"
-$agentsDir = Join-Path $ProjectDir ".cursor\agents"
-New-Item -ItemType Directory -Force -Path $rulesDir | Out-Null
-New-Item -ItemType Directory -Force -Path $agentsDir | Out-Null
-
-# --- Rules ---
-Write-Host "Installing rules..."
-$ruleTarget = Join-Path $rulesDir "pbr-workflow.mdc"
-$ruleSource = Join-Path $PluginDir "rules\pbr-workflow.mdc"
-if (Test-Path $ruleTarget) {
-    Write-Host "  pbr-workflow.mdc already exists, skipping (remove it first to reinstall)"
-} else {
-    New-Item -ItemType SymbolicLink -Path $ruleTarget -Target $ruleSource | Out-Null
-    Write-Host "  Linked pbr-workflow.mdc"
-}
-
-# --- Agents ---
-Write-Host "Installing agents..."
-Get-ChildItem (Join-Path $PluginDir "agents\*.md") | ForEach-Object {
-    $agentTarget = Join-Path $agentsDir $_.Name
-    if (Test-Path $agentTarget) {
-        Write-Host "  $($_.Name) already exists, skipping"
-    } else {
-        New-Item -ItemType SymbolicLink -Path $agentTarget -Target $_.FullName | Out-Null
-        Write-Host "  Linked $($_.Name)"
-    }
-}
-
-Write-Host ""
-Write-Host "Setup complete!" -ForegroundColor Green
-Write-Host ""
-Write-Host "What was installed:"
-Write-Host "  .cursor\rules\pbr-workflow.mdc  - Workflow rules (auto-loaded when .planning\ exists)"
-Write-Host "  .cursor\agents\*.md             - 10 specialized agents"
-Write-Host ""
-Write-Host "Next steps:"
-Write-Host "  1. Open this project in Cursor"
-Write-Host "  2. Start a conversation and use /pbr:begin to start a new project"
-Write-Host ""
-Write-Host "Skills are located at:"
-Write-Host "  $PluginDir\skills\"
-Write-Host ""
-Write-Host "To uninstall, remove the symlinks from .cursor\rules\ and .cursor\agents\"

package/plugins/cursor-pbr/setup.sh

@@ -1,83 +0,0 @@
-#!/usr/bin/env bash
-#
-# Plan-Build-Run for Cursor — Setup Script
-#
-# Usage:
-#   cd /path/to/your/project
-#   bash /path/to/plan-build-run/plugins/cursor-pbr/setup.sh
-#
-# This creates symlinks in your project's .cursor/ directory so Cursor
-# can discover PBR rules and agents. The plugin source stays in the
-# plan-build-run repo — symlinks keep everything up to date.
-
-set -euo pipefail
-
-# Resolve the absolute path to the cursor-pbr plugin directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PLUGIN_DIR="$SCRIPT_DIR"
-PROJECT_DIR="$(pwd)"
-
-echo "Plan-Build-Run for Cursor — Setup"
-echo "================================="
-echo ""
-echo "Plugin source: $PLUGIN_DIR"
-echo "Target project: $PROJECT_DIR"
-echo ""
-
-# Sanity check: don't install into the PBR repo itself
-if [ -f "$PROJECT_DIR/plugins/cursor-pbr/setup.sh" ]; then
-  echo "Error: You appear to be inside the plan-build-run repo itself."
-  echo "Run this script from your target project directory instead:"
-  echo ""
-  echo "  cd /path/to/your/project"
-  echo "  bash $0"
-  exit 1
-fi
-
-# Create .cursor directories if they don't exist
-mkdir -p "$PROJECT_DIR/.cursor/rules"
-
-# --- Rules ---
-echo "Installing rules..."
-if [ -e "$PROJECT_DIR/.cursor/rules/pbr-workflow.mdc" ]; then
-  echo "  pbr-workflow.mdc already exists, skipping (remove it first to reinstall)"
-else
-  ln -s "$PLUGIN_DIR/rules/pbr-workflow.mdc" "$PROJECT_DIR/.cursor/rules/pbr-workflow.mdc"
-  echo "  Linked pbr-workflow.mdc"
-fi
-
-# --- Agents ---
-# Cursor reads agent definitions from .cursor/agents/ (if supported)
-echo "Installing agents..."
-mkdir -p "$PROJECT_DIR/.cursor/agents"
-for agent_file in "$PLUGIN_DIR/agents/"*.md; do
-  agent_name="$(basename "$agent_file")"
-  target="$PROJECT_DIR/.cursor/agents/$agent_name"
-  if [ -e "$target" ]; then
-    echo "  $agent_name already exists, skipping"
-  else
-    ln -s "$agent_file" "$target"
-    echo "  Linked $agent_name"
-  fi
-done
-
-echo ""
-echo "Setup complete!"
-echo ""
-echo "What was installed:"
-echo "  .cursor/rules/pbr-workflow.mdc  — Workflow rules (auto-loaded when .planning/ exists)"
-echo "  .cursor/agents/*.md             — 10 specialized agents"
-echo ""
-echo "Next steps:"
-echo "  1. Open this project in Cursor"
-echo "  2. Start a conversation and use /pbr:begin to start a new project"
-echo "     (or paste the contents of a skill's SKILL.md as a prompt)"
-echo ""
-echo "Skills are located at:"
-echo "  $PLUGIN_DIR/skills/"
-echo ""
-echo "To uninstall, remove the symlinks:"
-echo "  rm .cursor/rules/pbr-workflow.mdc"
-echo "  rm .cursor/agents/codebase-mapper.md debugger.md executor.md general.md"
-echo "  rm .cursor/agents/integration-checker.md plan-checker.md planner.md"
-echo "  rm .cursor/agents/researcher.md synthesizer.md verifier.md"

package/plugins/cursor-pbr/skills/audit/SKILL.md

@@ -1,331 +0,0 @@
----
-name: audit
-description: "Review past Claude Code sessions for PBR workflow compliance and UX quality."
-argument-hint: "[--from DATE] [--to DATE] [--today] [--mode compliance|ux|full]"
----
-
-**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 tokens. Begin executing Step 0 immediately.**
-
-## Step 0 — Immediate Output
-
-**Before ANY tool calls**, display this banner:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► SESSION AUDIT                              ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-Then proceed to Step 1.
-
-# /pbr:audit — Session Compliance & UX Review
-
-You are running the **audit** skill. Your job is to analyze past Claude Code session logs for this project, checking PBR workflow compliance (STATE.md updates, hook firing, commit format, skill usage) and user experience quality (flow choice, friction, unmet expectations). You produce a comprehensive report document.
-
-This skill uses **parallel Task() delegation** to analyze multiple sessions simultaneously, keeping main context lean.
-
----
-
-## Context Budget
-
-Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
-
-Additionally for this skill:
-- **Delegate ALL session analysis** to audit agents — do NOT read JSONL files in main context
-- Main context handles: argument parsing, session discovery, agent orchestration, report synthesis
-- Target: main context stays under 20% utilization
-
----
-
-## Step 1 — Parse Arguments
-
-Parse `$ARGUMENTS` for:
-
-| Argument | Default | Description |
-|----------|---------|-------------|
-| `--from DATE` | Start of today | Start of audit window (ISO date or natural language) |
-| `--to DATE` | Now | End of audit window |
-| `--today` | false | Shorthand for `--from` start of today `--to` now |
-| `--mode MODE` | `full` | `compliance` = workflow only, `ux` = user experience only, `full` = both |
-
-**Natural language parsing**: Accept formats like:
-- `--today` or just `today`
-- `--from 2026-02-21` or `--from "yesterday"`
-- `--from "3 days ago"` or `--from "last monday"`
-- A bare date like `02/21` implies `--from 02/21 --to 02/21` (full day)
-- A bare `3` implies last 3 days
-
-If no arguments provided, default to `--today --mode full`.
-
-Display the parsed time range to the user:
-
-```
-Audit window: {from} → {to}
-Mode: {mode}
-```
-
----
-
-## Step 2 — Discover Session Logs
-
-Session JSONL files live at:
-```
-~/.claude/projects/{encoded-project-path}/*.jsonl
-```
-
-Where `{encoded-project-path}` encodes the project directory path (e.g., `D:\Repos\plan-build-run` → `D--Repos-plan-build-run`).
-
-**CRITICAL**: Determine the correct encoded path for the current project by listing `~/.claude/projects/` and finding the directory that matches.
-
-Use Bash to find sessions in the audit window:
-
-```bash
-find ~/.claude/projects/{encoded-path}/ -name "*.jsonl" -maxdepth 1 \
-  -newermt "{from_datetime}" ! -newermt "{to_datetime}" | sort
-```
-
-For each session file found, also check for subagent logs:
-```bash
-ls ~/.claude/projects/{encoded-path}/{session-id}/subagents/*.jsonl 2>/dev/null
-```
-
-Display discovery results:
-
-```
-Found {N} sessions in audit window:
-  {session-id-1} ({size}, {date})
-  {session-id-2} ({size}, {date})
-  ...
-```
-
-If no sessions found, display an error and exit:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-No session logs found between {from} and {to}.
-Check: ~/.claude/projects/{encoded-path}/
-```
-
----
-
-## Step 3 — Discover Git Activity
-
-In parallel with session analysis (Step 4), gather git commit data for the audit window:
-
-```bash
-git log --since="{from_iso}" --until="{to_iso}" --format="%h %s %an %ai" --all
-```
-
-Check for:
-- Conventional commit format violations
-- Forbidden `Co-Authored-By` lines
-- Release-please automated commits
-
-This data feeds into the final report synthesis.
-
----
-
-## Step 4 — Spawn Audit Agents
-
-**CRITICAL**: Spawn one `pbr:audit` agent per session, ALL in parallel. Do NOT analyze sessions sequentially.
-
-For each session:
-
-```
-Task({
-  subagent_type: "pbr:audit",
-  prompt: "<audit_assignment>
-    Session JSONL: {absolute_path_to_session.jsonl}
-    Subagent logs: {list of subagent jsonl paths, or 'none'}
-    Audit mode: {mode}
-    Output path: DO NOT write to disk — return findings inline.
-
-    Analyze this session for PBR workflow compliance and/or UX quality
-    per your audit checklists. Return your full findings as structured
-    markdown in your response.
-  </audit_assignment>"
-})
-```
-
-Also spawn a git analysis agent (can use a Bash agent or general-purpose):
-
-```
-Task({
-  subagent_type: "Bash",
-  model: "haiku",
-  prompt: "Run these git commands in {project_dir}:
-    1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all
-    2. git log --since='{from}' --until='{to}' --all --format='%B' | grep -i 'co-authored-by' || echo 'None found'
-    Report: all commits, any format violations against pattern {type}({scope}): {desc}, any co-author lines."
-})
-```
-
-Display progress:
-
-```
-◐ Analyzing {N} sessions in parallel...
-```
-
----
-
-## Step 5 — Collect and Synthesize
-
-As agents complete, collect their findings. Wait for all agents before proceeding.
-
-Synthesize across all sessions:
-
-### 5a. Executive Summary
-- Total sessions, total commits, releases
-- Overall compliance: how many sessions passed/failed
-- Headline finding (the most important issue)
-
-### 5b. Per-Session Summary Table
-| Session | Duration | Commands | Compliance | UX Rating |
-|---------|----------|----------|------------|-----------|
-
-### 5c. Cross-Session Patterns
-- Recurring issues (e.g., STATE.md never read across multiple sessions)
-- Hook coverage gaps
-- Common flow mistakes
-
-### 5d. Consolidated Findings
-Merge and deduplicate findings across sessions. Categorize by severity:
-- **CRITICAL**: Workflow bypassed despite user requests, hooks not firing
-- **HIGH**: State files not consulted, missing artifacts
-- **MEDIUM**: Suboptimal flow choice, missing feedback
-- **LOW**: Minor ceremony issues, informational
-
-### 5e. Recommendations
-Prioritize as:
-- **Immediate**: Fix in next session
-- **Short-term**: Fix in next sprint/milestone
-- **Medium-term**: Architectural improvements
-
----
-
-## Step 6 — Write Report
-
-**CRITICAL**: Write the full report to disk. Do NOT just display it inline.
-
-Write to: `.planning/audits/{YYYY-MM-DD}-session-audit.md`
-
-Create `.planning/audits/` directory if it doesn't exist.
-
-The report should follow this structure:
-
-```markdown
-# PBR Session Audit Report — {date range}
-
-**Audit Period:** {from} – {to}
-**Sessions Analyzed:** {N}
-**Commits:** {N}
-**Mode:** {mode}
-
----
-
-## Executive Summary
-{2-3 sentence overview}
-
-## Session Summary
-{per-session table}
-
-## Detailed Session Analysis
-{per-session findings}
-
-## Git Activity
-{commit summary, format compliance}
-
-## Cross-Session Patterns
-{recurring issues}
-
-## Consolidated Findings
-### Critical
-### High
-### Medium
-### Low
-
-## Recommendations
-### Immediate
-### Short-Term
-### Medium-Term
-
----
-*Generated by /pbr:audit on {date}*
-```
-
----
-
-## Step 7 — Display Summary
-
-After writing the report, display inline (keep it concise — the full report is on disk):
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► AUDIT COMPLETE ✓                           ║
-╚══════════════════════════════════════════════════════════════╝
-
-{N} sessions analyzed, {N} commits reviewed
-
-Compliance: {X}/{N} sessions passed
-UX Rating:  {average or per-session ratings}
-
-Top findings:
-  1. {headline finding 1}
-  2. {headline finding 2}
-  3. {headline finding 3}
-
-Full report: .planning/audits/{filename}
-
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-{Smart routing based on findings:}
-- If critical issues found: **Fix workflow** → `/pbr:quick`
-- If todos identified: **Create todos** → `/pbr:todo add "{description}"`
-- Default: **See project status** → `/pbr:status`
-
-`/clear` first → fresh context window
-```
-
----
-
-## Error Handling
-
-### Agent fails to analyze a session
-If an audit agent fails:
-```
-⚠ Failed to analyze session {id}: {error}
-Continuing with remaining {N-1} sessions.
-```
-
-Include a note in the final report that session was skipped.
-
-### No sessions found
-Display error (Step 2) and exit gracefully.
-
-### Very large session files (>5MB)
-Warn the agent to sample rather than read the full log:
-```
-Note: Session {id} is {size}MB. Sampling key sections (first 200 lines, last 200 lines, user messages, hook events).
-```
-
----
-
-## Anti-Patterns
-
-Reference: `skills/shared/universal-anti-patterns.md` for rules that apply to ALL skills.
-
-Additionally for this skill:
-
-1. **DO NOT** read JSONL files in main context — always delegate to audit agents
-2. **DO NOT** display the full report inline — write to disk, show summary
-3. **DO NOT** analyze sessions sequentially — spawn all agents in parallel
-4. **DO NOT** report findings without evidence (line numbers, timestamps, quotes)
-5. **DO NOT** judge explore sessions for missing STATE.md updates (explore is read-only)
-6. **DO NOT** flag release-please/merge commits as format violations
-7. **DO NOT** fabricate UX ratings — base them on concrete evidence (user repetitions, escalations, course-corrections)
-8. **DO NOT** exceed 5 headline findings in the inline summary — full details go in the report file