@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/copilot-pbr/references/ui-formatting.md

@@ -0,0 +1,449 @@
+# Plan-Build-Run UI Brand & Formatting Reference
+
+> **Migration note:** Skills are being migrated to these patterns. See Phase 5 for skill-level updates.
+
+Consistent output formatting for all Plan-Build-Run skills. Every skill that produces user-facing output should follow these patterns.
+
+## Stage Banners
+
+Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {STAGE NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+**Stage names (uppercase):**
+- `QUESTIONING`
+- `RESEARCHING`
+- `DEFINING REQUIREMENTS`
+- `CREATING ROADMAP`
+- `PLANNING PHASE {N}`
+- `EXECUTING WAVE {N}`
+- `VERIFYING`
+- `PHASE {N} COMPLETE ✓`
+- `MILESTONE COMPLETE`
+- `SCANNING CODEBASE`
+- `DEBUGGING`
+
+---
+
+## Invocation Banners
+
+**Every skill MUST display a branded banner as its very first output, BEFORE any file reads, state loading, or processing.** This is the user's immediate confirmation that their command was received.
+
+Format:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {SKILL NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+**Skill names (uppercase):**
+- `STARTING PROJECT` (begin)
+- `PLANNING PHASE {N}` (plan)
+- `BUILDING PHASE {N}` (build)
+- `REVIEWING PHASE {N}` (review)
+- `QUICK TASK` (quick)
+- `NEXT STEP` (continue)
+- `PROJECT STATUS` (status)
+- `RESUMING SESSION` (resume)
+- `PAUSING SESSION` (pause)
+- `HEALTH CHECK` (health)
+- `SETUP` (setup)
+- `CONFIGURATION` (config)
+- `COMMAND REFERENCE` (help)
+- `DISCUSSION` (discuss)
+- `EXPLORING` (explore)
+- `NOTE` (note)
+- `TODO` (todo)
+- `DEBUGGING` (debug)
+- `SCANNING CODEBASE` (scan)
+- `MILESTONE` (milestone)
+- `IMPORTING PLAN` (import)
+
+**Rules:**
+1. The banner MUST be output BEFORE any tool calls (Read, Glob, Bash, Task)
+2. The banner MUST be the first text the user sees
+3. After the banner, optionally show a 1-line context summary (e.g., "Phase 3 of 7 — API Layer")
+4. Then proceed to Step 1 (state loading, argument parsing, etc.)
+
+---
+
+## Headers
+
+Use these patterns for consistent visual hierarchy within sections:
+
+```
+## Phase 3: Authentication        <- Phase-level header
+### Plan 01: Database Schema      <- Plan-level header
+#### Task 1: Create User Table    <- Task-level header
+```
+
+---
+
+## Status Indicators
+
+| Status | Indicator | Usage |
+|--------|-----------|-------|
+| Complete | `✓` | Completed items, passed checks, verified |
+| Failed | `✗` | Failed verification, missing items, blocked |
+| In Progress | `◆` | Currently executing |
+| Pending | `○` | Not yet started |
+| Auto-approved | `⚡` | Automatically approved (gates) |
+| Warning | `⚠` | Warnings, non-blocking issues |
+| Milestone | `🎉` | Milestone complete (banner only) |
+
+---
+
+## Progress Display
+
+**Phase/milestone level:**
+```
+Progress: ████████░░ 80%
+```
+
+**Phase progress (detailed):**
+```
+Phase 3 of 5: Authentication
+Progress: [████████░░░░░░░░░░░░] 40%
+Plans: 2/5 complete
+```
+
+**Build progress (wave tracking):**
+```
+Wave 1: ✓ Plan 01, ✓ Plan 02
+Wave 2: ◆ Plan 03 (executing)
+Wave 3: ○ Plan 04
+```
+
+**Task level:**
+```
+Tasks: 2/4 complete
+```
+
+---
+
+## Spawning Indicators
+
+Show when agents are being launched:
+
+```
+◆ Spawning executor...
+
+◆ Spawning 4 executors in parallel...
+  → Plan 01: Database Schema
+  → Plan 02: Auth Service
+  → Plan 03: API Routes
+  → Plan 04: Test Suite
+
+✓ Plan 01 complete (2m 14s)
+```
+
+For research agents:
+```
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+
+✓ Researcher complete: STACK.md written
+```
+
+---
+
+## Checkpoint Boxes
+
+User action required. Use double-line box drawing, 62-character inner width.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Content}
+
+→ {ACTION PROMPT}
+```
+
+**Types:**
+- `CHECKPOINT: Verification Required` → `→ Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` → `→ Select: option-a / option-b`
+- `CHECKPOINT: Action Required` → `→ Type "done" when complete`
+
+---
+
+## AskUserQuestion Patterns
+
+Structured prompts for user decision points. All gate checks use AskUserQuestion instead of
+plain-text "Type approved" prompts. See `skills/shared/gate-prompts.md` for the full
+pattern catalog (21 named AskUserQuestion patterns).
+
+### Structure
+
+```
+AskUserQuestion:
+  question: "{contextual question}"
+  header: "{max 12 chars}"
+  options:
+    - label: "{Option 1}"  description: "{What happens}"
+    - label: "{Option 2}"  description: "{What happens}"
+  multiSelect: false
+```
+
+### Rules
+
+- **Max 4 options** per call. Split into 2-step flow if more are needed.
+- **Header max 12 characters.** Single word preferred (e.g., "Approve?", "Confirm", "Scope").
+- **multiSelect: false** always. Plan-Build-Run gates require single selection.
+- **Handle "Other"**: Users may type freeform text instead of selecting. Skills must handle this gracefully.
+- **Orchestrator only**: AskUserQuestion cannot be called from subagents.
+
+### Common Patterns
+
+**Approval gate** (approve-revise-abort):
+```
+question: "Approve these plans?"
+header: "Approve?"
+options:
+  - label: "Approve"          description: "Proceed with execution"
+  - label: "Request changes"  description: "Discuss adjustments before proceeding"
+  - label: "Abort"            description: "Cancel this operation"
+```
+
+**Simple confirmation** (yes-no):
+```
+question: "Re-plan this phase with gap context?"
+header: "Confirm"
+options:
+  - label: "Yes"  description: "Create gap-closure plans"
+  - label: "No"   description: "Skip re-planning"
+```
+
+**Category selection** (settings-category-select):
+```
+question: "What would you like to configure?"
+header: "Configure"
+options:
+  - label: "Depth"          description: "quick/standard/comprehensive"
+  - label: "Model profile"  description: "quality/balanced/budget/adaptive"
+  - label: "Features"       description: "Toggle workflow features and gates"
+  - label: "Git settings"   description: "branching strategy, commit mode"
+```
+
+**Dynamic routing** (action-routing):
+```
+question: "What would you like to do next?"
+header: "Next Step"
+options:
+  - label: "/pbr:execute-phase 3"    description: "Execute phase 3 plans"
+  - label: "/pbr:verify-work 2"   description: "Verify phase 2 results"
+  - label: "Something else"  description: "Enter a different command"
+```
+
+### When NOT to Use
+
+Do not use AskUserQuestion for:
+- Freeform text input (symptom descriptions, task descriptions, open questions)
+- Socratic discussion (explore, discuss follow-ups)
+- Situations with unbounded response space
+
+Use plain conversational prompts for these cases instead.
+
+### Cross-Reference
+
+For questioning philosophy, when to use/not use AskUserQuestion, freeform rule, and decision gate patterns, see `references/questioning.md`.
+
+---
+
+## Next Up Block
+
+Always present at end of major completions (phase complete, milestone complete, project init).
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**{Identifier}: {Name}** — {one-line description}
+
+`{copy-paste command}`
+
+<sub>`/clear` first → fresh context window</sub>
+```
+
+**Also available:**
+- `/pbr:alternative-1` — description
+- `/pbr:alternative-2` — description
+
+**Shorter routing (for minor completions):**
+```
+What's next?
+→ /pbr:plan-phase 4 — plan the next phase
+→ /pbr:verify-work 3 — review what was just built
+→ /pbr:progress — see full project status
+```
+
+---
+
+## Error Box
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## Tables
+
+Use tables for structured data:
+
+```markdown
+| Phase | Status | Plans | Progress |
+|-------|--------|-------|----------|
+| 1. Foundation | ✓ Complete | 3/3 | 100% |
+| 2. Database | ✓ Complete | 2/2 | 100% |
+| 3. Auth | ◆ Building | 1/3 | 33% |
+| 4. Frontend | ○ Pending | 0/4 | 0% |
+```
+
+---
+
+## Cost/Token Warnings
+
+```
+⚠ Budget check: This operation will spawn 4 agents (~400k tokens)
+  Estimated: ~20% of 5-hour window
+  Continue? [/pbr:settings to adjust depth first]
+```
+
+---
+
+## Completion Summary Templates
+
+### Phase Complete
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Phase {N}: {Name}**
+
+{X} plans executed
+Goal verified ✓
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
+
+/pbr:discuss-phase {N+1} — gather context and clarify approach
+
+<sub>/clear first → fresh context window</sub>
+
+**Also available:**
+- /pbr:plan-phase {N+1} — skip discussion, plan directly
+- /pbr:verify-work {N} — manual acceptance testing before continuing
+```
+
+### Milestone Complete
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
+╚══════════════════════════════════════════════════════════════╝
+
+**{version}**
+
+{N} phases completed
+All phase goals verified ✓
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Audit milestone** — verify requirements, cross-phase integration, E2E flows
+
+/pbr:audit-milestone
+
+<sub>/clear first → fresh context window</sub>
+
+**Also available:**
+- /pbr:verify-work — manual acceptance testing
+- /pbr:complete-milestone — archive milestone after audit passes
+```
+
+### Gaps Found
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                    ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Phase {N}: {Name}**
+
+Score: {X}/{Y} must-haves verified
+Report: .planning/phases/{phase_dir}/VERIFICATION.md
+
+### What's Missing
+
+{Extract gap summaries from VERIFICATION.md}
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Plan gap closure** — create additional plans to complete the phase
+
+/pbr:plan-phase {N} --gaps
+
+<sub>/clear first → fresh context window</sub>
+
+**Also available:**
+- cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
+- /pbr:verify-work {N} — manual testing before planning
+```
+
+---
+
+## Session Banners
+
+Use for session lifecycle transitions (pause/resume):
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
+╚══════════════════════════════════════════════════════════════╝
+
+Position: Phase {N} — {phase name}, Plan {M}
+Paused: {ISO datetime}
+Duration: {time since pause}
+
+{Summary of where work left off}
+```
+
+Other session banners: `SESSION SAVED ✓` (pause), `RESUMING SESSION` (resume start).
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Use varying box/banner widths — always 62-character inner width
+- Use `━━━` heavy bars or `───` thin dividers for banners/sections — use `╔═╗║╚═╝` boxes
+- Mix banner styles (`===`, `---`, `***`) with double-line boxes
+- Skip `PLAN-BUILD-RUN ►` prefix in stage banners
+- Use random emoji (only for milestone complete, `✓` for phase complete)
+- Skip the "Next Up" block after major completions
+- Reference non-Plan-Build-Run commands (always use `/pbr:*` commands)
+- Use non-Plan-Build-Run branding in banners

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

@@ -0,0 +1,95 @@
+# 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-work` 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-phase` before diving in
+- When asked to fix bugs, suggest `/pbr:debug` for systematic investigation
+- When asked about project status, suggest `/pbr:progress`
+- When starting a new session, suggest `/pbr:resume-work` if paused work exists
+
+## Planning Integrity
+
+- Do not modify files in `.planning/phases/` directly — use `/pbr:plan-phase` and `/pbr:execute-phase`
+- Do not skip verification — use `/pbr:verify-work` 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:new-project 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"