@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/commands/pbr/add-phase.md

@@ -0,0 +1,75 @@
+---
+description: "Add phase to end of current milestone in roadmap"
+argument-hint: "<description>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- STATE.md roadmap evolution tracking
+</objective>
+
+<context>
+Description: $ARGUMENTS
+
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</context>
+
+<process>
+## 1. Parse Arguments
+
+Extract phase description from $ARGUMENTS. If empty, ask user for a description.
+
+## 2. Validate State
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs roadmap analyze
+```
+
+Check that ROADMAP.md exists and has at least one milestone.
+
+## 3. Calculate Next Phase Number
+
+Read ROADMAP.md, find the highest integer phase number in the current milestone, add 1.
+
+## 4. Generate Slug
+
+```bash
+SLUG=$(node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs generate-slug "$ARGUMENTS")
+```
+
+## 5. Create Phase Directory and Update Roadmap
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs roadmap append-phase --goal "$ARGUMENTS"
+```
+
+Create `.planning/phases/{NN}-{slug}/` directory.
+
+## 6. Update State
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs state record-activity "Added phase {NN}: {description}"
+```
+
+## 7. Commit
+
+```bash
+git add .planning/ROADMAP.md .planning/STATE.md .planning/phases/
+git commit -m "docs: add phase {NN} — {slug}"
+```
+
+## 8. Report
+
+Display: "Phase {NN}: {description} added to roadmap."
+Suggest: `/pbr:discuss-phase {NN}` or `/pbr:plan-phase {NN}` as next steps.
+</process>

package/commands/pbr/add-todo.md

@@ -0,0 +1,8 @@
+---
+description: "Capture idea or task as todo from current conversation context"
+argument-hint: "[optional description]"
+---
+
+This command is provided by the `pbr:todo` skill with subcommand `add`.
+
+Pass arguments as: `add $ARGUMENTS`

package/commands/pbr/audit-milestone.md

@@ -0,0 +1,8 @@
+---
+description: "Audit milestone completion against original intent before archiving"
+argument-hint: "[version]"
+---
+
+This command is provided by the `pbr:milestone` skill with subcommand `audit`.
+
+Pass arguments as: `audit $ARGUMENTS`

package/commands/pbr/audit.md

@@ -0,0 +1,5 @@
+---
+description: "Review past Claude Code sessions for PBR workflow compliance and UX quality."
+---
+
+This command is provided by the `pbr:audit` skill.

package/commands/pbr/check-todos.md

@@ -0,0 +1,8 @@
+---
+description: "List pending todos and select one to work on"
+argument-hint: "[area filter]"
+---
+
+This command is provided by the `pbr:todo` skill with subcommand `list`.
+
+Pass arguments as: `list $ARGUMENTS`

package/commands/pbr/complete-milestone.md

@@ -0,0 +1,8 @@
+---
+description: "Archive completed milestone and prepare for next version"
+argument-hint: "<version>"
+---
+
+This command is provided by the `pbr:milestone` skill with subcommand `complete`.
+
+Pass arguments as: `complete $ARGUMENTS`

package/commands/pbr/config.md

@@ -0,0 +1,5 @@
+---
+description: "View or modify Plan-Build-Run project settings (models, gates, features)."
+---
+
+This command is provided by the `pbr:config` skill.

package/commands/pbr/continue.md

@@ -0,0 +1,5 @@
+---
+description: "Execute the next logical step automatically. No prompts, no decisions — just do it."
+---
+
+This command is provided by the `pbr:continue` skill.

package/commands/pbr/dashboard.md

@@ -0,0 +1,5 @@
+---
+description: "Launch the PBR web dashboard for the current project."
+---
+
+This command is provided by the `pbr:dashboard` skill.

package/commands/pbr/debug.md

@@ -0,0 +1,5 @@
+---
+description: "Systematic debugging with hypothesis testing. Persistent across sessions."
+---
+
+This command is provided by the `pbr:debug` skill.

package/commands/pbr/discuss-phase.md

@@ -0,0 +1,6 @@
+---
+description: "Gather phase context through adaptive questioning before planning"
+argument-hint: "<phase>"
+---
+
+This command is provided by the `pbr:discuss` skill.

package/commands/pbr/do.md

@@ -0,0 +1,5 @@
+---
+description: "Route freeform text to the right PBR skill automatically."
+---
+
+This command is provided by the `pbr:do` skill.

package/commands/pbr/execute-phase.md

@@ -0,0 +1,6 @@
+---
+description: "Execute all plans in a phase with wave-based parallelization"
+argument-hint: "<phase-number> [--gaps-only]"
+---
+
+This command is provided by the `pbr:build` skill.

package/commands/pbr/explore.md

@@ -0,0 +1,5 @@
+---
+description: "Explore ideas, think through approaches, and route insights to the right artifacts."
+---
+
+This command is provided by the `pbr:explore` skill.

package/commands/pbr/health.md

@@ -0,0 +1,5 @@
+---
+description: "Check planning directory integrity. Find and fix corrupted state."
+---
+
+This command is provided by the `pbr:health` skill.

package/commands/pbr/help.md

@@ -0,0 +1,5 @@
+---
+description: "Command reference and workflow guide for Plan-Build-Run."
+---
+
+This command is provided by the `pbr:help` skill.

package/commands/pbr/import.md

@@ -0,0 +1,5 @@
+---
+description: "Import an external plan document. Validates against project context, detects conflicts, and generates PLAN.md files."
+---
+
+This command is provided by the `pbr:import` skill.

package/commands/pbr/insert-phase.md

@@ -0,0 +1,65 @@
+---
+description: "Insert urgent work as decimal phase (e.g., 72.1) between existing phases"
+argument-hint: "<after> <description>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+
+Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+
+Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS (format: <after-phase-number> <description>)
+
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</context>
+
+<process>
+## 1. Parse Arguments
+
+Extract after-phase-number and description from $ARGUMENTS. Error if either is missing.
+
+## 2. Calculate Decimal Phase Number
+
+Find existing decimal phases after the target number to determine next available decimal (e.g., if 3.1 exists, use 3.2).
+
+## 3. Generate Slug
+
+```bash
+SLUG=$(node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs generate-slug "{description}")
+```
+
+## 4. Create Phase
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs roadmap insert-phase {after} --goal "{description}"
+```
+
+Create `.planning/phases/{NN.D}-{slug}/` directory.
+
+## 5. Update State
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs state record-activity "Inserted phase {NN.D}: {description}"
+```
+
+## 6. Commit
+
+```bash
+git add .planning/
+git commit -m "docs: insert phase {NN.D} — {slug}"
+```
+
+## 7. Report
+
+Display: "Phase {NN.D}: {description} inserted after phase {NN}."
+Suggest: `/pbr:plan-phase {NN.D}` as next step.
+</process>

package/commands/pbr/join-discord.md

@@ -0,0 +1,11 @@
+---
+description: "Join the PBR Discord community"
+---
+
+# Join the PBR Discord
+
+Connect with other Plan-Build-Run users, get help, share what you're building, and stay updated.
+
+**Invite link:** https://discord.gg/5JJgD5svVS
+
+Click the link or paste it into your browser to join.

package/commands/pbr/list-phase-assumptions.md

@@ -0,0 +1,69 @@
+---
+description: "Surface Claude's assumptions about a phase approach before planning"
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+Purpose: Help users see what Claude thinks BEFORE planning begins — enabling course correction early when assumptions are wrong.
+Output: Conversational output only (no file creation) — ends with "What do you think?" prompt.
+</objective>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+## 1. Validate Phase
+
+```bash
+PHASE_INFO=$(node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs roadmap get-phase "$ARGUMENTS")
+```
+
+Error if phase not found.
+
+## 2. Gather Context
+
+Read:
+- Phase goal and description from ROADMAP.md
+- Research files if they exist (`.planning/phases/{NN}-*/RESEARCH.md`)
+- Requirements mapped to this phase
+- Prior phase decisions from STATE.md
+
+## 3. Surface Assumptions
+
+Present assumptions across five areas:
+
+### Technical Approach
+What libraries, patterns, and architecture you'd use.
+
+### Implementation Order
+What you'd build first and why.
+
+### Scope Boundaries
+What's included vs what you'd deliberately exclude.
+
+### Risk Areas
+What could go wrong and what's uncertain.
+
+### Dependencies
+What this phase needs from prior phases and what it provides to later ones.
+
+## 4. Invite Feedback
+
+End with: "What do you think? Any of these assumptions wrong?"
+
+Offer next steps:
+- `/pbr:discuss-phase {N}` — discuss context before planning
+- `/pbr:plan-phase {N}` — proceed to planning
+- Correct specific assumptions here
+</process>

package/commands/pbr/map-codebase.md

@@ -0,0 +1,6 @@
+---
+description: "Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents"
+argument-hint: "[optional: specific area to map]"
+---
+
+This command is provided by the `pbr:scan` skill.

package/commands/pbr/new-milestone.md

@@ -0,0 +1,8 @@
+---
+description: "Start a new milestone cycle — update PROJECT.md and route to requirements"
+argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
+---
+
+This command is provided by the `pbr:milestone` skill with subcommand `new`.
+
+Pass arguments as: `new $ARGUMENTS`

package/commands/pbr/new-project.md

@@ -0,0 +1,6 @@
+---
+description: "Initialize a new project with deep context gathering and PROJECT.md"
+argument-hint: "[--auto]"
+---
+
+This command is provided by the `pbr:begin` skill.

package/commands/pbr/note.md

@@ -0,0 +1,5 @@
+---
+description: "Zero-friction idea capture. Append, list, or promote notes to todos."
+---
+
+This command is provided by the `pbr:note` skill.

package/commands/pbr/pause-work.md

@@ -0,0 +1,5 @@
+---
+description: "Create context handoff when pausing work mid-phase"
+---
+
+This command is provided by the `pbr:pause` skill.

package/commands/pbr/plan-milestone-gaps.md

@@ -0,0 +1,7 @@
+---
+description: "Create phases to close all gaps identified by milestone audit"
+---
+
+This command is provided by the `pbr:milestone` skill with subcommand `gaps`.
+
+Pass arguments as: `gaps`

package/commands/pbr/plan-phase.md

@@ -0,0 +1,6 @@
+---
+description: "Create detailed execution plan for a phase (PLAN.md) with verification loop"
+argument-hint: "[phase] [--research] [--skip-research] [--gaps] [--skip-verify]"
+---
+
+This command is provided by the `pbr:plan` skill.

package/commands/pbr/progress.md

@@ -0,0 +1,6 @@
+---
+description: "Check project progress, show context, and route to next action"
+argument-hint: "[--next]"
+---
+
+This command is provided by the `pbr:status` skill.

package/commands/pbr/quick.md

@@ -0,0 +1,5 @@
+---
+description: "Execute a quick ad-hoc task. Atomic commits + state tracking, skips full plan/review cycle."
+---
+
+This command is provided by the `pbr:quick` skill.

package/commands/pbr/reapply-patches.md

@@ -0,0 +1,40 @@
+---
+description: "Reapply local modifications after a PBR update"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<objective>
+After a PBR update wipes and reinstalls files, merge user's previously saved local modifications back into the new version. Uses intelligent comparison to handle cases where the upstream file also changed.
+</objective>
+
+<process>
+## 1. Detect Backed-up Patches
+
+```bash
+PATCHES_DIR="${HOME}/.claude/pbr-local-patches"
+if [ ! -d "$PATCHES_DIR" ]; then
+  PATCHES_DIR="./.claude/pbr-local-patches"
+fi
+```
+
+Read `backup-meta.json` from the patches directory.
+If no patches found: "No local patches found. Nothing to reapply." Exit.
+
+## 2. Show Patch Summary
+
+List all backed-up files with status.
+
+## 3. Merge Each File
+
+For each file in backup-meta.json:
+1. Read backed-up version (user's modified copy)
+2. Read newly installed version (current file after update)
+3. Compare and merge:
+   - Identical: skip (modification incorporated upstream)
+   - Different: identify user modifications, apply to new version
+   - Conflict: show both versions, ask user which to keep
+
+## 4. Report
+
+Display merge results table with status per file.
+</process>

package/commands/pbr/remove-phase.md

@@ -0,0 +1,66 @@
+---
+description: "Remove a future phase from roadmap and renumber subsequent phases"
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<objective>
+Remove an unstarted future phase from the roadmap and renumber all subsequent phases to maintain a clean, linear sequence.
+
+Purpose: Clean removal of work you've decided not to do, without polluting context with cancelled/deferred markers.
+Output: Phase deleted, all subsequent phases renumbered, git commit as historical record.
+</objective>
+
+<context>
+Phase: $ARGUMENTS
+
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</context>
+
+<process>
+## 1. Validate Phase Number
+
+Parse $ARGUMENTS as phase number. Error if empty.
+
+## 2. Check Phase Status
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs phase-info $ARGUMENTS
+```
+
+Verify the phase exists and has NOT been started (no PLAN.md or SUMMARY.md files). Refuse to remove completed or in-progress phases.
+
+## 3. Confirm Removal
+
+Display phase details and ask for confirmation:
+"Remove Phase {N}: {name}? This will renumber all subsequent phases."
+
+## 4. Remove Phase
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs phase remove $ARGUMENTS
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs roadmap remove-phase $ARGUMENTS
+```
+
+## 5. Update State
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs state record-activity "Removed phase {N}: {name}"
+```
+
+## 6. Commit
+
+```bash
+git add .planning/
+git commit -m "docs: remove phase {N} — {name}"
+```
+
+## 7. Report
+
+Display updated phase list and suggest `/pbr:progress` to review.
+</process>

