@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/skills/plan/decimal-phase-calc.md

@@ -0,0 +1,98 @@
+# Decimal Phase Numbering
+
+Rules for calculating decimal phase numbers when inserting phases into an existing roadmap.
+
+---
+
+## Core Rule
+
+Inserted phases get decimal numbers based on their insertion position. The integer part indicates where in the sequence the phase falls, and the decimal part indicates it was inserted.
+
+---
+
+## Calculation
+
+### Insert at position N
+
+```
+1. Find phase N in the roadmap
+2. Check if N.1 already exists
+3. If not: new phase is N.1
+4. If yes: check N.2, N.3, etc. until an unused number is found
+```
+
+### Examples
+
+**Insert between Phase 3 and Phase 4:**
+```
+Before: Phase 1, Phase 2, Phase 3, Phase 4, Phase 5
+After:  Phase 1, Phase 2, Phase 3, Phase 3.1, Phase 4, Phase 5
+```
+
+**Insert another between Phase 3 and Phase 4:**
+```
+Before: Phase 1, Phase 2, Phase 3, Phase 3.1, Phase 4, Phase 5
+After:  Phase 1, Phase 2, Phase 3, Phase 3.1, Phase 3.2, Phase 4, Phase 5
+```
+
+**Insert between Phase 3.1 and Phase 3.2:**
+This is NOT supported. Maximum one level of decimal insertion. If you need to insert between decimal phases, renumber the entire sequence first.
+
+---
+
+## Directory Naming
+
+```
+Phase 3   → .planning/phases/03-{slug}/
+Phase 3.1 → .planning/phases/03.1-{slug}/
+Phase 3.2 → .planning/phases/03.2-{slug}/
+```
+
+---
+
+## Plan ID Format
+
+Plans in decimal phases use the decimal in their ID:
+
+```
+Phase 3.1, Plan 01 → Plan ID: 3.1-01
+Phase 3.1, Plan 02 → Plan ID: 3.1-02
+```
+
+---
+
+## Execution Order
+
+Decimal phases execute AFTER their integer parent and BEFORE the next integer:
+
+```
+Execution order: 1, 2, 3, 3.1, 3.2, 4, 5
+```
+
+Dependencies:
+- Decimal phases inherit the dependencies of their integer parent by default
+- Additional dependencies can be declared explicitly
+- A decimal phase at N.M depends on phase N unless overridden
+
+---
+
+## Renumbering After Remove
+
+When a phase is removed, subsequent phases are renumbered:
+
+```
+Before: Phase 1, Phase 2, Phase 3, Phase 3.1, Phase 4
+Remove Phase 2:
+After:  Phase 1, Phase 2 (was 3), Phase 2.1 (was 3.1), Phase 3 (was 4)
+```
+
+All internal references (depends_on, plan IDs, directory names) must be updated during renumbering.
+
+---
+
+## Constraints
+
+1. Maximum one level of decimal numbering (no 3.1.1)
+2. Decimal part is always a single digit (3.1 through 3.9)
+3. Maximum 9 insertions at any position (3.1 through 3.9)
+4. If 9 insertions are needed, renumber the entire roadmap instead

package/plugins/pbr/skills/plan/templates/checker-prompt.md.tmpl

@@ -0,0 +1,21 @@
+<!-- Source: plan/SKILL.md | Purpose: Prompt template for spawning plan checker agent -->
+<!-- Depends on: templates/prompt-partials/phase-project-context.md.tmpl -->
+
+You are the plan-checker agent.
+
+<plans_to_check>
+Read and check each of these plan files:
+
+| Plan | File Path |
+|------|-----------|
+{For each PLAN.md file in .planning/phases/{NN}-{slug}/:}
+| {plan_id} | {absolute path to PLAN.md} |
+
+Read each plan file using the Read tool. Verify all 7 dimensions against each plan.
+</plans_to_check>
+
+<!-- Context blocks: Read and fill templates/prompt-partials/phase-project-context.md.tmpl -->
+<!-- Omit <prior_work> -- checker only needs plans and context -->
+
+Run all 7 verification dimensions on these plans. Return your structured report.
+Do NOT write any files. Return your findings as your response text.

