@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/cursor-pbr/skills/shared/gate-prompts.md

@@ -1,389 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/gate-prompts.md -->
-# Gate Prompt Patterns
-
-> Referenced by: plan, build, import, scan, review, milestone, config, status, resume, quick, begin, discuss, explore, debug skills
-> Purpose: Reusable AskUserQuestion patterns for structured gate checks
-
-These patterns provide consistent, structured prompts for user decision points. Skills reference these patterns by name to ensure all gate checks use the same format.
-
-## Rules
-
-- `header` must be max 12 characters
-- `multiSelect` is always `false` for gate checks
-- Always handle the "Other" case (user typed a freeform response instead of selecting)
-
----
-
-## Pattern: approve-revise-abort
-
-3-option gate for plan approval, gap-closure approval.
-
-```
-Use AskUserQuestion:
-  question: "Approve these {noun}?"
-  header: "Approve?"
-  options:
-    - label: "Approve"          description: "Proceed with {action}"
-    - label: "Request changes"  description: "Discuss adjustments before proceeding"
-    - label: "Abort"            description: "Cancel this operation"
-  multiSelect: false
-```
-
----
-
-## Pattern: yes-no
-
-Simple 2-option confirmation for re-planning, rebuild, replace plans, commit.
-
-```
-Use AskUserQuestion:
-  question: "{Specific question about the action}"
-  header: "Confirm"
-  options:
-    - label: "Yes"  description: "{What happens if yes}"
-    - label: "No"   description: "{What happens if no}"
-  multiSelect: false
-```
-
----
-
-## Pattern: stale-continue
-
-2-option refresh gate for staleness warnings, timestamp freshness.
-
-```
-Use AskUserQuestion:
-  question: "{Artifact} may be outdated. Refresh or continue?"
-  header: "Stale"
-  options:
-    - label: "Refresh"          description: "Update before proceeding (recommended)"
-    - label: "Continue anyway"  description: "Proceed with current version"
-  multiSelect: false
-```
-
----
-
-## Pattern: yes-no-pick
-
-3-option selection for seed selection, item inclusion.
-
-```
-Use AskUserQuestion:
-  question: "Include {items} in planning?"
-  header: "Include?"
-  options:
-    - label: "Yes, all"     description: "Include all matching items"
-    - label: "Let me pick"  description: "Choose which items to include"
-    - label: "No"           description: "Proceed without these items"
-  multiSelect: false
-```
-
----
-
-## Pattern: multi-option-failure
-
-4-option failure handler for build failures.
-
-```
-Use AskUserQuestion:
-  question: "Plan {id} failed. How should we proceed?"
-  header: "Failed"
-  options:
-    - label: "Retry"     description: "Re-run this plan's executor"
-    - label: "Skip"      description: "Mark as skipped, continue to next wave"
-    - label: "Rollback"  description: "Undo commits, revert to last good state"
-    - label: "Abort"     description: "Stop the entire build"
-  multiSelect: false
-```
-
----
-
-## Pattern: multi-option-escalation
-
-4-option escalation for review escalation (max AskUserQuestion supports).
-
-```
-Use AskUserQuestion:
-  question: "Phase {N} has failed verification {attempt} times. How should we proceed?"
-  header: "Escalate"
-  options:
-    - label: "Accept gaps"  description: "Mark as complete-with-gaps and move on"
-    - label: "Re-plan"      description: "Go back to /pbr:plan with gap context"
-    - label: "Debug"        description: "Spawn /pbr:debug to investigate root causes"
-    - label: "Retry"        description: "Try one more verification cycle"
-  multiSelect: false
-```
-
-Note: AskUserQuestion supports max 4 options. The original review escalation had 5 options (accept-gaps/re-plan/debug/override/retry). The "override" option is folded into the post-selection flow: if user selects "Accept gaps", offer a follow-up AskUserQuestion asking whether to accept all gaps or pick specific ones (the "override" behavior).
-
----
-
-## Pattern: multi-option-gaps
-
-4-option gap handler for review gaps-found.
-
-```
-Use AskUserQuestion:
-  question: "{count} verification gaps need attention. How should we proceed?"
-  header: "Gaps"
-  options:
-    - label: "Auto-fix"  description: "Diagnose root causes and create fix plans (recommended)"
-    - label: "Override"   description: "Accept specific gaps as false positives"
-    - label: "Manual"     description: "I'll fix these myself"
-    - label: "Skip"       description: "Save results for later"
-  multiSelect: false
-```
-
----
-
-## Pattern: multi-option-priority
-
-4-option priority selection for milestone gap priority.
-
-```
-Use AskUserQuestion:
-  question: "Which gaps should we address?"
-  header: "Priority"
-  options:
-    - label: "Must-fix only"   description: "Address critical/high gaps only"
-    - label: "Must + should"   description: "Address critical, high, and medium gaps"
-    - label: "Everything"      description: "Address all gaps including low priority"
-    - label: "Let me pick"     description: "Choose specific gaps to address"
-  multiSelect: false
-```
-
----
-
-## Pattern: settings-category-select
-
-4-option menu for configuration category selection (config skill).
-
-```
-Use AskUserQuestion:
-  question: "What would you like to configure?"
-  header: "Configure"
-  options:
-    - label: "Depth"          description: "quick/standard/comprehensive"
-    - label: "Model profile"  description: "quality/balanced/budget/adaptive"
-    - label: "Features"       description: "Toggle workflow features and gates"
-    - label: "Git settings"   description: "branching strategy, commit mode"
-  multiSelect: false
-```
-
-Note: Original 7 categories condensed to 4. "Models" (per-agent) merged into "Model profile". "Gates" and "Parallelization" merged into "Features". After selection, show a category-specific follow-up AskUserQuestion.
-
----
-
-## Pattern: toggle-confirm
-
-2-option confirmation for enabling/disabling boolean features (config skill).
-
-```
-Use AskUserQuestion:
-  question: "Enable {feature_name}?"
-  header: "Toggle"
-  options:
-    - label: "Enable"   description: "Turn this feature on"
-    - label: "Disable"  description: "Turn this feature off"
-  multiSelect: false
-```
-
----
-
-## Pattern: model-profile-select
-
-4-option selection for model profile presets (config skill).
-
-```
-Use AskUserQuestion:
-  question: "Select model profile"
-  header: "Profile"
-  options:
-    - label: "Quality"    description: "opus for all agents (highest cost)"
-    - label: "Balanced"   description: "sonnet/inherit mix (default)"
-    - label: "Budget"     description: "haiku for all agents (lowest cost)"
-    - label: "Adaptive"   description: "sonnet planning, haiku execution"
-  multiSelect: false
-```
-
----
-
-## Pattern: action-routing
-
-Up to 4 suggested next actions with selection (status, resume skills).
-
-```
-Use AskUserQuestion:
-  question: "What would you like to do next?"
-  header: "Next Step"
-  options:
-    - label: "{primary action}"   description: "{explanation}"
-    - label: "{alternative 1}"    description: "{explanation}"
-    - label: "{alternative 2}"    description: "{explanation}"
-    - label: "Something else"     description: "Enter a different command"
-  multiSelect: false
-```
-
-Note: Dynamically generate options from workflow state. The "Something else" option allows freeform input. Build 1-3 real options + always include "Something else" as the last option. If only 1 real option exists, use the yes-no pattern instead.
-
----
-
-## Pattern: pause-point-select
-
-Select from multiple resume points (resume skill).
-
-```
-Use AskUserQuestion:
-  question: "Found multiple pause points. Which would you like to resume?"
-  header: "Resume"
-  options:
-    - label: "Phase {A}"  description: "Paused {date}"
-    - label: "Phase {B}"  description: "Paused {date}"
-    - label: "Phase {C}"  description: "Paused {date}"
-    - label: "Phase {D}"  description: "Paused {date}"
-  multiSelect: false
-```
-
-Note: If more than 4 pause points exist, show the 4 most recent. The oldest option becomes "Show earlier" which re-prompts with the next batch.
-
----
-
-## Pattern: scope-confirm
-
-3-option confirmation for quick task scope validation (quick skill).
-
-```
-Use AskUserQuestion:
-  question: "This task looks complex. Proceed as quick task or use full planning?"
-  header: "Scope"
-  options:
-    - label: "Quick task"  description: "Execute as lightweight task"
-    - label: "Full plan"   description: "Switch to /pbr:plan for proper planning"
-    - label: "Revise"      description: "Let me rewrite the task description"
-  multiSelect: false
-```
-
----
-
-## Pattern: depth-select
-
-3-option depth selection for begin skill workflow preferences.
-
-```
-Use AskUserQuestion:
-  question: "How thorough should planning be?"
-  header: "Depth"
-  options:
-    - label: "Quick"           description: "3-5 phases, skip research, ~50% cheaper"
-    - label: "Standard"        description: "5-8 phases with research (default)"
-    - label: "Comprehensive"   description: "8-12 phases, deep research, ~2x cost"
-  multiSelect: false
-```
-
----
-
-## Pattern: git-strategy-select
-
-3-option git branching strategy for begin skill.
-
-```
-Use AskUserQuestion:
-  question: "Git branching strategy?"
-  header: "Git"
-  options:
-    - label: "None"                description: "Commit to current branch (default)"
-    - label: "Phase branches"      description: "Create a branch per phase"
-    - label: "Milestone branches"  description: "Create a branch per milestone"
-  multiSelect: false
-```
-
----
-
-## Pattern: context-handling
-
-3-option handler for existing CONTEXT.md in discuss skill.
-
-```
-Use AskUserQuestion:
-  question: "Phase {N} already has a CONTEXT.md. How should we handle it?"
-  header: "Context"
-  options:
-    - label: "Overwrite"  description: "Replace with new decisions"
-    - label: "Append"     description: "Add new decisions below existing ones"
-    - label: "Cancel"     description: "Keep existing and stop"
-  multiSelect: false
-```
-
----
-
-## Pattern: gray-area-option
-
-Dynamic template for presenting gray area choices in discuss skill.
-
-```
-Use AskUserQuestion:
-  question: "{Gray area title}"
-  header: "Decision"
-  options:
-    - label: "{Option 1}"        description: "{Concrete approach 1}"
-    - label: "{Option 2}"        description: "{Concrete approach 2}"
-    - label: "Let Claude decide"  description: "Mark as Claude's Discretion"
-  multiSelect: false
-```
-
-Note: Options are generated at runtime based on phase analysis. The pattern defines the structure; the skill fills in options per gray area. Always include "Let Claude decide" as the last option. If more than 4 options are identified, split into a 2-step flow (AskUserQuestion supports max 4 options).
-
----
-
-## Pattern: output-routing
-
-4-option confirmation for explore skill output proposals.
-
-```
-Use AskUserQuestion:
-  question: "How do you want to handle these proposed outputs?"
-  header: "Outputs"
-  options:
-    - label: "Approve all"  description: "Create all suggested artifacts"
-    - label: "Adjust"       description: "Modify the proposals before creating"
-    - label: "Add more"     description: "I have additional outputs to capture"
-    - label: "Skip"         description: "Don't create any artifacts from this session"
-  multiSelect: false
-```
-
----
-
-## Pattern: debug-session-select
-
-Dynamic template for debug session selection.
-
-```
-Use AskUserQuestion:
-  question: "Found active debug sessions. Which would you like?"
-  header: "Debug"
-  options:
-    - label: "#{NNN}: {title}"  description: "Started {date}, last: {hypothesis}"
-    - label: "#{NNN}: {title}"  description: "Started {date}, last: {hypothesis}"
-    - label: "#{NNN}: {title}"  description: "Started {date}, last: {hypothesis}"
-    - label: "New session"      description: "Start a fresh debug investigation"
-  multiSelect: false
-```
-
-Note: Options are generated at runtime from active debug sessions. If more than 3 active sessions exist, show the 3 most recent plus "New session" (max 4 options). Older sessions can be accessed by running `/pbr:debug` with the session number.
-
----
-
-## Pattern: debug-checkpoint
-
-3-option checkpoint response during debug investigation.
-
-```
-Use AskUserQuestion:
-  question: "Investigation has reached a checkpoint. How should we proceed?"
-  header: "Continue?"
-  options:
-    - label: "Continue"       description: "Keep investigating with current findings"
-    - label: "More info"      description: "I have additional context to share"
-    - label: "New approach"   description: "Try a different investigation angle"
-  multiSelect: false
-```

