@sienklogic/plan-build-run 2.53.0 → 2.55.0

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

@@ -0,0 +1,388 @@
+# 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/codex-pbr/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 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/codex-pbr/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/plugins/codex-pbr/skills/shared/state-update.md

@@ -0,0 +1,169 @@
+# STATE.md Update Pattern
+
+Standard pattern for updating `.planning/STATE.md`. Include this fragment in skills that modify project state.
+
+---
+
+**CRITICAL: STATE.md has TWO representations — YAML frontmatter AND markdown body. You MUST update BOTH when changing state. The status line reads frontmatter; humans and hooks read the body. If you only update frontmatter, the body goes stale and the status line shows wrong data. Do NOT skip body updates under any circumstances.**
+
+---
+
+## When to Update STATE.md
+
+| Event | What to Update |
+|-------|---------------|
+| Phase status changes (planned, building, verified) | Frontmatter fields AND Current Position section |
+| Plan completes or fails | Frontmatter fields AND Plan counter, status, last activity |
+| Phase advances to next phase | Frontmatter fields AND Phase line, Status, Last activity, Progress bar |
+| New decision made | Accumulated Context > Decisions |
+| Blocker discovered or resolved | Accumulated Context > Blockers/Concerns |
+| Session starts or ends | Session Continuity section |
+| Milestone boundary | Milestone section |
+
+---
+
+## 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)
+
+**CRITICAL: This section MUST match the frontmatter fields above it. When you update `current_phase` or `status` in frontmatter, you MUST also update the corresponding lines below. A hook will auto-fix drift, but do not rely on it.**
+
+```
+## 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 / total_phases) * 20)`
+
+### 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 CONTEXT.md** — avoid duplication between STATE.md and phase CONTEXT.md files
+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.md Archival
+
+When a milestone completes or a phase is verified, archive historical context to `.planning/HISTORY.md` to keep STATE.md lean:
+
+### What to Archive
+
+| Trigger | What moves to HISTORY.md |
+|---------|-------------------------|
+| 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 STATE.md) |
+
+### How to Archive
+
+Use `pbr-tools.js history append`:
+```
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "Phase 3 (Auth)" "Verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 User Auth" "Phases 1-4. All verified. Core auth flow complete."
+```
+
+### After Archiving
+
+Remove the archived content from STATE.md. The Accumulated Context section should contain ONLY:
+- Decisions relevant to the **current** phase
+- Active (unresolved) blockers
+- Pending todos for the current milestone
+
+Historical decisions live in HISTORY.md and per-phase SUMMARY.md files.
+
+---
+
+## Common Update Scenarios
+
+### After build completes
+```
+Plan: {N} of {total} in current phase
+Status: Building → Reviewing (if all plans done) or Building (if more plans remain)
+Last activity: {date} -- Built plan {plan_id}
+```
+
+### After review/verification passes
+```
+Status: Verified
+Last activity: {date} -- Phase {N} verified
+Progress: [{updated bar}] {new percent}%
+```
+Also update **Current focus** to point to the next phase.
+
+### After pause
+```
+## Session Continuity
+Last session: {timestamp}
+Stopped at: {what was in progress}
+Resume file: .planning/.pause-state.json
+```
+
+### After milestone completion
+```
+## Milestone
+Current: {project_name} {next_version}
+Phases: {new_start}-{new_end}
+Status: In progress
+```