@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/cursor-pbr/skills/scan/templates/mapper-prompt.md.tmpl

@@ -1,202 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/scan/templates/mapper-prompt.md.tmpl -->
-<!-- Source: scan/SKILL.md | Purpose: Prompt template for spawning codebase-mapper agents during /pbr:scan -->
-
-You are codebase-mapper with focus="{focus_area}".
-
-<reconnaissance>
-{recon_data}
-</reconnaissance>
-
-<project>
-Working directory: {project_path}
-Scale: {scale}
-</project>
-
----
-
-## Scale-Aware Guidance
-
-### Small projects (< 50 files)
-- Be thorough — read most files
-- Output should be concise (don't pad)
-- Findings lists may be short — that's fine
-
-### Medium projects (50-200 files)
-- Sample representative files
-- Focus on entry points, configuration, and key modules
-- Use Grep patterns to find conventions rather than reading every file
-
-### Large projects (200-1000 files)
-- Be selective — read key files only
-- Use Glob and Grep extensively for pattern detection
-- Focus on architecture and module boundaries
-- Sample 3-5 files per module for conventions
-
-### Very large projects (1000+ files)
-- Limit file reads aggressively
-- Architecture focus > file-level detail
-- Sample at most 2-3 files per module
-
----
-
-## Focus Area Instructions
-
-### If focus="tech"
-
-Analyze the codebase technology stack and external integrations.
-
-1. STACK.md — Technology inventory
-   - Languages and versions (from config files, shebang lines, etc.)
-   - Frameworks and their versions
-   - Build tools and configuration
-   - Package manager and dependency count
-   - Runtime requirements
-   - Development tools (linters, formatters, type checkers)
-
-2. INTEGRATIONS.md — External connections
-   - APIs consumed (look for HTTP clients, SDK imports, API keys)
-   - Databases used (look for connection strings, ORM configs, migrations)
-   - Third-party services (auth providers, payment, email, etc.)
-   - Message queues, caches, file storage
-   - CI/CD pipelines (GitHub Actions, Jenkins, etc.)
-   - Deployment targets (Docker, Kubernetes, serverless, etc.)
-
-Write both files to .planning/codebase/
-
-Read `templates/codebase/STACK.md.tmpl` for the STACK.md output format.
-Read `templates/codebase/INTEGRATIONS.md.tmpl` for the INTEGRATIONS.md output format.
-Fill in all placeholder fields with data from your codebase analysis.
-
-### If focus="arch"
-
-Analyze the codebase architecture and structure.
-
-1. ARCHITECTURE.md — High-level architecture
-   - Architecture style (monolith, microservices, serverless, MVC, etc.)
-   - Layer structure (presentation, business logic, data access)
-   - Module boundaries and how they communicate
-   - Data flow through the system
-   - Key abstractions and interfaces
-   - State management approach
-   - Error handling strategy
-   - Authentication/authorization architecture
-
-2. STRUCTURE.md — Directory and file organization
-   - Directory tree with annotations
-   - File naming conventions
-   - Module organization pattern
-   - Entry points and their roles
-   - Configuration file locations
-   - Environment-specific files
-
-Write both files to .planning/codebase/
-
-Read `templates/codebase/ARCHITECTURE.md.tmpl` for the ARCHITECTURE.md output format.
-Read `templates/codebase/STRUCTURE.md.tmpl` for the STRUCTURE.md output format.
-Fill in all placeholder fields with data from your codebase analysis.
-
-### If focus="quality"
-
-Analyze the codebase quality, conventions, and testing approach.
-
-1. CONVENTIONS.md — Coding standards in practice
-   - Naming conventions (files, functions, variables, classes)
-   - Code style (indentation, quotes, semicolons, etc.)
-   - Import/export patterns
-   - Comment style and documentation patterns
-   - Error handling patterns
-   - Logging patterns
-   - Configuration patterns (env vars, config files, constants)
-
-   IMPORTANT: Document what the codebase ACTUALLY does, not what it should do.
-   Look at multiple files to identify the dominant pattern.
-
-2. TESTING.md — Test infrastructure and coverage
-   - Test framework(s) used
-   - Test file organization
-   - Test types present (unit, integration, e2e)
-   - Test coverage (rough estimate from test file count vs source file count)
-   - Mocking patterns
-   - Test data management
-   - CI test configuration
-   - Notable gaps in testing
-
-Write both files to .planning/codebase/
-
-Read `templates/codebase/CONVENTIONS.md.tmpl` for the CONVENTIONS.md output format.
-Read `templates/codebase/TESTING.md.tmpl` for the TESTING.md output format.
-Fill in all placeholder fields with data from your codebase analysis.
-
-### If focus="concerns"
-
-Identify concerns, risks, and improvement opportunities in the codebase.
-
-Write CONCERNS.md to .planning/codebase/
-
-Analyze the codebase for:
-
-1. Security concerns
-   - Hardcoded secrets or credentials
-   - Injection vulnerabilities
-   - Insecure authentication patterns
-   - Missing input validation
-   - Outdated dependencies with known vulnerabilities
-
-2. Technical debt
-   - TODO/FIXME/HACK comments
-   - Dead code (unused exports, unreachable branches)
-   - Copy-pasted code (duplication)
-   - Overly complex functions
-   - Missing error handling
-   - Inconsistent patterns
-
-3. Scalability concerns
-   - N+1 query patterns
-   - Missing pagination
-   - Unbounded data loading
-   - Synchronous blocking operations
-   - Missing caching opportunities
-
-4. Maintainability concerns
-   - Missing documentation
-   - Complex inheritance hierarchies
-   - Tight coupling between modules
-   - Magic numbers/strings
-   - Missing type safety
-
-5. Operational concerns
-   - Missing health checks
-   - Insufficient logging
-   - No monitoring hooks
-   - Unclear deployment process
-
-Read `templates/codebase/CONCERNS.md.tmpl` for the CONCERNS.md output format.
-Fill in all placeholder fields with data from your codebase analysis.
-
----
-
-## Reconnaissance Detection Reference
-
-### Project Type Detection
-Look for:
-- package.json -> Node.js/JavaScript/TypeScript
-- requirements.txt / setup.py / pyproject.toml -> Python
-- CMakeLists.txt -> C/C++
-- go.mod -> Go
-- Cargo.toml -> Rust
-- pom.xml / build.gradle -> Java
-- *.sln / *.csproj -> .NET
-- Gemfile -> Ruby
-- composer.json -> PHP
-
-### Key Directory Detection
-Look for:
-- src/, lib/, app/ -> source code
-- test/, tests/, __tests__/, spec/ -> tests
-- docs/ -> documentation
-- config/, .config/ -> configuration
-- scripts/ -> build/deploy scripts
-- public/, static/, assets/ -> static assets
-- migrations/ -> database migrations
-
-Write output to: {output_path}

package/plugins/cursor-pbr/skills/setup/SKILL.md

@@ -1,296 +0,0 @@
----
-name: setup
-description: "Onboarding wizard. Initialize project, select models, verify setup."
----
-
-## Step 0 — Immediate Output
-
-**Before ANY tool calls**, display this banner:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► SETUP                                      ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-Then proceed to Step 1.
-
-# /pbr:setup — Plan-Build-Run Setup Wizard
-
-You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
-
----
-
-## Step 1: Detect Project State — Idempotency Guard
-
-Check if `.planning/` directory exists in the current working directory.
-
-**If `.planning/` exists**:
-- Check for existing core files: `STATE.md`, `ROADMAP.md`, `config.json`
-- If ANY of these exist, present a checkpoint:
-
-  Use AskUserQuestion:
-    question: "Existing project detected with {list of found files}. How should we proceed?"
-    header: "Setup"
-    options:
-      - label: "Resume"       description: "Keep existing .planning/ and review configuration (recommended)"
-      - label: "Reset"        description: "Archive current .planning/ to .planning.bak/ and start fresh"
-      - label: "Abort"        description: "Cancel setup — keep everything as-is"
-
-  - If "Resume": Tell the user: "Keeping existing project. Reviewing configuration." Skip to Step 3 (model selection)
-  - If "Reset": Run `mv .planning .planning.bak` (creating a backup), then proceed with fresh setup below
-  - If "Abort": Display "Setup cancelled. Run `/pbr:status` to see current project state." and stop
-
-- If `.planning/` exists but has NONE of the core files (empty or only has subdirs):
-  - Tell the user: "Found empty .planning/ directory. Proceeding with initialization."
-  - Continue to fresh setup below
-
-**If `.planning/` does NOT exist**:
-- Ask the user:
-
-```
-AskUserQuestion:
-  question: "No Plan-Build-Run project found. Would you like to initialize one?"
-  header: "Initialize"
-  options:
-    - label: "Yes, initialize here"
-      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
-    - label: "No, just exploring"
-      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
-```
-
-If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
-
-If "Yes", create the minimal `.planning/` structure:
-
-**CRITICAL: Create .planning/ directory structure NOW. Do NOT skip this step.**
-
-```bash
-mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
-```
-
-**CRITICAL: Write .planning/config.json NOW. Do NOT skip this step.**
-
-Create `.planning/config.json` with defaults:
-```json
-{
-  "version": 2,
-  "context_strategy": "aggressive",
-  "mode": "interactive",
-  "depth": "standard",
-  "features": {
-    "structured_planning": true,
-    "goal_verification": true,
-    "integration_verification": true,
-    "context_isolation": true,
-    "atomic_commits": true,
-    "session_persistence": true,
-    "research_phase": true,
-    "plan_checking": true,
-    "tdd_mode": false,
-    "status_line": true,
-    "auto_continue": false,
-    "auto_advance": false,
-    "team_discussions": false,
-    "inline_verify": false
-  },
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "sonnet"
-  },
-  "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "task_level": false,
-    "max_concurrent_agents": 3,
-    "min_plans_for_parallel": 2,
-    "use_teams": false
-  },
-  "planning": {
-    "commit_docs": true,
-    "max_tasks_per_plan": 3,
-    "search_gitignored": false
-  },
-  "git": {
-    "branching": "none",
-    "commit_format": "{type}({phase}-{plan}): {description}",
-    "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
-    "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
-    "mode": "enabled"
-  },
-  "gates": {
-    "confirm_project": true,
-    "confirm_roadmap": true,
-    "confirm_plan": true,
-    "confirm_execute": false,
-    "confirm_transition": true,
-    "issues_review": true
-  },
-  "safety": {
-    "always_confirm_destructive": true,
-    "always_confirm_external_services": true
-  }
-}
-```
-
-**CRITICAL: Write .planning/STATE.md NOW. Do NOT skip this step.**
-
-Create `.planning/STATE.md`:
-```markdown
----
-version: 2
-current_phase: 0
-total_phases: 0
-status: "initialized"
-progress_percent: 0
-last_activity: "{today's date}"
-last_command: "/pbr:setup"
-blockers: []
----
-# Project State
-
-## Current Position
-Phase: 0 of 0
-Status: initialized
-
-Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
-```
-
----
-
-## Step 2: Project Type (new projects only)
-
-```
-AskUserQuestion:
-  question: "What kind of project is this?"
-  header: "Project type"
-  options:
-    - label: "Greenfield"
-      description: "Starting from scratch — full planning cycle recommended"
-    - label: "Existing codebase"
-      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
-    - label: "Prototype/experiment"
-      description: "Quick iteration — lighter workflow with fewer gates"
-```
-
-Based on selection:
-- **Greenfield**: Keep defaults (full gates, structured planning)
-- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
-- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
-
-Update config.json with any changes.
-
----
-
-## Step 3: Model Selection
-
-```
-AskUserQuestion:
-  question: "Which model profile should Plan-Build-Run use for agents?"
-  header: "Models"
-  options:
-    - label: "Balanced (Recommended)"
-      description: "Sonnet for most agents, Haiku for synthesizer. Good quality/cost tradeoff."
-    - label: "Quality"
-      description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
-    - label: "Budget"
-      description: "Haiku for most agents. Fastest and cheapest, but lower quality."
-```
-
-Apply the selected profile to `config.json`:
-- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
-- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
-- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
-
----
-
-## Step 4: Workflow Preferences
-
-```
-AskUserQuestion:
-  question: "Which workflow features do you want enabled?"
-  header: "Features"
-  multiSelect: true
-  options:
-    - label: "Auto-continue"
-      description: "Automatically chain commands (build → review → next phase) without prompting"
-    - label: "TDD mode"
-      description: "Write tests before implementation in executor agents"
-    - label: "Strict gates"
-      description: "Require verification AND review to pass before advancing phases"
-    - label: "Git branching"
-      description: "Create a branch per phase for cleaner PR history"
-```
-
-Apply selections:
-- **Auto-continue**: Set `features.auto_continue: true`
-- **TDD mode**: Set `features.tdd_mode: true`
-- **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
-- **Git branching**: Set `git.branching: "phase"`
-
----
-
-## Step 4b: CLAUDE.md Integration
-
-Check if a `CLAUDE.md` file exists in the project root.
-
-**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, append the block below.
-**If it does NOT exist**: Create `CLAUDE.md` with the block below.
-
-Append/create this content:
-
-```markdown
-## Plan-Build-Run
-
-This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
-
-- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
-- Configuration: `.planning/config.json`
-- Run `/pbr:status` to see current project state and suggested next action.
-
-**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
-```
-
----
-
-## Step 5: Verification
-
-**CRITICAL: Run validation checks NOW to confirm setup succeeded. Do NOT skip this step.**
-
-Run a quick health check:
-
-1. Verify `.planning/config.json` is valid JSON
-2. Verify `.planning/STATE.md` exists and is parseable
-3. Verify hook scripts are accessible: `node ${PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
-4. Check that `npm test` works (if package.json exists)
-
-Display results:
-
-```
-Setup Complete!
-
-Project: {cwd basename}
-Model profile: {balanced/quality/budget}
-Depth: {quick/standard/comprehensive}
-Features: {list of enabled non-default features}
-
-Next steps:
-  /pbr:begin  — Full project setup with requirements and roadmap
-  /pbr:scan   — Analyze existing codebase (if adding to existing project)
-  /pbr:help   — Command reference
-  /pbr:config — Fine-tune individual settings
-```
-
----
-
-## Error Handling
-
-- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
-- If config.json write fails: Display the JSON content and ask user to save it manually
-- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics

package/plugins/cursor-pbr/skills/shared/commit-planning-docs.md

@@ -1,36 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/commit-planning-docs.md -->
-# Commit Planning Docs Pattern
-
-Standard pattern for committing planning artifacts to git. Reference this fragment in skills that create or modify `.planning/` files.
-
----
-
-## Pattern
-
-```
-If `planning.commit_docs: true` in config.json:
-1. Stage the relevant .planning/ files for this skill's output
-2. Commit with the format from the **Commit Messages by Skill** table below (most use `docs({scope}):` but some skills like pause use `wip(planning):`)
-3. Use the appropriate scope from the skill's commit conventions
-
-If `planning.commit_docs: false` or config.json missing:
-- Skip the commit step
-```
-
-## Commit Messages by Skill
-
-| Skill | Commit message format |
-|-------|----------------------|
-| build | `docs({phase}): add build summaries and verification` |
-| plan | `docs({phase}): add phase plans` |
-| review | `docs({phase}): add verification report` |
-| begin | `chore: initialize plan-build-run project planning` |
-| import | `docs({phase}): import external plans` |
-| quick | `docs(planning): quick task {NNN} - {slug}` |
-| scan | `docs(planning): initial codebase analysis` |
-| explore | `docs(planning): capture explore session outputs` |
-| debug | `docs(planning): open/resolve debug session {NNN}` |
-| discuss | `docs(planning): capture phase {N} discussion decisions` |
-| pause | `wip(planning): save session state — phase {N} plan {M}` |
-| todo | `docs(planning): add/complete todo {NNN}` |
-| milestone | `docs(planning): start/complete/audit milestone` |

package/plugins/cursor-pbr/skills/shared/config-loading.md

@@ -1,103 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/config-loading.md -->
-# Config Loading Pattern
-
-Standard pattern for loading `.planning/config.json` fields at the start of a skill invocation.
-
-> Referenced by: build, plan, review, import, begin, quick, milestone, scan skills
-
----
-
-## Tooling Shortcut
-
-Instead of reading and parsing STATE.md, ROADMAP.md, and config.json manually, run:
-```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
-```
-This returns a JSON object with `config`, `state`, `roadmap`, `current_phase`, and `progress`. Falls back gracefully if the script is missing -- parse files manually in that case.
-
-Additional tooling shortcuts:
-- `plan-index <phase>` -- returns plan inventory (plan_id, wave, depends_on, autonomous, must_haves_count per plan)
-- `phase-info <phase>` -- returns comprehensive phase status (verification, summaries, roadmap_status, filesystem_status, plan_count, completed)
-
----
-
-## Standard Config Fields
-
-These are the config.json fields commonly read by workflow skills. Each skill reads a subset depending on its needs.
-
-### Core Settings
-```
-depth                 -- quick | standard | comprehensive
-mode                  -- interactive | autonomous
-```
-
-### Feature Flags
-```
-features.research_phase        -- run researcher before planning
-features.plan_checking         -- validate plans via plan-checker agent
-features.goal_verification     -- run verifier after build
-features.inline_verify         -- per-task verification after each executor commit (opt-in)
-features.atomic_commits        -- require atomic commits per task
-features.auto_continue         -- write .auto-next signal on phase completion
-features.auto_advance          -- chain build->review->plan in autonomous mode
-features.integration_verification -- check cross-phase integration
-```
-
-### Gate Flags
-```
-gates.confirm_plan             -- require user approval before building
-gates.confirm_execute          -- require user confirmation before executing build
-gates.confirm_transition       -- require confirmation before advancing to next phase
-```
-
-### Parallelization
-```
-parallelization.enabled        -- whether to run plans in parallel
-parallelization.plan_level     -- parallel at plan level (within a wave)
-parallelization.max_concurrent_agents -- max simultaneous executors
-```
-
-### Planning
-```
-planning.commit_docs           -- commit planning docs after operations
-planning.max_tasks_per_plan    -- maximum tasks in a single plan
-```
-
-### Git
-```
-git.commit_format              -- commit message format
-git.branching         -- none | phase | milestone
-```
-
-### Models
-```
-models.researcher              -- model for researcher agent
-models.planner                 -- model for planner agent
-models.executor                -- model for executor agent
-models.verifier                -- model for verifier agent
-```
-
----
-
-## Config Field Matrix by Skill
-
-| Field | build | plan | review | import | begin | quick | milestone |
-|-------|-------|------|--------|--------|-------|-------|-----------|
-| depth | | X | | | X | | |
-| mode | X | X | X | | X | | |
-| features.research_phase | | X | | | | | |
-| features.plan_checking | | X | | X | | | |
-| features.goal_verification | X | | X | | | | |
-| features.inline_verify | X | | | | | | |
-| features.atomic_commits | X | | | | | | |
-| features.auto_continue | X | | | | | | |
-| features.auto_advance | X | X | X | | | | |
-| features.integration_verification | | | X | | | | X |
-| gates.confirm_plan | | X | | | | | |
-| gates.confirm_execute | X | | | | | | |
-| gates.confirm_transition | | | X | | | | |
-| parallelization.* | X | | | | | | |
-| planning.commit_docs | X | | | | | X | X |
-| git.commit_format | X | | | | X | X | |
-| git.branching | X | | | | | | |
-| models.* | | X | X | | X | | X |

package/plugins/cursor-pbr/skills/shared/context-budget.md

@@ -1,41 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/context-budget.md -->
-# Context Budget Rules
-
-Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() subagents.
-
-See also: `skills/shared/universal-anti-patterns.md` for the complete set of universal rules (context budget + file reading + behavioral rules).
-
----
-
-## Universal Rules
-
-Every skill that spawns agents or reads significant content must follow these rules:
-
-1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
-2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
-3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
-4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
-5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
-
-## Customization
-
-Skills should add skill-specific rules below the reference line. Common skill-specific additions:
-
-- **build**: "Minimize reading executor output — read only SUMMARY.md frontmatter, not full content"
-- **plan**: "Minimize reading subagent output — read only plan frontmatter for summaries"
-- **review**: "Minimize reading subagent output — read only VERIFICATION.md frontmatter for summaries"
-- **scan**: "Delegate ALL analysis to the 4 parallel codebase-mapper subagents"
-- **quick**: "Never implement the task yourself — ALL code changes go through a spawned executor"
-- **debug**: "Never perform investigation work yourself — delegate ALL analysis to the debugger subagent"
-
-Format in the SKILL.md:
-
-```markdown
-## Context Budget
-
-Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
-
-Additionally for this skill:
-- {Skill-specific rule 1}
-- {Skill-specific rule 2}
-```