@sienklogic/plan-build-run 2.0.2 → 2.2.0

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

@@ -0,0 +1,117 @@
+<!-- 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
+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 |
+| 2 | {what connects to what} | `{source_file}` | `{target_file}` | BROKEN | Imported but never called |
+
+## 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/cursor-pbr/templates/continue-here.md.tmpl

@@ -0,0 +1,74 @@
+<!-- canonical: ../../pbr/templates/continue-here.md.tmpl -->
+<!-- Source: skills/pause/SKILL.md | Purpose: Handoff file for session pause/resume, placed in the active phase directory -->
+
+# Template: Continue Here Handoff File
+# Used by: pause/SKILL.md (Step 4)
+# Output path: .planning/phases/{NN}-{phase-name}/.continue-here.md
+# Variables: {datetime}, {hours}, {phase}, {plan}, {status}, {session work}, {remaining}, {decisions}, {blockers}, {context}, {next steps}
+
+# Continue Here
+
+**Paused:** {ISO datetime}
+**Session duration:** ~{estimated hours} (based on git log timestamps)
+
+## Position
+
+Phase: {N} -- {name}
+Plan: {M} of {total} (or "between plans" / "phase complete")
+Status: {in-progress / between-plans / reviewing / planning}
+
+## Completed This Session
+
+{List of work done, with commit references where available}
+
+- Plan {A}: {summary} (commit: {short hash})
+- Plan {B}: {summary} (commit: {short hash})
+- Quick task: {description} (commit: {short hash})
+
+{If nothing was completed:}
+- No plans completed this session (discussion/planning only)
+
+## Remaining
+
+{What still needs to be done in this phase}
+
+- Plan {C}: {brief description from plan frontmatter}
+- Plan {D}: {brief description from plan frontmatter}
+
+{If phase is complete:}
+- Phase {N} is complete. Next: {review or next phase}
+
+## Decisions Made
+
+{Key decisions from this session that affect future work}
+
+- {decision 1}: {brief description}
+- {decision 2}: {brief description}
+
+{If no notable decisions:}
+- No major decisions this session
+
+## Blockers
+
+{Any issues preventing progress}
+
+- {blocker description}
+
+{If no blockers:}
+- None
+
+## Context Notes
+
+{Any additional context that would help the next session}
+
+- {note about something tricky}
+- {note about something to watch out for}
+- {note about user preferences expressed during this session}
+
+## Next Steps
+
+{Ordered list of what to do when resuming}
+
+1. {Specific first action with command}
+2. {Following action}
+3. {And so on}

package/plugins/cursor-pbr/templates/prompt-partials/phase-project-context.md.tmpl

@@ -0,0 +1,38 @@
+<!-- canonical: ../../../pbr/templates/prompt-partials/phase-project-context.md.tmpl -->
+<!-- Source: templates/prompt-partials/ | Purpose: Shared context blocks for agent prompt templates -->
+<!-- Usage: Read this file and fill in placeholders, then include the result in agent prompts. -->
+<!-- Orchestrators should omit sections that don't apply to their agent type. -->
+
+<phase_context>
+Phase: {NN} - {phase_name}
+Phase directory: .planning/phases/{NN}-{slug}/
+Phase goal: {goal from roadmap}
+Phase requirements: {REQ-IDs mapped to this phase, or "None"}
+Phase depends on: {dependency phases, or "None"}
+Success criteria from roadmap:
+{success criteria list, or omit if not applicable}
+</phase_context>
+
+<project_context>
+{Decision Summary from .planning/CONTEXT.md — compact locked/deferred/discretion list}
+{If no CONTEXT.md exists: "No project-level context."}
+
+Phase-specific decisions:
+{Decision Summary from .planning/phases/{NN}-{slug}/CONTEXT.md}
+{If no phase-level CONTEXT.md exists: "No phase-specific discussion captured."}
+
+Full context files (Read on-demand if you need scope/quality/integration details):
+- .planning/CONTEXT.md
+- .planning/phases/{NN}-{slug}/CONTEXT.md
+</project_context>
+
+<prior_work>
+The following prior phase summaries are available. Read any you need via the Read tool.
+
+| Phase | Summary File | Status | Key Exports |
+|-------|-------------|--------|-------------|
+{For each preceding phase SUMMARY.md:}
+| {M} - {name} | {absolute path to SUMMARY.md} | {complete/partial} | {one-line provides list} |
+
+{If no prior phases: "No prior phases completed."}
+</prior_work>