package/commands/pbr/research-phase.md

@@ -0,0 +1,59 @@
+---
+description: "Research how to implement a phase (standalone — usually use /pbr:plan-phase instead)"
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+---
+
+<objective>
+Research how to implement a phase. Spawns researcher agent with phase context.
+
+**Note:** This is a standalone research command. For most workflows, use `/pbr:plan-phase` which integrates research automatically.
+
+**Use this command when:**
+- You want to research without planning yet
+- You want to re-research after planning is complete
+- You need to investigate before deciding if a phase is feasible
+</objective>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</context>
+
+<process>
+## 1. Validate Phase
+
+```bash
+PHASE_INFO=$(node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs roadmap get-phase "$ARGUMENTS")
+```
+
+Error if phase not found. Extract phase_number, phase_name, goal.
+
+## 2. Check Existing Research
+
+Look for `.planning/phases/{NN}-*/RESEARCH.md`.
+If exists, offer: 1) Update research, 2) View existing, 3) Skip.
+
+## 3. Gather Context
+
+Read phase description, requirements, and prior decisions.
+
+## 4. Spawn Researcher
+
+```
+Task({
+  subagent_type: "pbr:researcher",
+  prompt: "Research implementation approach for Phase {N}: {name}\n\nPhase goal: {goal}\nRequirements: {requirements}\nPrior decisions: {decisions}\n\nWrite to: .planning/phases/{NN}-{slug}/{NN}-RESEARCH.md"
+})
+```
+
+## 5. Handle Return
+
+- `## RESEARCH COMPLETE`: Display summary, offer `/pbr:plan-phase {N}`
+- `## RESEARCH INCONCLUSIVE`: Show what was attempted, offer options
+</process>

