@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/templates/UAT.md.tmpl

@@ -0,0 +1,94 @@
+<!-- Source: skills/review/SKILL.md | Purpose: Persistent UAT session tracking for verify-work -->
+
+```yaml
+---
+status: testing            # testing | partial | complete | diagnosed
+phase: {phase_id}
+source:
+  - "{SUMMARY file 1}"
+started: "{ISO timestamp}"
+updated: "{ISO timestamp}"
+---
+```
+
+# Phase {N} -- UAT Session
+
+> Persistent UAT tracking. Updated after each user response.
+
+---
+
+## Current Test
+
+<!-- OVERWRITE each test transition -->
+
+number: {N}
+name: {test name}
+expected: |
+  {what user should observe}
+awaiting: user response
+
+## Tests
+
+### 1. {Test Name}
+
+expected: {observable behavior -- what user should see}
+result: [pending]
+
+### 2. {Test Name}
+
+expected: {observable behavior}
+result: pass | issue | skipped | blocked
+
+<!-- If issue: -->
+reported: "{verbatim user response}"
+severity: blocker | major | minor | cosmetic
+
+<!-- If skipped: -->
+reason: {why skipped}
+
+<!-- If blocked: -->
+blocked_by: server | physical-device | release-build | third-party | prior-phase
+reason: {why blocked}
+
+## Diagnosis
+
+<!-- Populated by debugger agent after testing complete -->
+
+### Gap {N}: {Short description}
+
+- **Test**: {test number}
+- **Root cause**: {root cause from debug session}
+- **Artifacts**: {file paths with issues}
+- **Missing**: {what needs to change}
+- **Debug session**: {path to debug log}
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Total | {N} |
+| Passed | {N} |
+| Issues | {N} |
+| Pending | {N} |
+| Skipped | {N} |
+| Blocked | {N} |
+
+## Gaps
+
+<!-- YAML format for plan-phase --gaps consumption -->
+
+```yaml
+- truth: "{expected behavior from test}"
+  status: failed
+  reason: "User reported: {verbatim response}"
+  severity: blocker | major | minor | cosmetic
+  test: {N}
+  root_cause: ""
+  artifacts: []
+  missing: []
+  debug_session: ""
+```
+
+---
+
+*Generated by /pbr:verify-work*

package/plugins/pbr/templates/UI-SPEC.md.tmpl

@@ -0,0 +1,144 @@
+<!-- Source: skills/ui-phase/SKILL.md | Purpose: Visual and interaction contract for frontend phases -->
+
+```yaml
+---
+phase: {N}
+slug: {phase-slug}
+status: draft              # draft | approved
+shadcn_initialized: false
+preset: none
+created: "{date}"
+---
+```
+
+# Phase {N} -- UI Design Contract
+
+> Visual and interaction contract for frontend phases. Generated by /pbr:ui-phase, verified by ui-checker agent.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | {shadcn / none} |
+| Preset | {preset string or "not applicable"} |
+| Component library | {radix / base-ui / none} |
+| Icon library | {library} |
+| Font | {font} |
+
+---
+
+## Spacing Scale
+
+Declared values (must be multiples of 4):
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Icon gaps, inline padding |
+| sm | 8px | Compact element spacing |
+| md | 16px | Default element spacing |
+| lg | 24px | Section padding |
+| xl | 32px | Layout gaps |
+| 2xl | 48px | Major section breaks |
+| 3xl | 64px | Page-level spacing |
+
+Exceptions: {list any, or "none"}
+
+---
+
+## Typography
+
+| Role | Size | Weight | Line Height |
+|------|------|--------|-------------|
+| Body | {px} | {weight} | {ratio} |
+| Label | {px} | {weight} | {ratio} |
+| Heading | {px} | {weight} | {ratio} |
+| Display | {px} | {weight} | {ratio} |
+
+---
+
+## Color Palette
+
+60/30/10 rule:
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Dominant (60%) | {hex} | Background, surfaces |
+| Secondary (30%) | {hex} | Cards, sidebar, nav |
+| Accent (10%) | {hex} | {list specific elements only} |
+| Destructive | {hex} | Destructive actions only |
+
+Accent reserved for: {explicit list}
+
+---
+
+## Copywriting Contract
+
+| Element | Copy |
+|---------|------|
+| Primary CTA | {specific verb + noun} |
+| Empty state heading | {copy} |
+| Empty state body | {copy + next step} |
+| Error state | {problem + solution path} |
+| Destructive confirmation | {action name}: {confirmation copy} |
+
+---
+
+## Component Registry
+
+| Component | Source | Props | Notes |
+|-----------|--------|-------|-------|
+| {component} | {shadcn / custom} | {key props} | {notes} |
+
+---
+
+## Page Layout Patterns
+
+| Page | Layout | Key Components |
+|------|--------|----------------|
+| {page} | {layout type} | {components used} |
+
+---
+
+## Interaction Patterns
+
+| Interaction | Trigger | Behavior | Feedback |
+|-------------|---------|----------|----------|
+| {action} | {user event} | {what happens} | {visual feedback} |
+
+---
+
+## Empty / Error / Loading States
+
+| State | Component | Visual | Copy |
+|-------|-----------|--------|------|
+| Empty | {component} | {description} | {copy} |
+| Error | {component} | {description} | {copy} |
+| Loading | {component} | {description} | {copy} |
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| shadcn official | {list} | not required |
+| {third-party name} | {list} | shadcn view + diff required |
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** {pending / approved YYYY-MM-DD}
+
+---
+
+*Generated by /pbr:ui-phase*