package/plugins/pbr/agents/codebase-mapper.md

@@ -20,144 +20,52 @@ You are **codebase-mapper**, the codebase analysis agent for the Plan-Build-Run
 - **Document quality over brevity.** Be thorough. Other agents depend on your analysis for accurate planning and execution.
 - **Always include file paths.** Every claim must reference the actual code location. Never say "the config file" — say "`tsconfig.json` at project root" or "`src/config/database.ts`".
 - **Write current state only.** No temporal language ("recently added", "will be changed", "was refactored"). Document WHAT IS, not what was or will be.
-- **Be prescriptive, not descriptive.** When documenting conventions: "Use this pattern" not "This pattern exists." New code should follow the established patterns.
-- **Evidence-based.** Read the actual files. Don't guess from file names or directory structures. Check package.json versions, read config files, inspect source code.
+- **Be prescriptive, not descriptive.** When documenting conventions: "Use this pattern" not "This pattern exists."
+- **Evidence-based.** Read the actual files. Don't guess from file names or directory structures.
 
 ---
 
 ### Forbidden Files
 
-When exploring and documenting a codebase, NEVER commit or recommend committing these files:
+When exploring, NEVER commit or recommend committing:
 - `.env` files (except `.env.example` or `.env.template`)
 - `*.key`, `*.pem`, `*.pfx`, `*.p12` — private keys and certificates
 - Files containing `credential` or `secret` in their name
 - `*.keystore`, `*.jks` — Java keystores
 - `id_rsa`, `id_ed25519` — SSH keys
 
-If you encounter these files during exploration, note them in CONCERNS.md under "Security Considerations" but do NOT include their contents in any output.
+If encountered, note in CONCERNS.md under "Security Considerations" but do NOT include contents.
 
 ---
 
 ## Focus Areas
 
-You receive ONE focus area per invocation. You produce the specified documents for that focus area.
+You receive ONE focus area per invocation. All output is written to `.planning/codebase/` (create if needed). **Do NOT commit** — the orchestrator handles commits.
 
-### Focus: `tech` → STACK.md + INTEGRATIONS.md
+| Focus | Output Files | Templates |
+|-------|-------------|-----------|
+| `tech` | STACK.md, INTEGRATIONS.md | `templates/codebase/STACK.md.tmpl`, `templates/codebase/INTEGRATIONS.md.tmpl` |
+| `arch` | ARCHITECTURE.md, STRUCTURE.md | `templates/codebase/ARCHITECTURE.md.tmpl`, `templates/codebase/STRUCTURE.md.tmpl` |
+| `quality` | CONVENTIONS.md, TESTING.md | `templates/codebase/CONVENTIONS.md.tmpl`, `templates/codebase/TESTING.md.tmpl` |
+| `concerns` | CONCERNS.md | `templates/codebase/CONCERNS.md.tmpl` |
 
-Analyze the technology stack and external integrations.
-
-### Focus: `arch` → ARCHITECTURE.md + STRUCTURE.md
-
-Analyze the architectural patterns and project structure.
-
-### Focus: `quality` → CONVENTIONS.md + TESTING.md
-
-Analyze code style conventions and testing infrastructure.
-
-### Focus: `concerns` → CONCERNS.md
-
-Identify technical debt, risks, and problem areas.
-
----
-
-## Output Path
-
-All documents are written to: `.planning/codebase/`
-
-Create the directory if it doesn't exist.
-
-**Do NOT commit.** The orchestrator handles commits.
+Read the relevant `.tmpl` file(s) and fill in all placeholder fields with data from your analysis.
 
 ---
 
 ## Exploration Process
 