package/commands/pbr/resume-work.md

@@ -0,0 +1,5 @@
+---
+description: "Resume work from previous session with full context restoration"
+---
+
+This command is provided by the `pbr:resume` skill.

package/commands/pbr/set-profile.md

@@ -0,0 +1,6 @@
+---
+description: "Switch model profile for PBR agents (quality/balanced/budget)"
+argument-hint: "<profile>"
+---
+
+This command is provided by the `pbr:profile` skill.

package/commands/pbr/settings.md

@@ -0,0 +1,5 @@
+---
+description: "Configure PBR workflow toggles and model profile"
+---
+
+This command is provided by the `pbr:config` skill.

package/commands/pbr/setup.md

@@ -0,0 +1,5 @@
+---
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md). For new projects, use /pbr:new-project."
+---
+
+This command is provided by the `pbr:setup` skill.

package/commands/pbr/statusline.md

@@ -0,0 +1,5 @@
+---
+description: "Install or configure the PBR status line in Claude Code."
+---
+
+This command is provided by the `pbr:statusline` skill.

package/commands/pbr/test.md

@@ -0,0 +1,5 @@
+---
+description: "Generate tests for completed phase code. Detects test framework and targets key files."
+---
+
+This command is provided by the `pbr:test` skill.

package/commands/pbr/undo.md

@@ -0,0 +1,5 @@
+---
+description: "Revert recent PBR-generated commits by phase/plan, safely using git revert."
+---
+
+This command is provided by the `pbr:undo` skill.

package/commands/pbr/update.md

@@ -0,0 +1,37 @@
+---
+description: "Update PBR to latest version with changelog display"
+allowed-tools:
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Check for PBR updates, install if available, and display what changed.
+</objective>
+
+<process>
+## 1. Detect Current Version
+
+```bash
+node $HOME/.claude/plan-build-run/bin/pbr-tools.cjs help 2>/dev/null | head -1
+cat $HOME/.claude/plan-build-run/package.json 2>/dev/null | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');console.log(JSON.parse(d).version)" 2>/dev/null
+```
+
+## 2. Check Latest Version
+
+```bash
+npm view plan-build-run version 2>/dev/null
+```
+
+## 3. Compare and Offer Update
+
+If newer version available, display changelog and ask for confirmation.
+
+```bash
+npm install -g plan-build-run@latest
+```
+
+## 4. Post-Update
+
+Display: "Updated to v{version}. Restart Claude Code to use the new version."
+</process>