@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/templates/INTEGRATION-REPORT.md.tmpl -->
 <!-- Source: agents/integration-checker.md | Purpose: Output format for cross-phase integration verification reports -->
 
 ```markdown
@@ -112,7 +111,22 @@ Phase 03 (Core)  ──provides──→ Phase 04 (Frontend)
 ### Flow 2: {Flow Name} - {STATUS}
 ...
 
-## 5. Integration Issues Summary
+## 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)
 
@@ -131,7 +145,7 @@ Phase 03 (Core)  ──provides──→ Phase 04 (Frontend)
 1. **{Issue}**: {description}
    - Fix: {recommended action}
 
-## 6. Integration Score
+## 7. Integration Score
 
 | Category | Items Checked | Passed | Failed | Score |
 |----------|--------------|--------|--------|-------|
@@ -139,6 +153,7 @@ Phase 03 (Core)  ──provides──→ Phase 04 (Frontend)
 | 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

package/plugins/cursor-pbr/templates/PROJECT.md.tmpl

@@ -0,0 +1,111 @@
+<!-- Downstream consumers:
+  - Planner agent: reads Vision/Scope to bound phases. Needs: project name, in-scope features, constraints, success criteria.
+  - Executor agent: reads Constraints/Key Decisions for implementation choices. Needs: locked technology decisions.
+  - Verifier agent: reads Success Criteria for pass/fail. Needs: testable, observable criteria.
+  - Dashboard PlanningReader: parses heading structure. Needs: standard ## headings.
+  Breaks if missing: Planner plans without boundaries; verifier has no criteria; dashboard shows empty project card.
+-->
+# {project_name}
+
+> {ONE sentence core value statement}
+<!-- Guidelines: One sentence, under 20 words. State what the project IS and its primary value. -->
+
+## What This Is
+
+<!-- Guidelines: 2-3 sentences. Product description, target user, problem being solved.
+     Avoid implementation details -- this is a "what" not "how" section. -->
+{2-3 sentences describing the product and problem it solves. Who is it for? What does it replace or improve?}
+
+## Core Value
+
+<!-- Guidelines: Expand on the one-liner. What makes this worth building? What does it replace or improve?
+     Keep to 2-3 sentences. This is the "why" behind the project. -->
+{Why this project matters -- the value proposition in 2-3 sentences.}
+
+## Requirements Summary
+
+<!-- Guidelines: Bulleted features grouped by area. Each In Scope item must trace to a REQ-ID in REQUIREMENTS.md. -->
+
+### In Scope (v1)
+
+- {Feature area}: {brief description}
+
+### Out of Scope
+
+<!-- Guidelines: Explicit exclusions with rationale. Prevents scope creep during planning. -->
+- {Feature}: {brief reason why excluded}
+
+## Context
+
+### Constraints
+
+<!-- Guidelines: Budget, timeline, team size, hosting, skill level. Non-negotiable external factors.
+     Even if there are no constraints, state "None identified" rather than omitting. -->
+- {constraint}
+
+### Key Decisions
+
+<!-- Guidelines: Technology and architecture decisions locked at project start. Each needs rationale.
+     These are LOCKED after creation -- changes require explicit scope-change discussion via /pbr:discuss-phase. -->
+| Decision | Rationale | Decided By |
+|----------|-----------|------------|
+| {decision} | {rationale} | {user/claude} |
+
+## Success Criteria
+
+<!-- Guidelines: Observable, testable conditions that define project success. No subjective adjectives.
+     Each should be verifiable by an automated test or manual inspection. -->
+- {Criterion 1 -- specific and measurable}
+- {Criterion 2 -- specific and measurable}
+- {Criterion 3 -- specific and measurable}
+
+## Milestones
+
+{project_name} planned in {phase_count} phases across {milestone_count} milestone(s).
+See `.planning/ROADMAP.md` for phase details.
+
+{{#brownfield}}
+## Existing Codebase
+
+### Validated Requirements
+
+<!-- Guidelines: Requirements inferred from existing code analysis. Each should reference the source file
+     or pattern that demonstrates the capability. Confidence reflects how certain the inference is. -->
+| Inferred Requirement | Evidence | Confidence |
+|---------------------|----------|------------|
+| {requirement} | {source file/pattern} | {HIGH/MEDIUM/LOW} |
+
+### Existing Architecture
+
+<!-- Guidelines: Current system structure as discovered by codebase scan.
+     Reference .planning/codebase/ analysis files where available. -->
+{Architecture summary from scan results}
+
+### Known Tech Debt
+
+<!-- Guidelines: Issues discovered during codebase analysis that should be addressed.
+     Include impact assessment and suggested remediation priority. -->
+- {debt item}: {impact and suggested remediation}
+{{/brownfield}}
+
+## Evolution
+
+This document evolves through the project lifecycle:
+- **Created by:** `/pbr:new-project` during project initialization
+- **Updated by:** `/pbr:discuss-phase` when scope or constraints change
+- **Frozen after:** Roadmap creation -- subsequent changes require explicit scope-change discussion via `/pbr:discuss-phase`
+
+## Quality Criteria
+
+A good PROJECT.md satisfies:
+- [ ] Core value is one sentence, under 20 words
+- [ ] What This Is answers: what, who, why in 2-3 sentences
+- [ ] Every In Scope item maps to at least one REQ-ID in REQUIREMENTS.md
+- [ ] Every Out of Scope item has a rationale
+- [ ] Success criteria are observable and testable
+- [ ] Key Decisions table has at least one entry
+- [ ] Constraints section is populated (even if "none identified")
+{{#brownfield}}
+- [ ] Validated Requirements cite evidence from existing code
+- [ ] Existing Architecture references codebase scan files
+{{/brownfield}}

package/plugins/cursor-pbr/templates/REQUIREMENTS.md.tmpl

@@ -0,0 +1,96 @@
+<!-- Downstream consumers:
+  - Planner agent: reads requirements for phase scoping. Needs: REQ-IDs, priorities, categories.
+  - Verifier agent: reads for completion checking. Needs: requirement status, testable statements.
+  - Roadmap skill: reads for phase-to-requirement mapping. Needs: REQ-ID to phase mapping in traceability table.
+  - Dashboard: parses requirement checkboxes and status columns. Needs: consistent table format.
+  Breaks if missing: Planner creates plans without requirement coverage; verifier cannot confirm completion; roadmap has no requirement traceability.
+-->
+# Requirements
+
+> Living document. Generated by `/pbr:new-project`, updated via `/pbr:discuss-phase`.
+> All requirements flow from here into plans via `implements:[]` in PLAN.md frontmatter.
+
+## Functional Requirements
+
+<!-- Guidelines: Capabilities the system must provide from the user's perspective.
+     Group by feature category. Each requirement must be testable -- if you can't write a test for it, rewrite it.
+     Priority: Must (blocks launch), Should (high value), Could (nice to have). -->
+
+Capabilities the system must provide from the user's perspective.
+
+### {Category} (e.g., Authentication, API, UI)
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| REQ-F-001 | {User-centric, testable statement of capability} | Must | Open |
+| REQ-F-002 | {User-centric, testable statement of capability} | Should | Open |
+
+### {Category 2}
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| REQ-F-010 | {User-centric, testable statement of capability} | Must | Open |
+
+## Non-Functional Requirements
+
+<!-- Guidelines: Quality attributes and constraints. Each must be observable and measurable.
+     "Fast" is not a requirement. "Page loads in <2s on 4G" is a requirement.
+     Categories: Performance, Security, Reliability, Scalability, Accessibility, Maintainability. -->
+
+Quality attributes and constraints the system must satisfy.
+
+| ID | Requirement | Category | Priority |
+|----|-------------|----------|----------|
+| REQ-NF-001 | {Observable quality statement -- e.g., "Page loads in <2s on 4G"} | Performance | Must |
+| REQ-NF-002 | {Observable quality statement} | Security | Must |
+| REQ-NF-003 | {Observable quality statement} | Reliability | Should |
+
+## Deferred Requirements (v2+)
+
+<!-- Guidelines: Requirements explicitly out of scope for v1 but tracked for future.
+     Include the reason for deferral so future planners understand the decision. -->
+
+Requirements explicitly out of scope for v1.
+
+| ID | Requirement | Deferred Reason |
+|----|-------------|----------------|
+| REQ-F-099 | {requirement} | {reason -- e.g., "Phase 2 priority"} |
+
+## Out of Scope
+
+<!-- Guidelines: Features explicitly excluded from the entire project. These must NOT appear in any plan.
+     Different from Deferred -- these are permanent exclusions. -->
+
+Features explicitly excluded. These must NOT appear in any plan.
+
+- {Feature}: {brief rationale}
+
+## Traceability
+
+<!-- Guidelines: Maps every requirement to its implementation phase and verification.
+     Phase column tracks which phase addresses the requirement.
+     Status tracks lifecycle: Open -> In Progress -> Implemented -> Verified.
+     Update this table as plans are created and completed. -->
+
+| REQ-ID | Phase | Implemented In | Verified In | Status |
+|--------|-------|---------------|------------|--------|
+| REQ-F-001 | Phase 01 | Phase 01 PLAN-01 | Phase 01 VERIFICATION.md | Verified |
+| REQ-F-002 | Phase 02 | -- | -- | Open |
+
+## Evolution
+
+This document evolves through the project lifecycle:
+- **Created by:** `/pbr:new-project` during project initialization
+- **Updated by:** `/pbr:discuss-phase` when requirements change or are reprioritized
+- **Updated by:** `/pbr:execute-phase` when implementations complete (status column updates)
+- **Referenced by:** `/pbr:verify` for completion checking
+
+## Quality Criteria
+
+A good REQUIREMENTS.md satisfies:
+- [ ] Every requirement has a unique ID following the naming convention (REQ-F-NNN or REQ-NF-NNN)
+- [ ] Every requirement is testable -- can write a pass/fail check for it
+- [ ] Every In Scope item in PROJECT.md maps to at least one requirement here
+- [ ] Traceability table is populated with phase assignments for all Must-priority requirements
+- [ ] No orphan requirements (every REQ-ID appears in at least one plan's `implements:[]`)
+- [ ] Status column is current (no stale "Open" for completed work)

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

@@ -1,41 +1,105 @@
-<!-- canonical: ../../pbr/templates/ROADMAP.md.tmpl -->
+<!-- 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}
 
-## 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
 
+<!-- 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
+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)
 
-**Dependencies**: None (starting phase)
+### 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
 
-### Phase 02: Authentication
-...
+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/cursor-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/cursor-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/cursor-pbr/templates/SUMMARY.md.tmpl

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/templates/SUMMARY.md.tmpl -->
 # SUMMARY.md Template
 
 > Referenced by: executor agent, build skill, review skill

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

@@ -1,18 +1,14 @@
-<!-- canonical: ../../pbr/templates/VERIFICATION-DETAIL.md.tmpl -->
 <!-- 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
+checked_at: "{ISO timestamp}"
 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}
+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}"
@@ -24,13 +20,18 @@ anti_patterns:
   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}
 
-> Verified: {date}
+> Checked at: {date}
 > Status: **{STATUS}**
-> Score: {verified}/{total} must-haves verified
+> Score: {must_haves_passed}/{must_haves_checked} must-haves verified
 > Re-verification: {yes/no}
 
 ## Observable Truths
@@ -54,8 +55,9 @@ anti_patterns:
 
 | # | Link Description | Source | Target | Status | Evidence |
 |---|-----------------|--------|--------|--------|----------|
-| 1 | {what connects to what} | `{source_file}` | `{target_file}` | WIRED | Import at L12, called at L45 |
+| 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