@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/cursor-pbr/references/subagent-coordination.md

@@ -1,120 +0,0 @@
-<!-- canonical: ../../pbr/references/subagent-coordination.md -->
-# Subagent Coordination Reference
-
-Patterns for spawning, monitoring, and consuming output from Task() subagents. Used by skills that delegate work to specialized agents.
-
----
-
-## When to Spawn vs Inline
-
-| Condition | Action |
-|-----------|--------|
-| >50 lines of analysis or code generation needed | Spawn a subagent |
-| Simple state read or file write | Do it inline |
-| Multiple files need reading for a decision | Spawn — protect orchestrator context |
-| User interaction needed (questions, confirmations) | Do it inline |
-| Work needs a fresh context window | Spawn |
-
----
-
-## Spawning Pattern
-
-Always use the modern subagent_type syntax. Agent definitions are auto-loaded by Claude Code — never inline them.
-
-```
-Task({
-  subagent_type: "pbr:{agent-name}",
-  prompt: <structured prompt with context>
-})
-```
-
-### Structured Input Format
-
-Provide context to subagents using tagged blocks:
-
-```xml
-<phase_context>
-Phase: {NN}-{slug}
-Goal: {goal from ROADMAP.md}
-</phase_context>
-
-<prior_work>
-{Frontmatter from relevant SUMMARY.md files}
-</prior_work>
-
-<instructions>
-{Specific instructions for this agent invocation}
-</instructions>
-```
-
-### What NOT to Include in Spawn Prompts
-
-- Full agent definition text (auto-loaded via subagent_type)
-- Full SUMMARY.md bodies (agent reads from disk)
-- Full PLAN.md bodies unless the agent needs them (executor does, verifier doesn't)
-- Content from unrelated phases
-
----
-
-## Reading Output
-
-After a subagent completes, read its output file — but only what you need.
-
-| Output Type | Orchestrator Reads | Agent Reads Full |
-|-------------|-------------------|-----------------|
-| SUMMARY.md | Frontmatter only (status, key_files, commits) | Yes, from disk |
-| VERIFICATION.md | Frontmatter only (status, must_haves_passed/failed) | Yes, from disk |
-| PLAN.md | Frontmatter only (wave, depends_on, files_modified) | Yes, from disk |
-| RESEARCH.md | Frontmatter + recommendations section | Yes, from disk |
-| Debug files | Latest hypothesis + result only | Yes, from disk |
-
-### Frontmatter-Only Read Pattern
-
-```
-Read the file, extract YAML frontmatter between --- markers.
-Parse: status, key_files, commits, provides.
-Do NOT read past the closing --- of frontmatter.
-```
-
----
-
-## State Update After Agent Completion
-
-After reading agent output, update STATE.md with minimal information:
-1. Update phase/plan status
-2. Record completion timestamp
-3. Note any blockers or warnings from frontmatter
-4. Do NOT copy agent output into STATE.md
-
----
-
-## Error Handling
-
-| Scenario | Action |
-|----------|--------|
-| Agent times out | Report to user, suggest retry |
-| Agent produces no output file | Report failure, check for partial work |
-| Output file has `status: failed` | Read failure details, present to user |
-| Agent reports warnings | Continue but show warnings in completion summary |
-
-### Retryable vs Fatal
-
-- **Retryable**: Timeout, transient file errors, partial completion
-- **Fatal**: Missing plan files, invalid state, circular dependencies
-- **User decision**: Verification failures, ambiguous requirements
-
----
-
-## Context Budget Impact
-
-Each subagent coordination step has a token cost in the orchestrator:
-
-| Step | Approximate Cost |
-|------|-----------------|
-| Reading state before spawn | 200-500 tokens |
-| Constructing spawn prompt | 500-1000 tokens |
-| Reading output frontmatter | 100-300 tokens |
-| Updating STATE.md | 200-400 tokens |
-| **Total per agent cycle** | **1,000-2,200 tokens** |
-
-Compare to inlining the same work: 5,000-20,000 tokens. Delegation saves 3-10x.

package/plugins/cursor-pbr/references/verification-patterns.md

@@ -1,199 +0,0 @@
-<!-- canonical: ../../pbr/references/verification-patterns.md -->
-# Goal-Backward Verification Patterns
-
-Reference patterns for deriving verification criteria from goals. Used by the planner to create `<verify>` and `<done>` elements, and by the verifier to check phase completion.
-
----
-
-## The Three-Layer Check
-
-Every must-have is verified through three layers, checked in order:
-
-### Layer 1: Existence
-
-Does the artifact exist?
-
-```bash
-# File existence
-ls -la src/auth/discord.ts
-
-# Module export existence
-grep -q "export.*authenticateWithDiscord" src/auth/discord.ts
-
-# Database table existence
-npx prisma db execute --stdin <<< "SELECT 1 FROM users LIMIT 1"
-
-# Route existence
-curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api/auth/login
-```
-
-### Layer 2: Substantiveness
-
-Is the artifact more than a stub?
-
-```bash
-# File has real content (not just exports)
-wc -l src/auth/discord.ts  # Should be > 10 lines for a real implementation
-
-# Function has a body (not just a signature)
-grep -A5 "authenticateWithDiscord" src/auth/discord.ts | grep -q "return"
-
-# Test file has actual test cases
-grep -c "it(" tests/auth.test.ts  # Should be > 0
-
-# API returns real data (not just 200 OK)
-curl -s http://localhost:3000/api/health | jq '.status' | grep -q "ok"
-```
-
-### Layer 3: Wiring
-
-Are components connected to each other?
-
-```bash
-# Module is imported where needed
-grep -q "from.*auth/discord" src/routes/auth.ts
-
-# Middleware is applied to routes
-grep -q "requireAuth" src/routes/protected.ts
-
-# Database is configured in app init
-grep -q "prisma" src/app.ts
-
-# Environment variables are referenced
-grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
-```
-
----
-
-## Verification by Feature Type
-
-### API Endpoint
-
-```
-Existence:  curl returns non-404 status
-Substance:  curl returns expected response shape (correct fields)
-Wiring:     endpoint calls the right service, middleware is applied
-```
-
-### Database Schema
-
-```
-Existence:  table/collection exists, can query without error
-Substance:  columns/fields match specification, constraints are applied
-Wiring:     application code references the schema, migrations run cleanly
-```
-
-### Authentication
-
-```
-Existence:  auth routes exist, auth module exports functions
-Substance:  login flow returns token, invalid creds return error
-Wiring:     protected routes use auth middleware, tokens are validated
-```
-
-### UI Component
-
-```
-Existence:  component file exists, exports default component
-Substance:  component renders expected elements (test or visual check)
-Wiring:     component is imported in parent, receives correct props, routes to it
-```
-
-### Configuration
-
-```
-Existence:  config file exists, environment variables documented
-Substance:  config values are used (not dead code), defaults are sensible
-Wiring:     application reads config at startup, config changes take effect
-```
-
----
-
-## Verify Command Patterns
-
-### TypeScript/JavaScript
-
-```bash
-# Type checking
-npx tsc --noEmit
-
-# Unit tests
-npm test
-npm test -- --grep "pattern"
-npx jest path/to/test
-
-# Linting
-npx eslint src/auth/
-
-# Build check
-npm run build
-```
-
-### Python
-
-```bash
-# Type checking
-mypy src/
-
-# Unit tests
-pytest tests/
-pytest tests/test_auth.py -v
-pytest -k "test_login"
-
-# Linting
-flake8 src/
-pylint src/auth/
-```
-
-### General
-
-```bash
-# File existence
-ls -la path/to/file
-
-# Content check
-grep -q "pattern" path/to/file
-
-# HTTP endpoint
-curl -s -o /dev/null -w "%{http_code}" http://localhost:PORT/path
-
-# Process running
-pgrep -f "process-name"
-
-# Port listening
-netstat -an | grep LISTEN | grep PORT
-```
-
----
-
-## Done Condition Patterns
-
-### Good Done Conditions (Observable, Falsifiable)
-
-- "User can log in with Discord and see their dashboard"
-- "API returns paginated list of items with correct total count"
-- "Database migration creates users table with all required columns"
-- "Protected routes return 401 without valid JWT"
-- "Build completes without TypeScript errors"
-
-### Bad Done Conditions (Vague, Not Falsifiable)
-
-- "Authentication is implemented" (how do you test this?)
-- "Code is clean" (subjective)
-- "Database is set up" (what does "set up" mean?)
-- "Tests pass" (which tests? what do they test?)
-- "File was created" (created with what content?)
-
-### Transformation Rule
-
-```
-Bad:  "Authentication is implemented"
-Good: "User can complete Discord OAuth flow and receive a valid JWT"
-
-Bad:  "Database is set up"
-Good: "Users table exists with id, email, name columns and can accept INSERT"
-
-Bad:  "Tests pass"
-Good: "All 5 auth middleware tests pass: valid token, expired token,
-       missing token, malformed token, and correct user extraction"
-```

package/plugins/cursor-pbr/skills/begin/templates/researcher-prompt.md.tmpl

@@ -1,20 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/begin/templates/researcher-prompt.md.tmpl -->
-<!-- Source: begin/SKILL.md | Purpose: Prompt template for spawning researcher agents during project initialization -->
-
-<project_context>
-Project: {project name from questioning}
-Description: {2-3 sentence description from questioning}
-Technology constraints: {any locked technology choices}
-User constraints: {budget, timeline, skill level, etc.}
-</project_context>
-
-<research_assignment>
-Topic: {topic - e.g., "Technology Stack Analysis"}
-Output file: .planning/research/{TOPIC}.md
-Mode: project-research
-
-Research these specific questions:
-{topic-specific questions - see below}
-</research_assignment>
-
-Write your findings to the output file using the Project Research output format from your agent definition. Use the Write tool to create the file.

package/plugins/cursor-pbr/skills/begin/templates/roadmap-prompt.md.tmpl

@@ -1,31 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/begin/templates/roadmap-prompt.md.tmpl -->
-<!-- Source: begin/SKILL.md | Purpose: Prompt template for spawning the planner agent in roadmap mode -->
-
-<project_context>
-Project: {project name}
-Description: {description}
-Depth: {quick|standard|comprehensive}
-</project_context>
-
-<roadmap_instructions>
-Create a project roadmap following the Roadmap Mode instructions in your agent definition.
-
-Read these files for context:
-- .planning/REQUIREMENTS.md — committed requirements
-- .planning/research/SUMMARY.md — research synthesis (if it exists)
-
-Phase count guidelines based on depth:
-- quick: 3-5 phases
-- standard: 5-8 phases
-- comprehensive: 8-12 phases
-
-Each phase should:
-1. Have a clear, achievable goal
-2. Map to specific REQ-IDs
-3. Build on prior phases logically
-4. Be independently verifiable
-
-Write the roadmap to .planning/ROADMAP.md using the roadmap format from your agent definition.
-</roadmap_instructions>
-
-Write the roadmap to .planning/ROADMAP.md using the Write tool.

package/plugins/cursor-pbr/skills/begin/templates/synthesis-prompt.md.tmpl

@@ -1,17 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/begin/templates/synthesis-prompt.md.tmpl -->
-<!-- Source: begin/SKILL.md | Purpose: Prompt template for spawning the synthesis agent after research completes -->
-
-<research_documents>
-Read the following research documents and synthesize them:
-{List all .planning/research/*.md files that were created}
-</research_documents>
-
-<synthesis_instructions>
-1. Read all research documents
-2. Identify consensus findings
-3. Resolve contradictions (higher source level wins)
-4. Produce a unified summary with clear recommendations
-5. Write the synthesis to .planning/research/SUMMARY.md using the Synthesis output format
-</synthesis_instructions>
-
-Write the synthesis to .planning/research/SUMMARY.md using the Write tool.

package/plugins/cursor-pbr/skills/debug/templates/continuation-prompt.md.tmpl

@@ -1,17 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/debug/templates/continuation-prompt.md.tmpl -->
-<!-- Source: skills/debug/SKILL.md | Purpose: Spawn prompt for continuation debugger investigation -->
-You are debugger. Continue investigating the following issue.
-
-Debug file: .planning/debug/{NNN}-{slug}.md
-Mode: continuation
-
-Previous findings:
-{paste investigation log and hypotheses from the debug file}
-
-Instructions:
-1. Read the debug file for full context
-2. Review what's already been tested
-3. Formulate NEW hypotheses based on prior findings
-4. Continue systematic investigation
-5. Update the debug file
-6. Return: ROOT_CAUSE_FOUND, CHECKPOINT, or INCONCLUSIVE

package/plugins/cursor-pbr/skills/debug/templates/initial-investigation-prompt.md.tmpl

@@ -1,28 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/debug/templates/initial-investigation-prompt.md.tmpl -->
-<!-- Source: skills/debug/SKILL.md | Purpose: Spawn prompt for initial debugger investigation -->
-You are debugger. Investigate the following issue systematically.
-
-Debug file: .planning/debug/{NNN}-{slug}.md
-Mode: initial_investigation
-
-Symptoms:
-- Expected: {expected}
-- Actual: {actual}
-- Reproduction: {steps}
-- Onset: {onset}
-- Scope: {scope}
-
-Instructions:
-1. Read the debug file for full context
-2. Formulate 2-3 initial hypotheses based on symptoms
-3. For each hypothesis:
-   a. State what you're testing and why
-   b. Design a specific test (command, code inspection, log check)
-   c. Execute the test
-   d. Record the result (confirmed, rejected, inconclusive)
-4. Update the debug file with findings
-5. Return one of:
-   - ROOT_CAUSE_FOUND: {cause} + FIX: {what to change}
-   - ROOT_CAUSE_FOUND: {cause} (if find_root_cause_only mode)
-   - CHECKPOINT: {what was found, what to investigate next}
-   - INCONCLUSIVE: {findings so far, suggested next approaches}

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

@@ -1,54 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/progress-display.md -->
-# 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/cursor-pbr/skills/shared/state-loading.md

@@ -1,63 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/state-loading.md -->
-# 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/cursor-pbr/templates/RESEARCH-SUMMARY.md.tmpl

@@ -1,98 +0,0 @@
-<!-- canonical: ../../pbr/templates/RESEARCH-SUMMARY.md.tmpl -->
-# 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/commands/begin.md

@@ -1,5 +0,0 @@
----
-description: "Start a new project. Deep questioning, research, requirements, and roadmap."
----
-
-This command is provided by the `dev:begin` skill.

package/plugins/pbr/commands/build.md

@@ -1,5 +0,0 @@
----
-description: "Execute all plans in a phase. Spawns agents to build in parallel, commits atomically."
----
-
-This command is provided by the `dev:build` skill.

package/plugins/pbr/commands/discuss.md

@@ -1,5 +0,0 @@
----
-description: "Talk through a phase before planning. Identifies gray areas and captures your decisions."
----
-
-This command is provided by the `dev:discuss` skill.

package/plugins/pbr/commands/milestone.md

@@ -1,5 +0,0 @@
----
-description: "Manage milestones: new, complete, audit, gaps."
----
-
-This command is provided by the `dev:milestone` skill.

package/plugins/pbr/commands/pause.md

@@ -1,5 +0,0 @@
----
-description: "Save your current session state for later resumption."
----
-
-This command is provided by the `dev:pause` skill.