@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/skills/shared/error-recovery-strategies.md

@@ -1,51 +0,0 @@
-# Error Recovery Strategies Fragment
-
-Standard recovery patterns for skills and agents when operations fail. Reference `error-reporting.md` for display formats.
-
-## Strategy 1: Retry with Backoff
-
-For transient failures (file locks, network timeouts, tool failures):
-
-1. Wait briefly, then retry the same operation (max 2 retries)
-2. If still failing after retries, fall through to Strategy 2
-
-Use for: git operations, file writes blocked by antivirus, API calls.
-
-## Strategy 2: Degrade Gracefully
-
-When a non-critical step fails, skip it and continue:
-
-1. Log a warning using the recoverable error format
-2. Note the skipped step in SUMMARY.md `deferred` field
-3. Continue with remaining work
-
-Use for: optional validations, dashboard launch, hook logger writes, note/todo updates.
-
-## Strategy 3: Escalate to User
-
-When a critical step fails and no automated fix exists:
-
-1. Display the fatal error format with actionable suggestions
-2. Do NOT attempt workarounds that could corrupt state
-3. Suggest `/pbr:health` as the first diagnostic step
-4. If in an agent context, return the error in the agent's output so the orchestrator can relay it
-
-Use for: STATE.md corruption, missing phase directories, config parse failures, git conflicts.
-
-## Strategy 4: Checkpoint and Abort
-
-When a multi-step operation partially fails:
-
-1. Commit any completed work (don't lose progress)
-2. Update STATE.md with accurate status (not the target status)
-3. Write a `.continue-here.md` breadcrumb if mid-phase
-4. Report what completed and what remains
-
-Use for: build phase with mixed plan results, verification with partial failures.
-
-## Anti-Patterns
-
-- **Never silently swallow errors** in catch blocks — at minimum call `logHook()` with the error message
-- **Never retry destructive operations** (deletes, force-pushes, state resets)
-- **Never auto-fix by deleting user artifacts** — only delete PBR internal state files (.active-skill, .context-tracker, .auto-next)
-- **Never continue building after STATE.md write failure** — state integrity is non-negotiable

package/plugins/pbr/skills/shared/progress-display.md

@@ -1,53 +0,0 @@
-# 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/state-loading.md

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

package/plugins/pbr/templates/RESEARCH-SUMMARY.md.tmpl

@@ -1,97 +0,0 @@
-# Research Summary
-
-> Synthesized: {date}
-> Input documents: {count}
-> Sources: {list of document names/paths}
-
-## Executive Summary
-
-{3-5 sentences maximum. What was researched, the single most important conclusion, and the recommended approach. This paragraph should give a planner enough context to start planning without reading further.}
-
-## Recommended Stack
-
-{Only include if project-level synthesis. For phase-level, skip this section.}
-
-| Layer | Choice | Version | Confidence | Alternatives | Source |
-|-------|--------|---------|------------|-------------|--------|
-| Runtime | {Node.js} | {20.x} | HIGH | {Bun, Deno} | {Doc A, Doc B} |
-| Framework | {Next.js} | {14.x} | HIGH | {Remix, Astro} | {Doc A} |
-| Database | {PostgreSQL} | {16.x} | HIGH | {MySQL} | {Doc A, Doc C} |
-| ORM | {Prisma} | {5.x} | MEDIUM | {Drizzle, TypeORM} | {Doc B} |
-| Auth | {NextAuth.js} | {5.x} | MEDIUM | {Clerk, Auth0} | {Doc A} |
-| Hosting | {Vercel} | - | MEDIUM | {AWS, Railway} | {Doc C} |
-| Testing | {Vitest} | {1.x} | HIGH | {Jest} | {Doc B} |
-
-### Stack Rationale
-
-{Brief explanation of why this combination. 2-3 sentences.}
-
-## Architecture Recommendations
-
-{Key architectural decisions informed by research. Use bullet points.}
-
-- **Pattern**: {Recommended pattern with rationale}
-- **Data flow**: {How data should move through the system}
-- **Separation**: {How to organize the code}
-- **State**: {How to manage state}
-
-## Key Patterns
-
-{Patterns to follow during implementation.}
-
-| Pattern | When to Use | Example |
-|---------|------------|---------|
-| {Repository} | {Database access} | {Brief code hint} |
-| {Middleware} | {Auth, logging, validation} | {Brief code hint} |
-| {DTO validation} | {API input/output} | {Zod schemas} |
-
-## Pitfalls & Warnings
-
-{Ranked by severity. These are the things most likely to cause problems.}
-
-| # | Pitfall | Severity | Source | Mitigation |
-|---|---------|----------|--------|------------|
-| 1 | {Most critical pitfall} | CRITICAL | {Doc A} | {How to avoid} |
-| 2 | {Second pitfall} | HIGH | {Doc B, Doc C} | {How to avoid} |
-| 3 | {Third pitfall} | MEDIUM | {Doc A} | {How to avoid} |
-
-## Contradictions Resolved
-
-{Where input documents disagreed and how it was resolved.}
-
-| Topic | Position A | Position B | Resolution | Basis |
-|-------|-----------|-----------|------------|-------|
-| {Database} | PostgreSQL (Doc A, C) | MongoDB (Doc B) | PostgreSQL | Majority + S2 source |
-| {Auth} | JWT (Doc A, B) | Sessions (Doc C) | JWT | Majority + better for API |
-
-{If any contradictions could not be resolved:}
-
-### Unresolved: {Topic}
-
-**Options**: {A} vs {B}
-**Trade-offs**: {A is better for X, B is better for Y}
-**Recommendation**: {best guess} `[NEEDS DECISION]`
-
-## Open Questions
-
-{Things that none of the research documents could definitively answer.}
-
-1. {Question} -- Impact: {what planning/implementation is blocked by this}
-2. {Question} -- Impact: {what planning/implementation is blocked by this}
-
-## Additional Notes
-
-{P3 (Nice to Know) items. Brief bullet points only.}
-
-- {Performance tip from Doc A}
-- {Future consideration from Doc C}
-- {Alternative approach worth noting from Doc B}
-
-## Sources
-
-{Consolidated source list from all input documents.}
-
-| # | Document | Key Contribution | Confidence |
-|---|----------|-----------------|------------|
-| 1 | {path/name} | {what it contributed} | {overall confidence} |
-| 2 | {path/name} | {what it contributed} | {overall confidence} |

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

@@ -1,124 +0,0 @@
-<!-- Source: agents/researcher.md | Purpose: Output format for research project ARCHITECTURE.md -->
-# Architecture Research
-
-**Domain:** {domain}
-**Researched:** {date}
-**Confidence:** {confidence}
-
-## Standard Architecture
-
-### System Overview
-
-```
-{ascii_architecture_diagram}
-```
-
-### Component Responsibilities
-
-| Component | Responsibility | Typical Implementation |
-|-----------|----------------|------------------------|
-| {component} | {responsibility} | {implementation} |
-
-## Recommended Project Structure
-
-```
-src/
-{project_structure}
-```
-
-### Structure Rationale
-
-- **{folder}/:** {rationale}
-
-## Architectural Patterns
-
-### Pattern 1: {pattern_name}
-
-**What:** {description}
-**When to use:** {conditions}
-**Trade-offs:** {pros_and_cons}
-
-**Example:**
-```{language}
-{code_example}
-```
-
-### Pattern 2: {pattern_name}
-
-**What:** {description}
-**When to use:** {conditions}
-**Trade-offs:** {pros_and_cons}
-
-### Pattern 3: {pattern_name}
-
-**What:** {description}
-**When to use:** {conditions}
-**Trade-offs:** {pros_and_cons}
-
-## Data Flow
-
-### Request Flow
-
-```
-{request_flow_diagram}
-```
-
-### State Management
-
-```
-{state_management_diagram}
-```
-
-### Key Data Flows
-
-1. **{flow_name}:** {description}
-2. **{flow_name}:** {description}
-
-## Scaling Considerations
-
-| Scale | Architecture Adjustments |
-|-------|--------------------------|
-| 0-1k users | {approach} |
-| 1k-100k users | {approach} |
-| 100k+ users | {approach} |
-
-### Scaling Priorities
-
-1. **First bottleneck:** {description}
-2. **Second bottleneck:** {description}
-
-## Anti-Patterns
-
-### Anti-Pattern 1: {name}
-
-**What people do:** {mistake}
-**Why it's wrong:** {problem}
-**Do this instead:** {correct_approach}
-
-### Anti-Pattern 2: {name}
-
-**What people do:** {mistake}
-**Why it's wrong:** {problem}
-**Do this instead:** {correct_approach}
-
-## Integration Points
-
-### External Services
-
-| Service | Integration Pattern | Notes |
-|---------|---------------------|-------|
-| {service} | {pattern} | {notes} |
-
-### Internal Boundaries
-
-| Boundary | Communication | Notes |
-|----------|---------------|-------|
-| {boundary} | {communication} | {notes} |
-
-## Sources
-
-- {sources}
-
----
-*Architecture research for: {domain}*
-*Researched: {date}*

package/plugins/pbr/templates/research/STACK.md.tmpl

@@ -1,71 +0,0 @@
-<!-- Source: agents/researcher.md | Purpose: Output format for research project STACK.md (external tech evaluation) -->
-# Stack Research
-
-**Domain:** {domain}
-**Researched:** {date}
-**Confidence:** {confidence}
-
-## Recommended Stack
-
-### Core Technologies
-
-| Technology | Version | Purpose | Why Recommended |
-|------------|---------|---------|-----------------|
-| {technology} | {version} | {purpose} | {rationale} |
-
-### Supporting Libraries
-
-| Library | Version | Purpose | When to Use |
-|---------|---------|---------|-------------|
-| {library} | {version} | {purpose} | {use_case} |
-
-### Development Tools
-
-| Tool | Purpose | Notes |
-|------|---------|-------|
-| {tool} | {purpose} | {notes} |
-
-## Installation
-
-```bash
-# Core
-{core_install_commands}
-
-# Supporting
-{supporting_install_commands}
-
-# Dev dependencies
-{dev_install_commands}
-```
-
-## Alternatives Considered
-
-| Recommended | Alternative | When to Use Alternative |
-|-------------|-------------|-------------------------|
-| {our_choice} | {alternative} | {conditions} |
-
-## What NOT to Use
-
-| Avoid | Why | Use Instead |
-|-------|-----|-------------|
-| {technology} | {problem} | {alternative} |
-
-## Stack Patterns by Variant
-
-**If {condition}:**
-- Use {variation}
-- Because {reason}
-
-## Version Compatibility
-
-| Package A | Compatible With | Notes |
-|-----------|-----------------|-------|
-| {package_a} | {package_b} | {notes} |
-
-## Sources
-
-- {sources}
-
----
-*Stack research for: {domain}*
-*Researched: {date}*

package/plugins/pbr/templates/research/SUMMARY.md.tmpl

@@ -1,112 +0,0 @@
-<!-- Source: agents/researcher.md | Purpose: Output format for research project SUMMARY.md (executive overview with roadmap implications) -->
-# Project Research Summary
-
-**Project:** {project_name}
-**Domain:** {domain}
-**Researched:** {date}
-**Confidence:** {confidence}
-
-## Executive Summary
-
-{executive_summary}
-
-## Key Findings
-
-### Recommended Stack
-
-{stack_summary}
-
-**Core technologies:**
-- {technology}: {purpose} -- {rationale}
-
-### Expected Features
-
-{features_summary}
-
-**Must have (table stakes):**
-- {feature} -- users expect this
-
-**Should have (competitive):**
-- {feature} -- differentiator
-
-**Defer (v2+):**
-- {feature} -- not essential for launch
-
-### Architecture Approach
-
-{architecture_summary}
-
-**Major components:**
-1. {component} -- {responsibility}
-2. {component} -- {responsibility}
-3. {component} -- {responsibility}
-
-### Critical Pitfalls
-
-{pitfalls_summary}
-
-1. **{pitfall}** -- {avoidance}
-2. **{pitfall}** -- {avoidance}
-3. **{pitfall}** -- {avoidance}
-
-## Implications for Roadmap
-
-Based on research, suggested phase structure:
-
-### Phase 1: {phase_name}
-**Rationale:** {why_first}
-**Delivers:** {deliverables}
-**Addresses:** {features}
-**Avoids:** {pitfall}
-
-### Phase 2: {phase_name}
-**Rationale:** {why_this_order}
-**Delivers:** {deliverables}
-**Uses:** {stack_elements}
-**Implements:** {architecture_component}
-
-### Phase 3: {phase_name}
-**Rationale:** {why_this_order}
-**Delivers:** {deliverables}
-
-### Phase Ordering Rationale
-
-- {ordering_rationale}
-
-### Research Flags
-
-Phases likely needing deeper research during planning:
-- **Phase {x}:** {reason}
-
-Phases with standard patterns (skip research-phase):
-- **Phase {x}:** {reason}
-
-## Confidence Assessment
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | {confidence} | {notes} |
-| Features | {confidence} | {notes} |
-| Architecture | {confidence} | {notes} |
-| Pitfalls | {confidence} | {notes} |
-
-**Overall confidence:** {confidence}
-
-### Gaps to Address
-
-- {gap}: {handling}
-
-## Sources
-
-### Primary (HIGH confidence)
-- {source}
-
-### Secondary (MEDIUM confidence)
-- {source}
-
-### Tertiary (LOW confidence)
-- {source}
-
----
-*Research completed: {date}*
-*Ready for roadmap: yes*

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

@@ -1,81 +0,0 @@
-# Phase Research: {Phase Name}
-
-> Research conducted: {date}
-> Research date: {ISO date}
-> Mode: phase-research
-> Phase: {NN}-{phase-name}
-> Confidence: {overall HIGH/MEDIUM/LOW}
-> Coverage: {COMPLETE/PARTIAL/INSUFFICIENT}
-> Retrieval cycles: {1-3}
-
-## User Constraints
-
-{Copied verbatim from CONTEXT.md}
-
-## Phase Goal
-
-{What this phase aims to achieve, extracted from the phase definition}
-
-## Implementation Approach
-
-### Recommended Approach
-
-{Detailed implementation strategy with source attribution}
-
-**Steps**:
-1. {Step with [S{n}] attribution}
-2. ...
-
-**Key decisions**:
-- {Decision with rationale and source}
-
-### Configuration Details
-
-{Specific configuration values, environment variables, file paths}
-
-```{language}
-// Source: [S{n}]
-{configuration example}
-```
-
-### API Patterns
-
-{Relevant API signatures, request/response formats, authentication patterns}
-
-### Data Models
-
-{Database schemas, type definitions, data flow}
-
-## Dependencies
-
-{What needs to be installed, configured, or available}
-
-| Dependency | Version | Purpose | Required By |
-|-----------|---------|---------|-------------|
-| ... | ... | ... | ... |
-
-## Pitfalls for This Phase
-
-{Phase-specific things that can go wrong}
-
-1. **{Pitfall}** [S{n}]: {Description}
-
-## Testing Strategy
-
-{How to verify this phase works correctly}
-
-## Coverage Assessment
-
-| Question | Status | Confidence | Cycle Resolved |
-|----------|--------|------------|----------------|
-| {Implementation question 1} | ANSWERED | HIGH | 1 |
-| {Implementation question 2} | GAP | — | — |
-
-**Overall coverage**: {COMPLETE/PARTIAL/INSUFFICIENT}
-**Gaps remaining**: {List any unresolved questions}
-
-## Sources
-
-| # | Type | URL/Description | Confidence |
-|---|------|----------------|------------|
-| ... | ... | ... | ... |