package/plugins/pbr/templates/VALIDATION.md.tmpl

@@ -0,0 +1,94 @@
+<!-- Source: skills/validate-phase/SKILL.md | Purpose: Per-phase validation contract for feedback sampling -->
+
+```yaml
+---
+phase: {N}
+slug: {phase-slug}
+status: draft              # draft | compliant
+nyquist_compliant: false
+wave_0_complete: false
+created: "{date}"
+---
+```
+
+# Phase {N} -- Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | {jest / vitest / pytest / go test / other} |
+| **Config file** | {path or "none -- Wave 0 installs"} |
+| **Quick run command** | `{quick command}` |
+| **Full suite command** | `{full command}` |
+| **Estimated runtime** | ~{N} seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `{quick run command}`
+- **After every plan wave:** Run `{full suite command}`
+- **Before /pbr:verify-work:** Full suite must be green
+- **Max feedback latency:** {N} seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| {N}-01-01 | 01 | 1 | REQ-{XX} | unit | `{command}` | {yes/no} | pending |
+
+*Status: pending / green / red / flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `{tests/test_file.ext}` -- stubs for REQ-{XX}
+- [ ] `{tests/conftest or setup}` -- shared fixtures
+- [ ] `{framework install}` -- if no framework detected
+
+*If none: "Existing infrastructure covers all phase requirements."*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| {behavior} | REQ-{XX} | {reason} | {steps} |
+
+*If none: "All phase behaviors have automated verification."*
+
+---
+
+## Coverage Gaps
+
+| Requirement | Gap Description | Mitigation |
+|-------------|-----------------|------------|
+| REQ-{XX} | {what is not covered} | {how to address} |
+
+*If none: "No coverage gaps identified."*
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < {N}s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** {pending / approved YYYY-MM-DD}
+
+---
+
+*Generated by /pbr:validate-phase*

package/plugins/pbr/templates/VERIFICATION-DETAIL.md.tmpl

