@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/codex-pbr/templates/ROADMAP.md.tmpl

@@ -0,0 +1,105 @@
+<!-- Downstream consumers:
+  - Planner agent: reads phase goals/dependencies for plan creation. Needs: phase Goal, Provides, Depends on fields.
+  - Build agent: reads current phase details for execution context. Needs: phase name, goal, planned plans.
+  - Status skill: reads progress table for completion tracking. Needs: Progress table with Plans Complete column.
+  - check-plan-format.js (validateRoadmap): parses ## Milestone: sections and ### Phase NN: headings. Needs: exact heading format, **Goal:**, **Provides:**, **Depends on:** in each phase.
+  - check-roadmap-sync.js: parses progress table rows against STATE.md phase status. Needs: progress table structure unchanged.
+  - Dashboard parseRoadmapMd: parses Phase Overview table. Needs: standard table format.
+  Breaks if missing: Planner creates plans without dependency awareness; validators reject malformed roadmaps; dashboard shows empty roadmap.
+-->
+# Project Roadmap
+
+> Generated: {date}
+> Total phases: {n}
+> Estimated plans: {n}
+
+## Dependency Graph
+
+<!-- Guidelines: ASCII art showing phase dependencies. Arrow direction = "depends on".
+     Keep it simple -- complex graphs should reference a separate dependency map file. -->
+```
+Phase 01 ──> Phase 02 ──> Phase 04
+         └──> Phase 03 ──> Phase 05
+                       └──> Phase 04
+```
+
+---
+
+## Milestone: {project name} v1.0
+
+<!-- Guidelines: Milestone heading MUST use exact format "## Milestone: {name}".
+     The validator splits content by this heading pattern. -->
+**Goal:** {overall project goal from requirements}
+**Phases:** 1 - {n}
+**Requirement coverage:** {covered}/{total} requirements mapped
+
+### Phase Checklist
+<!-- Guidelines: One checkbox per phase. Format: "- [ ] Phase NN: {name} -- {one-line goal}".
+     Check off phases as they complete. -->
+- [ ] Phase 01: {name} -- {one-line goal summary}
+- [ ] Phase 02: {name} -- {one-line goal summary}
+- [ ] Phase 03: {name} -- {one-line goal summary}
+
+## Phase Details
+
+### Phase 01: Project Setup
+
+<!-- Guidelines: Phase heading MUST use exact format "### Phase NN: {name}".
+     Each phase MUST include **Goal:**, **Provides:**, and **Depends on:** fields.
+     The validator checks for all three -- missing any triggers a warning. -->
+**Goal**: {goal statement}
+**Provides**:
+- {what this phase delivers for downstream phases}
+**Depends on**: None (starting phase)
+
+**Must-Haves**:
+- {truth 1}
+- {truth 2}
+
+**Planned Plans**:
+<!-- Guidelines: Numbered list of plans within this phase. Include wave and autonomy level.
+     Wave indicates parallelization grouping. Autonomous plans need no human checkpoints. -->
+1. {plan name} (Wave 1, autonomous)
+2. {plan name} (Wave 1, autonomous)
+
+### Phase 02: {name}
+
+**Goal**: {goal statement}
+**Provides**:
+- {deliverable}
+**Depends on**: Phase 01
+
+**Must-Haves**:
+- {truth 1}
+
+**Planned Plans**:
+1. {plan name} (Wave 1, autonomous)
+
+## Progress
+
+<!-- Guidelines: Progress table MUST include "Plans Complete" column header with proper separator row.
+     The validator checks for this exact column name and separator format (|---|---|...).
+     Update this table as plans complete. -->
+| Phase | Plans Complete | Status |
+|-------|---------------|--------|
+| Phase 01 | 0/2 | Not Started |
+| Phase 02 | 0/1 | Not Started |
+
+## Evolution
+
+This document evolves through the project lifecycle:
+- **Created by:** `/pbr:new-project` during roadmap generation
+- **Updated by:** `/pbr:execute-phase` as phases and plans complete (progress table, phase checklist)
+- **Updated by:** `/pbr:discuss-phase` if scope changes require phase restructuring
+- **Referenced by:** `/pbr:plan-phase` for phase scoping and dependency resolution
+
+## Quality Criteria
+
+A good ROADMAP.md satisfies:
+- [ ] Every phase has **Goal:**, **Provides:**, and **Depends on:** fields
+- [ ] Phase numbers are sequential with no gaps
+- [ ] Progress table row count matches phase count
+- [ ] Dependencies form a DAG (no circular dependencies)
+- [ ] Phase Checklist items match Phase Details sections 1:1
+- [ ] Requirement coverage line accounts for all Must-priority requirements
+- [ ] Dependency graph is consistent with phase **Depends on:** declarations

