@sienklogic/plan-build-run 2.0.2 → 2.2.0

package/plugins/cursor-pbr/skills/todo/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: todo
+description: "File-based persistent todos. Add, list, complete — survives sessions."
+argument-hint: "add <description> | list [theme] | done <NNN>"
+---
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► TODO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
+# /pbr:todo — Persistent File-Based Todos
+
+## Why File-Based
+
+Native Claude Code Tasks are session-scoped — they vanish when the conversation ends. Plan-Build-Run todos are individual `.md` files in `.planning/todos/` that persist across sessions, context resets, and compactions.
+
+## Subcommands
+
+Parse `$ARGUMENTS` to determine the subcommand:
+
+### `add <description>`
+
+1. Ensure `.planning/todos/pending/` directory exists
+2. Generate NNN: scan **both** `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, then increment by 1 (zero-padded to 3 digits)
+3. Generate slug: take the first ~4 meaningful words from the description, lowercase, hyphen-separated (e.g., "Add rate limiting to login" → `add-rate-limiting-login`)
+4. Infer theme from description (e.g., "auth" → security, "test" → testing, "UI" → frontend, "refactor" → quality)
+5. Check for duplicates — read existing pending todos, if a similar one exists, ask user via AskUserQuestion
+6. Create `.planning/todos/pending/{NNN}-{slug}.md`:
+
+```yaml
+---
+title: "{description}"
+status: pending
+priority: P2
+source: conversation
+created: {YYYY-MM-DD}
+theme: {inferred-theme}
+---
+
+## Goal
+
+{description expanded into a clear goal statement}
+
+## Scope
+
+{any relevant context from the current conversation, or bullet points of what's in/out of scope}
+
+## Acceptance Criteria
+
+- [ ] {primary acceptance criterion derived from description}
+```
+
+7. Update STATE.md Pending Todos section
+
+   If the Write fails, display:
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  ERROR                                                       ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Failed to write todo file.
+
+   **To fix:** Check that `.planning/todos/pending/` exists and is writable.
+   ```
+
+8. Confirm with branded output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► TODO ADDED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Todo {NNN}:** {description}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Work on it now** or see your task list
+
+`/pbr:quick`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:todo list` — see all pending todos
+- `/pbr:status` — see project status
+
+───────────────────────────────────────────────────────────────
+```
+
+### `list [theme]`
+
+1. Read all files in `.planning/todos/pending/`
+2. Parse frontmatter from each
+3. If theme filter provided, filter by theme
+4. Display as table:
+
+```
+Pending Todos:
+| # | Title | Priority | Theme | Created |
+|---|-------|----------|-------|---------|
+| 074 | Status-line customization options | P2 | capability | 2026-02-10 |
+| 075 | Add WebSearch/WebFetch/Context7 to researcher | P2 | capability | 2026-02-10 |
+```
+
+5. Offer actions with branded routing:
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Pick a todo** — mark one done or start working
+
+`/pbr:todo done <NNN>`
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:quick` — work on one now
+- `/pbr:status` — see project status
+
+───────────────────────────────────────────────────────────────
+```
+
+### `done <NNN>`
+
+1. Find `.planning/todos/pending/{NNN}-*.md` (match by number prefix)
+2. If not found, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Todo {NNN} not found in pending todos.
+
+**To fix:** Run `/pbr:todo list` to see available numbers.
+```
+3. Ensure `.planning/todos/done/` directory exists (create if needed)
+4. Read the pending file content
+5. Update frontmatter in the content: set `status: done` and add `completed: {YYYY-MM-DD}`
+6. Write the updated content to `.planning/todos/done/{NNN}-{slug}.md`
+7. Delete the original file from `.planning/todos/pending/` (use `rm` via Bash)
+8. Update STATE.md
+9. Confirm with branded output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► TODO COMPLETED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Todo {NNN}:** {title}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**See remaining tasks**
+
+`/pbr:todo list`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:continue` — execute next logical step
+- `/pbr:status` — see project status
+
+───────────────────────────────────────────────────────────────
+```
+
+### No arguments
+
+Show a brief summary: count of pending todos, grouped by theme, plus usage hint.
+
+## State Integration
+
+After any todo operation, update the "Pending Todos" section of STATE.md with the current count and list.
+
+## Git Integration
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `planning.commit_docs: true` in config, commit todo changes:
+- `docs(planning): add todo {NNN}`
+- `docs(planning): complete todo {NNN}`

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

@@ -0,0 +1,53 @@
+<!-- canonical: ../../pbr/templates/CONTEXT.md.tmpl -->
+# 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/cursor-pbr/templates/INTEGRATION-REPORT.md.tmpl

@@ -0,0 +1,152 @@
+<!-- canonical: ../../pbr/templates/INTEGRATION-REPORT.md.tmpl -->
+<!-- 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. 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}
+
+## 6. 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} | {%} |
+| **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/cursor-pbr/templates/RESEARCH-SUMMARY.md.tmpl

@@ -0,0 +1,98 @@
+<!-- canonical: ../../pbr/templates/RESEARCH-SUMMARY.md.tmpl -->
+# 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/cursor-pbr/templates/ROADMAP.md.tmpl

@@ -0,0 +1,41 @@
+<!-- canonical: ../../pbr/templates/ROADMAP.md.tmpl -->
+# 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
+```
+
+## 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/cursor-pbr/templates/SUMMARY.md.tmpl

@@ -0,0 +1,82 @@
+<!-- canonical: ../../pbr/templates/SUMMARY.md.tmpl -->
+# 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 |