@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/cursor-pbr/templates/research/SUMMARY.md.tmpl

@@ -1,112 +0,0 @@
-<!-- Source: agents/researcher.md | Purpose: Output format for research project SUMMARY.md (executive overview with roadmap implications) -->
-# Project Research Summary
-
-**Project:** {project_name}
-**Domain:** {domain}
-**Researched:** {date}
-**Confidence:** {confidence}
-
-## Executive Summary
-
-{executive_summary}
-
-## Key Findings
-
-### Recommended Stack
-
-{stack_summary}
-
-**Core technologies:**
-- {technology}: {purpose} -- {rationale}
-
-### Expected Features
-
-{features_summary}
-
-**Must have (table stakes):**
-- {feature} -- users expect this
-
-**Should have (competitive):**
-- {feature} -- differentiator
-
-**Defer (v2+):**
-- {feature} -- not essential for launch
-
-### Architecture Approach
-
-{architecture_summary}
-
-**Major components:**
-1. {component} -- {responsibility}
-2. {component} -- {responsibility}
-3. {component} -- {responsibility}
-
-### Critical Pitfalls
-
-{pitfalls_summary}
-
-1. **{pitfall}** -- {avoidance}
-2. **{pitfall}** -- {avoidance}
-3. **{pitfall}** -- {avoidance}
-
-## Implications for Roadmap
-
-Based on research, suggested phase structure:
-
-### Phase 1: {phase_name}
-**Rationale:** {why_first}
-**Delivers:** {deliverables}
-**Addresses:** {features}
-**Avoids:** {pitfall}
-
-### Phase 2: {phase_name}
-**Rationale:** {why_this_order}
-**Delivers:** {deliverables}
-**Uses:** {stack_elements}
-**Implements:** {architecture_component}
-
-### Phase 3: {phase_name}
-**Rationale:** {why_this_order}
-**Delivers:** {deliverables}
-
-### Phase Ordering Rationale
-
-- {ordering_rationale}
-
-### Research Flags
-
-Phases likely needing deeper research during planning:
-- **Phase {x}:** {reason}
-
-Phases with standard patterns (skip research-phase):
-- **Phase {x}:** {reason}
-
-## Confidence Assessment
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | {confidence} | {notes} |
-| Features | {confidence} | {notes} |
-| Architecture | {confidence} | {notes} |
-| Pitfalls | {confidence} | {notes} |
-
-**Overall confidence:** {confidence}
-
-### Gaps to Address
-
-- {gap}: {handling}
-
-## Sources
-
-### Primary (HIGH confidence)
-- {source}
-
-### Secondary (MEDIUM confidence)
-- {source}
-
-### Tertiary (LOW confidence)
-- {source}
-
----
-*Research completed: {date}*
-*Ready for roadmap: yes*

package/plugins/cursor-pbr/templates/research-outputs/phase-research.md.tmpl