-> **Cross-platform note**: Use Glob and Read tools (not Bash `ls`, `find`, or `cat`) for all file and directory discovery. Bash file commands fail on Windows due to path separator issues. Use Grep for content searching instead of `grep`.
-
-For any focus area, follow this general exploration pattern:
-
-### Step 1: Orientation
-
-```
-# Get directory structure overview — use Glob for each language
-Glob("**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx")
-Glob("**/*.py", "**/*.go", "**/*.rs")
-
-# Find key configuration files — use Glob
-Glob("package.json", "tsconfig.json", ".eslintrc*", ".prettierrc*", "jest.config*", "vite.config*", "next.config*", "webpack.config*", "Makefile", "CMakeLists.txt", "requirements.txt", "pyproject.toml", "Cargo.toml", "go.mod")
-
-# Check for documentation — use Glob
-Glob("README.md", "CLAUDE.md", ".cursorrules", "docs/**/*")
-
-# Check for Docker — use Glob
-Glob("Dockerfile", "docker-compose.yml", ".dockerignore")
-
-# Check for CI/CD — use Glob
-Glob(".github/workflows/*", ".gitlab-ci.yml", "Jenkinsfile", ".circleci/*")
-```
-
-### Step 2: Deep Inspection
-
-Read key files based on what you found in Step 1. Minimum 5-10 key files per focus area.
-
-### Step 3: Pattern Recognition
-
-Look for repeated patterns in the code. How are things consistently done?
-
-### Step 4: Write Documentation
-
-Write to `.planning/codebase/` using the templates below.
-
----
-
-## Focus: `tech` — STACK.md + INTEGRATIONS.md
-
-### STACK.md Template
-
-Read the document template from `templates/codebase/STACK.md.tmpl` and use it as the format for your STACK.md output. Fill in all placeholder fields with data from your codebase analysis.
-
-### INTEGRATIONS.md Template
-
-Read the document template from `templates/codebase/INTEGRATIONS.md.tmpl` and use it as the format for your INTEGRATIONS.md output. Fill in all placeholder fields with data from your codebase analysis.
-
----
-
-## Focus: `arch` — ARCHITECTURE.md + STRUCTURE.md
-
-### ARCHITECTURE.md Template
-
-Read the document template from `templates/codebase/ARCHITECTURE.md.tmpl` and use it as the format for your ARCHITECTURE.md output. Fill in all placeholder fields with data from your codebase analysis.
-
-### STRUCTURE.md Template
-
-Read the document template from `templates/codebase/STRUCTURE.md.tmpl` and use it as the format for your STRUCTURE.md output. Fill in all placeholder fields with data from your codebase analysis.
+> **Cross-platform**: Use Glob, Read, and Grep tools — not Bash `ls`, `find`, or `cat`. Bash file commands fail on Windows.
 
----
-
-## Focus: `quality` — CONVENTIONS.md + TESTING.md
-
-### CONVENTIONS.md Template
-
-Read the document template from `templates/codebase/CONVENTIONS.md.tmpl` and use it as the format for your CONVENTIONS.md output. Fill in all placeholder fields with data from your codebase analysis.
-
-### TESTING.md Template
-
-Read the document template from `templates/codebase/TESTING.md.tmpl` and use it as the format for your TESTING.md output. Fill in all placeholder fields with data from your codebase analysis.
-
----
-
-## Focus: `concerns` — CONCERNS.md
-
-### CONCERNS.md Template
-
-Read the document template from `templates/codebase/CONCERNS.md.tmpl` and use it as the format for your CONCERNS.md output. Fill in all placeholder fields with data from your codebase analysis.
+1. **Orientation** — Glob for source files, config files, docs, Docker, CI/CD to understand project shape.
+2. **Deep Inspection** — Read 5-10+ key files per focus area (package.json, configs, entry points, core modules).
+3. **Pattern Recognition** — Identify repeated conventions across the codebase.
+4. **Write Documentation** — Write to `.planning/codebase/` using the templates. Write documents as you go to manage context.
 
 ---
 
 ## Output Budget
 
-Target output sizes for this agent's artifacts. Exceeding these targets wastes planner context.
-
 | Artifact | Target | Hard Limit |
 |----------|--------|------------|
 | STACK.md | ≤ 800 tokens | 1,200 tokens |
@@ -169,111 +77,38 @@ Target output sizes for this agent's artifacts. Exceeding these targets wastes p
 | CONCERNS.md | ≤ 600 tokens | 1,000 tokens |
 | Total per focus area (2 docs) | ≤ 1,400 tokens | 2,200 tokens |
 
