@sienklogic/plan-build-run 2.3.0 → 2.4.0

package/plugins/copilot-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/copilot-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/copilot-pbr/setup.ps1

@@ -0,0 +1,93 @@
+#
+# Plan-Build-Run for GitHub Copilot CLI — Setup Script (Windows)
+#
+# Usage:
+#   cd C:\path\to\your\project
+#   powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\copilot-pbr\setup.ps1
+#
+# Installs PBR as a Copilot CLI plugin using `copilot plugin install`
+# if available, or creates symlinks in ~/.copilot/installed-plugins/ as fallback.
+
+$ErrorActionPreference = "Stop"
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$PluginDir = $ScriptDir
+$ProjectDir = Get-Location
+
+Write-Host "Plan-Build-Run for GitHub Copilot CLI - 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\copilot-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
+}
+
+# Strategy 1: Try copilot plugin install
+$copilotCmd = Get-Command copilot -ErrorAction SilentlyContinue
+if ($copilotCmd) {
+    Write-Host "Found Copilot CLI. Installing plugin via 'copilot plugin install'..."
+    Write-Host ""
+    & copilot plugin install --local "$PluginDir"
+    Write-Host ""
+    Write-Host "Plugin installed successfully via Copilot CLI." -ForegroundColor Green
+} else {
+    # Strategy 2: Manual symlink
+    Write-Host "Copilot CLI not found in PATH. Falling back to manual symlink install."
+    Write-Host ""
+
+    $installDir = Join-Path $env:USERPROFILE ".copilot\installed-plugins\pbr"
+    $parentDir = Join-Path $env:USERPROFILE ".copilot\installed-plugins"
+    New-Item -ItemType Directory -Force -Path $parentDir | Out-Null
+
+    if (Test-Path $installDir) {
+        Write-Host "  $installDir already exists, skipping (remove it first to reinstall)"
+    } else {
+        New-Item -ItemType SymbolicLink -Path $installDir -Target $PluginDir | Out-Null
+        Write-Host "  Linked $PluginDir -> $installDir"
+    }
+}
+
+# Install project-level agents
+Write-Host ""
+Write-Host "Installing project-level agents..."
+$agentsDir = Join-Path $ProjectDir ".github\agents"
+New-Item -ItemType Directory -Force -Path $agentsDir | Out-Null
+
+Get-ChildItem (Join-Path $PluginDir "agents\*.agent.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 "  Plugin (global):  ~/.copilot/installed-plugins/pbr (or via copilot plugin install)"
+Write-Host "  Agents (project): .github\agents\*.agent.md"
+Write-Host ""
+Write-Host "Next steps:"
+Write-Host "  1. Open a terminal in this project"
+Write-Host "  2. Run: copilot"
+Write-Host "  3. 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:"
+Write-Host "  copilot plugin uninstall pbr"
+Write-Host "  # or: Remove-Item ~/.copilot/installed-plugins/pbr"
+Write-Host "  Remove-Item .github\agents\*.agent.md"

package/plugins/copilot-pbr/setup.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+#
+# Plan-Build-Run for GitHub Copilot CLI — Setup Script
+#
+# Usage:
+#   cd /path/to/your/project
+#   bash /path/to/plan-build-run/plugins/copilot-pbr/setup.sh
+#
+# This installs PBR as a Copilot CLI plugin using `copilot plugin install`
+# if available, or creates symlinks in ~/.copilot/installed-plugins/ as fallback.
+
+set -euo pipefail
+
+# Resolve the absolute path to the copilot-pbr plugin directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_DIR="$SCRIPT_DIR"
+PROJECT_DIR="$(pwd)"
+
+echo "Plan-Build-Run for GitHub Copilot CLI — 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/copilot-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
+
+# Strategy 1: Try copilot plugin install (if copilot CLI is available)
+if command -v copilot &> /dev/null; then
+  echo "Found Copilot CLI. Installing plugin via 'copilot plugin install'..."
+  echo ""
+  copilot plugin install --local "$PLUGIN_DIR"
+  echo ""
+  echo "Plugin installed successfully via Copilot CLI."
+else
+  # Strategy 2: Manual symlink into ~/.copilot/installed-plugins/
+  echo "Copilot CLI not found in PATH. Falling back to manual symlink install."
+  echo ""
+
+  INSTALL_DIR="$HOME/.copilot/installed-plugins/pbr"
+  mkdir -p "$HOME/.copilot/installed-plugins"
+
+  if [ -e "$INSTALL_DIR" ]; then
+    echo "  $INSTALL_DIR already exists, skipping (remove it first to reinstall)"
+  else
+    ln -s "$PLUGIN_DIR" "$INSTALL_DIR"
+    echo "  Linked $PLUGIN_DIR -> $INSTALL_DIR"
+  fi
+fi
+
+# Also install agents into project-level .github/agents/ for repo-scoped discovery
+echo ""
+echo "Installing project-level agents..."
+mkdir -p "$PROJECT_DIR/.github/agents"
+for agent_file in "$PLUGIN_DIR/agents/"*.agent.md; do
+  agent_name="$(basename "$agent_file")"
+  target="$PROJECT_DIR/.github/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 "  Plugin (global):  ~/.copilot/installed-plugins/pbr (or via copilot plugin install)"
+echo "  Agents (project): .github/agents/*.agent.md"
+echo ""
+echo "Next steps:"
+echo "  1. Open a terminal in this project"
+echo "  2. Run: copilot"
+echo "  3. Use /pbr:begin to start a new project"
+echo ""
+echo "Skills are located at:"
+echo "  $PLUGIN_DIR/skills/"
+echo ""
+echo "To uninstall:"
+echo "  copilot plugin uninstall pbr"
+echo "  # or: rm ~/.copilot/installed-plugins/pbr"
+echo "  rm .github/agents/*.agent.md"