@@ -1,81 +0,0 @@
-# Phase Research: {Phase Name}
-
-> Research conducted: {date}
-> Research date: {ISO date}
-> Mode: phase-research
-> Phase: {NN}-{phase-name}
-> Confidence: {overall HIGH/MEDIUM/LOW}
-> Coverage: {COMPLETE/PARTIAL/INSUFFICIENT}
-> Retrieval cycles: {1-3}
-
-## User Constraints
-
-{Copied verbatim from CONTEXT.md}
-
-## Phase Goal
-
-{What this phase aims to achieve, extracted from the phase definition}
-
-## Implementation Approach
-
-### Recommended Approach
-
-{Detailed implementation strategy with source attribution}
-
-**Steps**:
-1. {Step with [S{n}] attribution}
-2. ...
-
-**Key decisions**:
-- {Decision with rationale and source}
-
-### Configuration Details
-
-{Specific configuration values, environment variables, file paths}
-
-```{language}
-// Source: [S{n}]
-{configuration example}
-```
-
-### API Patterns
-
-{Relevant API signatures, request/response formats, authentication patterns}
-
-### Data Models
-
-{Database schemas, type definitions, data flow}
-
-## Dependencies
-
-{What needs to be installed, configured, or available}
-
-| Dependency | Version | Purpose | Required By |
-|-----------|---------|---------|-------------|
-| ... | ... | ... | ... |
-
-## Pitfalls for This Phase
-
-{Phase-specific things that can go wrong}
-
-1. **{Pitfall}** [S{n}]: {Description}
-
-## Testing Strategy
-
-{How to verify this phase works correctly}
-
-## Coverage Assessment
-
-| Question | Status | Confidence | Cycle Resolved |
-|----------|--------|------------|----------------|
-| {Implementation question 1} | ANSWERED | HIGH | 1 |
-| {Implementation question 2} | GAP | — | — |
-
-**Overall coverage**: {COMPLETE/PARTIAL/INSUFFICIENT}
-**Gaps remaining**: {List any unresolved questions}
-
-## Sources
-
-| # | Type | URL/Description | Confidence |
-|---|------|----------------|------------|
-| ... | ... | ... | ... |

package/plugins/cursor-pbr/templates/research-outputs/project-research.md.tmpl