package/plugins/pbr/skills/plan/templates/gap-closure-prompt.md.tmpl

@@ -0,0 +1,32 @@
+<!-- Source: plan/SKILL.md | Purpose: Prompt template for planner gap closure mode -->
+
+You are the planner agent operating in Gap Closure mode.
+
+<verification_report>
+Read the verification report for gap details:
+File: {absolute path to VERIFICATION.md}
+</verification_report>
+
+<existing_plans>
+Read existing plans for context on what was already built:
+
+| Plan | File Path |
+|------|-----------|
+{For each PLAN.md in the phase directory:}
+| {plan_id} | {absolute path to PLAN.md} |
+</existing_plans>
+
+<project_context>
+{If CONTEXT.md exists:}
+Project context (locked decisions, constraints): {absolute path to CONTEXT.md}
+Read this file for locked decisions that must be honored in gap-closure plans.
+{If not: "No CONTEXT.md found."}
+</project_context>
+
+<gap_closure_instructions>
+Read the verification report and create targeted plans to close each gap.
+Follow your Gap Closure Mode instructions.
+Number new plans starting after the last existing plan number.
+Set gap_closure: true in the frontmatter of each new plan.
+Write gap-closure plan files to: .planning/phases/{NN}-{slug}/
+</gap_closure_instructions>

package/plugins/pbr/skills/plan/templates/planner-prompt.md.tmpl

@@ -0,0 +1,38 @@
+<!-- Source: plan/SKILL.md | Purpose: Prompt template for spawning planner agent during phase planning -->
+<!-- Depends on: templates/prompt-partials/phase-project-context.md.tmpl -->
+
+You are the planner agent operating in Standard Planning mode.
+
+<!-- Context blocks: Read and fill templates/prompt-partials/phase-project-context.md.tmpl -->
+<!-- Include all 3 blocks: phase_context, project_context, prior_work -->
+
+<research>
+{If RESEARCH.md exists:}
+Phase research available at: {absolute path to RESEARCH.md}
+Read this file for technology recommendations, implementation patterns, and pitfalls.
+{If not: "No phase-specific research conducted."}
+{If research SUMMARY.md exists:}
+Research summary available at: {absolute path to research SUMMARY.md}
+</research>
+
+<config>
+Max tasks per plan: {from config.json}
+Parallelization enabled: {from config.json}
+TDD mode: {from config.json}
+</config>
+
+<planning_instructions>
+Create executable plans for this phase following your Standard Planning mode instructions.
+
+Key rules:
+1. Apply goal-backward methodology — derive must-haves first
+2. 2-3 tasks per plan, 5-8 files per plan maximum
+3. Assign wave numbers for parallel execution
+4. Every task needs all 5 elements: name, files, action, verify, done
+5. Honor all locked decisions from CONTEXT.md
+6. Do NOT include deferred ideas
+7. Write plan files to: .planning/phases/{NN}-{slug}/{phase}-{plan_num}-PLAN.md
+8. If any task requires env vars, API keys, or external service setup, note it in the task's <action> — the executor will generate USER-SETUP.md automatically
+
+Use the Write tool to create each plan file.
+</planning_instructions>

package/plugins/pbr/skills/plan/templates/researcher-prompt.md.tmpl

@@ -0,0 +1,19 @@
+<!-- Source: plan/SKILL.md | Purpose: Prompt template for spawning researcher agent during phase planning -->
+<!-- Depends on: templates/prompt-partials/phase-project-context.md.tmpl -->
+
+You are the researcher agent operating in Phase Research mode.
+
+<!-- Context blocks: Read and fill templates/prompt-partials/phase-project-context.md.tmpl -->
+<!-- Include the filled <phase_context> and <project_context> blocks here. -->
+<!-- Omit <prior_work> and deferred ideas -- researcher doesn't need them -->
+
+<research_questions>
+Research these specific questions for this phase:
+1. What is the best implementation approach for {phase goal}?
+2. What libraries/packages are needed?
+3. What are the common pitfalls for this type of work?
+4. What configuration is needed?
+5. How does this integrate with what's already been built?
+</research_questions>
+
+Write your findings to .planning/phases/{NN}-{slug}/RESEARCH.md using the Phase Research output format. Use the Write tool.

