@sienklogic/plan-build-run 2.0.2 → 2.2.0

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

@@ -0,0 +1,202 @@
+<\!-- 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

@@ -0,0 +1,250 @@
+---
+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
+
+Check if `.planning/` directory exists in the current working directory.
+
+**If `.planning/` exists**:
+- Read `.planning/config.json` to check current settings
+- Tell the user: "Existing Plan-Build-Run project detected. This wizard will review your configuration."
+- Skip to Step 3 (model selection)
+
+**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:
+
+```bash
+mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
+```
+
+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
+  }
+}
+```
+
+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 5: Verification
+
+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 ${CLAUDE_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

@@ -0,0 +1,36 @@
+<!-- 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

@@ -0,0 +1,103 @@
+<!-- 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

@@ -0,0 +1,41 @@
+<!-- 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}
+```