@sienklogic/plan-build-run 2.0.2 → 2.2.0

package/plugins/cursor-pbr/references/planning-config.md

@@ -0,0 +1,214 @@
+<!-- canonical: ../../pbr/references/planning-config.md -->
+# Planning Config Reference
+
+Schema, fields, defaults, and behavioral effects of Plan-Build-Run's `config.json`.
+
+---
+
+## Overview
+
+Plan-Build-Run's configuration lives at `.planning/config.json` in the project root. It is created by `/pbr:begin` and can be modified via `/pbr:config` or by editing the file directly. The config controls workflow behavior, model selection, parallelization, git integration, and confirmation gates.
+
+---
+
+## Schema Version
+
+```json
+{ "version": 2 }
+```
+
+The `version` field tracks schema migrations. Current version is `2`. When loading a config with an older version, Plan-Build-Run runs automatic migration (e.g., v1 to v2 adds missing fields with defaults, renames `model_profile` to per-agent `models` object).
+
+---
+
+## Top-Level Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `version` | number | `2` | Config schema version |
+| `context_strategy` | string | `"aggressive"` | Context budget strategy: `aggressive`, `balanced`, `minimal` |
+| `mode` | string | `"interactive"` | Workflow mode: `interactive` |
+| `depth` | string | `"standard"` | Research/planning depth: `quick`, `standard`, `comprehensive` |
+
+### depth
+
+Controls how thorough research and planning phases are:
+
+| Value | Behavior |
+|-------|----------|
+| `quick` | Minimal research, smaller plans, faster execution |
+| `standard` | Balanced research depth, standard plan detail |
+| `comprehensive` | Deep research with multiple sources, detailed plans with more tasks |
+
+### context_strategy
+
+Controls how aggressively Plan-Build-Run manages context budget:
+
+| Value | Behavior |
+|-------|----------|
+| `aggressive` | Proactive compaction warnings, strict context isolation, minimal file reads in main context |
+| `balanced` | Moderate context management with some inline reads |
+| `minimal` | Relaxed context management, more inline content allowed |
+
+---
+
+## features
+
+Boolean toggles that enable or disable specific workflow capabilities.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `structured_planning` | `true` | Use phased planning with ROADMAP and plan files |
+| `goal_verification` | `true` | Run verifier agent after builds to check goals are met |
+| `integration_verification` | `true` | Run cross-phase integration checks |
+| `context_isolation` | `true` | Isolate work into subagents to protect main context |
+| `atomic_commits` | `true` | Require one commit per task (vs. batched commits) |
+| `session_persistence` | `true` | Persist state across sessions via STATE.md |
+| `research_phase` | `true` | Run research before planning |
+| `plan_checking` | `true` | Run plan-checker agent before execution |
+| `tdd_mode` | `false` | Enable Test-Driven Development for all tasks (Red-Green-Refactor) |
+| `status_line` | `true` | Show status line in session UI |
+| `auto_continue` | `false` | Write `.auto-next` signal on phase completion for automatic continuation |
+| `auto_advance` | `false` | Chain build→review→plan automatically in autonomous mode (requires `mode: autonomous`) |
+| `team_discussions` | `false` | Enable team-based discussion workflows (never used for execution) |
+| `inline_verify` | `false` | Run per-task verification after each executor commit (opt-in, adds latency) |
+
+### Notable interactions
+
+- `goal_verification: false` skips the post-build verification step. The build skill appends a note suggesting `/pbr:review` manually.
+- `tdd_mode: true` causes all task types to follow Red-Green-Refactor, producing 3 commits per task instead of 1.
+- `auto_continue: true` writes a `.planning/.auto-next` file containing the next command (e.g., `/pbr:plan 4`), allowing wrapper scripts to chain phases.
+- `auto_advance: true` + `mode: autonomous` enables full phase cycling: build completes → auto-invoke review → if verification passes → auto-invoke plan for next phase. Hard stops at: checkpoints, verification gaps, errors, milestone boundaries.
+- `inline_verify: true` spawns a haiku-model verifier after each plan completes within a wave. Adds ~10-20s latency per plan but catches issues before dependent plans run.
+
+---
+
+## models
+
+Per-agent model selection. See `references/model-profiles.md` for full details.
+
+```json
+{
+  "models": {
+    "researcher": "sonnet",
+    "planner": "inherit",
+    "executor": "inherit",
+    "verifier": "sonnet",
+    "integration_checker": "sonnet",
+    "debugger": "inherit",
+    "mapper": "sonnet",
+    "synthesizer": "haiku"
+  }
+}
+```
+
+Valid values: `sonnet`, `opus`, `haiku`, `inherit`.
+
+---
+
+## parallelization
+
+Controls whether and how plans execute concurrently.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable parallel plan execution within a wave |
+| `plan_level` | boolean | `true` | Parallelize at plan level (multiple plans in same wave) |
+| `task_level` | boolean | `false` | Parallelize at task level within a plan (not currently used) |
+| `max_concurrent_agents` | number | `3` | Maximum simultaneous executor subagents |
+| `min_plans_for_parallel` | number | `2` | Minimum plans in a wave to trigger parallel execution |
+| `use_teams` | boolean | `false` | Use Agent Teams for coordination (discussion only, never execution) |
+
+### Behavior
+
+When `enabled: true` and a wave has >= `min_plans_for_parallel` plans, the build orchestrator spawns up to `max_concurrent_agents` executor Task() calls in parallel using `run_in_background: true`.
+
+When `enabled: false` or a wave has only 1 plan, executors run sequentially.
+
+Git lock conflicts can occur with parallel execution. Executors handle this with retry logic (wait 2s, max 3 attempts). If conflicts persist, reduce `max_concurrent_agents` to 1.
+
+---
+
+## planning
+
+Controls planning behavior and documentation.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `commit_docs` | boolean | `true` | Commit planning docs (SUMMARY, VERIFICATION) after builds |
+| `max_tasks_per_plan` | number | `3` | Maximum tasks per plan (keeps plans focused and atomic) |
+| `search_gitignored` | boolean | `false` | Include gitignored files in codebase scanning |
+
+### commit_docs
+
+When `true`, after all plans in a phase complete, the build orchestrator stages and commits planning artifacts:
+```
+docs({phase}): add build summaries and verification
+```
+
+When `false`, planning docs remain unstaged/uncommitted.
+
+---
+
+## git
+
+Controls git integration and branching.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `branching` | string | `"none"` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
+| `commit_format` | string | `"{type}({phase}-{plan}): {description}"` | Commit message template |
+| `phase_branch_template` | string | `"plan-build-run/phase-{phase}-{slug}"` | Phase branch naming |
+| `milestone_branch_template` | string | `"plan-build-run/{milestone}-{slug}"` | Milestone branch naming |
+| `mode` | string | `"enabled"` | Git mode: `enabled` or `disabled` |
+
+See `references/git-integration.md` for full branching strategy details.
+
+### mode: disabled
+
+When `git.mode` is `"disabled"`, no git commands are run at all -- no commits, no branching, no hook validation. Useful for prototyping or non-git projects.
+
+---
+
+## gates
+
+Confirmation gates that pause execution to ask the user before proceeding.
+
+| Field | Default | When Triggered |
+|-------|---------|----------------|
+| `confirm_project` | `true` | Before creating a new Plan-Build-Run project (`/pbr:begin`) |
+| `confirm_roadmap` | `true` | Before finalizing a roadmap |
+| `confirm_plan` | `true` | Before finalizing plans for a phase |
+| `confirm_execute` | `false` | Before starting phase execution (`/pbr:build`) |
+| `confirm_transition` | `true` | Before transitioning to the next phase |
+| `issues_review` | `true` | Before proceeding when issues are detected |
+
+Setting a gate to `false` makes that step automatic (no user prompt).
+
+---
+
+## safety
+
+Safety controls for destructive or external operations.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `always_confirm_destructive` | boolean | `true` | Always ask before destructive git operations |
+| `always_confirm_external_services` | boolean | `true` | Always ask before calling external APIs or services |
+
+These cannot be disabled via `/pbr:config` -- they require manual editing of `config.json` as a deliberate action.
+
+---
+
+## Validation Rules
+
+When modifying config (via `/pbr:config` or direct edit):
+
+| Field | Valid Values |
+|-------|-------------|
+| `depth` | `quick`, `standard`, `comprehensive` |
+| `models.*` | `sonnet`, `inherit`, `haiku`, `opus` |
+| `context_strategy` | `aggressive`, `balanced`, `minimal` |
+| `git.branching` | `none`, `phase`, `milestone`, `disabled` |
+| `git.mode` | `enabled`, `disabled` |
+| All boolean fields | `true`, `false` |

