@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/templates/codebase/TESTING.md.tmpl

@@ -0,0 +1,107 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for TESTING.md codebase analysis -->
+# Testing Infrastructure
+
+> Analyzed: {date}
+> Test files found: {n}
+> Coverage: {percentage if configured}
+
+## Framework
+
+| Aspect | Value | Config |
+|--------|-------|--------|
+| Test runner | {Jest / Vitest / pytest / etc.} | {config file path} |
+| Assertion library | {built-in / chai / etc.} | - |
+| Mocking | {jest.mock / vitest.mock / unittest.mock} | - |
+| Coverage tool | {c8 / istanbul / coverage.py} | {config} |
+
+## Running Tests
+
+```bash
+# All tests
+{npm test}
+
+# Specific file
+{npm test -- path/to/file}
+
+# Watch mode
+{npm run test:watch}
+
+# Coverage
+{npm run test:coverage}
+
+# Specific pattern
+{npm test -- --grep "pattern"}
+```
+
+## Test Organization
+
+| Aspect | Pattern | Example |
+|--------|---------|---------|
+| Location | {co-located / separate directory} | `src/auth/auth.test.ts` or `tests/auth.test.ts` |
+| File naming | {.test.ts / .spec.ts / test_.py} | `UserService.test.ts` |
+| Describe blocks | {module/function/feature} | `describe('UserService')` |
+| Test naming | {should X / it X / test_X} | `it('should return user by id')` |
+
+## Test Structure Pattern
+
+```{language}
+// Pattern used in this codebase: {evidence file:line}
+{actual test structure from codebase}
+```
+
+## Mocking Patterns
+
+### External Services
+
+```{language}
+// How external services are mocked: {evidence file:line}
+{actual mock pattern from codebase}
+```
+
+### Database
+
+```{language}
+// How database is mocked/seeded: {evidence file:line}
+{actual pattern from codebase}
+```
+
+### API Calls
+
+```{language}
+// How API calls are mocked: {evidence file:line}
+{actual pattern from codebase}
+```
+
+## Fixtures & Test Data
+
+| Type | Location | Pattern |
+|------|----------|---------|
+| {Factories} | {tests/factories/} | {createUser(), createPost()} |
+| {Fixtures} | {tests/fixtures/} | {JSON files} |
+| {Seeds} | {prisma/seed.ts} | {Prisma seed script} |
+
+## Coverage Configuration
+
+| Setting | Value |
+|---------|-------|
+| Threshold | {if configured: line %, branch %, function %} |
+| Include | {file patterns} |
+| Exclude | {file patterns} |
+| Reporter | {text / html / lcov} |
+
+## E2E Testing
+
+| Aspect | Value | Config |
+|--------|-------|--------|
+| Framework | {Playwright / Cypress / none} | {config file} |
+| Location | {e2e/ or tests/e2e/} | - |
+| Base URL | {config} | - |
+
+## Testing Gaps
+
+| Area | Has Tests | Notes |
+|------|-----------|-------|
+| {Unit tests} | {YES/NO/PARTIAL} | {coverage details} |
+| {Integration tests} | {YES/NO/PARTIAL} | {coverage details} |
+| {E2E tests} | {YES/NO/PARTIAL} | {coverage details} |
+| {API tests} | {YES/NO/PARTIAL} | {coverage details} |

package/plugins/pbr/templates/continue-here.md.tmpl

@@ -0,0 +1,73 @@
+<!-- Source: skills/pause/SKILL.md | Purpose: Handoff file for session pause/resume, placed in the active phase directory -->
+
+# Template: Continue Here Handoff File
+# Used by: pause/SKILL.md (Step 4)
+# Output path: .planning/phases/{NN}-{phase-name}/.continue-here.md
+# Variables: {datetime}, {hours}, {phase}, {plan}, {status}, {session work}, {remaining}, {decisions}, {blockers}, {context}, {next steps}
+
+# Continue Here
+
+**Paused:** {ISO datetime}
+**Session duration:** ~{estimated hours} (based on git log timestamps)
+
+## Position
+
+Phase: {N} -- {name}
+Plan: {M} of {total} (or "between plans" / "phase complete")
+Status: {in-progress / between-plans / reviewing / planning}
+
+## Completed This Session
+
+{List of work done, with commit references where available}
+
+- Plan {A}: {summary} (commit: {short hash})
+- Plan {B}: {summary} (commit: {short hash})
+- Quick task: {description} (commit: {short hash})
+
+{If nothing was completed:}
+- No plans completed this session (discussion/planning only)
+
+## Remaining
+
+{What still needs to be done in this phase}
+
+- Plan {C}: {brief description from plan frontmatter}
+- Plan {D}: {brief description from plan frontmatter}
+
+{If phase is complete:}
+- Phase {N} is complete. Next: {review or next phase}
+
+## Decisions Made
+
+{Key decisions from this session that affect future work}
+
+- {decision 1}: {brief description}
+- {decision 2}: {brief description}
+
+{If no notable decisions:}
+- No major decisions this session
+
+## Blockers
+
+{Any issues preventing progress}
+
+- {blocker description}
+
+{If no blockers:}
+- None
+
+## Context Notes
+
+{Any additional context that would help the next session}
+
+- {note about something tricky}
+- {note about something to watch out for}
+- {note about user preferences expressed during this session}
+
+## Next Steps
+
+{Ordered list of what to do when resuming}
+
+1. {Specific first action with command}
+2. {Following action}
+3. {And so on}

