@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/codex-pbr/templates/research-outputs/ARCHITECTURE.md.tmpl

@@ -0,0 +1,91 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges architecture findings into SUMMARY.md. Needs: component list, pattern names, data flow summary.
+  - Planner agent: uses architecture for phase dependency ordering. Needs: component dependencies, build order implications, API contract shapes.
+  - Build skill: uses architecture patterns during implementation. Needs: specific patterns tied to the chosen stack, anti-patterns to avoid.
+  Breaks if missing: Planner creates phases with wrong dependency order; build agents implement without architectural guidance.
+-->
+# Architecture Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## System Architecture
+
+{High-level overview of the system architecture and its major components.}
+
+## Component Diagram
+
+```
+{text_based_component_diagram}
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Depends On |
+|-----------|----------------|------------|
+| {component} | {responsibility} | {dependencies} |
+
+## Data Flow
+
+### Primary Data Flow
+
+```
+{text_based_data_flow_diagram}
+```
+
+### Key Data Paths
+
+1. **{path_name}:** {description_of_data_flow}
+
+## API Contracts
+
+### {API Endpoint or Interface}
+
+**Request:**
+```
+{request_shape}
+```
+
+**Response:**
+```
+{response_shape}
+```
+
+**Error cases:** {error_description}
+
+## Architecture Patterns
+
+| Pattern | Where Used | Why |
+|---------|-----------|-----|
+| {pattern_name} | {component_or_layer} | {rationale} |
+
+### Pattern Details
+
+#### {Pattern Name}
+
+**What:** {description}
+**When to use:** {conditions}
+**Trade-offs:** {pros_and_cons}
+
+## Anti-Patterns to Avoid
+
+1. **{anti_pattern_name}**
+   - **What people do:** {mistake}
+   - **Why it fails:** {problem}
+   - **Do instead:** {correct_approach}
+
+## Quality Gates
+
+- [ ] Architecture patterns are specific to the chosen stack (not generic advice)
+- [ ] Data flow covers all major paths (happy path, error path, async flows)
+- [ ] API contracts include request shape, response shape, and error cases
+- [ ] Component diagram shows all major components and their connections
+- [ ] At least 2 anti-patterns documented with concrete alternatives
+- [ ] Sources include at least one official documentation or architecture guide reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/codex-pbr/templates/research-outputs/FEATURES.md.tmpl

@@ -0,0 +1,64 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges feature findings into SUMMARY.md. Needs: categorized feature list with priorities and effort estimates.
+  - Planner agent: uses feature priorities for requirement prioritization and phase scoping. Needs: must-have/should-have/defer categorization, effort estimates.
+  - Begin skill: presents feature inventory to user for scope discussion. Needs: clear feature descriptions with competitive context.
+  Breaks if missing: Planner scopes phases without feature priority data; synthesizer produces SUMMARY with no feature guidance.
+-->
+# Features Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Feature Inventory
+
+| Feature | Category | Priority | Effort | Description |
+|---------|----------|----------|--------|-------------|
+| {feature} | {category} | {must-have/should-have/defer} | {S/M/L/XL} | {brief_description} |
+
+## Competitive Analysis
+
+| Feature | Our Approach | Alternative 1 | Alternative 2 | Tradeoff |
+|---------|-------------|---------------|---------------|----------|
+| {feature} | {our_approach} | {alt_1} | {alt_2} | {tradeoff_analysis} |
+
+## Prioritization Rationale
+
+### Must-Have (table stakes)
+
+{Features users expect as baseline. Without these, the product is not viable.}
+
+- **{feature}:** {why_must_have}
+
+### Should-Have (competitive)
+
+{Features that differentiate from alternatives. Important but not blocking launch.}
+
+- **{feature}:** {why_should_have}
+
+### Defer (v2+)
+
+{Features explicitly excluded from initial scope with rationale.}
+
+- **{feature}:** {why_defer}
+
+## Deferred Features
+
+| Feature | Reason Deferred | Revisit When | Effort if Added Later |
+|---------|----------------|--------------|----------------------|
+| {feature} | {reason} | {trigger} | {effort_estimate} |
+
+## Quality Gates
+
+- [ ] Every feature categorized as must-have, should-have, or defer
+- [ ] Effort estimates present for all features (S/M/L/XL)
+- [ ] Competitive analysis has at least 2 alternatives per major feature
+- [ ] Must-have features have clear rationale for why they are table stakes
+- [ ] Deferred features include revisit triggers
+- [ ] Sources include at least one market or user research reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/codex-pbr/templates/research-outputs/PITFALLS.md.tmpl

@@ -0,0 +1,50 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges pitfall findings into SUMMARY.md. Needs: numbered pitfalls with severity and avoidance strategies.
+  - Planner agent: reads pitfalls to add defensive verification steps to plans. Needs: specific, actionable avoidance strategies.
+  - Build skill: uses avoidance strategies during implementation. Needs: detection methods to catch pitfalls early.
+  Breaks if missing: Plans lack defensive verification; synthesizer produces SUMMARY with no risk awareness.
+-->
+# Pitfalls Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Critical Pitfalls
+
+{Pitfalls that cause project failure or major rework if not avoided.}
+
+1. **{pitfall_name}** [{source}]
+   - **Impact:** {what_goes_wrong}
+   - **Root cause:** {why_it_happens}
+   - **Avoidance:** {specific_steps_to_prevent}
+   - **Detection:** {how_to_catch_early}
+
+## Common Mistakes
+
+{Mistakes that cause delays but are recoverable.}
+
+1. **{mistake_name}** [{source}]
+   - **Impact:** {what_goes_wrong}
+   - **Avoidance:** {what_to_do_instead}
+
+## Environment-Specific Gotchas
+
+| Environment | Gotcha | Workaround |
+|-------------|--------|------------|
+| {env} | {issue} | {fix} |
+
+## Quality Gates
+
+- [ ] At least 3 critical pitfalls identified with source attribution
+- [ ] Each critical pitfall has a concrete avoidance strategy (not "be careful")
+- [ ] Each critical pitfall has a detection method
+- [ ] Environment-specific gotchas checked for target platform
+- [ ] Common mistakes section has at least 2 entries
+- [ ] Sources include at least one official documentation reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/codex-pbr/templates/research-outputs/STACK.md.tmpl

@@ -0,0 +1,63 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges stack findings into SUMMARY.md. Needs: technology table with versions and rationale, confidence levels per recommendation.
+  - Planner agent: uses stack decisions for phase planning and dependency ordering. Needs: prescriptive technology choices (not "consider X or Y"), version numbers, package manager.
+  - Dashboard ResearchTab: displays research confidence. Needs: frontmatter confidence field.
+  Breaks if missing: Synthesizer produces SUMMARY with vague stack section; planner makes technology decisions without research backing.
+-->
+# Stack Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Core Stack
+
+| Technology | Version | Purpose | Why Standard |
+|------------|---------|---------|--------------|
+| {technology} | {version} | {purpose} | {rationale} |
+
+## Supporting Tools
+
+| Tool | Version | Purpose | When to Use |
+|------|---------|---------|-------------|
+| {tool} | {version} | {purpose} | {use_case} |
+
+## Package Manager
+
+**Recommended:** {package_manager}
+**Why:** {rationale}
+
+## Deployment Target
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Platform | {platform} | {notes} |
+| Hosting | {hosting} | {notes} |
+| CI/CD | {ci_cd} | {notes} |
+
+## Alternatives Considered
+
+| Recommended | Alternative | Why Not |
+|-------------|-------------|---------|
+| {our_choice} | {alternative} | {rejection_reason} |
+
+## Version Compatibility
+
+| Package A | Compatible With | Notes |
+|-----------|-----------------|-------|
+| {package_a} | {package_b} | {compatibility_notes} |
+
+## Quality Gates
+
+- [ ] All technology recommendations are prescriptive ("Use X") not exploratory ("Consider X or Y")
+- [ ] Every technology entry has a specific version number (not "latest")
+- [ ] Core stack table has at least 3 entries
+- [ ] Alternatives Considered table documents at least 2 rejected alternatives with rationale
+- [ ] Package manager recommendation includes rationale
+- [ ] Sources include at least one official documentation reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/codex-pbr/templates/research-outputs/SUMMARY.md.tmpl

@@ -0,0 +1,98 @@
+<!-- Downstream consumers:
+  - Planner agent (primary consumer): reads SUMMARY.md for all phase planning decisions. Needs: stack recommendation, architecture recommendation, key risks, feature priorities, confidence assessment.
+  - Begin skill: presents synthesis to user for approval before roadmap creation. Needs: executive summary, consolidated recommendations.
+  - Dashboard ResearchTab: displays synthesis with confidence levels. Needs: confidence assessment table, research coverage.
+  Breaks if missing: Planner makes phase decisions without research backing; user approves roadmap without seeing synthesis; dashboard shows empty research card.
+-->
+# Research Synthesis
+
+**Synthesized:** {date}
+**Input documents:** {count}
+**Confidence:** {overall_confidence}
+
+## Executive Summary
+
+{Unified findings across all research dimensions in under 200 words. State: what was researched, key conclusions, primary recommendation, and confidence level.}
+
+## Stack Recommendation
+
+**Recommended stack:** {one_line_summary}
+
+{Key technology choices with rationale, sourced from STACK research.}
+
+- **{technology}:** {version} -- {why_chosen}
+
+## Architecture Recommendation
+
+**Recommended pattern:** {pattern_name}
+
+{Architecture approach with component overview, sourced from ARCHITECTURE research.}
+
+- **{component}:** {responsibility}
+
+## Key Risks
+
+{Top risks from PITFALLS research, ordered by impact.}
+
+1. **{risk}** -- {mitigation}
+2. **{risk}** -- {mitigation}
+3. **{risk}** -- {mitigation}
+
+## Feature Priorities
+
+{Prioritized feature summary from FEATURES research.}
+
+**Must-have:** {must_have_features}
+**Should-have:** {should_have_features}
+**Deferred:** {deferred_features}
+
+## Consolidated Recommendations
+
+{Actionable recommendations that integrate findings across all dimensions.}
+
+1. {recommendation}
+2. {recommendation}
+3. {recommendation}
+
+## Confidence Assessment
+
+| Dimension | Confidence | Gaps |
+|-----------|------------|------|
+| Stack | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Features | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Architecture | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+| Pitfalls | {HIGH/MEDIUM/LOW} | {gaps_or_none} |
+
+**Overall confidence:** {confidence}
+
+## Research Coverage
+
+| Dimension | Status | Notes |
+|-----------|--------|-------|
+| Stack | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Features | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Architecture | {COMPLETE/PARTIAL/MISSING} | {notes} |
+| Pitfalls | {COMPLETE/PARTIAL/MISSING} | {notes} |
+
+**Dimensions researched:** {count}/4
+**Gaps requiring attention:** {list_or_none}
+
+## Quality Gates
+
+- [ ] Executive summary is under 200 words
+- [ ] All 4 research dimensions referenced (Stack, Features, Architecture, Pitfalls)
+- [ ] Confidence gaps explicitly listed for each dimension
+- [ ] Recommendations are prescriptive and actionable (not "consider" or "evaluate")
+- [ ] Partial failure handled -- missing dimensions noted, not silently omitted
+- [ ] Sources consolidated from all input documents
+
+## Sources
+
+### Primary (HIGH confidence)
+- {source}
+
+### Secondary (MEDIUM confidence)
+- {source}
+
+### Tertiary (LOW confidence)
+- {source}

package/plugins/copilot-pbr/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — Plan-Build-Run for GitHub Copilot CLI
+
+## 2.3.1 (2026-02-19)
+
+Initial port of Plan-Build-Run to GitHub Copilot CLI.
+
+### What's included
+- 22 skills ported from Cursor plugin (argument-hint removed — not supported by Copilot CLI)
+- 10 agents with `.agent.md` extension and Copilot CLI frontmatter (`tools`, `infer`, `target`)
+- Hook configuration using Copilot CLI's `bash`/`powershell` format (6 of 11 events supported)
+- Setup scripts for macOS/Linux (bash) and Windows (PowerShell)
+- Full reference docs and templates from the shared PBR corpus
+
+### Copilot CLI adaptations
+- Agent files use `.agent.md` extension (Copilot CLI requirement)
+- Hook blocking uses JSON output (`permissionDecision: "deny"`) instead of exit code 2
+- Missing hook events: `SubagentStart`, `SubagentStop`, `TaskCompleted`, `PostToolUseFailure`, `PreCompact`, `Stop`
+- Skills omit `argument-hint` frontmatter (not supported by Copilot CLI)
+- Plugin manifest at `plugin.json` root (not in `.claude-plugin/` or `.cursor-plugin/`)

package/plugins/copilot-pbr/README.md

@@ -0,0 +1,139 @@
+# Plan-Build-Run for GitHub Copilot CLI
+
+A structured development workflow plugin for GitHub Copilot CLI that solves context rot through disciplined agent delegation, file-based state, and goal-backward verification.
+
+## Installation
+
+### Automated Setup (Recommended)
+
+The setup script installs PBR as a Copilot CLI plugin and symlinks agents into your project.
+
+**macOS / Linux:**
+```bash
+cd /path/to/your/project
+bash /path/to/plan-build-run/plugins/copilot-pbr/setup.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+cd C:\path\to\your\project
+powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\copilot-pbr\setup.ps1
+```
+
+This installs:
+- The PBR plugin (globally via `copilot plugin install` or symlink to `~/.copilot/installed-plugins/`)
+- `.github/agents/*.agent.md` — 10 specialized agent definitions (project-scoped)
+
+### Manual Setup
+
+If you prefer not to use the setup script:
+
+1. Run `copilot plugin install --local /path/to/plugins/copilot-pbr`
+2. Copy or symlink all files from `agents/` into your project's `.github/agents/` directory
+3. Skills (in `skills/`) are prompt templates — paste a skill's `SKILL.md` content into Copilot CLI chat to invoke it, or use `/pbr:*` slash commands if the plugin is installed
+
+### Uninstall
+
+```bash
+copilot plugin uninstall pbr
+rm .github/agents/*.agent.md
+```
+
+## Quick Start
+
+The core workflow follows four steps per phase:
+
+```
+/pbr:new-project     — Define your project: requirements, research, roadmap
+/pbr:plan-phase 1    — Create a detailed plan for phase 1
+/pbr:execute-phase 1   — Execute the plan with atomic commits
+/pbr:verify-work 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. |
+
+## 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:settings` to interactively adjust settings like depth, model profiles, and gate behavior.
+
+## Hook Compatibility
+
+Copilot CLI supports 6 hook events vs Claude Code's full set. The following hooks are active in this port:
+
+| Event | Scripts |
+|-------|---------|
+| sessionStart | progress-tracker.js |
+| postToolUse | post-write-dispatch.js, post-write-quality.js, check-subagent-output.js, suggest-compact.js, track-context-budget.js |
+| preToolUse | pre-bash-dispatch.js, pre-write-dispatch.js, validate-task.js, validate-skill-args.js |
+| sessionEnd | session-cleanup.js |
+
+**Not available** in Copilot CLI (present in Claude Code/Cursor ports): `SubagentStart`, `SubagentStop`, `TaskCompleted`, `PostToolUseFailure`, `PreCompact`, `Stop`.
+
+**Impact of missing hooks:**
+
+- No auto-continue between skills (`Stop` hook) — you must manually run the next command
+- No tool failure logging (`PostToolUseFailure`) — silent failures won't be recorded to `.planning/logs/`
+- No context budget preservation on compaction (`PreCompact`) — STATE.md won't be auto-preserved when context is compressed
+- No subagent lifecycle tracking (`SubagentStart`/`SubagentStop`/`TaskCompleted`) — agent spawn/completion events aren't logged
+
+## Cross-Plugin Compatibility
+
+This plugin works alongside the Claude Code and Cursor versions of Plan-Build-Run. All three plugins share the same `.planning/` directory and file formats, so you can switch between tools without losing state. Hook scripts under `plugins/pbr/scripts/` are shared between all plugins via relative paths.
+
+## Links
+
+- Repository: [https://github.com/SienkLogic/plan-build-run](https://github.com/SienkLogic/plan-build-run)
+- License: MIT