package/plugins/cursor-pbr/references/questioning.md

@@ -0,0 +1,215 @@
+<!-- canonical: ../../pbr/references/questioning.md -->
+# Deep Questioning Guide
+
+Techniques for understanding a user's project vision during `/pbr:begin`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
+
+---
+
+## Core Questioning Techniques
+
+### Challenge Vagueness
+
+When the user says something abstract or general, push for specifics.
+
+| They say | You ask |
+|----------|---------|
+| "It should be fast" | "Fast how? Page load under 1 second? API response under 200ms? What's the baseline today?" |
+| "A dashboard" | "What's on the dashboard? What data? What can users do with it?" |
+| "User management" | "What can users do? Sign up, log in, reset password? Roles? Permissions? Teams?" |
+| "It needs to scale" | "Scale to what? 100 users? 100,000? What's the growth timeline?" |
+
+### Make Abstract Concrete
+
+Ask for examples and walk-throughs.
+
+- "Walk me through what a user does when they first open this."
+- "Give me an example of [that feature] in action."
+- "If I were a user right now, what would I see?"
+- "What does a typical session look like from start to finish?"
+
+### Surface Assumptions
+
+Expose hidden assumptions the user hasn't stated.
+
+- "Why do you assume [X]? Is that a hard requirement?"
+- "Have you considered [alternative]? What made you choose [their approach]?"
+- "What if [assumption] turns out to be wrong?"
+- "Is that because of a technical constraint, or a preference?"
+
+### Find Edges
+
+Probe for edge cases and boundary conditions.
+
+- "What happens when [unexpected input]?"
+- "What if two users do [action] at the same time?"
+- "What about offline/slow connections?"
+- "What if the user has [unusual state]?"
+- "What's the maximum [items/users/data] this needs to handle?"
+
+### Reveal Motivation
+
+Understand the WHY behind features.
+
+- "Why does that matter?"
+- "What problem does that solve for the user?"
+- "What happens if we don't build that?"
+- "Who specifically needs this? Why?"
+- "What's the cost of getting this wrong?"
+
+### Prioritize Ruthlessly
+
+Force ranking and trade-off decisions.
+
+- "If you could only ship three features, which three?"
+- "Would you rather have [A] done well or [A and B] done halfway?"
+- "What's the minimum that would make this useful?"
+- "What would you cut if you had to ship in half the time?"
+
+### Surface Implications
+
+When the user states a preference or makes a choice, surface what it implies before moving on. This avoids surprises later and reveals whether the user has thought through the consequences.
+
+- "You want real-time updates. That typically means WebSockets, which adds deployment complexity. Are you prepared for that, or would polling work?"
+- "Card-based layout with sort/filter usually means client-side state management. How complex are your filtering needs?"
+- "You mentioned multi-tenant. That affects database design, auth, billing — have you thought through isolation boundaries?"
+- "Self-hosted deployment means you own uptime. Do you have monitoring and on-call plans?"
+
+The pattern: **[stated preference] implies [consequence]. Is that acceptable, or should we reconsider?**
+
+### Frame Trade-offs, Not Menus
+
+Replace "Do you want A or B?" with trade-off framing that shows real consequences.
+
+| Instead of | Ask |
+|------------|-----|
+| "SQL or NoSQL?" | "SQL gives you strong consistency and relationships but needs schema migrations. NoSQL gives you flexible documents but makes joins painful. What matters more for your data?" |
+| "SSR or SPA?" | "SSR gives you better SEO and initial load, but adds server cost. SPA gives you snappier interactions but hurts discoverability. What's the priority?" |
+| "Monolith or microservices?" | "A monolith ships faster and is simpler to debug, but gets harder to scale independently. Microservices scale cleanly but add deployment and coordination overhead. Where are you on that spectrum?" |
+
+The pattern: **A gives you X but costs Y. B gives you Z but costs W. What matters more to you?**
+
+This produces better answers than binary choices because users reveal their actual priorities.
+
+---
+
+## Required Context Checklist
+
+By the end of questioning, you should have clear answers for ALL of these:
+
+### The Problem
+- [ ] What problem is being solved?
+- [ ] Who has this problem? (specific users/personas)
+- [ ] How are they solving it today? (current state)
+- [ ] Why is the current solution inadequate?
+
+### The Solution
+- [ ] What is being built? (concrete description)
+- [ ] What does "done" look like? (at least 3 success criteria)
+- [ ] What are the core features? (prioritized)
+- [ ] What is explicitly NOT being built? (scope boundaries)
+
+### Constraints
+- [ ] Technology choices already made (language, framework, hosting)
+- [ ] Budget constraints (money, time, resources)
+- [ ] Team constraints (size, skill level, availability)
+- [ ] Integration constraints (existing systems, APIs, databases)
+- [ ] Timeline expectations (deadlines, milestones)
+
+### Decisions Already Made
+- [ ] Architecture preferences or requirements
+- [ ] Deployment environment (cloud, self-hosted, serverless)
+- [ ] Authentication approach
+- [ ] Data storage approach
+- [ ] Third-party services to use
+
+### Edge Cases and Concerns
+- [ ] What keeps them up at night about this project?
+- [ ] What's the hardest part?
+- [ ] What might go wrong?
+- [ ] What are they unsure about?
+
+---
+
+## Progressive Depth Layers
+
+Structure the conversation as deepening layers. Each layer builds on the previous one. You do not need to complete every layer in every project, but the order matters — do not jump to Layer 3 before Layer 1 is solid.
+
+### Layer 1: Shape — "What are you building?"
+Establish the broad outline. What is it, who is it for, what does it do?
+- Core purpose and user personas
+- Primary features and workflows
+- Technology preferences or constraints
+
+### Layer 2: Feel — "How should users experience this?"
+Move from structure to experience. How does it feel to use?
+- UI expectations, interaction patterns, responsiveness
+- Tone, branding, visual direction
+- Performance expectations from the user's perspective
+
+### Layer 3: Edges — "What happens when things go wrong?"
+Probe failure modes, edge cases, and the unexpected.
+- Error handling, empty states, data conflicts
+- Permission boundaries, rate limits, abuse scenarios
+- What the user has NOT thought about yet
+
+### Layer 4: System — "How does this fit into the bigger picture?"
+Zoom out to the surrounding ecosystem.
+- Integrations, data flows, deployment environment
+- Operational concerns — monitoring, backups, migrations
+- Future evolution and extensibility
+
+---
+
+## Conversation Flow
+
+The conversation should feel natural, not like an interrogation. Follow this general arc:
+
+### Opening (1-2 exchanges)
+Start broad and let them paint the picture:
+- "What are you building?"
+- "Tell me about this project."
+
+### Exploration (3-5 exchanges)
+Dive into specifics on each area they mention:
+- Follow their energy — explore what they're excited about
+- Circle back to areas they glossed over
+- Use "tell me more about..." and "what does that mean exactly?"
+
+### Constraints (2-3 exchanges)
+Shift to practical matters:
+- "What are you working with? Language, framework, hosting?"
+- "Any hard constraints I should know about?"
+- "What's the timeline looking like?"
+
+### Prioritization (1-2 exchanges)
+Force trade-offs:
+- "Of everything we discussed, what's the core? What MUST be in v1?"
+- "What can wait for v2?"
+
+### Confirmation (1 exchange)
+Summarize back what you heard and confirm:
+- "Let me play this back: you're building [X] that [does Y] for [users Z]. The core features are [A, B, C]. You're using [stack]. The biggest risk is [concern]. Did I get that right?"
+
+---
+
+## Domain-Aware Probing
+
+When the user mentions a specific technology area (e.g., "React app", "REST API", "real-time chat"), use domain-specific follow-up questions to go deeper. General questions miss critical details that only matter in that domain.
+
+See **[skills/shared/domain-probes.md](../shared/domain-probes.md)** for technology-specific probing patterns organized by domain (frontend frameworks, databases, APIs, auth, deployment, etc.). Reference those patterns when the conversation enters a technology-specific area rather than relying on generic follow-ups.
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** present a form and ask users to fill it in
+2. **DO NOT** ask all questions at once — have a conversation
+3. **DO NOT** assume you know what they want — ask
+4. **DO NOT** suggest technologies before understanding the problem
+5. **DO NOT** skip edge case exploration
+6. **DO NOT** accept vague answers — push for specifics
+7. **DO NOT** rush through questioning to get to planning
+8. **DO NOT** ignore concerns or hand-wave them away
+9. **DO NOT** lead the user toward a particular solution
+10. **DO NOT** forget to summarize and confirm understanding
+11. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"