package/plugins/codex-pbr/templates/SUMMARY-complex.md.tmpl

@@ -0,0 +1,112 @@
+# SUMMARY-complex.md Template
+
+<!-- Downstream consumers:
+  - check-plan-format.js (validateSummary): validates frontmatter fields (phase, plan, status, provides, requires, key_files). Does NOT validate body sections.
+  - Status skill: reads plan completion status and metrics. Needs: frontmatter status field, metrics block.
+  - Dashboard: displays plan details and accomplishments. Needs: frontmatter + body structure.
+  Breaks if missing: Validator rejects summary without required frontmatter; status skill cannot track completion; dashboard shows empty plan card.
+-->
+
+> Use when: decisions were made OR fileCount > 6
+> Referenced by: executor agent (complex plans, architectural work)
+
+## Frontmatter (YAML)
+
+```yaml
+---
+phase: "{phase_id}"
+plan: "{plan_id}"
+status: "complete"           # complete | partial | checkpoint
+subsystem: "{main subsystem affected}"
+tags:
+  - "{tag1}"
+requires:
+  - "{plan_id}: {artifact}"
+provides:
+  - "{export/artifact description}"
+affects:
+  - "{affected area 1}"
+tech_stack:
+  - "{technology used}"
+key_files:
+  - "{file1}: {what it does}"
+key_decisions:
+  - "{decision 1}: {rationale}"
+patterns:
+  - "{pattern used}: {where}"
+metrics:
+  duration_minutes: {n}
+  tasks_completed: {n}
+  tasks_total: {n}
+  commits: {n}
+  files_created: {n}
+  files_modified: {n}
+deferred:
+  - "{thing noticed but not implemented}"
+self_check_failures:
+  - "{failure description}"
+architecture_notes:
+  - "{key architectural decision and why}"
+---
+```
+
+## Body Structure
+
+```markdown
+# Plan Summary: {plan_id}
+
+## What Was Built
+
+{2-3 paragraph description of what was accomplished}
+
+## Architecture Decisions
+
+| Decision | Options Considered | Chosen | Rationale |
+|----------|-------------------|--------|-----------|
+| {decision} | {opt1}, {opt2} | {chosen} | {why} |
+
+## Task Results
+
+| Task | Status | Commit | Files | Verify |
+|------|--------|--------|-------|--------|
+| {task_id}: {name} | done | {hash} | {count} | passed |
+
+## Key Implementation Details
+
+{Important details about HOW things were implemented}
+
+## Integration Points
+
+{How this plan connects to other plans - imports, exports, shared state}
+
+## Known Issues
+
+{Issues discovered during execution}
+
+## Dependencies Provided
+
+{What other plans can now depend on}
+
+## Deferred Items
+
+{Items noticed but intentionally deferred - with rationale}
+
+## Quality Criteria
+
+A good plan summary satisfies:
+- [ ] All frontmatter fields are populated (no empty or placeholder values)
+- [ ] key_files paths reference files that exist in the repository
+- [ ] What Was Built section describes concrete outcomes, not process
+- [ ] Architecture Decisions table documents any deviations from the plan
+- [ ] Task Results table has a row for every task in the plan
+- [ ] Deferred Items section explains rationale for each deferral
+```
+
+## Selection Heuristic
+
+Use this template when ANY of the following are true:
+- Key architectural decisions were made during execution
+- Total files created or modified > 6
+- Deviations from the plan occurred
+- Multiple integration points were established
+- The plan touched shared infrastructure or patterns