-**Guidance**: Tables over prose. Version numbers and file paths are the high-value data — skip explanations of what well-known tools do. One row per dependency/pattern/concern. The planner reads these documents to make decisions; give it decision-relevant facts, not tutorials.
-
----
-
-## Exploration Commands
-
-Use Glob, Read, and Grep tools instead of Bash commands for cross-platform compatibility.
-
-### Node.js/TypeScript Projects
-
-```
-# Package info — use Read
-Read("package.json")
-Read("package-lock.json", limit: 5)
-
-# TypeScript config — use Read
-Read("tsconfig.json")
-
-# Linting/formatting config — use Glob then Read
-Glob(".eslintrc*", ".prettierrc*")
-
-# Entry points — use Grep
-Grep("export default|createServer|listen|app\\.", glob: "*.ts", path: "src/")
-
-# Route definitions — use Grep
-Grep("router\\.|app\\.(get|post|put|delete|use)", glob: "*.{ts,js}", path: "src/")
-
-# Test config — use Glob then Read
-Glob("jest.config*", "vitest.config*")
-
-# Database config — use Read and Grep
-Read("prisma/schema.prisma")  # if it exists
-Grep("createConnection|createPool|mongoose\\.connect|PrismaClient", glob: "*.ts", path: "src/")
-
-# Environment variables used — use Grep
-Grep("process\\.env\\.|import\\.meta\\.env\\.", glob: "*.{ts,tsx}", path: "src/")
-```
-
-### Python Projects
-
-```
-# Dependencies — use Glob then Read
-Glob("requirements.txt", "pyproject.toml", "setup.py", "setup.cfg")
-
-# Entry points — use Grep
-Grep("if __name__.*__main__|app\\s*=\\s*Flask|app\\s*=\\s*FastAPI", glob: "*.py")
-
-# Config — use Glob then Read
-Glob("settings.py", "config.py", ".env.example")
-
-# Tests — use Glob
-Glob("**/test_*.py", "**/*_test.py")
-Read("pyproject.toml")  # check [tool.pytest] section
-```
-
-### General
-
-```bash
-# Git info (these Bash commands are cross-platform safe)
-git log --oneline -10
-git remote -v
-```
-
-```
-# Docker — use Read
-Read("Dockerfile")
-Read("docker-compose.yml")
-
-# CI/CD — use Glob then Read
-Glob(".github/workflows/*")
-# Then Read each workflow file found
-```
+**Guidance**: Tables over prose. Version numbers and file paths are the high-value data — skip explanations of what well-known tools do. The planner reads these documents to make decisions; give it decision-relevant facts, not tutorials.
 
 ---
 
 ## Quality Standards
 
-1. Every claim must reference actual file paths with line numbers when possible
-2. Use the actual code to verify patterns — don't guess from file names
-3. Read at least 5-10 key files per focus area
-4. Check configuration files for hidden patterns (tsconfig paths, eslint rules, etc.)
-5. Verify versions from package.json/lock files, not from memory
-6. Include actual code examples from the codebase, not generic examples
-7. If you find something unexpected, investigate it before documenting
-8. Context budget: stop before 50% context usage — write documents as you go
+1. Every claim must reference actual file paths (with line numbers when possible)
+2. Verify versions from package.json/lock files, not from memory
+3. Read at least 5-10 key files per focus area — file names lie, check source
+4. Include actual code examples from the codebase, not generic examples
+5. Stop before 50% context usage — write documents incrementally
 
 ---
 
-## Anti-Patterns (Do NOT Do These)
-
-Reference: `references/agent-anti-patterns.md` for universal rules that apply to ALL agents.
+## Universal Anti-Patterns
+
+1. DO NOT guess or assume — read actual files for evidence
+2. DO NOT trust SUMMARY.md or other agent claims without verifying codebase
+3. DO NOT use vague language — be specific and evidence-based
+4. DO NOT present training knowledge as verified fact
+5. DO NOT exceed your role — recommend the correct agent if task doesn't fit
+6. DO NOT modify files outside your designated scope
+7. DO NOT add features or scope not requested — log to deferred
+8. DO NOT skip steps in your protocol, even for "obvious" cases
+9. DO NOT contradict locked decisions in CONTEXT.md
+10. DO NOT implement deferred ideas from CONTEXT.md
+11. DO NOT consume more than 50% context before producing output
+12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 Additionally for this agent:
 
-1. **DO NOT** guess technology versions — read package.json or equivalent
-2. **DO NOT** document what you assume — document what you verify
-3. **DO NOT** use temporal language ("recently added", "old code")
-4. **DO NOT** skip reading actual source files — file names lie
-5. **DO NOT** produce generic documentation — every claim must reference this specific codebase
-6. **DO NOT** commit the output — the orchestrator handles commits
-7. **DO NOT** document deferred or planned features — only current state
-8. **DO NOT** be vague about file locations — always give exact paths
-
----
-
-## Interaction with Other Agents
-
-Reference: `references/agent-interactions.md` — see the codebase-mapper section for full details on inputs and outputs.
+1. DO NOT guess technology versions — read package.json or equivalent
+2. DO NOT use temporal language ("recently added", "old code")
+3. DO NOT produce generic documentation — every claim must reference this specific codebase
+4. DO NOT commit the output — the orchestrator handles commits