@sienklogic/plan-build-run 2.0.1 → 2.1.0

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

@@ -0,0 +1,96 @@
+<!-- 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

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

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

@@ -0,0 +1,83 @@
+#!/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"