@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/templates/verification-report.md

@@ -0,0 +1,322 @@
+# Verification Report Template
+
+Template for `.planning/phases/XX-name/{phase_num}-VERIFICATION.md` — phase goal verification results.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+verified: YYYY-MM-DDTHH:MM:SSZ
+status: passed | gaps_found | human_needed
+score: N/M must-haves verified
+---
+
+# Phase {X}: {Name} Verification Report
+
+**Phase Goal:** {goal from ROADMAP.md}
+**Verified:** {timestamp}
+**Status:** {passed | gaps_found | human_needed}
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | {truth from must_haves} | ✓ VERIFIED | {what confirmed it} |
+| 2 | {truth from must_haves} | ✗ FAILED | {what's wrong} |
+| 3 | {truth from must_haves} | ? UNCERTAIN | {why can't verify} |
+
+**Score:** {N}/{M} truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Message list component | ✓ EXISTS + SUBSTANTIVE | Exports ChatList, renders Message[], no stubs |
+| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | File exists but POST returns placeholder |
+| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Model defined with all fields |
+
+**Artifacts:** {N}/{M} verified
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|----|--------|---------|
+| Chat.tsx | /api/chat | fetch in useEffect | ✓ WIRED | Line 23: `fetch('/api/chat')` with response handling |
+| ChatInput | /api/chat POST | onSubmit handler | ✗ NOT WIRED | onSubmit only calls console.log |
+| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns hardcoded response, no DB call |
+
+**Wiring:** {N}/{M} connections verified
+
+## Requirements Coverage
+
+| Requirement | Status | Blocking Issue |
+|-------------|--------|----------------|
+| {REQ-01}: {description} | ✓ SATISFIED | - |
+| {REQ-02}: {description} | ✗ BLOCKED | API route is stub |
+| {REQ-03}: {description} | ? NEEDS HUMAN | Can't verify WebSocket programmatically |
+
+**Coverage:** {N}/{M} requirements satisfied
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| src/app/api/chat/route.ts | 12 | `// TODO: implement` | ⚠️ Warning | Indicates incomplete |
+| src/components/Chat.tsx | 45 | `return <div>Placeholder</div>` | 🛑 Blocker | Renders no content |
+| src/hooks/useChat.ts | - | File missing | 🛑 Blocker | Expected hook doesn't exist |
+
+**Anti-patterns:** {N} found ({blockers} blockers, {warnings} warnings)
+
+## Human Verification Required
+
+{If no human verification needed:}
+None — all verifiable items checked programmatically.
+
+{If human verification needed:}
+
+### 1. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+
+### 2. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+
+## Gaps Summary
+
+{If no gaps:}
+**No gaps found.** Phase goal achieved. Ready to proceed.
+
+{If gaps found:}
+
+### Critical Gaps (Block Progress)
+
+1. **{Gap name}**
+   - Missing: {what's missing}
+   - Impact: {why this blocks the goal}
+   - Fix: {what needs to happen}
+
+2. **{Gap name}**
+   - Missing: {what's missing}
+   - Impact: {why this blocks the goal}
+   - Fix: {what needs to happen}
+
+### Non-Critical Gaps (Can Defer)
+
+1. **{Gap name}**
+   - Issue: {what's wrong}
+   - Impact: {limited impact because...}
+   - Recommendation: {fix now or defer}
+
+## Recommended Fix Plans
+
+{If gaps found, generate fix plan recommendations:}
+
+### {phase}-{next}-PLAN.md: {Fix Name}
+
+**Objective:** {What this fixes}
+
+**Tasks:**
+1. {Task to fix gap 1}
+2. {Task to fix gap 2}
+3. {Verification task}
+
+**Estimated scope:** {Small / Medium}
+
+---
+
+### {phase}-{next+1}-PLAN.md: {Fix Name}
+
+**Objective:** {What this fixes}
+
+**Tasks:**
+1. {Task}
+2. {Task}
+
+**Estimated scope:** {Small / Medium}
+
+---
+
+## Verification Metadata
+
+**Verification approach:** Goal-backward (derived from phase goal)
+**Must-haves source:** {PLAN.md frontmatter | derived from ROADMAP.md goal}
+**Automated checks:** {N} passed, {M} failed
+**Human checks required:** {N}
+**Total verification time:** {duration}
+
+---
+*Verified: {timestamp}*
+*Verifier: Claude (subagent)*
+```
+
+---
+
+## Guidelines
+
+**Status values:**
+- `passed` — All must-haves verified, no blockers
+- `gaps_found` — One or more critical gaps found
+- `human_needed` — Automated checks pass but human verification required
+
+**Evidence types:**
+- For EXISTS: "File at path, exports X"
+- For SUBSTANTIVE: "N lines, has patterns X, Y, Z"
+- For WIRED: "Line N: code that connects A to B"
+- For FAILED: "Missing because X" or "Stub because Y"
+
+**Severity levels:**
+- 🛑 Blocker: Prevents goal achievement, must fix
+- ⚠️ Warning: Indicates incomplete but doesn't block
+- ℹ️ Info: Notable but not problematic
+
+**Fix plan generation:**
+- Only generate if gaps_found
+- Group related fixes into single plans
+- Keep to 2-3 tasks per plan
+- Include verification task in each plan
+
+---
+
+## Example
+
+```markdown
+---
+phase: 03-chat
+verified: 2025-01-15T14:30:00Z
+status: gaps_found
+score: 2/5 must-haves verified
+---
+
+# Phase 3: Chat Interface Verification Report
+
+**Phase Goal:** Working chat interface where users can send and receive messages
+**Verified:** 2025-01-15T14:30:00Z
+**Status:** gaps_found
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | User can see existing messages | ✗ FAILED | Component renders placeholder, not message data |
+| 2 | User can type a message | ✓ VERIFIED | Input field exists with onChange handler |
+| 3 | User can send a message | ✗ FAILED | onSubmit handler is console.log only |
+| 4 | Sent message appears in list | ✗ FAILED | No state update after send |
+| 5 | Messages persist across refresh | ? UNCERTAIN | Can't verify - send doesn't work |
+
+**Score:** 1/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Message list component | ✗ STUB | Returns `<div>Chat will be here</div>` |
+| `src/components/ChatInput.tsx` | Message input | ✓ EXISTS + SUBSTANTIVE | Form with input, submit button, handlers |
+| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | GET returns [], POST returns { ok: true } |
+| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Message model with id, content, userId, createdAt |
+
+**Artifacts:** 2/4 verified
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|----|--------|---------|
+| Chat.tsx | /api/chat GET | fetch | ✗ NOT WIRED | No fetch call in component |
+| ChatInput | /api/chat POST | onSubmit | ✗ NOT WIRED | Handler only logs, doesn't fetch |
+| /api/chat GET | database | prisma.message.findMany | ✗ NOT WIRED | Returns hardcoded [] |
+| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns { ok: true }, no DB call |
+
+**Wiring:** 0/4 connections verified
+
+## Requirements Coverage
+
+| Requirement | Status | Blocking Issue |
+|-------------|--------|----------------|
+| CHAT-01: User can send message | ✗ BLOCKED | API POST is stub |
+| CHAT-02: User can view messages | ✗ BLOCKED | Component is placeholder |
+| CHAT-03: Messages persist | ✗ BLOCKED | No database integration |
+
+**Coverage:** 0/3 requirements satisfied
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| src/components/Chat.tsx | 8 | `<div>Chat will be here</div>` | 🛑 Blocker | No actual content |
+| src/app/api/chat/route.ts | 5 | `return Response.json([])` | 🛑 Blocker | Hardcoded empty |
+| src/app/api/chat/route.ts | 12 | `// TODO: save to database` | ⚠️ Warning | Incomplete |
+
+**Anti-patterns:** 3 found (2 blockers, 1 warning)
+
+## Human Verification Required
+
+None needed until automated gaps are fixed.
+
+## Gaps Summary
+
+### Critical Gaps (Block Progress)
+
+1. **Chat component is placeholder**
+   - Missing: Actual message list rendering
+   - Impact: Users see "Chat will be here" instead of messages
+   - Fix: Implement Chat.tsx to fetch and render messages
+
+2. **API routes are stubs**
+   - Missing: Database integration in GET and POST
+   - Impact: No data persistence, no real functionality
+   - Fix: Wire prisma calls in route handlers
+
+3. **No wiring between frontend and backend**
+   - Missing: fetch calls in components
+   - Impact: Even if API worked, UI wouldn't call it
+   - Fix: Add useEffect fetch in Chat, onSubmit fetch in ChatInput
+
+## Recommended Fix Plans
+
+### 03-04-PLAN.md: Implement Chat API
+
+**Objective:** Wire API routes to database
+
+**Tasks:**
+1. Implement GET /api/chat with prisma.message.findMany
+2. Implement POST /api/chat with prisma.message.create
+3. Verify: API returns real data, POST creates records
+
+**Estimated scope:** Small
+
+---
+
+### 03-05-PLAN.md: Implement Chat UI
+
+**Objective:** Wire Chat component to API
+
+**Tasks:**
+1. Implement Chat.tsx with useEffect fetch and message rendering
+2. Wire ChatInput onSubmit to POST /api/chat
+3. Verify: Messages display, new messages appear after send
+
+**Estimated scope:** Small
+
+---
+
+## Verification Metadata
+
+**Verification approach:** Goal-backward (derived from phase goal)
+**Must-haves source:** 03-01-PLAN.md frontmatter
+**Automated checks:** 2 passed, 8 failed
+**Human checks required:** 0 (blocked by automated failures)
+**Total verification time:** 2 min
+
+---
+*Verified: 2025-01-15T14:30:00Z*
+*Verifier: Claude (subagent)*
+```

package/plan-build-run/workflows/add-phase.md

@@ -0,0 +1,111 @@
+<purpose>
+Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/pbr:add-phase Add authentication` → description = "Add authentication"
+- Example: `/pbr:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /pbr:add-phase <description>
+Example: /pbr:add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node ~/.claude/plan-build-run/scripts/pbr-tools.cjs init phase-op "0")
+```
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /pbr:new-project to initialize.
+```
+Exit.
+</step>
+
+<step name="add_phase">
+**Delegate the phase addition to pbr-tools:**
+
+```bash
+RESULT=$(node ~/.claude/plan-build-run/scripts/pbr-tools.cjs phase add "${description}")
+```
+
+The CLI handles:
+- Finding the highest existing integer phase number
+- Calculating next phase number (max + 1)
+- Generating slug from description
+- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
+- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
+
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: .planning/ROADMAP.md
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/pbr:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/pbr:add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `pbr-tools phase add` executed successfully
+- [ ] Phase directory created
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps
+</success_criteria>

package/plan-build-run/workflows/add-todo.md

@@ -0,0 +1,157 @@
+<purpose>
+Capture an idea, task, or issue that surfaces during a PBR session as a structured todo for later work. Enables "thought → capture → continue" flow without losing context.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="init_context">
+Load todo context:
+
+```bash
+INIT=$(node ~/.claude/plan-build-run/scripts/pbr-tools.cjs init todos)
+```
+
+Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`.
+
+Ensure directories exist:
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+
+Note existing areas from the todos array for consistency in infer_area step.
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+- `/pbr:add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**Without arguments:** Analyze recent conversation to extract:
+- The specific problem, idea, or task discussed
+- Relevant file paths mentioned
+- Technical details (error messages, line numbers, constraints)
+
+Formulate:
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What's wrong or why this is needed
+- `solution`: Approach hints or "TBD" if just an idea
+- `files`: Relevant paths with line numbers from conversation
+</step>
+
+<step name="infer_area">
+Infer area from file paths:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing area from step 2 if similar match exists.
+</step>
+
+<step name="check_duplicates">
+```bash
+# Search for key words from title in existing todos
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+If potential duplicate found:
+1. Read the existing todo
+2. Compare scope
+
+If overlapping, use AskUserQuestion:
+- header: "Duplicate?"
+- question: "Similar todo exists: [title]. What would you like to do?"
+- options:
+  - "Skip" — keep existing todo
+  - "Replace" — update existing with new context
+  - "Add anyway" — create as separate todo
+</step>
+
+<step name="create_file">
+Use values from init context: `timestamp` and `date` are already available.
+
+Generate slug for the title:
+```bash
+slug=$(node ~/.claude/plan-build-run/scripts/pbr-tools.cjs generate-slug "$title" --raw)
+```
+
+Write to `.planning/todos/pending/${date}-${slug}.md`:
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future Claude to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+If `.planning/STATE.md` exists:
+
+1. Use `todo_count` from init context (or re-run `init todos` if count changed)
+2. Update "### Pending Todos" under "## Accumulated Context"
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+```bash
+node ~/.claude/plan-build-run/scripts/pbr-tools.cjs commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
+```
+
+Tool respects `commit_docs` config and gitignore automatically.
+
+Confirm: "Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/pbr:check-todos)
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Directory structure exists
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future Claude
+- [ ] No duplicates (checked and resolved)
+- [ ] Area consistent with existing todos
+- [ ] STATE.md updated if exists
+- [ ] Todo and state committed to git
+</success_criteria>