package/plugins/codex-pbr/templates/SUMMARY-minimal.md.tmpl

@@ -0,0 +1,48 @@
+# SUMMARY-minimal.md Template
+
+> Use when: taskCount <= 2 AND fileCount <= 3
+> Referenced by: executor agent (quick tasks, simple plans)
+
+## Frontmatter (YAML)
+
+```yaml
+---
+phase: "{phase_id}"
+plan: "{plan_id}"
+status: "complete"           # complete | partial | checkpoint
+requires: []
+provides:
+  - "{export/artifact description}"
+key_files:
+  - "{file1}: {what it does}"
+deferred: []
+metrics:
+  tasks_completed: {n}
+  tasks_total: {n}
+  commits: {n}
+---
+```
+
+## Body Structure
+
+```markdown
+# Plan Summary: {plan_id}
+
+## What Was Built
+
+{1 paragraph description}
+
+## Task Results
+
+| Task | Status | Commit | Files |
+|------|--------|--------|-------|
+| {task_id}: {name} | done | {hash} | {count} |
+```
+
+## Selection Heuristic
+
+Use this template when ALL of the following are true:
+- Total tasks in the plan <= 2
+- Total files created or modified <= 3
+- No key decisions were made
+- No deviations from the plan occurred

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

@@ -0,0 +1,81 @@
+# SUMMARY.md Template
+
+> Referenced by: executor agent, build skill, review skill
+> Do not edit this template during execution — copy the structure into your output.
+
+## Frontmatter (YAML)
+
+```yaml
+---
+phase: "{phase_id}"
+plan: "{plan_id}"
+status: "complete"           # complete | partial | checkpoint
+subsystem: "{main subsystem affected}"
+tags:
+  - "{tag1}"
+  - "{tag2}"
+requires:                    # What this plan needs from other plans
+  - "{plan_id}: {artifact}"
+provides:                    # What this plan produces for other plans
+  - "{export/artifact description}"
+affects:
+  - "{affected area 1}"
+  - "{affected area 2}"
+tech_stack:
+  - "{technology used}"
+key_files:
+  - "{file1}: {what it does}"
+  - "{file2}: {what it does}"
+key_decisions:
+  - "{decision 1}: {rationale}"
+patterns:
+  - "{pattern used}: {where}"
+metrics:
+  duration_minutes: {n}
+  tasks_completed: {n}
+  tasks_total: {n}
+  commits: {n}
+  files_created: {n}
+  files_modified: {n}
+deferred:
+  - "{thing noticed but not implemented}"
+self_check_failures:         # Only present if self-check found issues
+  - "{failure description}"
+---
+```
+
+## Body Structure
+
+```markdown
+# Plan Summary: {plan_id}
+
+## What Was Built
+
+{2-3 paragraph description of what was accomplished}
+
+## Task Results
+
+| Task | Status | Commit | Files | Verify |
+|------|--------|--------|-------|--------|
+| {task_id}: {name} | done | {hash} | {count} | passed |
+
+## Key Implementation Details
+
+{Important details about HOW things were implemented that future plans need to know}
+
+## Known Issues
+
+{Any issues discovered during execution that weren't blockers but should be tracked}
+
+## Dependencies Provided
+
+{What other plans can now depend on — exports, files, APIs created}
+```
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `complete` | All tasks completed successfully |
+| `partial` | Some tasks completed, execution stopped |
+| `checkpoint` | Execution paused at a checkpoint task, waiting for human |

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