package/plugins/cursor-pbr/skills/shared/phase-argument-parsing.md

@@ -1,46 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/phase-argument-parsing.md -->
-# Phase Argument Parsing
-
-How skills parse and validate phase number arguments from `$ARGUMENTS`.
-
-## Parsing Rules
-
-1. **Integer phases**: `3` → Phase 3 (standard phase)
-2. **Decimal phases**: `3.1` → Phase 3.1 (inserted phase)
-3. **Zero-padded**: `03` → Phase 3 (strip leading zeros for display, keep for file paths)
-4. **No argument**: Use current phase from STATE.md
-
-## Normalization
-
-```
-Input       → Normalized  → Directory Name
-"3"         → 3           → 03-{slug}
-"03"        → 3           → 03-{slug}
-"3.1"       → 3.1         → 03.1-{slug}
-""          → (current)   → (read from STATE.md)
-```
-
-## Validation
-
-1. Phase number must be numeric (integer or decimal with one decimal place)
-2. Phase must exist in ROADMAP.md (or be a valid target for insert/add)
-3. Phase must be in the expected state for the operation:
-   - `/pbr:plan N` — phase must not already have plans (unless re-planning)
-   - `/pbr:build N` — phase must have plans
-   - `/pbr:review N` — phase must have been built (SUMMARY.md files exist)
-
-## Finding Phase Directory
-
-```
-Given phase number N:
-1. List directories in .planning/phases/
-2. Find directory matching pattern: {NN}-* or {N.M}-*
-3. If not found, check ROADMAP.md for phase name
-4. If still not found, error: "Phase N not found"
-```
-
-## Error Messages
-
-- No argument and no current phase: "Which phase? Specify a number or run /pbr:status to see where you are."
-- Phase not found: "Phase {N} not found in .planning/phases/. Run /pbr:status to see available phases."
-- Wrong state: "Phase {N} hasn't been planned yet. Run /pbr:plan {N} first."

