@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plan-build-run/skills/shared/gate-prompts.md

@@ -0,0 +1,390 @@
+# 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.
+
+**For checkpoint box format details, see `@references/ui-brand.md`** — checkpoint boxes use double-line border drawing with 62-character inner width. All gate types (approval, decision, information) should use the standardized checkpoint box format from ui-brand.md when presenting user-facing decision points.
+
+## 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-phase 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-phase 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/plan-build-run/skills/shared/phase-argument-parsing.md

@@ -0,0 +1,45 @@
+# 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-phase N` — phase must not already have plans (unless re-planning)
+   - `/pbr:execute-phase N` — phase must have plans
+   - `/pbr:verify-work 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-phase {N} first."

package/plan-build-run/skills/shared/revision-loop.md

@@ -0,0 +1,81 @@
+# 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/plan-build-run/skills/shared/state-update.md

@@ -0,0 +1,154 @@
+# STATE.md Update Pattern
+
+Standard pattern for updating `.planning/STATE.md`. CLI commands handle both YAML frontmatter and markdown body atomically. Skills and agents call `pbr-tools.cjs` commands instead of writing STATE.md directly.
+
+> Referenced by: build, plan, review, milestone, pause, resume, continue, begin, import, quick skills
+
+---
+
+## CLI Command Reference
+
+All commands use: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command>`
+
+| Action | CLI Command | What It Updates |
+|--------|------------|-----------------|
+| Update single field | `state update <field> <value>` | Frontmatter field + body line |
+| Update multiple fields | `state patch '{"field":"value",...}'` | Multiple frontmatter fields + body lines atomically |
+| Advance plan counter | `state advance-plan` | `plans_complete` + `progress_percent` in frontmatter and body |
+| Recalculate progress | `state update-progress` | `progress_percent` from disk (counts plans vs summaries) |
+| Complete a phase | `phase complete <N>` | STATE.md (advance phase, reset plans) + ROADMAP.md (checkbox, table) |
+| Record activity | `state record-activity "<desc>"` | `last_activity` with today's date + description |
+| Load full state | `state load` | Returns JSON -- does not write |
+
+---
+
+## When to Use Each Command
+
+| Event | CLI Command |
+|-------|------------|
+| Plan completes | `state advance-plan` then `state update-progress` |
+| Phase status changes | `state update status <value>` |
+| Phase fully built and verified | `phase complete <N>` |
+| After any state mutation | `state record-activity "<what happened>"` |
+| Session starts (read only) | `state load` |
+| New decision made | Edit STATE.md "Accumulated Context > Decisions" section directly (CLI does not manage this section) |
+| Blocker discovered | Edit STATE.md "Accumulated Context > Blockers" section directly |
+
+---
+
+## Section Format
+
+STATE.md has 5 sections. Always preserve this order:
+
+### 1. Project Reference (lines 4-7)
+```
+## Project Reference
+See: .planning/PROJECT.md (updated {date})
+**Core value:** {one-liner from PROJECT.md}
+**Current focus:** Phase {N} - {name}
+```
+Update `Current focus` when phase changes.
+
+### 2. Current Position (lines 9-14)
+```
+## Current Position
+Phase: {N} of {total} ({Phase name})
+Plan: {completed} of {total_plans} in current phase
+Status: {Ready to plan | Planning | Building | Reviewing | Verified}
+Last activity: {YYYY-MM-DD} -- {brief description}
+Progress: [{progress_bar}] {percent}%
+```
+
+**Progress bar format:** 20 characters using `█` (done) and `░` (remaining).
+```
+Phase 3 of 10 = 20% → [████░░░░░░░░░░░░░░░░] 20%
+Phase 7 of 10 = 70% → [██████████████░░░░░░] 70%
+```
+Calculation: `filled = Math.round((completed_phases / phase_count) * 20)` where `phase_count` is derived from ROADMAP.md (available via `stateLoad` as `phase_count`)
+
+### 3. Accumulated Context (lines 16-25)
+```
+## Accumulated Context
+
+### Decisions
+{Active decisions relevant to current work}
+
+### Pending Todos
+{Outstanding items, or "None"}
+
+### Blockers/Concerns
+{Active blockers, or "None"}
+```
+
+### 4. Milestone (lines 27-30)
+```
+## Milestone
+Current: {project_name} {version}
+Phases: {start}-{end}
+Status: {In progress | Complete}
+```
+
+### 5. Session Continuity (lines 32-35)
+```
+## Session Continuity
+Last session: {ISO timestamp}
+Stopped at: {brief description of last action}
+Resume file: {path or "None"}
+```
+
+---
+
+## Size Limit Enforcement
+
+**Hard limit: 150 lines.** After every STATE.md write, check the line count. If over 150 lines, compact:
+
+1. **Collapse completed phase entries** to one-liners:
+   ```
+   Phase 1: verified 2026-02-08
+   Phase 2: verified 2026-02-09
+   ```
+2. **Remove decisions already captured in phase CONTEXT.md files** -- avoid duplication between STATE.md and phase-level CONTEXT.md
+3. **Remove old session entries** -- keep only the current session's continuity data
+4. **Keep these always:** current phase detail, active blockers, core value statement, milestone info
+
+If still over 150 lines after compaction, the Accumulated Context section has grown too large. Move non-critical decisions to the phase's CONTEXT.md file.
+
+---
+
+## History Archival
+
+When a milestone completes or a phase is verified, archive historical context to the STATE.md ## History section to keep the Accumulated Context section lean:
+
+### What to Archive
+
+| Trigger | What moves to STATE.md ## History |
+|---------|----------------------------------|
+| Phase verified | One-liner summary: "Phase {N} ({name}): verified {date}" |
+| Milestone complete | Full milestone record: name, phases covered, key decisions |
+| Accumulated Context > 20 lines | Decisions from completed phases (keep only current-phase decisions in Accumulated Context) |
+
+### How to Archive
+
+Use `pbr-tools.cjs` to append to STATE.md ## History:
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-activity "Phase 3 (Auth): verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
+```
+
+### After Archiving
+
+Remove the archived content from the Accumulated Context section. It should contain ONLY:
+
+- Decisions relevant to the **current** phase
+- Active (unresolved) blockers
+- Pending todos for the current milestone
+
+Historical decisions live in STATE.md ## History and per-phase SUMMARY.md files.
+
+---
+
+## Anti-Pattern
+
+> **DO NOT** use Write or Edit to modify STATE.md frontmatter or the Current Position body section.
+> Always use CLI commands. They ensure frontmatter and body stay in sync.
+> **Exception:** Accumulated Context sections (Decisions, Blockers, Todos) are edited directly since they are freeform text.