package/plugins/pbr/templates/prompt-partials/phase-project-context.md.tmpl

@@ -0,0 +1,37 @@
+<!-- Source: templates/prompt-partials/ | Purpose: Shared context blocks for agent prompt templates -->
+<!-- Usage: Read this file and fill in placeholders, then include the result in agent prompts. -->
+<!-- Orchestrators should omit sections that don't apply to their agent type. -->
+
+<phase_context>
+Phase: {NN} - {phase_name}
+Phase directory: .planning/phases/{NN}-{slug}/
+Phase goal: {goal from roadmap}
+Phase requirements: {REQ-IDs mapped to this phase, or "None"}
+Phase depends on: {dependency phases, or "None"}
+Success criteria from roadmap:
+{success criteria list, or omit if not applicable}
+</phase_context>
+
+<project_context>
+{Decision Summary from .planning/CONTEXT.md — compact locked/deferred/discretion list}
+{If no CONTEXT.md exists: "No project-level context."}
+
+Phase-specific decisions:
+{Decision Summary from .planning/phases/{NN}-{slug}/CONTEXT.md}
+{If no phase-level CONTEXT.md exists: "No phase-specific discussion captured."}
+
+Full context files (Read on-demand if you need scope/quality/integration details):
+- .planning/CONTEXT.md
+- .planning/phases/{NN}-{slug}/CONTEXT.md
+</project_context>
+
+<prior_work>
+The following prior phase summaries are available. Read any you need via the Read tool.
+
+| Phase | Summary File | Status | Key Exports |
+|-------|-------------|--------|-------------|
+{For each preceding phase SUMMARY.md:}
+| {M} - {name} | {absolute path to SUMMARY.md} | {complete/partial} | {one-line provides list} |
+
+{If no prior phases: "No prior phases completed."}
+</prior_work>

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

@@ -0,0 +1,124 @@
+<!-- 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

@@ -0,0 +1,71 @@
+<!-- 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

@@ -0,0 +1,112 @@
+<!-- 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

@@ -0,0 +1,81 @@
+# 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 |
+|---|------|----------------|------------|
+| ... | ... | ... | ... |

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

@@ -0,0 +1,99 @@
+# Research: {Topic Title}
+
+> Research conducted: {date}
+> Research date: {ISO date}
+> Mode: project-research
+> Confidence: {overall HIGH/MEDIUM/LOW}
+> Coverage: {COMPLETE/PARTIAL/INSUFFICIENT}
+> Retrieval cycles: {1-3}
+> Sources consulted: {count}
+
+## User Constraints
+
+{Copied verbatim from CONTEXT.md if it exists. Otherwise: "No CONTEXT.md found."}
+
+## Executive Summary
+
+{2-3 paragraph overview of findings. What is this technology/domain? Why does it matter for this project? What is the recommended approach?}
+
+## Standard Stack
+
+{The conventional/recommended technology stack for this domain}
+
+| Layer | Technology | Version | Confidence | Source |
+|-------|-----------|---------|------------|--------|
+| Runtime | Node.js | 20.x LTS | HIGH | [S2] |
+| Framework | Next.js | 14.x | HIGH | [S2] |
+| ... | ... | ... | ... | ... |
+
+### Stack Rationale
+
+{Why this combination? What alternatives were considered and why they were rejected?}
+
+### Stack Risks
+
+{Known issues, upcoming deprecations, migration concerns}
+
+## Architecture Patterns
+
+### Recommended Pattern: {Name}
+
+{Description with source attribution}
+
+**When to use**: ...
+**When to avoid**: ...
+**Example structure**:
+```
+project/
+  src/
+    ...
+```
+
+### Alternative Pattern: {Name}
+
+{Only include if CONTEXT.md doesn't lock the architecture}
+
+## Common Pitfalls
+
+{Numbered list of things that commonly go wrong}
+
+1. **{Pitfall name}** [S{n}]: {Description and how to avoid}
+2. ...
+
+## Code Examples
+
+{Working code snippets for key patterns. Every snippet must include source attribution.}
+
+### {Pattern Name}
+
+```{language}
+// Source: [S{n}] {url or description}
+{code}
+```
+
+## Integration Points
+
+{How this technology connects with other systems. API patterns, data flow, authentication.}
+
+## Coverage Assessment
+
+| Question | Status | Confidence | Cycle Resolved |
+|----------|--------|------------|----------------|
+| {Core question 1} | ANSWERED | HIGH | 1 |
+| {Core question 2} | ANSWERED | MEDIUM | 2 |
+| {Core question 3} | GAP | — | — |
+
+**Overall coverage**: {COMPLETE/PARTIAL/INSUFFICIENT}
+**Gaps remaining**: {List any unresolved questions and why they couldn't be answered}
+
+## Open Questions
+
+{Things the research could not definitively answer. These need human input or further investigation.}
+
+## Sources
+
+| # | Type | URL/Description | Confidence |
+|---|------|----------------|------------|
+| S1 | Official Docs | {url} | HIGH |
+| S2 | GitHub | {url} | HIGH |
+| ... | ... | ... | ... |