package/plugins/cursor-pbr/skills/shared/progress-display.md

@@ -1,53 +0,0 @@
-# Progress Display Fragment
-
-Standard progress display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.
-
-## Progress Bar
-
-Always 20 characters wide using `█` (filled) and `░` (empty):
-
-```
-Progress: [████████████░░░░░░░░] 60%
-```
-
-Calculate: `filled = Math.round(percent / 5)`, `empty = 20 - filled`
-
-## Phase Table
-
-Use when displaying multiple phases (status, milestone skills):
-
-```
-| Phase | Name             | Status    | Plans | Progress |
-|-------|------------------|-----------|-------|----------|
-| 01    | Setup            | ✓ complete | 2/2   | 100%     |
-| 02    | Authentication   | ◐ building | 1/3   | 33%      |
-| 03    | Dashboard        | ○ pending  | 0/4   | 0%       |
-```
-
-## Status Indicators
-
-| Symbol | Meaning | When to use |
-|--------|---------|-------------|
-| `✓` | Complete | Phase/plan/task finished |
-| `✗` | Failed | Verification failed |
-| `○` | Pending | Not started |
-| `◐` | In Progress | Currently executing |
-| `?` | Needs Human | Checkpoint requiring user action |
-| `⚠` | Warning | Non-blocking issue |
-| `⊘` | Blocked | Waiting on dependency |
-
-## Wave Progress (build skill)
-
-```
-Wave 1: ✓ Plan 01, ✓ Plan 02
-Wave 2: ◐ Plan 03 (executing)
-Wave 3: ○ Plan 04, ○ Plan 05
-```
-
-## Compact Status Line
-
-For inline status updates:
-
-```
-Phase 3 of 8 (Auth) — building — [████████░░░░░░░░░░░░] 40%
-```

