@sienklogic/plan-build-run 2.3.1 → 2.4.1

package/plugins/cursor-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/cursor-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/cursor-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/cursor-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/cursor-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/cursor-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 |
+| ... | ... | ... | ... |

package/plugins/cursor-pbr/templates/research-outputs/synthesis.md.tmpl

@@ -0,0 +1,36 @@
+# Research Synthesis: {Topic}
+
+> Synthesized: {date}
+> Mode: synthesis
+> Input documents: {count}
+> Confidence: {overall}
+
+## Executive Summary
+
+{Unified findings across all input documents}
+
+## Key Findings
+
+{Numbered list of the most important findings, with source document attribution}
+
+## Contradictions Resolved
+
+{Where input documents disagreed and how it was resolved}
+
+| Topic | Document A Says | Document B Says | Resolution | Basis |
+|-------|----------------|----------------|------------|-------|
+| ... | ... | ... | ... | ... |
+
+## Recommended Approach
+
+{The synthesized recommendation}
+
+## Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| ... | ... | ... | ... |
+
+## Sources
+
+{Consolidated source list from all input documents}

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",
@@ -9,5 +9,10 @@
   "homepage": "https://github.com/SienkLogic/plan-build-run",
   "repository": "https://github.com/SienkLogic/plan-build-run",
   "license": "MIT",
-  "keywords": ["claude-code", "context-engineering", "development-workflow", "subagent-delegation"]
+  "keywords": [
+    "claude-code",
+    "context-engineering",
+    "development-workflow",
+    "subagent-delegation"
+  ]
 }

package/plugins/pbr/skills/milestone/SKILL.md

@@ -263,10 +263,13 @@ Archive a completed milestone and prepare for the next one.
 
 5. **Archive milestone documents:**
 
-   Copy/create archive files:
-   - `.planning/milestones/{version}-ROADMAP.md` — snapshot of ROADMAP.md at completion
-   - `.planning/milestones/{version}-REQUIREMENTS.md` — snapshot of REQUIREMENTS.md
-   - `.planning/milestones/{version}-STATS.md` — milestone statistics
+   Create a versioned archive directory and move phase directories into it:
+   - `.planning/milestones/{version}/ROADMAP.md` — snapshot of ROADMAP.md at completion
+   - `.planning/milestones/{version}/REQUIREMENTS.md` — snapshot of REQUIREMENTS.md
+   - `.planning/milestones/{version}/STATS.md` — milestone statistics
+   - `.planning/milestones/{version}/phases/{NN}-{slug}/` — move each milestone phase directory from `.planning/phases/` into the archive
+
+   **Move phases:** For each phase belonging to this milestone, move (not copy) its directory from `.planning/phases/{NN}-{slug}/` to `.planning/milestones/{version}/phases/{NN}-{slug}/`. This keeps the active phases directory clean for the next milestone.
 
    **Stats file content:**
 
@@ -293,7 +296,7 @@ Archive a completed milestone and prepare for the next one.
    ```markdown
    ## Milestone: {name} ({version}) -- COMPLETED
 
-   Phases {start}-{end} completed on {date}. See `.planning/milestones/{version}-ROADMAP.md` for details.
+   Phases {start}-{end} completed on {date}. See `.planning/milestones/{version}/ROADMAP.md` for details.
 
    | Phase | Status |
    |-------|--------|
@@ -325,7 +328,7 @@ Archive a completed milestone and prepare for the next one.
 
 9. **Commit:**
    ```bash
-   git add .planning/milestones/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md .planning/HISTORY.md
+   git add .planning/milestones/ .planning/phases/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md .planning/HISTORY.md
    git commit -m "docs(planning): complete milestone {version}"
    ```
 
@@ -342,7 +345,7 @@ Archive a completed milestone and prepare for the next one.
     - {count} commits, {lines} lines of code
     - {duration} days
 
-    Archived to: .planning/milestones/{version}-*
+    Archived to: .planning/milestones/{version}/
     Git tag: {version}
 
     ───────────────────────────────────────────────────────────────