@sienklogic/plan-build-run 2.54.0 → 2.55.0

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

@@ -0,0 +1,52 @@
+# CONTEXT.md Template
+
+> Referenced by: begin skill (Step 9c), discuss skill, plan skill
+> Created during /pbr:begin. Updated by /pbr:discuss and /pbr:plan --assumptions.
+
+## Structure
+
+```markdown
+# Project Context
+
+## Locked Decisions
+
+{Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE.
+ These MUST be honored by every plan and executor — no exceptions.}
+
+| Decision | Rationale | Locked By |
+|----------|-----------|-----------|
+| {e.g., "Use TypeScript"} | {User preference, team skill} | User |
+| {e.g., "PostgreSQL via Supabase"} | {Existing infrastructure} | User |
+
+## User Constraints
+
+{Budget, timeline, skill level, hosting, team size — factors that shape planning}
+
+- {e.g., "Solo developer, no team"}
+- {e.g., "Deploy to Hetzner VPS"}
+- {e.g., "Must work offline"}
+
+## Deferred Ideas
+
+{Features explicitly moved to v2 or out-of-scope. Plans MUST NOT include these.}
+
+| Idea | Reason Deferred |
+|------|----------------|
+| {feature} | {reason} |
+
+## Claude's Discretion Areas
+
+{Areas where the planner can make implementation choices without asking the user.
+ Document the choice made and rationale when exercised.}
+
+| Area | Choice Made | Rationale |
+|------|------------|-----------|
+| {e.g., "State management library"} | {e.g., "Zustand"} | {e.g., "Lightweight, fits project size"} |
+```
+
+## Rules
+
+- Locked decisions are immutable once set — only the user can change them
+- Deferred ideas must NEVER appear in plans
+- Discretion areas are documented when the planner exercises choice
+- Phase-level CONTEXT.md files (in phase directories) override project-level for that phase

package/plugins/codex-pbr/templates/INTEGRATION-REPORT.md.tmpl

@@ -0,0 +1,167 @@
+<!-- Source: agents/integration-checker.md | Purpose: Output format for cross-phase integration verification reports -->
+
+```markdown
+# Integration Verification Report
+
+> Verified: {date}
+> Phases checked: {comma-separated list of phase IDs}
+> Status: **{INTEGRATED | GAPS_FOUND}**
+
+## Phase Dependency Graph
+
+```
+Phase 01 (Setup) ──provides──→ Phase 02 (Auth)
+Phase 01 (Setup) ──provides──→ Phase 03 (Core)
+Phase 02 (Auth)  ──provides──→ Phase 03 (Core)
+Phase 02 (Auth)  ──provides──→ Phase 04 (Frontend)
+Phase 03 (Core)  ──provides──→ Phase 04 (Frontend)
+```
+
+## 1. Export/Import Wiring
+
+### Export Status Summary
+
+| Phase | Total Exports | Consumed | Orphaned | Unused Imports | Mismatched |
+|-------|--------------|----------|----------|---------------|------------|
+| 01 | {n} | {n} | {n} | {n} | {n} |
+| 02 | {n} | {n} | {n} | {n} | {n} |
+
+### Detailed Export Map
+
+| Export | Source Phase | Source File:Line | Consumer(s) | Status |
+|--------|------------|-----------------|-------------|--------|
+| DatabaseConnection | 01 | src/db/conn.ts:5 | Phase 02, 03 | CONSUMED |
+| ConfigLoader | 01 | src/config/index.ts:12 | Phase 03 | CONSUMED |
+| ThemeProvider | 04 | src/theme/provider.tsx:8 | - | ORPHANED |
+
+### Orphaned Exports (created but never used)
+
+| Export | Phase | File | Line | Likely Intended Consumer |
+|--------|-------|------|------|------------------------|
+| {name} | {phase} | {file} | {line} | {best guess or "unknown"} |
+
+### Unused Imports (imported but symbol never called)
+
+| File | Imported Symbol | Source Module | Line |
+|------|----------------|--------------|------|
+| {file} | {symbol} | {module} | {line} |
+
+## 2. API Coverage
+
+### Route Coverage Matrix
+
+| Route | Method | Handler | Frontend Caller | Auth | Status |
+|-------|--------|---------|----------------|------|--------|
+| /api/users | GET | users.ts:12 | UserList.tsx:34 | YES | COVERED |
+| /api/users/:id | DELETE | users.ts:45 | - | YES | NO_CALLER |
+| /api/settings | PUT | - | Settings.tsx:22 | - | NO_HANDLER |
+
+### Uncovered Routes (backend exists, no frontend caller)
+
+| Route | Method | Handler | Possible Reason |
+|-------|--------|---------|----------------|
+| {route} | {method} | {file:line} | {guess: future feature, admin only, etc.} |
+
+### Missing Handlers (frontend calls, no backend route)
+
+| Frontend File | Calls | Expected Route | Expected Method |
+|--------------|-------|---------------|----------------|
+| {file} | fetch('/api/X') | /api/X | GET |
+
+## 3. Auth Protection
+
+### Route Protection Summary
+
+| Category | Total | Protected | Unprotected | Status |
+|----------|-------|-----------|-------------|--------|
+| API Routes | {n} | {n} | {n} | {OK/ISSUES} |
+| Pages | {n} | {n} | {n} | {OK/ISSUES} |
+| Public Routes | {n} | - | {n} | OK |
+
+### Unprotected Routes (SECURITY ISSUES)
+
+| Route | Method | Handler | Should Protect | Evidence |
+|-------|--------|---------|---------------|----------|
+| {route} | {method} | {file:line} | YES | No auth middleware in chain |
+
+### Auth Flow Completeness
+
+| Step | Status | Evidence |
+|------|--------|----------|
+| Login form exists | {YES/NO} | {file:line} |
+| Auth API called | {YES/NO} | {file:line} |
+| Token/session created | {YES/NO} | {file:line} |
+| Token sent with requests | {YES/NO} | {file:line} |
+| Auth middleware applied | {YES/NO} | {file:line} |
+| Unauthorized redirect | {YES/NO} | {file:line} |
+
+## 4. End-to-End Flows
+
+### Flow 1: {Flow Name} - {STATUS}
+
+| Step | Description | Component | Exists | Connected to Next | Evidence |
+|------|------------|-----------|--------|-------------------|----------|
+| 1 | {step desc} | {file} | YES | YES | import at L12, call at L45 |
+| 2 | {step desc} | {file} | YES | NO | handler exists but not called |
+| 3 | {step desc} | - | NO | - | File not found |
+
+**Break point**: {If BROKEN, where exactly the chain breaks}
+**Impact**: {What user action fails because of this break}
+
+### Flow 2: {Flow Name} - {STATUS}
+...
+
+## 5. Data-Flow Propagation
+
+### Cross-Boundary Data Flows
+
+| Data Field | Source | Intermediate Steps | Destination | Status |
+|------------|--------|-------------------|-------------|--------|
+| {field name} | {origin, e.g., hook stdin `data.session_id`} | {module1:L12 → module2:L45} | {dest, e.g., metrics.jsonl `session_id`} | PROPAGATED |
+| {field name} | {origin} | {module1:L12 → module2:L45} | {dest} | DATA_DROPPED |
+
+### Data-Flow Issues
+
+| Field | Dropped At | Available In Scope | Passed Instead | Fix |
+|-------|-----------|-------------------|----------------|-----|
+| {field} | {file:line} | `data.session_id` | `undefined` | Pass `data.session_id` |
+
+## 6. Integration Issues Summary
+
+### Critical Issues (system cannot function)
+
+1. **{Issue}**: {description with evidence}
+   - Impact: {what breaks}
+   - Fix: {recommended action}
+
+### Warnings (partial functionality)
+
+1. **{Issue}**: {description with evidence}
+   - Impact: {what's degraded}
+   - Fix: {recommended action}
+
+### Info (cleanup opportunities)
+
+1. **{Issue}**: {description}
+   - Fix: {recommended action}
+
+## 7. Integration Score
+
+| Category | Items Checked | Passed | Failed | Score |
+|----------|--------------|--------|--------|-------|
+| Export wiring | {n} | {n} | {n} | {%} |
+| API coverage | {n} | {n} | {n} | {%} |
+| Auth protection | {n} | {n} | {n} | {%} |
+| E2E flows | {n} | {n} | {n} | {%} |
+| Data-flow propagation | {n} | {n} | {n} | {%} |
+| **Overall** | {n} | {n} | {n} | **{%}** |
+
+## Recommendations
+
+{Prioritized list of actions to fix integration issues}
+
+1. **[CRITICAL]** {Most important fix}
+2. **[CRITICAL]** {Second most important}
+3. **[WARNING]** {Important but not blocking}
+4. ...
+```

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