@@ -0,0 +1,119 @@
+<!-- Source: agents/verifier.md | Purpose: Detailed output format for verification reports produced by the verifier agent -->
+
+```yaml
+---
+phase: "{phase_id}"
+status: "passed"           # passed | gaps_found | human_needed
+checked_at: "{ISO timestamp}"
+is_re_verification: false  # true if re-verifying after gap closure
+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}"
+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}
+
+> Checked at: {date}
+> Status: **{STATUS}**
+> Score: {must_haves_passed}/{must_haves_checked} must-haves verified
+> Re-verification: {yes/no}
+
+## Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | {truth statement} | VERIFIED | {evidence summary with file paths and line numbers} |
+| 2 | {truth statement} | FAILED | {what's wrong, what was expected, what was found} |
+| 3 | {truth statement} | HUMAN_NEEDED | {why it can't be verified programmatically} |
+
+## Artifact Verification
+
+| # | Artifact | L1: Exists | L2: Substantive | L3: Wired | Status |
+|---|----------|-----------|-----------------|-----------|--------|
+| 1 | `{file/export}` | YES | YES (142 lines, real logic) | WIRED (imported by 3 files) | PASS |
+| 2 | `{file/export}` | YES | STUB (TODO at L42, empty handler L67) | N/A | FAIL |
+| 3 | `{file/export}` | YES | YES | ORPHANED (not imported anywhere) | FAIL |
+| 4 | `{file/export}` | NO | N/A | N/A | FAIL |
+
+## Key Link Verification
+
+| # | Link Description | Source | Target | Status | Evidence |
+|---|-----------------|--------|--------|--------|----------|
+| 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}
+
+- **Must-Have**: {which must-have this gap blocks}
+- **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}
+...
+
+## Human Verification Items
+
+{Only present if there are items requiring human verification}
+
+### Item 1: {What needs checking}
+
+- **Must-Have**: {which must-have this relates to}
+- **Why Manual**: {why it can't be verified automatically}
+- **How to Test**: {step-by-step instructions}
+- **Expected Result**: {what success looks like}
+
+## Anti-Pattern Scan
+
+| Pattern | Count | Severity | Files |
+|---------|-------|----------|-------|
+| TODO/FIXME comments | {n} | {low/medium/high} | {file list} |
+| Stub implementations | {n} | {high} | {file list} |
+| Console.log in production | {n} | {low} | {file list} |
+| Skipped tests | {n} | {medium} | {file list} |
+| Hardcoded secrets | {n} | {critical} | {file list} |
+| Empty catch blocks | {n} | {medium} | {file list} |
+
+## Regressions
+
+{Only present in re-verification mode}
+
+| # | Must-Have | Previous Status | Current Status | Evidence |
+|---|----------|----------------|----------------|----------|
+| 1 | {must-have} | VERIFIED | FAILED | {what changed} |
+
+## Summary
+
+### Phase Health
+- **Must-haves**: {n}/{total} verified ({percentage}%)
+- **Gaps**: {n} blocking, {n} non-blocking
+- **Anti-patterns**: {n} total ({n} critical)
+- **Human items**: {n} pending
+
+### Recommendations
+1. {Most important action to take}
+2. {Second most important}
+3. ...
+```

package/plugins/codex-pbr/templates/codebase/ARCHITECTURE.md.tmpl

