@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/templates/context.md

@@ -0,0 +1,297 @@
+# Phase Context Template
+
+Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implementation decisions for a phase.
+
+**Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
+
+**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
+**Downstream consumers:**
+- `pbr-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
+- `pbr-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Area 1 that was discussed]
+- [Specific decision made]
+- [Another decision if applicable]
+
+### [Area 2 that was discussed]
+- [Specific decision made]
+
+### [Area 3 that was discussed]
+- [Specific decision made]
+
+### Claude's Discretion
+[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- [Component/hook/utility]: [How it could be used in this phase]
+
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
+
+### Integration Points
+- [Where new code connects to existing system]
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: [date]*
+```
+
+<good_examples>
+
+**Example 1: Visual feature (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Layout style
+- Card-based layout, not timeline or list
+- Each card shows: author avatar, name, timestamp, full post content, reaction counts
+- Cards have subtle shadows, rounded corners — modern feel
+
+### Loading behavior
+- Infinite scroll, not pagination
+- Pull-to-refresh on mobile
+- New posts indicator at top ("3 new posts") rather than auto-inserting
+
+### Empty state
+- Friendly illustration + "Follow people to see posts here"
+- Suggest 3-5 accounts to follow based on interests
+
+### Claude's Discretion
+- Loading skeleton design
+- Exact spacing and typography
+- Error state handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
+- Cards should feel like Linear's issue cards — clean, not cluttered
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Commenting on posts — Phase 5
+- Bookmarking posts — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 03-post-feed*
+*Context gathered: 2025-01-20*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### Claude's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 02-backup-command*
+*Context gathered: 2025-01-20*
+```
+
+**Example 3: Organization task (Photo library)**
+
+```markdown
+# Phase 1: Photo Organization - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Grouping criteria
+- Primary grouping by year, then by month
+- Events detected by time clustering (photos within 2 hours = same event)
+- Event folders named by date + location if available
+
+### Duplicate handling
+- Keep highest resolution version
+- Move duplicates to _duplicates folder (don't delete)
+- Log all duplicate decisions for review
+
+### Naming convention
+- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
+- Preserve original filename as suffix for searchability
+- Handle name collisions with incrementing suffix
+
+### Claude's Discretion
+- Exact clustering algorithm
+- How to handle photos with no EXIF data
+- Folder emoji usage
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want to be able to find photos by roughly when they were taken"
+- Don't delete anything — worst case, move to a review folder
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Face detection grouping — future phase
+- Cloud sync — out of scope for now
+
+</deferred>
+
+---
+
+*Phase: 01-photo-organization*
+*Context gathered: 2025-01-20*
+```
+
+</good_examples>
+
+<guidelines>
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
+
+**Good content (concrete decisions):**
+- "Card-based layout, not timeline"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
+
+**Bad content (too vague):**
+- "Should feel modern and clean"
+- "Good user experience"
+- "Fast and responsive"
+- "Easy to use"
+
+**After creation:**
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-CONTEXT.md`
+- `pbr-phase-researcher` uses decisions to focus investigation
+- `pbr-planner` uses decisions + research to create executable tasks
+- Downstream agents should NOT need to ask the user again about captured decisions
+</guidelines>

package/plan-build-run/templates/continue-here.md

@@ -0,0 +1,78 @@
+# Continue-Here Template
+
+Copy and fill this structure for `.planning/phases/XX-name/.continue-here.md`:
+
+```yaml
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: 2025-01-15T14:30:00Z
+---
+```
+
+```markdown
+<current_state>
+[Where exactly are we? What's the immediate context?]
+</current_state>
+
+<completed_work>
+[What got done this session - be specific]
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done on it]
+</completed_work>
+
+<remaining_work>
+[What's left in this phase]
+
+- Task 3: [name] - [what's left to do]
+- Task 4: [name] - Not started
+- Task 5: [name] - Not started
+</remaining_work>
+
+<decisions_made>
+[Key decisions and why - so next session doesn't re-debate]
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisions_made>
+
+<blockers>
+[Anything stuck or waiting on external factors]
+
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+<context>
+[Mental state, "vibe", anything that helps resume smoothly]
+
+[What were you thinking about? What was the plan?
+This is the "pick up exactly where you left off" context.]
+</context>
+
+<next_action>
+[The very first thing to do when resuming]
+
+Start with: [specific action]
+</next_action>
+```
+
+<yaml_fields>
+Required YAML frontmatter:
+
+- `phase`: Directory name (e.g., `02-authentication`)
+- `task`: Current task number
+- `total_tasks`: How many tasks in phase
+- `status`: `in_progress`, `blocked`, `almost_done`
+- `last_updated`: ISO timestamp
+</yaml_fields>
+
+<guidelines>
+- Be specific enough that a fresh Claude instance understands immediately
+- Include WHY decisions were made, not just what
+- The `<next_action>` should be actionable without reading anything else
+- This file gets DELETED after resume - it's not permanent storage
+</guidelines>

package/plan-build-run/templates/crud-flow-verification.md

@@ -0,0 +1,277 @@
+# CRUD Flow Verification Template
+
+Use this template to verify end-to-end Create/Read/Update/Delete flows for any entity in the system.
+
+## Entity: {ENTITY_NAME}
+
+**Source phase:** {phase that introduced this entity}
+**API base:** {/api/entity or equivalent}
+**Model/Schema:** {path to model definition}
+
+---
+
+## 10-Step Verification
+
+### Step 1: Model/Schema Exists
+
+Verify the entity has a defined data model.
+
+```bash
+# Prisma/Drizzle
+grep -r "model {Entity}" prisma/ --include="*.prisma" 2>/dev/null
+grep -r "{entity}" src/ --include="*.schema.ts" 2>/dev/null
+
+# SQLAlchemy / Django
+grep -r "class {Entity}" --include="*.py" 2>/dev/null | grep -E "Base|Model|db.Model"
+
+# Mongoose
+grep -r "{entity}Schema\|model.*{Entity}" --include="*.ts" --include="*.js" 2>/dev/null
+```
+
+- [ ] Model defined with required fields
+- [ ] Relationships/foreign keys defined
+- [ ] Validation constraints present
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 2: Create Route Exists
+
+Verify a POST/create endpoint exists.
+
+```bash
+# Next.js App Router
+find src/app/api/{entity} -name "route.ts" 2>/dev/null
+
+# Express
+grep -rn "router.post.*{entity}\|app.post.*{entity}" --include="*.ts" --include="*.js" 2>/dev/null
+
+# FastAPI
+grep -rn "@router.post.*{entity}\|@app.post.*{entity}" --include="*.py" 2>/dev/null
+
+# Flask
+grep -rn "@.*route.*{entity}.*methods.*POST" --include="*.py" 2>/dev/null
+```
+
+- [ ] POST endpoint exists
+- [ ] Input validation on create
+- [ ] Returns created entity or ID
+- [ ] Proper error responses (400, 409, 500)
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 3: Read Routes Exist (List + Detail)
+
+Verify GET endpoints for listing and single-entity retrieval.
+
+```bash
+# List endpoint (GET /entities)
+grep -rn "GET.*{entity}" --include="*.ts" --include="*.js" --include="*.py" 2>/dev/null
+
+# Detail endpoint (GET /entities/:id)
+grep -rn "{entity}.*\[id\]\|{entity}.*:id\|{entity}.*<.*id" --include="*.ts" --include="*.js" --include="*.py" 2>/dev/null
+```
+
+- [ ] List endpoint returns array/paginated results
+- [ ] Detail endpoint returns single entity
+- [ ] 404 handling for missing entity
+- [ ] Query filters/pagination supported (list)
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 4: Update Route Exists
+
+Verify PUT/PATCH endpoint exists.
+
+```bash
+# Express/Next.js
+grep -rn "router\.\(put\|patch\).*{entity}\|app\.\(put\|patch\).*{entity}" --include="*.ts" --include="*.js" 2>/dev/null
+
+# FastAPI
+grep -rn "@router\.\(put\|patch\).*{entity}" --include="*.py" 2>/dev/null
+```
+
+- [ ] PUT or PATCH endpoint exists
+- [ ] Input validation on update
+- [ ] Returns updated entity
+- [ ] 404 for missing entity
+- [ ] Ownership/permission check
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 5: Delete Route Exists
+
+Verify DELETE endpoint exists.
+
+```bash
+# Express/Next.js
+grep -rn "router\.delete.*{entity}\|app\.delete.*{entity}" --include="*.ts" --include="*.js" 2>/dev/null
+
+# FastAPI
+grep -rn "@router\.delete.*{entity}" --include="*.py" 2>/dev/null
+```
+
+- [ ] DELETE endpoint exists
+- [ ] Returns confirmation or 204
+- [ ] 404 for missing entity
+- [ ] Cascade handling (related records)
+- [ ] Ownership/permission check
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 6: UI Create Form Wired to API
+
+Verify the create form submits to the correct API endpoint.
+
+```bash
+# Find create/add form component
+grep -r -l "create.*{entity}\|add.*{entity}\|new.*{entity}" src/ \
+  --include="*.tsx" --include="*.jsx" --include="*.vue" 2>/dev/null
+
+# Check it calls POST API
+grep -E "fetch.*{entity}.*POST\|axios\.post.*{entity}\|method.*POST" \
+  {form_file} 2>/dev/null
+```
+
+- [ ] Create form component exists
+- [ ] Form submits to correct POST endpoint
+- [ ] Success feedback shown to user
+- [ ] Error feedback shown on failure
+- [ ] Form clears/redirects after success
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 7: UI List View Wired to API
+
+Verify the list view fetches and displays entities.
+
+```bash
+# Find list component
+grep -r -l "list.*{entity}\|{entity}.*list\|{entity}.*table" src/ \
+  --include="*.tsx" --include="*.jsx" --include="*.vue" 2>/dev/null
+
+# Check it fetches from GET API
+grep -E "fetch.*{entity}\|useSWR.*{entity}\|useQuery.*{entity}" \
+  {list_file} 2>/dev/null
+```
+
+- [ ] List component exists
+- [ ] Fetches from correct GET endpoint
+- [ ] Renders entity data in list/table
+- [ ] Loading state shown during fetch
+- [ ] Empty state when no entities
+- [ ] Error state on fetch failure
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 8: UI Edit Form Wired to API
+
+Verify the edit form loads existing data and submits updates.
+
+```bash
+# Find edit form component
+grep -r -l "edit.*{entity}\|update.*{entity}" src/ \
+  --include="*.tsx" --include="*.jsx" --include="*.vue" 2>/dev/null
+
+# Check it loads then submits
+grep -E "fetch.*{entity}.*PUT\|fetch.*{entity}.*PATCH\|axios\.\(put\|patch\).*{entity}" \
+  {edit_file} 2>/dev/null
+```
+
+- [ ] Edit form component exists
+- [ ] Pre-populates with existing entity data
+- [ ] Submits to correct PUT/PATCH endpoint
+- [ ] Success feedback shown
+- [ ] Optimistic update or refetch after save
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 9: UI Delete Action Wired to API
+
+Verify delete action triggers API call and updates UI.
+
+```bash
+# Find delete button/action
+grep -r -l "delete.*{entity}\|remove.*{entity}" src/ \
+  --include="*.tsx" --include="*.jsx" --include="*.vue" 2>/dev/null
+
+# Check it calls DELETE API
+grep -E "fetch.*{entity}.*DELETE\|axios\.delete.*{entity}" \
+  {delete_file} 2>/dev/null
+```
+
+- [ ] Delete button/action exists
+- [ ] Confirmation prompt before delete
+- [ ] Calls correct DELETE endpoint
+- [ ] Entity removed from UI after delete
+- [ ] Error handling on delete failure
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+### Step 10: Auth Protection on All CRUD Routes
+
+Verify all CRUD operations check authentication and authorization.
+
+```bash
+# Check auth on all entity routes
+grep -B5 "{entity}" routes/ src/ --include="*.ts" --include="*.js" --include="*.py" 2>/dev/null | \
+  grep -E "requireAuth|isAuthenticated|Depends.*auth|login_required|getServerSession"
+```
+
+- [ ] Create requires authentication
+- [ ] Read may be public or authenticated (as designed)
+- [ ] Update requires authentication + ownership check
+- [ ] Delete requires authentication + ownership check
+- [ ] Admin-only operations protected by role check
+
+**Status:** {PASS | FAIL | PARTIAL}
+**Notes:** {details}
+
+---
+
+## CRUD Flow Summary
+
+| Step | Check | Status |
+|------|-------|--------|
+| 1 | Model/Schema | {status} |
+| 2 | Create Route | {status} |
+| 3 | Read Routes | {status} |
+| 4 | Update Route | {status} |
+| 5 | Delete Route | {status} |
+| 6 | UI Create -> API | {status} |
+| 7 | UI List -> API | {status} |
+| 8 | UI Edit -> API | {status} |
+| 9 | UI Delete -> API | {status} |
+| 10 | Auth Protection | {status} |
+
+**CRUD Score:** {passed}/{total} steps passing ({percent}%)
+
+**Critical Gaps:**
+- {gap 1}
+- {gap 2}