@@ -1,99 +0,0 @@
-# Research: {Topic Title}
-
-> Research conducted: {date}
-> Research date: {ISO date}
-> Mode: project-research
-> Confidence: {overall HIGH/MEDIUM/LOW}
-> Coverage: {COMPLETE/PARTIAL/INSUFFICIENT}
-> Retrieval cycles: {1-3}
-> Sources consulted: {count}
-
-## User Constraints
-
-{Copied verbatim from CONTEXT.md if it exists. Otherwise: "No CONTEXT.md found."}
-
-## Executive Summary
-
-{2-3 paragraph overview of findings. What is this technology/domain? Why does it matter for this project? What is the recommended approach?}
-
-## Standard Stack
-
-{The conventional/recommended technology stack for this domain}
-
-| Layer | Technology | Version | Confidence | Source |
-|-------|-----------|---------|------------|--------|
-| Runtime | Node.js | 20.x LTS | HIGH | [S2] |
-| Framework | Next.js | 14.x | HIGH | [S2] |
-| ... | ... | ... | ... | ... |
-
-### Stack Rationale
-
-{Why this combination? What alternatives were considered and why they were rejected?}
-
-### Stack Risks
-
-{Known issues, upcoming deprecations, migration concerns}
-
-## Architecture Patterns
-
-### Recommended Pattern: {Name}
-
-{Description with source attribution}
-
-**When to use**: ...
-**When to avoid**: ...
-**Example structure**:
-```
-project/
-  src/
-    ...
-```
-
-### Alternative Pattern: {Name}
-
-{Only include if CONTEXT.md doesn't lock the architecture}
-
-## Common Pitfalls
-
-{Numbered list of things that commonly go wrong}
-
-1. **{Pitfall name}** [S{n}]: {Description and how to avoid}
-2. ...
-
-## Code Examples
-
-{Working code snippets for key patterns. Every snippet must include source attribution.}
-
-### {Pattern Name}
-
-```{language}
-// Source: [S{n}] {url or description}
-{code}
-```
-
-## Integration Points
-
-{How this technology connects with other systems. API patterns, data flow, authentication.}
-
-## Coverage Assessment
-
-| Question | Status | Confidence | Cycle Resolved |
-|----------|--------|------------|----------------|
-| {Core question 1} | ANSWERED | HIGH | 1 |
-| {Core question 2} | ANSWERED | MEDIUM | 2 |
-| {Core question 3} | GAP | — | — |
-
-**Overall coverage**: {COMPLETE/PARTIAL/INSUFFICIENT}
-**Gaps remaining**: {List any unresolved questions and why they couldn't be answered}
-
-## Open Questions
-
-{Things the research could not definitively answer. These need human input or further investigation.}
-
-## Sources
-
-| # | Type | URL/Description | Confidence |
-|---|------|----------------|------------|
-| S1 | Official Docs | {url} | HIGH |
-| S2 | GitHub | {url} | HIGH |
-| ... | ... | ... | ... |

package/plugins/cursor-pbr/templates/research-outputs/synthesis.md.tmpl

@@ -1,36 +0,0 @@
-# Research Synthesis: {Topic}
-
-> Synthesized: {date}
-> Mode: synthesis
-> Input documents: {count}
-> Confidence: {overall}
-
-## Executive Summary
-
-{Unified findings across all input documents}
-
-## Key Findings
-
-{Numbered list of the most important findings, with source document attribution}
-
-## Contradictions Resolved
-
-{Where input documents disagreed and how it was resolved}
-
-| Topic | Document A Says | Document B Says | Resolution | Basis |
-|-------|----------------|----------------|------------|-------|
-| ... | ... | ... | ... | ... |
-
-## Recommended Approach
-
-{The synthesized recommendation}
-
-## Risks and Mitigations
-
-| Risk | Likelihood | Impact | Mitigation |
-|------|-----------|--------|------------|
-| ... | ... | ... | ... |
-
-## Sources
-
-{Consolidated source list from all input documents}

package/plugins/pbr/references/agent-interactions.md

@@ -1,134 +0,0 @@
-# Agent Interaction Map
-
-This document shows how Plan-Build-Run agents communicate through files on disk. Agents never message each other directly -- they read and write shared files in `.planning/`.
-
-## Interaction Graph
-
-```
-                    User / Orchestrator
-                     |           ^
-                     v           |
-              +--------------+   |
-              |  researcher  |---+---> planner
-              +--------------+         |    ^
-                     |                 v    |
-              +--------------+   +--------------+
-              | synthesizer  |   | plan-checker |
-              +--------------+   +--------------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  executor  |
-                                 +-----------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  verifier  |----> planner (gap closure)
-                                 +-----------+
-                                       |
-                                       v
-                              +--------------------+
-                              | integration-checker|
-                              +--------------------+
-```
-
-## Per-Agent Interaction Details
-
-### researcher
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | User/Orchestrator | Research topics, CONTEXT.md constraints, phase goals |
-| Produces for | planner | Research documents with technology details and recommendations |
-| Produces for | synthesizer | Research documents to be combined |
-| Produces for | User | Direct reading for decision-making |
-
-### synthesizer
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents to synthesize |
-| Receives from | Orchestrator | Paths to research documents, synthesis request |
-| Produces for | planner | SUMMARY.md as consolidated research input for planning |
-| Produces for | User | High-level project/phase research overview |
-
-### planner
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents with technology details and recommendations |
-| Receives from | plan-checker | Issue reports requiring plan revision |
-| Receives from | verifier | VERIFICATION.md reports requiring gap closure plans |
-| Receives from | User/Orchestrator | Phase goals, CONTEXT.md, planning requests |
-| Produces for | plan-checker | Plan files for quality verification |
-| Produces for | executor | Plan files for execution |
-| Produces for | verifier | Must-have definitions for verification (embedded in plan frontmatter) |
-
-### plan-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Plan files to check, phase context |
-| Receives from | planner | Newly created or revised plan files |
-| Produces for | planner | Issue reports for revision |
-| Produces for | Orchestrator/User | Pass/fail decision on plan quality |
-
-### executor
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Plan files to execute, continuation instructions |
-| Receives from | planner | The plans themselves (indirectly, via files) |
-| Produces for | verifier | SUMMARY.md for verification, committed code for inspection |
-| Produces for | Orchestrator | Checkpoint responses, completion status |
-| Produces for | planner | Deferred ideas (in SUMMARY.md) for future planning |
-
-### verifier
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phase to verify, timing trigger |
-| Receives from | executor | Completed work (via codebase and SUMMARY.md) |
-| Receives from | Previous VERIFICATION.md | Gaps to re-check (in re-verification mode) |
-| Produces for | planner | Gap list for gap-closure planning (via VERIFICATION.md) |
-| Produces for | Orchestrator | Phase status (passed/gaps_found/human_needed) |
-| Produces for | User | Human verification items with specific test instructions |
-
-### integration-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phases to check, trigger event (milestone/review) |
-| Receives from | verifier | Phase-level verification reports (for context on per-phase status) |
-| Produces for | planner | Integration gap list for cross-phase fix plans |
-| Produces for | Orchestrator | Integration status for milestone decisions |
-| Produces for | User | Integration health overview and security issues |
-
-### debugger
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Bug reports, symptoms, reproduction steps |
-| Receives from | executor | Errors encountered during execution (via checkpoint responses) |
-| Receives from | verifier | Issues discovered during verification |
-| Produces for | Orchestrator/User | Root cause analysis, fix commits, checkpoint requests |
-| Produces for | planner | Findings requiring architectural changes |
-| Produces for | executor | Simple fix instructions for executor to apply |
-
-### codebase-mapper
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Focus area to analyze, project path |
-| Receives from | researcher | May be invoked alongside researcher for new projects |
-| Produces for | planner | STACK.md, ARCHITECTURE.md, STRUCTURE.md for informed planning |
-| Produces for | executor | CONVENTIONS.md for code style, TESTING.md for test patterns |
-| Produces for | verifier | All documents as reference for what "correct" looks like |
-| Produces for | User | Direct reading for project understanding |
-
-### general
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Ad-hoc task instructions |
-| Produces for | Orchestrator/User | Task output (files, formatting, config changes) |

package/plugins/pbr/references/pbr-rules.md

@@ -1,194 +0,0 @@
-# Plan-Build-Run Rules
-
-Authoritative rules for all Plan-Build-Run skills, agents, hooks, and workflows.
-Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these rules govern.
-
----
-
-## Philosophy
-
-1. **Context is precious.** The orchestrator stays lean (~15% usage). Delegate heavy work to subagents.
-2. **State lives on disk.** Skills and agents communicate through `.planning/` files, not messages.
-3. **Agents are black boxes.** Clear input/output contracts. Agents never read other agent definitions.
-4. **Gates provide safety.** Users control pace via config toggles. Never skip a gate.
-5. **One task, one commit.** Atomic commits for clean history and easy rollback.
-6. **Cross-platform always.** `path.join()`, CommonJS, test on Windows/macOS/Linux.
-7. **Test everything.** 70% coverage minimum. All 9 CI matrix combinations must pass.
-8. **PLAN-BUILD-RUN branding only.** Always use `PLAN-BUILD-RUN ►` prefix in banners.
-
----
-
-## Context Budget
-
-9. Target 15% orchestrator context usage. Warn user at 30%.
-10. **Never** read agent definitions (`agents/*.md`) in the orchestrator — `subagent_type` auto-loads them.
-11. **Never** inline large files into `Task()` prompts — tell agents to read files from disk.
-12. **Never** read full subagent output — read frontmatter only (first 10-20 lines).
-13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
-14. Use the `limit` parameter on Read to restrict line counts.
-15. Proactively suggest `/pbr:pause` when context gets heavy — before compaction, not after.
-15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
-
----
-
-## State Management
-
-16. STATE.md is the **single source of truth** for current position.
-17. **Never** infer current phase from directory listings, git log, or conversation history.
-18. Always read STATE.md before making state-dependent decisions.
-19. Update STATE.md at: begin, plan, build, review, pause, continue, milestone.
-20. **Never** commit STATE.md mid-skill — hooks handle session persistence.
-21. Agents write artifacts (SUMMARY.md, VERIFICATION.md). Only the orchestrator writes STATE.md.
-22. Every ROADMAP.md phase must have a matching `.planning/phases/` directory, and vice versa.
-23. config.json is validated against `scripts/config-schema.json` on load.
-
----
-
-## Agent Spawning
-
-24. Always use `subagent_type: "pbr:{name}"` to spawn agents.
-25. Pass file paths to agents, not file contents.
-26. Agents never read other agent definition files.
-27. Each agent gets a fresh 200k token context window — let them do the heavy reading.
-
----
-
-## User Interaction Patterns
-
-28. Use `AskUserQuestion` for all structured gate checks — never plain-text "Type approved" prompts.
-29. AskUserQuestion is an orchestrator-only tool. It **cannot** be called from subagents (Task contexts).
-30. Max 4 options per AskUserQuestion call. If more options exist, split into a 2-step flow.
-31. `header` field must be max 12 characters. Keep it a single word when possible.
-32. `multiSelect` is always `false` for Plan-Build-Run gate checks.
-33. Always handle the "Other" case — users may type freeform text instead of selecting an option.
-34. Reuse patterns from `skills/shared/gate-prompts.md` by name. Do not reinvent prompts inline.
-35. Do **not** use AskUserQuestion for freeform text input (symptom gathering, Socratic discussion, open-ended questions). Use plain conversation for those.
-36. Skills that do not require user interaction (continue, health, help, pause) intentionally omit AskUserQuestion from allowed-tools.
-
----
-
-## Skill Authoring
-
-37. Every SKILL.md starts with YAML frontmatter: `name`, `description`, `allowed-tools`, `argument-hint`.
-38. Skills that spawn agents **must** have a `## Context Budget` section.
-39. Mark each step as `(inline)` or `(delegate)` — inline for light work, delegate for analysis.
-40. Reference templates and references by filename — never inline them.
-41. Gate checks: read config toggle → display summary → ask user → proceed/abort/revise.
-42. Use branded UI elements from `references/ui-formatting.md`.
-
----
-
-## Agent Authoring
-
-43. Every agent file starts with YAML frontmatter: `name`, `description`, `model`, `memory`, `tools`.
-44. Agent name matches the agent file name (no prefix needed).
-45. `tools` array: only include tools the agent actually uses.
-46. Agents write artifacts to disk. They never modify STATE.md or ROADMAP.md.
-47. Agent definitions are self-contained — no cross-agent references.
-
----
-
-## Hook Development
-
-48. All hooks use **CommonJS** (`require`), never ES modules (`import`).
-49. All hooks call `logHook()` from `hook-logger.js`. No silent exits.
-50. Exit codes: `0` = allow/success, `2` = block (PreToolUse only), other = error (logged, non-blocking).
-51. Hooks receive JSON on stdin, write JSON to stdout.
-52. Fail gracefully: wrap in try/catch, exit 0 on parse errors.
-53. Every hook in `hooks.json` must have a `statusMessage` field (gerund form: "Validating...", keep short).
-54. Windows file deletion: use 3-attempt retry loop to handle AV/indexer locks.
-55. Every hook script must have a corresponding `tests/{name}.test.js`.
-
----
-
-## Commits
-
-56. Format: `{type}({scope}): {description}`.
-57. Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`.
-58. Valid scopes: `{NN}-{MM}` (phase-plan), `quick-{NNN}`, `planning`, or any lowercase word.
-59. **Never** use `git add .` or `git add -A` — stage specific files only.
-60. Blocked files: `.env` (not `.env.example`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*credential*`, `*secret*` (unless in `tests/` or `*.example`).
-61. TDD tasks: exactly 3 commits — RED (test), GREEN (feat), REFACTOR.
-62. Executors: one atomic commit per task.
-
----
-
-## Templates
-
-63. Default syntax: `{variable}` placeholders for string substitution.
-64. Only use EJS (`<%= %>`, `<% %>`) when loops or conditionals are genuinely needed.
-65. Template files use `.tmpl` extension. Name matches the output file (e.g., `SUMMARY.md.tmpl` → `SUMMARY.md`).
-66. Templates live in `templates/` (global), `templates/codebase/` (scan), `templates/research/` (research), or `skills/{name}/templates/` (skill-specific).
-
----
-
-## File Naming
-
-67. Skills: `plugins/pbr/skills/{skill-name}/SKILL.md` — lowercase hyphenated dir, uppercase `SKILL.md`.
-68. Agents: `plugins/pbr/agents/{name}.md` — agent name matches file name.
-69. Scripts: `plugins/pbr/scripts/{name}.js` — lowercase, hyphenated, CommonJS.
-70. References: `plugins/pbr/references/{name}.md` — lowercase, hyphenated.
-71. Tests: `tests/{script-name}.test.js` — mirrors the script name.
-
----
-
-## Testing
-
-72. Test files mirror script names: `scripts/foo.js` → `tests/foo.test.js`.
-73. Use the fixture project at `tests/fixtures/fake-project/` for integration tests.
-74. Hook tests: use stdin/stdout protocol with `execSync()`, timeout 5000ms, run in temp dir.
-75. Coverage target: 70% branches/functions/lines/statements.
-76. CI matrix: Node 18/20/22 × ubuntu/macos/windows. All 9 must pass.
-77. Local pre-push: `npm run lint && npm test && npm run validate`.
-
----
-
-## Cross-Platform
-
-78. **Never** hardcode `/` or `\` — always `path.join()`.
-79. Use `\n` in string literals — Node.js and Git normalize line endings.
-80. In `hooks.json`, use `${CLAUDE_PLUGIN_ROOT}` — Claude Code expands this internally on all platforms.
-81. **Never** use `$CLAUDE_PLUGIN_ROOT` (shell expansion is platform-dependent).
-82. **Never** rely on execute bits — always invoke via `node script.js`.
-
----
-
-## Dependencies & Gates
-
-83. Check all `depends_on` plans have SUMMARY.md files before executing.
-84. Checkpoint tasks (`checkpoint:human-verify`) require STOP — write partial SUMMARY.md, return metadata.
-85. Respect all `gates.confirm_*` config toggles. Never auto-proceed when a gate is enabled.
-
----
-
-## Logging
-
-86. Hook scripts → `logHook()` (writes to `logs/hooks.jsonl`, max 200 entries).
-87. Workflow milestones → `logEvent()` (writes to `logs/events.jsonl`, max 1,000 entries).
-88. Rule of thumb: inside a hook? `logHook()`. Tracking a high-level event? `logEvent()`.
-
----
-
-## Gotchas
-
-89. JSDoc `*/` in glob patterns closes Babel comments early — use `//` line comments instead.
-90. Regex anchors: use `\b` word boundaries, not `^` anchors (misses chained commands like `cd && git commit`).
-91. Windows cwd locking in tests: use `cwd` option in `execSync()` instead of `process.chdir()`.
-92. PLAN.md frontmatter must include all required fields: `phase`, `plan`, `type`, `wave`, `depends_on`, `files_modified`, `autonomous`, `must_haves`.
-
----
-
-## Quick Reference: Never Do This
-
-| # | Anti-Pattern | Impact |
-|---|-------------|--------|
-| 1 | Read agent definitions in orchestrator | Context balloons 15% → 88% |
-| 2 | Inline large files into Task() prompts | Wasted orchestrator context |
-| 3 | Read full subagent output | Context bloat |
-| 4 | Use non-Plan-Build-Run branding | User confusion |
-| 5 | Hardcode path separators | Cross-platform breakage |
-| 6 | Use ES modules in hooks | Hook fails to load |
-| 7 | Skip hook logging | Silent failures |
-| 8 | Modify STATE.md in agents | Race conditions, corruption |
-| 9 | Use `git add .` | Sensitive data leaks |
-| 10 | Skip tests for new scripts | CI failures, regressions |