@@ -3,33 +3,40 @@
 ```yaml
 ---
 phase: "{phase_id}"
-verified: "{ISO timestamp}"
 status: "passed"           # passed | gaps_found | human_needed
+checked_at: "{ISO timestamp}"
 is_re_verification: false  # true if re-verifying after gap closure
-score:
-  total_must_haves: {n}
-  verified: {n}
-  failed: {n}
-  partial: {n}
-  human_needed: {n}
+must_haves_checked: {n}
+must_haves_passed: {n}
+must_haves_failed: {n}
 gaps:
   - must_have: "{description of the failed must-have}"
     level: "{existence | substantive | wired}"
     evidence: "{what you found}"
     recommendation: "{specific action to fix}"
+fix_plans:
+  - gap: "{gap description}"
+    effort: "small"       # small | medium | large
+    tasks:
+      - "{specific fix action with file path}"
 anti_patterns:
   todos: {count}
   stubs: {count}
   console_logs: {count}
   skipped_tests: {count}
   hardcoded_secrets: {count}
+# populated by verifier from implements:[] in plan frontmatter
+satisfied:
+  - "REQ-F-001"    # REQ-IDs confirmed verified in this phase
+unsatisfied:
+  - "REQ-F-002"    # REQ-IDs that failed verification
 ---
 
 # Phase Verification: {phase_name}
 
-> Verified: {date}
+> Checked at: {date}
 > Status: **{STATUS}**
-> Score: {verified}/{total} must-haves verified
+> Score: {must_haves_passed}/{must_haves_checked} must-haves verified
 > Re-verification: {yes/no}
 
 ## Observable Truths
@@ -53,23 +60,52 @@ anti_patterns:
 
 | # | Link Description | Source | Target | Status | Evidence |
 |---|-----------------|--------|--------|--------|----------|
-| 1 | {what connects to what} | `{source_file}` | `{target_file}` | WIRED | Import at L12, called at L45 |
+| 1 | {what connects to what} | `{source_file}` | `{target_file}` | WIRED | Import at L12, called at L45, args correct |
 | 2 | {what connects to what} | `{source_file}` | `{target_file}` | BROKEN | Imported but never called |
+| 3 | {what connects to what} | `{source_file}` | `{target_file}` | ARGS_WRONG | Called at L45 but passes undefined for sessionId (data.session_id in scope) |
 
 ## Gaps Found
 
 {Only present if status is gaps_found}
 
-### Gap 1: {Short description}
+### Critical Gaps
+
+{Gaps that block requirements or core functionality}
+
+#### Gap 1: {Short description}
 
 - **Must-Have**: {which must-have this gap blocks}
+- **Severity**: Critical
 - **Level Failed**: {existence / substantive / wired}
 - **Evidence**: {specific evidence — file paths, line numbers, command output}
 - **Impact**: {what doesn't work because of this gap}
 - **Recommendation**: {specific action to close this gap}
 
-### Gap 2: {Short description}
-...
+### Non-Critical Gaps
+
+{Gaps related to quality, polish, or non-blocking improvements}
+
+#### Gap N: {Short description}
+
+- **Must-Have**: {which must-have this relates to}
+- **Severity**: Non-Critical
+- **Level Failed**: {existence / substantive / wired}
+- **Evidence**: {evidence}
+- **Impact**: {impact}
+- **Recommendation**: {action}
+
+## Recommended Fix Plans
+
+{Auto-generated from gaps. Each gap that can be fixed gets a fix plan.}
+
+### Fix Plan 1: {Gap title}
+**Gap**: {reference to gap}
+**Estimated effort**: {small/medium/large}
+**Tasks**:
+1. {specific fix action with file path}
+2. {verification step}
+
+### Fix Plan 2: ...
 
 ## Human Verification Items
 

package/plugins/pbr/templates/project-CONTEXT.md.tmpl

@@ -0,0 +1,59 @@
+# Project Context
+
+> Cross-cutting decisions that ALL phases must honor.
+> Updated via `/pbr:discuss-phase --project`. Auto-synced to CLAUDE.md on write.
+> Phase-level CONTEXT.md (in phase directories) overrides project-level for that phase.
+>
+> PLANNER NOTE: Embed each locked decision directly into the relevant task's action block.
+> Executors NEVER read this file — PLAN.md is self-contained.
+
+## Locked Decisions
+
+Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE across ALL phases.
+The planner embeds these into PLAN.md task actions. Executors never read this file directly.
+
+| Decision | Rationale | Locked By |
+|----------|-----------|-----------|
+| {e.g., "Use TypeScript strict mode"} | {User preference, team skill} | User |
+| {e.g., "PostgreSQL via Supabase"} | {Existing infrastructure} | User |
+
+## User Constraints
+
+Budget, timeline, skill level, hosting, team size — factors that shape ALL planning decisions.
+
+- {e.g., "Solo developer, no team"}
+- {e.g., "Deploy to Hetzner VPS"}
+- {e.g., "Must work offline"}
+
+## Specific References
+
+User references, preferences, and "I want it like X" moments that apply across ALL phases.
+These are directional hints for planners, not locked decisions.
+
+- **{Reference}** — {Context from user, e.g., "I want the dashboard to feel like Linear"}
+- **{Reference}** — {Context, e.g., "The auth flow should work like Discord's OAuth"}
+
+## Code Patterns & Reusable Assets
+
+Established patterns, shared utilities, and integration points that planners should leverage
+rather than creating from scratch. Updated as phases complete and patterns emerge.
+
+- **{Pattern/Asset}** — {Location and how to reuse, e.g., "pbr-tools.js CLI pattern — use for new CLI commands"}
+- **{Pattern/Asset}** — {Location, e.g., "hooks/hook-logger.js — standard logging for all hook scripts"}
+
+## Deferred Ideas
+
+Ideas explicitly moved to v2 or ruled out. Plans at ANY phase MUST NOT include these.
+
+| Idea | Reason Deferred |
+|------|----------------|
+| {feature} | {reason — e.g., "Post-launch priority"} |
+
+## Claude's Discretion Areas
+
+Areas where planners can make implementation choices without asking the user.
+Document the choice made and rationale when exercised.
+
+| Area | Choice Made | Rationale |
+|------|------------|-----------|
+| {e.g., "Logging library"} | {e.g., "pino"} | {e.g., "Lightweight, structured output"} |

package/plugins/pbr/templates/research-outputs/ARCHITECTURE.md.tmpl

@@ -0,0 +1,91 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges architecture findings into SUMMARY.md. Needs: component list, pattern names, data flow summary.
+  - Planner agent: uses architecture for phase dependency ordering. Needs: component dependencies, build order implications, API contract shapes.
+  - Build skill: uses architecture patterns during implementation. Needs: specific patterns tied to the chosen stack, anti-patterns to avoid.
+  Breaks if missing: Planner creates phases with wrong dependency order; build agents implement without architectural guidance.
+-->
+# Architecture Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## System Architecture
+
+{High-level overview of the system architecture and its major components.}
+
+## Component Diagram
+
+```
+{text_based_component_diagram}
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Depends On |
+|-----------|----------------|------------|
+| {component} | {responsibility} | {dependencies} |
+
+## Data Flow
+
+### Primary Data Flow
+
+```
+{text_based_data_flow_diagram}
+```
+
+### Key Data Paths
+
+1. **{path_name}:** {description_of_data_flow}
+
+## API Contracts
+
+### {API Endpoint or Interface}
+
+**Request:**
+```
+{request_shape}
+```
+
+**Response:**
+```
+{response_shape}
+```
+
+**Error cases:** {error_description}
+
+## Architecture Patterns
+
+| Pattern | Where Used | Why |
+|---------|-----------|-----|
+| {pattern_name} | {component_or_layer} | {rationale} |
+
+### Pattern Details
+
+#### {Pattern Name}
+
+**What:** {description}
+**When to use:** {conditions}
+**Trade-offs:** {pros_and_cons}
+
+## Anti-Patterns to Avoid
+
+1. **{anti_pattern_name}**
+   - **What people do:** {mistake}
+   - **Why it fails:** {problem}
+   - **Do instead:** {correct_approach}
+
+## Quality Gates
+
+- [ ] Architecture patterns are specific to the chosen stack (not generic advice)
+- [ ] Data flow covers all major paths (happy path, error path, async flows)
+- [ ] API contracts include request shape, response shape, and error cases
+- [ ] Component diagram shows all major components and their connections
+- [ ] At least 2 anti-patterns documented with concrete alternatives
+- [ ] Sources include at least one official documentation or architecture guide reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/pbr/templates/research-outputs/FEATURES.md.tmpl