@@ -0,0 +1,97 @@
+# 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/codex-pbr/templates/ROADMAP.md.tmpl

@@ -0,0 +1,47 @@
+# Project Roadmap
+
+> Generated: {date}
+> Total phases: {n}
+> Estimated plans: {n}
+
+## Phase Overview
+
+| Phase | Name | Goal | Plans | Wave | Status |
+|-------|------|------|-------|------|--------|
+| 01 | Project Setup | Development environment ready | 2 | 1 | pending |
+| 02 | Authentication | Users can sign in | 3 | 1 | pending |
+| 03 | Core Models | Data layer complete | 4 | 2 | pending |
+| ... | ... | ... | ... | ... | ... |
+
+## Dependency Graph
+
+```
+Phase 01 ──→ Phase 02 ──→ Phase 04
+         └──→ Phase 03 ──→ Phase 05
+                       └──→ Phase 04
+```
+
+---
+
+## Milestone: {project name} v1.0
+
+**Goal:** {overall project goal from requirements}
+**Phases:** 1 - {n}
+
+## Phase Details
+
+### Phase 01: Project Setup
+
+**Goal**: {goal statement}
+**Must-Haves**:
+- {truth 1}
+- {truth 2}
+
+**Planned Plans**:
+1. {plan name} (Wave 1, autonomous)
+2. {plan name} (Wave 1, autonomous)
+
+**Dependencies**: None (starting phase)
+
+### Phase 02: Authentication
+...

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

@@ -0,0 +1,95 @@
+# SUMMARY-complex.md Template
+
+> 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}
+```
+
+## 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,117 @@
+<!-- Source: agents/verifier.md | Purpose: Detailed output format for verification reports produced by the verifier agent -->
+
+```yaml
+---
+phase: "{phase_id}"
+verified: "{ISO timestamp}"
+status: "passed"           # passed | gaps_found | human_needed
+is_re_verification: false  # true if re-verifying after gap closure
+score:
+  total_must_haves: {n}
+  verified: {n}
+  failed: {n}
+  partial: {n}
+  human_needed: {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}
+---
+
+# Phase Verification: {phase_name}
+
+> Verified: {date}
+> Status: **{STATUS}**
+> Score: {verified}/{total} 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. ...
+```