package/plugins/cursor-pbr/skills/shared/revision-loop.md

@@ -1,82 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/revision-loop.md -->
-# Revision Loop Pattern
-
-Standard pattern for iterative agent revision with feedback. Used when a checker/validator finds issues and the producing agent needs to revise its output.
-
-> Referenced by: plan, import, review skills
-
----
-
-## Pattern: Check-Revise-Escalate (max 3 iterations)
-
-This pattern applies whenever:
-1. An agent produces output (plans, imports, gap-closure plans)
-2. A checker/validator evaluates that output
-3. Issues are found that need revision
-
-### Flow
-
-```
-iteration = 0
-
-LOOP:
-  1. Run checker/validator on current output
-  2. Read checker results
-  3. If PASSED or only INFO-level issues:
-     → Accept output, exit loop
-  4. If BLOCKER or WARNING issues found:
-     a. iteration += 1
-     b. If iteration > 3:
-        → Escalate to user (see "After 3 Iterations" below)
-     c. Re-spawn the producing agent with checker feedback appended
-     d. After revision completes, go to LOOP
-```
-
-### Re-spawn Prompt Structure
-
-When re-spawning the producing agent for revision, append the checker feedback:
-
-```
-<checker_feedback>
-{Inline the checker's issue report}
-</checker_feedback>
-
-<revision_instructions>
-Address ALL BLOCKER and WARNING issues identified above.
-- For each BLOCKER: make the required change
-- For each WARNING: address or explain why it's acceptable
-- Do NOT introduce new issues while fixing existing ones
-- Preserve all content not flagged by the checker
-</revision_instructions>
-```
-
-### After 3 Iterations
-
-If issues persist after 3 revision cycles:
-
-1. Present remaining issues to the user
-2. Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
-   question: "Issues remain after 3 revision attempts. Proceed with current output?"
-   header: "Proceed?"
-   options:
-     - label: "Proceed anyway"   description: "Accept output with remaining issues"
-     - label: "Adjust approach"  description: "Discuss a different approach"
-3. If "Proceed anyway": accept current output and continue
-4. If "Adjust approach" or "Other": discuss with user, then re-enter the producing step with updated context
-
-### Skill-Specific Variations
-
-| Skill | Producer Agent | Checker Agent | Revision Template |
-|-------|---------------|---------------|-------------------|
-| plan | planner | plan-checker | `skills/plan/templates/revision-prompt.md.tmpl` |
-| import | inline (orchestrator) | plan-checker | Inline revision by orchestrator |
-| review (auto-fix) | planner (gap mode) | plan-checker | Same as plan |
-
----
-
-## Important Notes
-
-- **INFO-level issues are always acceptable** -- they don't trigger revision
-- **Each iteration gets a fresh agent spawn** -- don't try to continue in the same context
-- **Checker feedback must be inlined** -- the revision agent needs to see exactly what failed
-- **Don't silently swallow issues** -- always present the final state to the user after exiting the loop

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

