@sienklogic/plan-build-run 2.0.0 → 2.0.1

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

@@ -1,45 +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."
+# 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/pbr/skills/shared/progress-display.md

@@ -1,53 +1,53 @@
-# 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%
-```
+# 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/pbr/skills/shared/revision-loop.md

@@ -1,81 +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
+# 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/pbr/skills/shared/state-loading.md

@@ -1,62 +1,62 @@
-# 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)
+# 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)