package/plugins/cursor-pbr/references/reading-verification.md

@@ -0,0 +1,128 @@
+<!-- canonical: ../../pbr/references/reading-verification.md -->
+# Reading Verification Reports
+
+A user-friendly guide to understanding verification results. For agent-facing patterns, see `verification-patterns.md`.
+
+---
+
+## What Verification Checks
+
+After building a phase, Plan-Build-Run runs automated verification to check whether the code actually delivers what was planned. It checks every "must-have" from the plan through three layers:
+
+### Layer 1: Existence
+
+**Question**: Does the file/function/route exist at all?
+
+This is the most basic check. If the plan said "create `src/auth.ts`" — does that file exist on disk? If it said "add a `/login` route" — can we find it in the codebase?
+
+**Common failures**: File was planned but never created, renamed to a different path, or deleted by a later task.
+
+### Layer 2: Substantiveness
+
+**Question**: Is the code real, or just a stub/placeholder?
+
+A file can exist but contain nothing useful — an empty function, a `throw new Error('Not implemented')`, or a component that just renders its own name. This layer catches those cases.
+
+**Common failures**: Function body is empty, returns hardcoded test data, or only has a TODO comment.
+
+### Layer 3: Wiring
+
+**Question**: Are the pieces connected to each other?
+
+Code can exist and be real, but if nothing imports it or calls it, it's dead code. This layer checks that modules are imported where needed, middleware is applied to routes, and components are rendered in the right places.
+
+**Common failures**: Module created but never imported, route handler exists but not registered in the router, component built but not used in any page.
+
+---
+
+## Reading the Verification Report
+
+A `VERIFICATION.md` file looks like this:
+
+```
+Status: passed (or gaps_found)
+Must-haves checked: 8
+Passed: 7
+Gaps: 1
+```
+
+### When status is "passed"
+
+All must-haves passed all three layers. The phase is complete and you can move on.
+
+### When status is "gaps_found"
+
+One or more must-haves failed verification. Each gap includes:
+
+- **Must-have**: What was expected (from the plan)
+- **Failed layer**: Which check failed (existence, substantiveness, or wiring)
+- **Evidence**: The specific command output or file content that shows the failure
+- **Suggested fix**: What to do about it
+
+---
+
+## Common Gap Types and What They Mean
+
+### "File not found"
+**Layer**: Existence
+**Meaning**: A planned file was never created or was created at a different path.
+**Fix**: Usually a simple oversight — the executor may have created it with a slightly different name. Check the phase directory for similar files.
+
+### "Function is a stub"
+**Layer**: Substantiveness
+**Meaning**: The file exists but the implementation is incomplete. Common indicators: empty function bodies, `TODO` comments, placeholder return values.
+**Fix**: The executor may have run out of context before finishing. Re-running the build usually resolves this.
+
+### "Module not imported"
+**Layer**: Wiring
+**Meaning**: The code was written correctly but nothing uses it. The import statement is missing from the consuming file.
+**Fix**: Usually a one-line fix — add the import statement to the right file.
+
+### "Test has no assertions"
+**Layer**: Substantiveness
+**Meaning**: A test file exists but doesn't actually test anything — empty `it()` blocks or `expect(true).toBe(true)`.
+**Fix**: Real test assertions need to be written. This usually happens when TDD mode is off and the executor generates placeholder tests.
+
+### "Route not registered"
+**Layer**: Wiring
+**Meaning**: A route handler function was created but never mounted on the Express/Fastify/etc. router.
+**Fix**: Add the route registration (usually `app.use()` or `router.get()`) to the main app file.
+
+---
+
+## How to Close Gaps
+
+You have several options:
+
+### Option 1: Re-run the build (most common)
+```
+/pbr:build <N>
+```
+The executor will detect what's already complete and only fix what's missing.
+
+### Option 2: Create a gap-closure plan
+```
+/pbr:plan <N> --gaps
+```
+This creates a focused plan that targets only the specific gaps found during verification.
+
+### Option 3: Manual fix
+For small gaps (like a missing import), you can fix the code yourself and then re-run verification:
+```
+/pbr:review <N>
+```
+
+### Option 4: Override (for false positives)
+If verification flagged something that's actually correct (e.g., a function intentionally returns an empty array), you can override the gap during review. The override is recorded in the verification report.
+
+---
+
+## Understanding Verification Attempts
+
+The verification report tracks `attempt` count. If a phase has been verified multiple times:
+
+- **Attempt 1**: Normal first verification
+- **Attempt 2**: Gaps were found and fixed, re-verifying
+- **Attempt 3+**: Escalation — Plan-Build-Run will offer additional options like accepting with gaps, switching to debug mode, or re-planning the phase
+
+Multiple attempts don't mean something is wrong — complex phases often need a round of gap-closure before passing.