@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/references/ui-formatting.md

@@ -0,0 +1,399 @@
+# Plan-Build-Run UI Brand & Formatting Reference
+
+Consistent output formatting for all Plan-Build-Run skills. Every skill that produces user-facing output should follow these patterns.
+
+## Stage Banners
+
+Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► {STAGE NAME}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Stage names (uppercase):**
+- `QUESTIONING`
+- `RESEARCHING`
+- `DEFINING REQUIREMENTS`
+- `CREATING ROADMAP`
+- `PLANNING PHASE {N}`
+- `EXECUTING WAVE {N}`
+- `VERIFYING`
+- `PHASE {N} COMPLETE ✓`
+- `MILESTONE COMPLETE 🎉`
+- `SCANNING CODEBASE`
+- `DEBUGGING`
+
+---
+
+## Headers
+
+Use these patterns for consistent visual hierarchy within sections:
+
+```
+## Phase 3: Authentication        <- Phase-level header
+### Plan 01: Database Schema      <- Plan-level header
+#### Task 1: Create User Table    <- Task-level header
+```
+
+---
+
+## Status Indicators
+
+| Status | Indicator | Usage |
+|--------|-----------|-------|
+| Complete | `✓` | Completed items, passed checks |
+| Failed | `✗` | Failed verification, missing items |
+| Pending | `○` | Not yet started |
+| In Progress | `◐` | Currently executing |
+| Needs Human | `?` | Requires human verification |
+| Warning | `⚠` | Warnings, non-blocking issues |
+| Blocked | `⊘` | Blocked by dependency |
+| Auto-approved | `⚡` | Automatically approved (gates) |
+
+---
+
+## Progress Display
+
+**Phase/milestone level:**
+```
+Progress: ████████░░ 80%
+```
+
+**Phase progress (detailed):**
+```
+Phase 3 of 5: Authentication
+Progress: [████████░░░░░░░░░░░░] 40%
+Plans: 2/5 complete
+```
+
+**Build progress (wave tracking):**
+```
+Wave 1: ✓ Plan 01, ✓ Plan 02
+Wave 2: ◐ Plan 03 (executing)
+Wave 3: ○ Plan 04
+```
+
+**Task level:**
+```
+Tasks: 2/4 complete
+```
+
+---
+
+## Spawning Indicators
+
+Show when agents are being launched:
+
+```
+◐ Spawning executor...
+
+◐ Spawning 4 executors in parallel...
+  → Plan 01: Database Schema
+  → Plan 02: Auth Service
+  → Plan 03: API Routes
+  → Plan 04: Test Suite
+
+✓ Plan 01 complete (2m 14s)
+```
+
+For research agents:
+```
+◐ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+
+✓ Researcher complete: STACK.md written
+```
+
+---
+
+## Checkpoint Boxes
+
+User action required. Use double-line box drawing, 62-character width.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Content}
+
+──────────────────────────────────────────────────────────────
+→ {ACTION PROMPT}
+──────────────────────────────────────────────────────────────
+```
+
+**Types:**
+- `CHECKPOINT: Verification Required` → `→ Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` → `→ Select: option-a / option-b`
+- `CHECKPOINT: Action Required` → `→ Type "done" when complete`
+
+---
+
+## AskUserQuestion Patterns
+
+Structured prompts for user decision points. All gate checks use AskUserQuestion instead of
+plain-text "Type approved" prompts. See `skills/shared/gate-prompts.md` for the full
+pattern catalog (21 named AskUserQuestion patterns).
+
+### Structure
+
+```
+AskUserQuestion:
+  question: "{contextual question}"
+  header: "{max 12 chars}"
+  options:
+    - label: "{Option 1}"  description: "{What happens}"
+    - label: "{Option 2}"  description: "{What happens}"
+  multiSelect: false
+```
+
+### Rules
+
+- **Max 4 options** per call. Split into 2-step flow if more are needed.
+- **Header max 12 characters.** Single word preferred (e.g., "Approve?", "Confirm", "Scope").
+- **multiSelect: false** always. Plan-Build-Run gates require single selection.
+- **Handle "Other"**: Users may type freeform text instead of selecting. Skills must handle this gracefully.
+- **Orchestrator only**: AskUserQuestion cannot be called from subagents.
+
+### Common Patterns
+
+**Approval gate** (approve-revise-abort):
+```
+question: "Approve these plans?"
+header: "Approve?"
+options:
+  - label: "Approve"          description: "Proceed with execution"
+  - label: "Request changes"  description: "Discuss adjustments before proceeding"
+  - label: "Abort"            description: "Cancel this operation"
+```
+
+**Simple confirmation** (yes-no):
+```
+question: "Re-plan this phase with gap context?"
+header: "Confirm"
+options:
+  - label: "Yes"  description: "Create gap-closure plans"
+  - label: "No"   description: "Skip re-planning"
+```
+
+**Category selection** (settings-category-select):
+```
+question: "What would you like to configure?"
+header: "Configure"
+options:
+  - label: "Depth"          description: "quick/standard/comprehensive"
+  - label: "Model profile"  description: "quality/balanced/budget/adaptive"
+  - label: "Features"       description: "Toggle workflow features and gates"
+  - label: "Git settings"   description: "branching strategy, commit mode"
+```
+
+**Dynamic routing** (action-routing):
+```
+question: "What would you like to do next?"
+header: "Next Step"
+options:
+  - label: "/pbr:build 3"    description: "Execute phase 3 plans"
+  - label: "/pbr:review 2"   description: "Verify phase 2 results"
+  - label: "Something else"  description: "Enter a different command"
+```
+
+### When NOT to Use
+
+Do not use AskUserQuestion for:
+- Freeform text input (symptom descriptions, task descriptions, open questions)
+- Socratic discussion (explore, discuss follow-ups)
+- Situations with unbounded response space
+
+Use plain conversational prompts for these cases instead.
+
+---
+
+## Next Up Block
+
+Always present at end of major completions (phase complete, milestone complete, project init).
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{Identifier}: {Name}** — {one-line description}
+
+`{copy-paste command}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:alternative-1` — description
+- `/pbr:alternative-2` — description
+
+───────────────────────────────────────────────────────────────
+```
+
+**Shorter routing (for minor completions):**
+```
+What's next?
+→ /pbr:plan 4 — plan the next phase
+→ /pbr:review 3 — review what was just built
+→ /pbr:status — see full project status
+```
+
+---
+
+## Error Box
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## Tables
+
+Use tables for structured data:
+
+```markdown
+| Phase | Status | Plans | Progress |
+|-------|--------|-------|----------|
+| 1. Foundation | ✓ Complete | 3/3 | 100% |
+| 2. Database | ✓ Complete | 2/2 | 100% |
+| 3. Auth | ◐ Building | 1/3 | 33% |
+| 4. Frontend | ○ Pending | 0/4 | 0% |
+```
+
+---
+
+## Cost/Token Warnings
+
+```
+⚠ Budget check: This operation will spawn 4 agents (~400k tokens)
+  Estimated: ~20% of 5-hour window
+  Continue? [/pbr:config to adjust depth first]
+```
+
+---
+
+## Completion Summary Templates
+
+### Phase Complete
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {N}: {Name}**
+
+{X} plans executed
+Goal verified ✓
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
+
+/pbr:discuss {N+1} — gather context and clarify approach
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- /pbr:plan {N+1} — skip discussion, plan directly
+- /pbr:review {N} — manual acceptance testing before continuing
+
+───────────────────────────────────────────────────────────────
+```
+
+### Milestone Complete
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**{version}**
+
+{N} phases completed
+All phase goals verified ✓
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Audit milestone** — verify requirements, cross-phase integration, E2E flows
+
+/pbr:milestone audit
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- /pbr:review — manual acceptance testing
+- /pbr:milestone complete — skip audit, archive directly
+
+───────────────────────────────────────────────────────────────
+```
+
+### Gaps Found
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {N}: {Name}**
+
+Score: {X}/{Y} must-haves verified
+Report: .planning/phases/{phase_dir}/VERIFICATION.md
+
+### What's Missing
+
+{Extract gap summaries from VERIFICATION.md}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan gap closure** — create additional plans to complete the phase
+
+/pbr:plan {N} --gaps
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
+- /pbr:review {N} — manual testing before planning
+
+───────────────────────────────────────────────────────────────
+```
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Use varying box/banner widths
+- Mix banner styles (`===`, `---`, `***`) with `━━━` banners
+- Skip `PLAN-BUILD-RUN ►` prefix in stage banners
+- Use random emoji (only `🎉` for milestone complete, `✓` for phase complete)
+- Skip the "Next Up" block after major completions
+- Reference non-Plan-Build-Run commands (always use `/dev:*` commands)
+- Use non-Plan-Build-Run branding in banners

package/plugins/pbr/references/verification-patterns.md

@@ -0,0 +1,198 @@
+# Goal-Backward Verification Patterns
+
+Reference patterns for deriving verification criteria from goals. Used by the planner to create `<verify>` and `<done>` elements, and by the verifier to check phase completion.
+
+---
+
+## The Three-Layer Check
+
+Every must-have is verified through three layers, checked in order:
+
+### Layer 1: Existence
+
+Does the artifact exist?
+
+```bash
+# File existence
+ls -la src/auth/discord.ts
+
+# Module export existence
+grep -q "export.*authenticateWithDiscord" src/auth/discord.ts
+
+# Database table existence
+npx prisma db execute --stdin <<< "SELECT 1 FROM users LIMIT 1"
+
+# Route existence
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api/auth/login
+```
+
+### Layer 2: Substantiveness
+
+Is the artifact more than a stub?
+
+```bash
+# File has real content (not just exports)
+wc -l src/auth/discord.ts  # Should be > 10 lines for a real implementation
+
+# Function has a body (not just a signature)
+grep -A5 "authenticateWithDiscord" src/auth/discord.ts | grep -q "return"
+
+# Test file has actual test cases
+grep -c "it(" tests/auth.test.ts  # Should be > 0
+
+# API returns real data (not just 200 OK)
+curl -s http://localhost:3000/api/health | jq '.status' | grep -q "ok"
+```
+
+### Layer 3: Wiring
+
+Are components connected to each other?
+
+```bash
+# Module is imported where needed
+grep -q "from.*auth/discord" src/routes/auth.ts
+
+# Middleware is applied to routes
+grep -q "requireAuth" src/routes/protected.ts
+
+# Database is configured in app init
+grep -q "prisma" src/app.ts
+
+# Environment variables are referenced
+grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
+```
+
+---
+
+## Verification by Feature Type
+
+### API Endpoint
+
+```
+Existence:  curl returns non-404 status
+Substance:  curl returns expected response shape (correct fields)
+Wiring:     endpoint calls the right service, middleware is applied
+```
+
+### Database Schema
+
+```
+Existence:  table/collection exists, can query without error
+Substance:  columns/fields match specification, constraints are applied
+Wiring:     application code references the schema, migrations run cleanly
+```
+
+### Authentication
+
+```
+Existence:  auth routes exist, auth module exports functions
+Substance:  login flow returns token, invalid creds return error
+Wiring:     protected routes use auth middleware, tokens are validated
+```
+
+### UI Component
+
+```
+Existence:  component file exists, exports default component
+Substance:  component renders expected elements (test or visual check)
+Wiring:     component is imported in parent, receives correct props, routes to it
+```
+
+### Configuration
+
+```
+Existence:  config file exists, environment variables documented
+Substance:  config values are used (not dead code), defaults are sensible
+Wiring:     application reads config at startup, config changes take effect
+```
+
+---
+
+## Verify Command Patterns
+
+### TypeScript/JavaScript
+
+```bash
+# Type checking
+npx tsc --noEmit
+
+# Unit tests
+npm test
+npm test -- --grep "pattern"
+npx jest path/to/test
+
+# Linting
+npx eslint src/auth/
+
+# Build check
+npm run build
+```
+
+### Python
+
+```bash
+# Type checking
+mypy src/
+
+# Unit tests
+pytest tests/
+pytest tests/test_auth.py -v
+pytest -k "test_login"
+
+# Linting
+flake8 src/
+pylint src/auth/
+```
+
+### General
+
+```bash
+# File existence
+ls -la path/to/file
+
+# Content check
+grep -q "pattern" path/to/file
+
+# HTTP endpoint
+curl -s -o /dev/null -w "%{http_code}" http://localhost:PORT/path
+
+# Process running
+pgrep -f "process-name"
+
+# Port listening
+netstat -an | grep LISTEN | grep PORT
+```
+
+---
+
+## Done Condition Patterns
+
+### Good Done Conditions (Observable, Falsifiable)
+
+- "User can log in with Discord and see their dashboard"
+- "API returns paginated list of items with correct total count"
+- "Database migration creates users table with all required columns"
+- "Protected routes return 401 without valid JWT"
+- "Build completes without TypeScript errors"
+
+### Bad Done Conditions (Vague, Not Falsifiable)
+
+- "Authentication is implemented" (how do you test this?)
+- "Code is clean" (subjective)
+- "Database is set up" (what does "set up" mean?)
+- "Tests pass" (which tests? what do they test?)
+- "File was created" (created with what content?)
+
+### Transformation Rule
+
+```
+Bad:  "Authentication is implemented"
+Good: "User can complete Discord OAuth flow and receive a valid JWT"
+
+Bad:  "Database is set up"
+Good: "Users table exists with id, email, name columns and can accept INSERT"
+
+Bad:  "Tests pass"
+Good: "All 5 auth middleware tests pass: valid token, expired token,
+       missing token, malformed token, and correct user extraction"
+```

package/plugins/pbr/references/wave-execution.md

@@ -0,0 +1,95 @@
+# Wave-Based Execution
+
+How Plan-Build-Run parallelizes plan execution within a phase while respecting dependencies.
+
+---
+
+## What Are Waves?
+
+Waves are dependency-based groupings of plans within a phase. Plans in the same wave have no dependencies on each other and can execute in parallel. Plans in later waves depend on earlier waves completing first.
+
+```
+Wave 1: [plan-01, plan-02]      (no dependencies, can run in parallel)
+Wave 2: [plan-03]               (depends on wave 1 plans)
+Wave 3: [plan-04, plan-05]      (depends on wave 2)
+```
+
+## How Wave Numbers Are Assigned
+
+Wave numbers come from the `depends_on` field in each plan's YAML frontmatter:
+
+```yaml
+---
+plan: "03-01"
+wave: 1
+depends_on: []          # No dependencies → Wave 1
+---
+```
+
+```yaml
+---
+plan: "03-03"
+wave: 2
+depends_on: [03-01]     # Depends on Wave 1 plan → Wave 2
+---
+```
+
+**Rules**:
+- Wave 1 plans must have `depends_on: []`
+- Wave 2+ plans must depend only on plans from earlier waves
+- No plan depends on a plan in the same wave (that would require sequential execution within the wave)
+
+## Execution Order
+
+1. All Wave 1 plans execute (in parallel if enabled)
+2. Wait for all Wave 1 plans to complete
+3. All Wave 2 plans execute (in parallel if enabled)
+4. Repeat until all waves complete
+
+## Parallelization Config
+
+Controlled by `config.json`:
+
+```json
+{
+  "parallelization": {
+    "enabled": true,
+    "plan_level": true,
+    "max_concurrent_agents": 3
+  }
+}
+```
+
+| Setting | Effect |
+|---------|--------|
+| `enabled: false` | All plans execute sequentially, regardless of wave |
+| `plan_level: true` | Plans within a wave run in parallel |
+| `max_concurrent_agents` | Cap on simultaneous executor agents (default: 3) |
+
+When `enabled: false` or `plan_level: false`, plans execute one at a time within each wave, in plan ID order.
+
+## Git Lock Handling
+
+When multiple executors run in parallel, git lock conflicts can occur. Executors handle this with a retry pattern:
+
+```bash
+git commit -m "message" || (sleep 2 && git commit -m "message") || (sleep 2 && git commit -m "message")
+```
+
+Maximum 3 attempts with 2-second delays between retries.
+
+## Checkpoint Manifest
+
+The build skill tracks wave progress in `.checkpoint-manifest.json`:
+
+```json
+{
+  "plans": ["03-01", "03-02", "03-03"],
+  "checkpoints_resolved": ["03-01", "03-02"],
+  "wave": 2,
+  "commit_log": [...],
+  "last_good_commit": "abc1234"
+}
+```
+
+On crash/resume, the manifest tells the build skill which plans are complete and which wave to resume from.