@@ -0,0 +1,98 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for ARCHITECTURE.md codebase analysis -->
+# Architecture
+
+> Analyzed: {date}
+> Pattern: {MVC / Layered / Hexagonal / Microservices / Monolith / etc.}
+
+## Pattern Overview
+
+{2-3 paragraphs describing the overall architectural pattern with evidence from the codebase}
+
+**Evidence**: {file paths, import patterns, directory structure that support this classification}
+
+## Layers
+
+| Layer | Purpose | Directory | Key Files |
+|-------|---------|-----------|-----------|
+| {Presentation} | {UI rendering} | {src/components/} | {App.tsx, Layout.tsx} |
+| {API/Routes} | {HTTP handling} | {src/routes/ or src/app/api/} | {users.ts, auth.ts} |
+| {Business Logic} | {Core domain} | {src/services/} | {UserService.ts} |
+| {Data Access} | {Database interaction} | {src/repositories/ or src/db/} | {UserRepo.ts} |
+| {Infrastructure} | {External services} | {src/lib/ or src/integrations/} | {email.ts, storage.ts} |
+
+### Layer Rules
+
+{How layers communicate — what imports what? What are the dependency rules?}
+
+```
+Presentation → API → Business → Data Access → Database
+                ↓
+            Infrastructure
+```
+
+## Data Flow
+
+### Request Lifecycle
+
+{How a typical request flows through the system}
+
+```
+1. Client sends request
+2. → {Router/Framework} routes to handler
+3. → {Middleware} runs (auth, validation, logging)
+4. → {Controller/Handler} processes request
+5. → {Service} executes business logic
+6. → {Repository/Model} queries database
+7. → Response returns through the stack
+```
+
+### State Management
+
+| Context | Approach | Implementation | Files |
+|---------|----------|---------------|-------|
+| Client state | {Redux / Zustand / Context / etc.} | {how it's structured} | {store files} |
+| Server state | {React Query / SWR / etc.} | {how it's used} | {hook files} |
+| Session state | {JWT / cookies / etc.} | {how it's managed} | {auth files} |
+
+## Key Abstractions
+
+| Abstraction | Purpose | Implementation | Used By |
+|-------------|---------|---------------|---------|
+| {Repository} | {Database access} | {Abstract class + implementations} | {Services} |
+| {Middleware} | {Cross-cutting concerns} | {Function signature} | {Routes} |
+| {DTO/Schema} | {Data validation} | {Zod schemas / class-validator} | {Routes, Services} |
+
+## Entry Points
+
+| Type | File | Config | Notes |
+|------|------|--------|-------|
+| Web app | {src/app/page.tsx} | {port 3000} | {Next.js App Router} |
+| API server | {src/server.ts} | {port 8080} | {Express server} |
+| CLI | {src/cli.ts} | - | {Commander.js} |
+| Workers | {src/workers/} | {queue config} | {Bull/BullMQ} |
+| Cron | {src/cron/} | {schedule} | {node-cron} |
+
+## Error Handling Strategy
+
+| Layer | Pattern | Implementation |
+|-------|---------|---------------|
+| API | {Error middleware + HTTP status codes} | {src/middleware/error.ts} |
+| Service | {Custom error classes} | {src/errors/} |
+| Client | {Error boundaries + toast notifications} | {src/components/ErrorBoundary.tsx} |
+
+### Error Flow
+
+```
+Service throws AppError → Controller catches → Error middleware formats response → Client displays
+```
+
+## Security Architecture
+
+| Aspect | Implementation | Files |
+|--------|---------------|-------|
+| Authentication | {how auth works} | {files} |
+| Authorization | {RBAC / ABAC / etc.} | {files} |
+| Input validation | {where and how} | {files} |
+| CORS | {configuration} | {files} |
+| Rate limiting | {if present} | {files} |
+| CSRF protection | {if present} | {files} |

package/plugins/codex-pbr/templates/codebase/CONCERNS.md.tmpl

@@ -0,0 +1,93 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for CONCERNS.md codebase analysis -->
+# Concerns & Technical Debt
+
+> Analyzed: {date}
+> Severity summary: {n critical, n high, n medium, n low}
+
+## Technical Debt
+
+| # | Area | Issue | Severity | Files | Evidence |
+|---|------|-------|----------|-------|----------|
+| 1 | {area} | {what's wrong} | critical/high/medium/low | {file paths} | {what you saw} |
+| 2 | {area} | {what's wrong} | {severity} | {file paths} | {what you saw} |
+
+### Debt Details
+
+#### TD-1: {Issue Title}
+
+**Severity**: {critical / high / medium / low}
+**Files**: {list of affected files}
+**Description**: {detailed description of the issue}
+**Evidence**: {specific code examples, line numbers}
+**Impact**: {what problems this causes or could cause}
+**Recommendation**: {specific action to fix}
+
+## Known Bugs
+
+| # | Description | Severity | Location | Reproduction |
+|---|-------------|----------|----------|--------------|
+| 1 | {bug description} | {severity} | {file:line} | {how to trigger} |
+
+## Security Considerations
+
+| # | Issue | Severity | Location | Recommendation |
+|---|-------|----------|----------|----------------|
+| 1 | {Missing input validation on API} | high | {src/routes/users.ts} | {Add zod schema validation} |
+| 2 | {Hardcoded secret in source} | critical | {src/config.ts:42} | {Move to environment variable} |
+| 3 | {SQL injection risk} | critical | {src/db/queries.ts:15} | {Use parameterized queries} |
+| 4 | {No rate limiting} | medium | {src/server.ts} | {Add express-rate-limit} |
+| 5 | {No CSRF protection} | medium | {src/routes/} | {Add csrf tokens} |
+
+## Performance Risks
+
+| # | Issue | Location | Impact | Recommendation |
+|---|-------|----------|--------|----------------|
+| 1 | {N+1 query in user list} | {src/routes/users.ts:30} | {Slow page load} | {Use eager loading} |
+| 2 | {No pagination on large queries} | {src/routes/posts.ts:15} | {Memory exhaustion} | {Add cursor pagination} |
+| 3 | {Synchronous file operations} | {src/utils/file.ts} | {Blocks event loop} | {Use async fs methods} |
+
+## Fragile Areas
+
+| # | Area | Why Fragile | Impact of Breaking | Files |
+|---|------|-------------|-------------------|-------|
+| 1 | {Auth middleware} | {Tightly coupled to 5 services} | {All protected routes fail} | {files} |
+| 2 | {Data migration} | {No rollback mechanism} | {Data loss on failure} | {files} |
+
+## Dependency Risks
+
+| Package | Version | Issue | Recommendation |
+|---------|---------|-------|----------------|
+| {package} | {version} | {Deprecated / EOL / Known vulnerability} | {Update to X / Replace with Y} |
+
+## Scaling Limitations
+
+| # | Limitation | When It Breaks | Current State | Fix Approach |
+|---|-----------|---------------|---------------|-------------|
+| 1 | {Single database instance} | {>1000 concurrent users} | {adequate for current load} | {Read replicas} |
+| 2 | {In-memory session store} | {Multiple server instances} | {single instance} | {Redis session store} |
+
+## Missing Infrastructure
+
+| Category | Status | Impact | Priority |
+|----------|--------|--------|----------|
+| Error monitoring | {absent/partial/present} | {bugs go unnoticed} | {high} |
+| Logging | {absent/partial/present} | {hard to debug production} | {high} |
+| CI/CD | {absent/partial/present} | {manual deployments} | {medium} |
+| Automated tests | {absent/partial/present} | {regressions not caught} | {high} |
+| Documentation | {absent/partial/present} | {onboarding difficulty} | {low} |
+| Backup/Recovery | {absent/partial/present} | {data loss risk} | {critical} |
+| Health checks | {absent/partial/present} | {outages not detected} | {medium} |
+
+## Recommendations (Prioritized)
+
+### Critical (Fix Immediately)
+1. {Recommendation with specific action}
+
+### High (Fix Soon)
+1. {Recommendation with specific action}
+
+### Medium (Plan to Fix)
+1. {Recommendation with specific action}
+
+### Low (When Convenient)
+1. {Recommendation with specific action}