@@ -1,63 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/state-loading.md -->
-# State Loading Pattern
-
-Standard pattern for loading project state at the start of a skill invocation. Include this fragment in skills that need project context.
-
----
-
-## Minimal State Read (for simple skills)
-
-Use when the skill only needs to know the current position. Skills: status, help, note, todo, pause, config.
-STATE.md is lean — it contains only current-phase context. Historical data lives in HISTORY.md.
-
-```
-1. Read .planning/STATE.md lines 1-20 only
-2. Extract: current phase, plan, status
-3. If STATE.md missing: inform user, suggest /pbr:begin
-```
-
-## Full State Read (for workflow skills)
-
-Use when the skill needs complete project context. Skills: build, plan, review, begin, milestone, continue, resume, debug.
-
-Reading order (always this sequence):
-
-```
-1. Read .planning/STATE.md
-   - Extract: Current Position section (phase, plan, status)
-   - Extract: Blockers/Concerns section (if not "None")
-   - Extract: Session Continuity section (if present)
-
-2. Read .planning/config.json
-   - Extract: depth, mode, features flags
-   - Extract: models configuration
-   - Extract: gates configuration
-
-3. Read .planning/ROADMAP.md (if exists)
-   - Extract: Phase Overview table (current + next 2 phases)
-   - Extract: dependency chain for current phase
-   - Do NOT read full phase details for past phases
-
-4. Read .planning/HISTORY.md (ONLY when cross-phase context is needed)
-   - Do NOT read HISTORY.md for normal build/plan/review operations
-   - Read ONLY when: debugging a regression that may trace to a prior phase,
-     or when a milestone audit needs historical context
-   - Use: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load`
-   - This returns structured JSON -- do not read the raw file
-```
-
-## Error Handling
-
-| File Missing | Action |
-|-------------|--------|
-| STATE.md | Warn user: "No STATE.md found. Run /pbr:begin to initialize." |
-| config.json | Use defaults (depth: standard, mode: interactive) |
-| ROADMAP.md | Continue without roadmap context (acceptable for quick tasks) |
-| .planning/ dir | Exit: "No .planning directory. This is not a Plan-Build-Run project." |
-
-## What NOT to Read During State Loading
-
-- Full SUMMARY.md bodies from prior phases (read frontmatter only if needed)
-- Agent definition files (agents/*.md) — auto-loaded by subagent_type
-- PLAN.md files from other phases (only current phase plans)
-- .planning/logs/ files (only health skill reads these)