@sienklogic/plan-build-run 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -5,8 +5,57 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.3.1...plan-build-run-v2.4.0) (2026-02-19)
+
+
+### Features
+
+* **tools:** add GitHub Copilot CLI plugin port ([3977261](https://github.com/SienkLogic/plan-build-run/commit/39772618479551a58123d08d99cbcb1178a0cd2a))
+* **tools:** archive milestones into versioned directories with phase migration ([206b925](https://github.com/SienkLogic/plan-build-run/commit/206b925dd6692131f0d9127d10cd07208c777e40))
+
+
+### Bug Fixes
+
+* **tools:** parse simple two-column roadmap table in dashboard ([f881004](https://github.com/SienkLogic/plan-build-run/commit/f8810045739ffeaf29a495f824bc34828c8e6c4d))
+* **tools:** resolve lint errors in cross-plugin compat tests ([731efb2](https://github.com/SienkLogic/plan-build-run/commit/731efb221cf630a697a48bf732eed736b9514b1c))
+* **tools:** sync dashboard skill paths and missing templates across all plugins ([ee7d770](https://github.com/SienkLogic/plan-build-run/commit/ee7d770c09f8dd7da1b1b9f76d162f0e87fc58a5))
+
+
+### Documentation
+
+* **tools:** add /pbr:dashboard command to README dashboard section ([e1d3a60](https://github.com/SienkLogic/plan-build-run/commit/e1d3a60e0f8cffcd2f093725e73a0eca0a6c67ad))
+* **tools:** add missing 2.3.0 and 2.3.1 changelog entries ([82c5cb2](https://github.com/SienkLogic/plan-build-run/commit/82c5cb21a741be4bfe13613debdeb54f862ce1f3))
+* **tools:** make platform badges clickable links to install pages ([a1f6b68](https://github.com/SienkLogic/plan-build-run/commit/a1f6b68a786458a6040d0fa50a99e01431016332))
+* **tools:** update README with Copilot CLI support and current stats ([edad2d9](https://github.com/SienkLogic/plan-build-run/commit/edad2d924198d6598eed1fb0b0a23c164617e5b6))
+
 ## [Unreleased]
 
+## [2.3.1] - 2026-02-19
+
+### Added
+- **GitHub Copilot CLI plugin** (`plugins/copilot-pbr/`) — complete port with 22 skills, 10 agents (`.agent.md` format), and Copilot CLI hook configuration
+- Setup scripts (`setup.sh`, `setup.ps1`) for Copilot CLI plugin installation with `copilot plugin install` support
+- Cross-plugin compatibility tests now cover all three plugins (Claude Code, Cursor, Copilot CLI) — 164 tests via data-driven `describe.each`
+- New cross-plugin guard tests: `references/ files match PBR` and `templates/ files match PBR` catch drift automatically
+- Dashboard skill now works from Copilot CLI sessions (`/pbr:dashboard`)
+- Platform badges in README link to install pages (wiki or anchor)
+
+### Fixed
+- Synced 13 missing template files (`codebase/`, `research/`, `research-outputs/`) to Cursor and Copilot plugins
+- Dashboard skill in derivative plugins now references correct relative path (`../../dashboard/`) instead of nonexistent `<plugin-root>/dashboard/`
+- Cross-plugin frontmatter parser now handles both `\r\n` and `\n` line endings (was silently failing on Windows-style files)
+- Test count: 1219 tests across 44 suites (up from 1134)
+
+## [2.3.0] - 2026-02-19
+
+### Added
+- `/pbr:do` freeform router — routes natural language input to the right PBR skill automatically
+- Smart skill suggestions in hook feedback when freeform text is detected
+- Freeform text guard hook for `/pbr:plan` and todo work subcommand
+
+### Fixed
+- Dashboard skill `argument-hint` synced to Cursor plugin
+
 ## [2.2.0] - 2026-02-19
 
 ### Added

package/README.md

@@ -3,11 +3,11 @@
 </p>
 
 <p align="center">
-  <strong>Context-engineered development workflow for Claude Code and Cursor.</strong>
+  <strong>Context-engineered development workflow for Claude Code, Cursor, and GitHub Copilot CLI.</strong>
   <br />
   Build ambitious multi-phase software without quality degradation.
   <br />
-  Works with any Claude Code plan. Shines on Max. Now available for Cursor IDE.
+  Works with any Claude Code plan. Shines on Max. Now available for Cursor IDE and GitHub Copilot CLI.
   <br />
   <br />
   <a href="#why-plan-build-run">Why Plan-Build-Run?</a> &bull;
@@ -20,12 +20,13 @@
 
 <p align="center">
   <a href="https://github.com/SienkLogic/plan-build-run/actions"><img src="https://img.shields.io/github/actions/workflow/status/SienkLogic/plan-build-run/ci.yml?style=for-the-badge&label=CI&logo=github" alt="CI Status" /></a>
-  <img src="https://img.shields.io/badge/Claude_Code-Plugin-7C3AED?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code Plugin" />
-  <img src="https://img.shields.io/badge/Cursor-Plugin-00A67E?style=for-the-badge&logo=cursor&logoColor=white" alt="Cursor Plugin" />
+  <a href="#install"><img src="https://img.shields.io/badge/Claude_Code-Plugin-7C3AED?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code Plugin" /></a>
+  <a href="https://github.com/SienkLogic/plan-build-run/wiki/Cursor-IDE"><img src="https://img.shields.io/badge/Cursor-Plugin-00A67E?style=for-the-badge&logo=cursor&logoColor=white" alt="Cursor Plugin" /></a>
+  <a href="https://github.com/SienkLogic/plan-build-run/wiki/Copilot-CLI"><img src="https://img.shields.io/badge/Copilot_CLI-Plugin-1F6FEB?style=for-the-badge&logo=github&logoColor=white" alt="Copilot CLI Plugin" /></a>
   <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
   <a href="LICENSE"><img src="https://img.shields.io/github/license/SienkLogic/plan-build-run?style=for-the-badge" alt="License" /></a>
   <a href="https://www.npmjs.com/package/@sienklogic/plan-build-run"><img src="https://img.shields.io/npm/v/@sienklogic/plan-build-run?style=for-the-badge&logo=npm&logoColor=white" alt="npm" /></a>
-  <img src="https://img.shields.io/badge/Tests-1008_passing-brightgreen?style=for-the-badge" alt="1008 Tests" />
+  <img src="https://img.shields.io/badge/Tests-1213_passing-brightgreen?style=for-the-badge" alt="1213 Tests" />
 </p>
 
 ---
@@ -88,7 +89,8 @@ All `/pbr:*` commands are now available globally.
 
 </details>
 
-### Install for Cursor IDE
+<details>
+<summary><strong>Install for Cursor IDE</strong></summary>
 
 Plan-Build-Run also works in Cursor. The setup script symlinks rules and agents into your project's `.cursor/` directory.
 
@@ -106,25 +108,54 @@ powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\curso
 
 Both plugins share the same `.planning/` directory — start a project in Claude Code, continue in Cursor, or vice versa. See [`plugins/cursor-pbr/README.md`](plugins/cursor-pbr/README.md) for full details.
 
-### Dashboard (Optional)
+</details>
+
+<details>
+<summary><strong>Install for GitHub Copilot CLI</strong></summary>
 
-Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser. To set it up:
+Plan-Build-Run also works in GitHub Copilot CLI. The setup script installs PBR as a Copilot CLI plugin and symlinks agents into your project.
 
+**macOS / Linux:**
 ```bash
-# One-time install of dashboard dependencies
-npm run dashboard:install
+cd /path/to/your/project
+bash /path/to/plan-build-run/plugins/copilot-pbr/setup.sh
+```
 
-# Launch the dashboard for any project with a .planning/ directory
-npm run dashboard -- --dir /path/to/your/project
-# Opens at http://127.0.0.1:3000
+**Windows (PowerShell):**
+```powershell
+cd C:\path\to\your\project
+powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\copilot-pbr\setup.ps1
 ```
 
-Or run directly:
+All three plugins share the same `.planning/` directory — start in any tool, continue in another. See [`plugins/copilot-pbr/README.md`](plugins/copilot-pbr/README.md) for full details.
+
+</details>
+
+<details>
+<summary><strong>Dashboard (Optional)</strong></summary>
+
+Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser.
 
 ```bash
-node dashboard/bin/cli.js --dir /path/to/your/project --port 3000
+# One-time install of dashboard dependencies
+npm run dashboard:install
+
+# Launch the dashboard (defaults to current directory)
+npm run dashboard
+
+# Or specify a project directory and port
+npm run dashboard -- --dir /path/to/your/project --port 3000
 ```
 
+Or launch it directly from a Claude Code, Cursor, or Copilot CLI session:
+```
+/pbr:dashboard
+```
+
+Opens at `http://127.0.0.1:3000` with live updates via SSE.
+
+</details>
+
 ### Quick Start (Max / Max 5x)
 
 Full pipeline with parallel research and multi-agent builds. Best experience.
@@ -187,7 +218,7 @@ Set `depth: quick` in `/pbr:config` to reduce agent spawns across all workflows.
 | `/pbr:build <N>` | Build a phase: parallel execution in waves, atomic commits | 2-4 (quick: 1-2) |
 | `/pbr:review <N>` | Verify a phase: automated 3-layer checks + conversational UAT | 1 |
 
-See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 21 commands with flags, cost-by-depth tables, and detailed descriptions.
+See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 22 commands with flags, cost-by-depth tables, and detailed descriptions.
 
 ---
 
@@ -218,6 +249,8 @@ See **[Architecture](https://github.com/SienkLogic/plan-build-run/wiki/Architect
 | **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 15 lifecycle hooks that enforce discipline at zero token cost |
 | **[Project Structure](https://github.com/SienkLogic/plan-build-run/wiki/Project-Structure)** | The `.planning/` directory layout, key files, and file ownership |
 | **[Dashboard](https://github.com/SienkLogic/plan-build-run/wiki/Dashboard)** | Web UI with live updates for browsing project state |
+| **[Cursor IDE](https://github.com/SienkLogic/plan-build-run/wiki/Cursor-IDE)** | Cursor plugin installation and cross-IDE workflow |
+| **[Copilot CLI](https://github.com/SienkLogic/plan-build-run/wiki/Copilot-CLI)** | GitHub Copilot CLI plugin: installation, hooks, and differences |
 | **[Philosophy](https://github.com/SienkLogic/plan-build-run/wiki/Philosophy)** | Design principles and platform alignment strategy |
 | **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart)** | Feature comparison and key differentiators |
 
@@ -231,7 +264,7 @@ git clone https://github.com/SienkLogic/plan-build-run.git
 cd plan-build-run
 npm install
 
-# Run tests (1008 tests, 42 suites)
+# Run tests (1213 tests, 44 suites)
 npm test
 
 # Lint
@@ -252,11 +285,12 @@ CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md]
 
 | Metric | Count |
 |--------|-------|
-| Skills (slash commands) | 21 |
+| Skills (slash commands) | 22 |
 | Specialized agents | 10 |
 | Hook scripts | 28 |
-| Tests | 1008 |
-| Test suites | 42 |
+| Supported platforms | 3 (Claude Code, Cursor, Copilot CLI) |
+| Tests | 1213 |
+| Test suites | 44 |
 | Config toggles | 12 top-level keys |
 
 ---

package/dashboard/src/services/dashboard.service.js

@@ -198,10 +198,33 @@ export async function parseRoadmapFile(projectDir) {
       });
     }
 
-    // Use Progress table if available, then checkbox list, then H3 headings
+    // 5. Parse simple two-column table: "| 1. Name | Completed |"
+    //    Used in milestone-archived roadmaps
+    const simpleTableRegex = /^\|\s*(\d+)\.\s+(.+?)\s*\|\s*(.+?)\s*\|$/gm;
+    const simplePhases = [];
+    for (const match of content.matchAll(simpleTableRegex)) {
+      const id = parseInt(match[1], 10);
+      const name = match[2].trim();
+      const statusText = match[3].trim().toLowerCase();
+
+      let status;
+      if (statusText === 'completed' || statusText === 'complete') status = 'complete';
+      else if (statusText === 'in progress' || statusText === 'in-progress') status = 'in-progress';
+      else status = 'not-started';
+
+      const cbInfo = checkboxMap.get(id);
+      const goalDesc = goalMap.get(id);
+      const description = cbInfo?.description || goalDesc || '';
+
+      simplePhases.push({ id, name, description, status });
+    }
+
+    // Use Progress table if available, then simple table, then checkbox list, then H3 headings
     let phases;
     if (progressPhases.length > 0) {
       phases = progressPhases;
+    } else if (simplePhases.length > 0) {
+      phases = simplePhases;
     } else if (checkboxMap.size > 0) {
       phases = [...checkboxMap.entries()]
         .map(([id, info]) => ({

package/dashboard/src/services/milestone.service.js

@@ -5,7 +5,10 @@ import { getRoadmapData } from './roadmap.service.js';
 
 /**
  * Scan .planning/milestones/ for archived milestone files.
- * Groups files by version prefix (e.g., v1.0-ROADMAP.md, v1.0-STATS.md).
+ * Supports two formats:
+ * - Directory: v{version}/ containing ROADMAP.md, STATS.md, etc.
+ * - Flat file: v{version}-{TYPE}.md (legacy)
+ * Directory format takes precedence if both exist for the same version.
  *
  * @param {string} projectDir - Absolute path to the project root
  * @returns {Promise<Array<{version: string, name: string, date: string, duration: string, files: string[]}>>}
@@ -15,33 +18,69 @@ export async function listArchivedMilestones(projectDir) {
 
   let entries;
   try {
-    entries = await readdir(milestonesDir);
+    entries = await readdir(milestonesDir, { withFileTypes: true });
   } catch (err) {
     if (err.code === 'ENOENT') return [];
     throw err;
   }
 
-  // Group files by version prefix: v1.0-ROADMAP.md -> version "1.0"
   const versionMap = new Map();
-  const versionPattern = /^v([\w.-]+)-(\w+)\.md$/;
 
-  for (const file of entries) {
-    const match = file.match(versionPattern);
+  // Pass 1: Detect directory-format milestones (v1.0/, v2.0/, etc.)
+  const dirPattern = /^v([\w.-]+)$/;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const match = entry.name.match(dirPattern);
     if (!match) continue;
 
     const version = match[1];
+    // Read files inside the version directory
+    let dirFiles;
+    try {
+      dirFiles = await readdir(join(milestonesDir, entry.name));
+    } catch (_e) {
+      continue;
+    }
+    const mdFiles = dirFiles.filter(f => f.endsWith('.md'));
+    if (mdFiles.length === 0) continue;
+
+    versionMap.set(version, { version, name: '', date: '', duration: '', files: mdFiles, format: 'directory' });
+  }
+
+  // Pass 2: Detect flat-file milestones (v1.0-ROADMAP.md, etc.) — skip versions already found as directories
+  const filePattern = /^v([\w.-]+)-(\w+)\.md$/;
+  for (const entry of entries) {
+    if (entry.isDirectory()) continue;
+    const match = entry.name.match(filePattern);
+    if (!match) continue;
+
+    const version = match[1];
+    // Skip if this version was already found as a directory
+    if (versionMap.has(version) && versionMap.get(version).format === 'directory') continue;
+
     if (!versionMap.has(version)) {
-      versionMap.set(version, { version, name: '', date: '', duration: '', files: [] });
+      versionMap.set(version, { version, name: '', date: '', duration: '', files: [], format: 'flat' });
     }
-    versionMap.get(version).files.push(file);
+    versionMap.get(version).files.push(entry.name);
   }
 
   // Try to parse STATS.md for each version to get name/date/duration
   for (const [version, milestone] of versionMap) {
-    const statsFile = `v${version}-STATS.md`;
-    if (milestone.files.includes(statsFile)) {
+    let statsPath;
+    if (milestone.format === 'directory') {
+      if (milestone.files.includes('STATS.md')) {
+        statsPath = join(milestonesDir, `v${version}`, 'STATS.md');
+      }
+    } else {
+      const statsFile = `v${version}-STATS.md`;
+      if (milestone.files.includes(statsFile)) {
+        statsPath = join(milestonesDir, statsFile);
+      }
+    }
+
+    if (statsPath) {
       try {
-        const { frontmatter } = await readMarkdownFile(join(milestonesDir, statsFile));
+        const { frontmatter } = await readMarkdownFile(statsPath);
         milestone.name = frontmatter.milestone || frontmatter.name || `v${version}`;
         milestone.date = frontmatter.completed || frontmatter.date || '';
         milestone.duration = frontmatter.duration || '';
@@ -53,8 +92,10 @@ export async function listArchivedMilestones(projectDir) {
     }
   }
 
-  // Sort by version descending (newest first)
-  return [...versionMap.values()].sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }));
+  // Sort by version descending (newest first) — strip internal format field
+  return [...versionMap.values()]
+    .sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }))
+    .map(({ format: _f, ...rest }) => rest);
 }
 
 /**
@@ -89,14 +130,24 @@ export async function getMilestoneDetail(projectDir, version) {
 
   const sections = [];
   for (const type of fileTypes) {
-    const filePath = join(milestonesDir, `v${version}-${type}.md`);
+    // Try directory format first, then fall back to flat file
+    const dirPath = join(milestonesDir, `v${version}`, `${type}.md`);
+    const flatPath = join(milestonesDir, `v${version}-${type}.md`);
+
+    let result;
     try {
-      const result = await readMarkdownFile(filePath);
-      sections.push({ type, frontmatter: result.frontmatter, html: result.html });
+      result = await readMarkdownFile(dirPath);
     } catch (err) {
       if (err.code !== 'ENOENT') throw err;
-      // File doesn't exist for this type — skip
+      try {
+        result = await readMarkdownFile(flatPath);
+      } catch (err2) {
+        if (err2.code !== 'ENOENT') throw err2;
+        // Neither format exists for this type — skip
+        continue;
+      }
     }
+    sections.push({ type, frontmatter: result.frontmatter, html: result.html });
   }
 
   return { version, sections };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

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,129 @@
+# 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:begin     — Define your project: requirements, research, roadmap
+/pbr:plan 1    — Create a detailed plan for phase 1
+/pbr:build 1   — Execute the plan with atomic commits
+/pbr:review 1  — Verify the build matched the plan
+```
+
+Repeat `plan` / `build` / `review` for each phase in your roadmap.
+
+## Skills (22)
+
+| Skill | Description |
+|-------|-------------|
+| 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. |
+| todo | File-based persistent todos. Add, list, complete — survives sessions. |
+
+## Agents (10)
+
+| Agent | Description |
+|-------|-------------|
+| 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:config` 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`.
+
+## 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

package/plugins/copilot-pbr/agents/codebase-mapper.agent.md

@@ -0,0 +1,109 @@
+---
+name: codebase-mapper
+description: "Explores existing codebases and writes structured analysis documents. Four focus areas: tech, arch, quality, concerns."
+tools: ["*"]
+infer: true
+target: "github-copilot"
+---
+
+# Plan-Build-Run Codebase Mapper
+
+You are **codebase-mapper**, the codebase analysis agent for the Plan-Build-Run development system. You explore existing codebases and produce structured documentation that helps other agents (and humans) understand the project's technology stack, architecture, conventions, and concerns.
+
+## Core Philosophy
+
+- **Document quality over brevity.** Be thorough. Other agents depend on your analysis for accurate planning and execution.
+- **Always include file paths.** Every claim must reference the actual code location. Never say "the config file" — say "`tsconfig.json` at project root" or "`src/config/database.ts`".
+- **Write current state only.** No temporal language ("recently added", "will be changed", "was refactored"). Document WHAT IS, not what was or will be.
+- **Be prescriptive, not descriptive.** When documenting conventions: "Use this pattern" not "This pattern exists."
+- **Evidence-based.** Read the actual files. Don't guess from file names or directory structures.
+
+---
+
+### Forbidden Files
+
+When exploring, NEVER commit or recommend committing:
+- `.env` files (except `.env.example` or `.env.template`)
+- `*.key`, `*.pem`, `*.pfx`, `*.p12` — private keys and certificates
+- Files containing `credential` or `secret` in their name
+- `*.keystore`, `*.jks` — Java keystores
+- `id_rsa`, `id_ed25519` — SSH keys
+
+If encountered, note in CONCERNS.md under "Security Considerations" but do NOT include contents.
+
+---
+
+## Focus Areas
+
+You receive ONE focus area per invocation. All output is written to `.planning/codebase/` (create if needed). **Do NOT commit** — the orchestrator handles commits.
+
+| Focus | Output Files | Templates |
+|-------|-------------|-----------|
+| `tech` | STACK.md, INTEGRATIONS.md | `templates/codebase/STACK.md.tmpl`, `templates/codebase/INTEGRATIONS.md.tmpl` |
+| `arch` | ARCHITECTURE.md, STRUCTURE.md | `templates/codebase/ARCHITECTURE.md.tmpl`, `templates/codebase/STRUCTURE.md.tmpl` |
+| `quality` | CONVENTIONS.md, TESTING.md | `templates/codebase/CONVENTIONS.md.tmpl`, `templates/codebase/TESTING.md.tmpl` |
+| `concerns` | CONCERNS.md | `templates/codebase/CONCERNS.md.tmpl` |
+
+Read the relevant `.tmpl` file(s) and fill in all placeholder fields with data from your analysis.
+
+---
+
+## Exploration Process
+
+> **Cross-platform**: Use Glob, Read, and Grep tools — not Bash `ls`, `find`, or `cat`. Bash file commands fail on Windows.
+
+1. **Orientation** — Glob for source files, config files, docs, Docker, CI/CD to understand project shape.
+2. **Deep Inspection** — Read 5-10+ key files per focus area (package.json, configs, entry points, core modules).
+3. **Pattern Recognition** — Identify repeated conventions across the codebase.
+4. **Write Documentation** — Write to `.planning/codebase/` using the templates. Write documents as you go to manage context.
+
+---
+
+## Output Budget
+
+| Artifact | Target | Hard Limit |
+|----------|--------|------------|
+| STACK.md | ≤ 800 tokens | 1,200 tokens |
+| INTEGRATIONS.md | ≤ 600 tokens | 1,000 tokens |
+| ARCHITECTURE.md | ≤ 1,000 tokens | 1,500 tokens |
+| STRUCTURE.md | ≤ 600 tokens | 1,000 tokens |
+| CONVENTIONS.md | ≤ 800 tokens | 1,200 tokens |
+| TESTING.md | ≤ 600 tokens | 1,000 tokens |
+| CONCERNS.md | ≤ 600 tokens | 1,000 tokens |
+| Total per focus area (2 docs) | ≤ 1,400 tokens | 2,200 tokens |
+
+**Guidance**: Tables over prose. Version numbers and file paths are the high-value data — skip explanations of what well-known tools do. The planner reads these documents to make decisions; give it decision-relevant facts, not tutorials.
+
+---
+
+## Quality Standards
+
+1. Every claim must reference actual file paths (with line numbers when possible)
+2. Verify versions from package.json/lock files, not from memory
+3. Read at least 5-10 key files per focus area — file names lie, check source
+4. Include actual code examples from the codebase, not generic examples
+5. Stop before 50% context usage — write documents incrementally
+
+---
+
+## Universal Anti-Patterns
+
+1. DO NOT guess or assume — read actual files for evidence
+2. DO NOT trust SUMMARY.md or other agent claims without verifying codebase
+3. DO NOT use vague language — be specific and evidence-based
+4. DO NOT present training knowledge as verified fact
+5. DO NOT exceed your role — recommend the correct agent if task doesn't fit
+6. DO NOT modify files outside your designated scope
+7. DO NOT add features or scope not requested — log to deferred
+8. DO NOT skip steps in your protocol, even for "obvious" cases
+9. DO NOT contradict locked decisions in CONTEXT.md
+10. DO NOT implement deferred ideas from CONTEXT.md
+11. DO NOT consume more than 50% context before producing output
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
+
+Additionally for this agent:
+
+1. DO NOT guess technology versions — read package.json or equivalent
+2. DO NOT use temporal language ("recently added", "old code")
+3. DO NOT produce generic documentation — every claim must reference this specific codebase
+4. DO NOT commit the output — the orchestrator handles commits