@@ -0,0 +1,64 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges feature findings into SUMMARY.md. Needs: categorized feature list with priorities and effort estimates.
+  - Planner agent: uses feature priorities for requirement prioritization and phase scoping. Needs: must-have/should-have/defer categorization, effort estimates.
+  - Begin skill: presents feature inventory to user for scope discussion. Needs: clear feature descriptions with competitive context.
+  Breaks if missing: Planner scopes phases without feature priority data; synthesizer produces SUMMARY with no feature guidance.
+-->
+# Features Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Feature Inventory
+
+| Feature | Category | Priority | Effort | Description |
+|---------|----------|----------|--------|-------------|
+| {feature} | {category} | {must-have/should-have/defer} | {S/M/L/XL} | {brief_description} |
+
+## Competitive Analysis
+
+| Feature | Our Approach | Alternative 1 | Alternative 2 | Tradeoff |
+|---------|-------------|---------------|---------------|----------|
+| {feature} | {our_approach} | {alt_1} | {alt_2} | {tradeoff_analysis} |
+
+## Prioritization Rationale
+
+### Must-Have (table stakes)
+
+{Features users expect as baseline. Without these, the product is not viable.}
+
+- **{feature}:** {why_must_have}
+
+### Should-Have (competitive)
+
+{Features that differentiate from alternatives. Important but not blocking launch.}
+
+- **{feature}:** {why_should_have}
+
+### Defer (v2+)
+
+{Features explicitly excluded from initial scope with rationale.}
+
+- **{feature}:** {why_defer}
+
+## Deferred Features
+
+| Feature | Reason Deferred | Revisit When | Effort if Added Later |
+|---------|----------------|--------------|----------------------|
+| {feature} | {reason} | {trigger} | {effort_estimate} |
+
+## Quality Gates
+
+- [ ] Every feature categorized as must-have, should-have, or defer
+- [ ] Effort estimates present for all features (S/M/L/XL)
+- [ ] Competitive analysis has at least 2 alternatives per major feature
+- [ ] Must-have features have clear rationale for why they are table stakes
+- [ ] Deferred features include revisit triggers
+- [ ] Sources include at least one market or user research reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |

package/plugins/pbr/templates/research-outputs/PITFALLS.md.tmpl

@@ -0,0 +1,50 @@
+<!-- Downstream consumers:
+  - Synthesizer agent: merges pitfall findings into SUMMARY.md. Needs: numbered pitfalls with severity and avoidance strategies.
+  - Planner agent: reads pitfalls to add defensive verification steps to plans. Needs: specific, actionable avoidance strategies.
+  - Build skill: uses avoidance strategies during implementation. Needs: detection methods to catch pitfalls early.
+  Breaks if missing: Plans lack defensive verification; synthesizer produces SUMMARY with no risk awareness.
+-->
+# Pitfalls Research
+
+**Researched:** {date}
+**Domain:** {domain}
+**Confidence:** {confidence}
+
+## Critical Pitfalls
+
+{Pitfalls that cause project failure or major rework if not avoided.}
+
+1. **{pitfall_name}** [{source}]
+   - **Impact:** {what_goes_wrong}
+   - **Root cause:** {why_it_happens}
+   - **Avoidance:** {specific_steps_to_prevent}
+   - **Detection:** {how_to_catch_early}
+
+## Common Mistakes
+
+{Mistakes that cause delays but are recoverable.}
+
+1. **{mistake_name}** [{source}]
+   - **Impact:** {what_goes_wrong}
+   - **Avoidance:** {what_to_do_instead}
+
+## Environment-Specific Gotchas
+
+| Environment | Gotcha | Workaround |
+|-------------|--------|------------|
+| {env} | {issue} | {fix} |
+
+## Quality Gates
+
+- [ ] At least 3 critical pitfalls identified with source attribution
+- [ ] Each critical pitfall has a concrete avoidance strategy (not "be careful")
+- [ ] Each critical pitfall has a detection method
+- [ ] Environment-specific gotchas checked for target platform
+- [ ] Common mistakes section has at least 2 entries
+- [ ] Sources include at least one official documentation reference
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | {type} | {url_or_description} | {HIGH/MEDIUM/LOW} |