package/plugins/pbr/skills/plan/templates/revision-prompt.md.tmpl

@@ -0,0 +1,23 @@
+<!-- Source: plan/SKILL.md | Purpose: Prompt template for planner revision mode when checker finds issues -->
+
+You are the planner agent operating in Revision Mode.
+
+<original_plans>
+Read the current plan files that need revision:
+
+| Plan | File Path |
+|------|-----------|
+{For each PLAN.md in the phase directory:}
+| {plan_id} | {absolute path to PLAN.md} |
+
+Read each plan file using the Read tool before revising.
+</original_plans>
+
+<checker_feedback>
+[Inline the checker's issue report]
+</checker_feedback>
+
+<revision_instructions>
+Revise the plans to address all BLOCKER and WARNING issues. Follow your Revision Mode instructions.
+Preserve task IDs that don't need changes. Write updated plan files to the same paths.
+</revision_instructions>

package/plugins/pbr/skills/quick/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: quick
+description: "Execute an ad-hoc task with atomic commits. Skips full plan/review."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion
+---
+
+# /pbr:quick — Quick Ad-Hoc Task Execution
+
+You are running the **quick** skill. Your job is to execute a small, self-contained task outside the normal plan/build/review cycle. Quick tasks get their own tracking, atomic commits, and state integration, but skip the overhead of full planning.
+
+This skill **spawns a single Task(subagent_type: "pbr:executor")** for execution.
+
+---
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- **Never** implement the task yourself — you are a router, not a builder. ALL code changes go through a spawned `Task(subagent_type: "pbr:executor")`
+- **Never** skip creating `.planning/quick/{NNN}-{slug}/` and writing PLAN.md — even trivial tasks need tracking artifacts
+- **Minimize** reading executor output into main context — read only SUMMARY.md frontmatter
+
+## Core Principle
+
+**Quick tasks are for small, well-defined work.** If the user describes something that would take more than 3-5 tasks or touches multiple subsystems, suggest using the full plan/build cycle instead.
+
+---
+
+## Flow
+
+### Step 1: Check Project Context
+
+1. Check if `.planning/` directory exists
+   - If yes: read config.json for settings
+   - If no: warn "No Plan-Build-Run project found. This will create a standalone quick task. Consider running `/pbr:begin` first for full project tracking."
+
+2. Write `.planning/.active-skill` with the content `quick` (single word, no newline). This registers you with the workflow enforcement hook — it will block source code writes until PLAN.md exists.
+
+3. Check if ROADMAP.md exists
+   - If yes: note the current phase context (quick tasks may relate to the active phase)
+   - If no: proceed without phase context
+
+### Step 2: Get Task Description
+
+If `$ARGUMENTS` is provided and non-empty:
+- Use `$ARGUMENTS` as the task description
+
+If `$ARGUMENTS` is empty:
+- Ask the user: "What do you need done? Describe the task in a sentence or two."
+  This is a freeform text prompt — do NOT use AskUserQuestion here. Task descriptions require arbitrary text input, not option selection.
+
+### Step 3: Validate Scope
+
+Analyze the task description. If it appears to involve:
+- More than ~5 files
+- Multiple independent subsystems
+- Significant architectural decisions
+- Complex multi-step workflows
+
+Then use the **scope-confirm** pattern (see `skills/shared/gate-prompts.md`):
+
+Use AskUserQuestion:
+  question: "This task looks complex. Quick tasks work best for bug fixes, small features, config changes, and single-module refactors. How would you like to proceed?"
+  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
+
+If user selects "Quick task": continue to Step 4.
+If user selects "Full plan": respond "Use `/pbr:plan` to create a full planning cycle for this task." and stop.
+If user selects "Revise": go back to Step 2 to get a new task description.
+If user types something else (freeform): interpret their response and proceed accordingly.
+
+### Step 4: Generate Slug and Task Number
+
+**Generate slug:**
+- Take the first 4-5 meaningful words from the description
+- Lowercase, hyphen-separated
+- Remove articles (a, an, the) and prepositions
+- Example: "Fix auth bug in login flow" -> "fix-auth-bug-login"
+
+**Find next task number:**
+1. Scan `.planning/quick/` directory for existing quick task directories
+2. Extract the NNN prefix from directory names (pattern: `{NNN}-{slug}/`)
+3. Next number = highest existing NNN + 1
+4. If no existing tasks: start at 001
+5. Zero-pad to 3 digits
+
+### Step 5: Create Quick Task Directory
+
+Create: `.planning/quick/{NNN}-{slug}/`
+
+### Step 6: Create Minimal PLAN.md
+
+Write `.planning/quick/{NNN}-{slug}/PLAN.md`:
+
+Read `references/plan-format.md` for the plan file format. Fill in all `{variable}` placeholders with actual task data from the user's description and project context.
+
+**Plan generation rules:**
+- Break the task into 1-3 tasks maximum (prefer fewer)
+- Each task should be atomic (one commit per task)
+- Infer file paths from the description and project context
+- Include concrete verification commands
+- If verification is unclear, use `echo "Manual verification needed"` and add a note
+
+**For multi-task quick tasks**, add sequential tasks:
+
+```markdown
+<task name="{task 1}" type="auto">
+...
+</task>
+
+<task name="{task 2}" type="auto">
+...
+</task>
+```
+
+**PLANNING GATE — verify before spawning executor:**
+
+Before proceeding to Step 7, confirm these exist on disk:
+1. `.planning/quick/{NNN}-{slug}/` directory exists
+2. `.planning/quick/{NNN}-{slug}/PLAN.md` exists, is non-empty, and contains at least one `<task>` block
+
+If either check fails, you have skipped steps. Go back and complete Steps 4-6. Do NOT proceed to spawning an executor.
+
+### Step 7: Spawn Executor
+
+**Pre-spawn check** — Verify `.planning/quick/{NNN}-{slug}/PLAN.md` exists and contains at least one `<task>` block. If missing, STOP and complete Steps 4-6 first.
+
+Display to the user: `◐ Spawning executor...`
+
+Spawn a `Task(subagent_type: "pbr:executor")` with the following prompt:
+
+```
+You are executor. Execute the following quick task plan.
+
+Plan file: .planning/quick/{NNN}-{slug}/PLAN.md
+Phase: quick
+Plan ID: {NNN}
+
+Read the plan file and execute all tasks sequentially. Follow all executor protocols:
+- Atomic commits per task
+- Commit format: fix(quick-{NNN}): {description} (or feat/refactor/test as appropriate)
+- Run verify commands
+- Create SUMMARY.md at .planning/quick/{NNN}-{slug}/SUMMARY.md
+
+Execute now.
+```
+
+### Step 8: Read Results
+
+After the executor completes:
+1. Read `.planning/quick/{NNN}-{slug}/SUMMARY.md`
+2. Check the status field:
+   - `completed` — task succeeded
+   - `partial` — some tasks completed, others failed
+   - `failed` — task failed entirely
+
+### Step 9: Update STATE.md
+
+If STATE.md exists, update the Quick Tasks section.
+
+**If the section doesn't exist, create it:**
+
+```markdown
+### Quick Tasks
+
+| # | Description | Status | Commit |
+|---|-------------|--------|--------|
+```
+
+**Add the new entry:**
+
+```markdown
+| {NNN} | {description} | {status indicator} | {commit hash or "N/A"} |
+```
+
+Status indicators:
+- Completed: checkmark
+- Partial: warning indicator
+- Failed: X indicator
+
+### Step 10: Commit Planning Docs
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `planning.commit_docs: true` in config.json:
+- Stage the quick task directory files (PLAN.md, SUMMARY.md)
+- Stage STATE.md changes
+- Commit: `docs(planning): quick task {NNN} - {slug}`
+
+### Step 11: Report Results
+
+**Artifact check** — Before reporting, verify all required artifacts exist:
+1. `.planning/quick/{NNN}-{slug}/PLAN.md` exists
+2. `.planning/quick/{NNN}-{slug}/SUMMARY.md` exists and is non-empty
+3. STATE.md contains a quick task entry for {NNN} (if STATE.md exists)
+
+If SUMMARY.md is missing: the executor may have failed — re-read executor output and report the failure.
+If STATE.md entry is missing: write it now (Step 9 was skipped).
+
+Display results to the user with branded output:
+
+**If completed:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► QUICK TASK COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Quick Task {NNN}:** {description}
+Commit: {hash} — {commit message}
+Files: {list of files changed}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Continue your workflow** — task complete
+
+`/pbr:status`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:continue` — execute next logical step
+- `/pbr:todo list` — see pending todos
+
+───────────────────────────────────────────────────────────────
+```
+
+**If partial:**
+```
+⚠ Quick Task {NNN}: {description}
+Completed: {N} of {M} tasks
+Failed task: {task name} — {failure reason}
+
+→ Re-run with `/pbr:quick` to retry
+→ `/pbr:debug` to investigate the failure
+```
+
+**If failed:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Quick Task {NNN} failed: {failure details}
+
+**To fix:** {what to try next}
+```
+
+---
+
+## Quick Task Plan Generation
+
+### Inferring File Paths
+
+When the user describes a task, infer file paths from:
+1. The project structure (use Glob to find existing files matching keywords)
+2. The tech stack (from prior SUMMARY.md files or package.json/requirements.txt)
+3. Naming conventions in the codebase
+4. Explicit file mentions in the description
+
+### Inferring Verification
+
+Choose verification based on context:
+
+| Context | Verification Command |
+|---------|---------------------|
+| TypeScript project | `npx tsc --noEmit` |
+| Has test files | `npm test` or `pytest` |
+| Has ESLint | `npx eslint {files}` |
+| Python project | `python -c "import {module}"` |
+| Config change | `cat {file}` to verify content |
+| Script | Run the script with safe args |
+| Unknown | `echo "Manual verification needed"` |
+
+### Commit Type Selection
+
+| Task Nature | Commit Type |
+|-------------|-------------|
+| Bug fix | `fix` |
+| New feature/functionality | `feat` |
+| Code restructuring | `refactor` |
+| Adding tests | `test` |
+| Config/tooling changes | `chore` |
+| Documentation | `docs` |
+
+---
+
+## Edge Cases
+
+### No `.planning/` directory
+- Create `.planning/quick/` directory
+- Proceed without STATE.md integration
+- Warn user about limited tracking
+
+### Executor fails entirely
+- Read error output
+- Present to user with suggestion
+- Do NOT auto-retry — let the user decide
+
+### Task description is too vague
+- Ask clarifying questions as plain text prompts (do NOT use AskUserQuestion — these require freeform text answers):
+  - "Which file(s) need to change?"
+  - "What should the end result look like?"
+  - "Is there a specific error to fix?"
+
+### User provides a file path in the description
+- Use it directly in the plan
+- Read the file first to understand its context
+- Tailor the plan to the specific file
+
+---
+
+## Anti-Patterns
+
+**These are the most common failure modes. If you violate any of these, the skill has not executed correctly.**
+
+1. **DO NOT** implement the task yourself — you MUST spawn a `Task(subagent_type: "pbr:executor")`. This is the single most important rule.
+2. **DO NOT** skip creating `.planning/quick/{NNN}-{slug}/` — every quick task gets a tracking directory
+3. **DO NOT** skip writing PLAN.md — the executor needs a plan file to follow
+4. **DO NOT** create elaborate multi-wave plans — quick tasks should be 1-3 tasks max
+5. **DO NOT** spawn multiple executors — one executor for the whole quick task
+6. **DO NOT** skip the SUMMARY.md — even quick tasks need documentation
+7. **DO NOT** use `git add .` — stage specific files only
+8. **DO NOT** skip verification — every task needs a verify step
+9. **DO NOT** create a quick task for something that needs planning — suggest `/pbr:plan`
+10. **DO NOT** modify STATE.md if it doesn't exist (other than warning)
+11. **DO NOT** break the numbering sequence — always find the next number