@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/references/tdd.md

@@ -0,0 +1,263 @@
+<overview>
+TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
+
+**Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
+
+**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
+</overview>
+
+<when_to_use_tdd>
+## When TDD Improves Quality
+
+**TDD candidates (create a TDD plan):**
+- Business logic with defined inputs/outputs
+- API endpoints with request/response contracts
+- Data transformations, parsing, formatting
+- Validation rules and constraints
+- Algorithms with testable behavior
+- State machines and workflows
+- Utility functions with clear specifications
+
+**Skip TDD (use standard plan with `type="auto"` tasks):**
+- UI layout, styling, visual components
+- Configuration changes
+- Glue code connecting existing components
+- One-off scripts and migrations
+- Simple CRUD with no business logic
+- Exploratory prototyping
+
+**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+→ Yes: Create a TDD plan
+→ No: Use standard plan, add tests after if needed
+</when_to_use_tdd>
+
+<tdd_plan_structure>
+## TDD Plan Structure
+
+Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
+
+```markdown
+---
+phase: XX-name
+plan: NN
+type: tdd
+---
+
+<objective>
+[What feature and why]
+Purpose: [Design benefit of TDD for this feature]
+Output: [Working, tested feature]
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@relevant/source/files.ts
+</context>
+
+<feature>
+  <name>[Feature name]</name>
+  <files>[source file, test file]</files>
+  <behavior>
+    [Expected behavior in testable terms]
+    Cases: input → expected output
+  </behavior>
+  <implementation>[How to implement once tests pass]</implementation>
+</feature>
+
+<verification>
+[Test command that proves feature works]
+</verification>
+
+<success_criteria>
+- Failing test written and committed
+- Implementation passes test
+- Refactor complete (if needed)
+- All 2-3 commits present
+</success_criteria>
+
+<output>
+After completion, create SUMMARY.md with:
+- RED: What test was written, why it failed
+- GREEN: What implementation made it pass
+- REFACTOR: What cleanup was done (if any)
+- Commits: List of commits produced
+</output>
+```
+
+**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD—use a standard plan and add tests after.
+</tdd_plan_structure>
+
+<execution_flow>
+## Red-Green-Refactor Cycle
+
+**RED - Write failing test:**
+1. Create test file following project conventions
+2. Write test describing expected behavior (from `<behavior>` element)
+3. Run test - it MUST fail
+4. If test passes: feature exists or test is wrong. Investigate.
+5. Commit: `test({phase}-{plan}): add failing test for [feature]`
+
+**GREEN - Implement to pass:**
+1. Write minimal code to make test pass
+2. No cleverness, no optimization - just make it work
+3. Run test - it MUST pass
+4. Commit: `feat({phase}-{plan}): implement [feature]`
+
+**REFACTOR (if needed):**
+1. Clean up implementation if obvious improvements exist
+2. Run tests - MUST still pass
+3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
+
+**Result:** Each TDD plan produces 2-3 atomic commits.
+</execution_flow>
+
+<test_quality>
+## Good Tests vs Bad Tests
+
+**Test behavior, not implementation:**
+- Good: "returns formatted date string"
+- Bad: "calls formatDate helper with correct params"
+- Tests should survive refactors
+
+**One concept per test:**
+- Good: Separate tests for valid input, empty input, malformed input
+- Bad: Single test checking all edge cases with multiple assertions
+
+**Descriptive names:**
+- Good: "should reject empty email", "returns null for invalid ID"
+- Bad: "test1", "handles error", "works correctly"
+
+**No implementation details:**
+- Good: Test public API, observable behavior
+- Bad: Mock internals, test private methods, assert on internal state
+</test_quality>
+
+<framework_setup>
+## Test Framework Setup (If None Exists)
+
+When executing a TDD plan but no test framework is configured, set it up as part of the RED phase:
+
+**1. Detect project type:**
+```bash
+# JavaScript/TypeScript
+if [ -f package.json ]; then echo "node"; fi
+
+# Python
+if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
+
+# Go
+if [ -f go.mod ]; then echo "go"; fi
+
+# Rust
+if [ -f Cargo.toml ]; then echo "rust"; fi
+```
+
+**2. Install minimal framework:**
+| Project | Framework | Install |
+|---------|-----------|---------|
+| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
+| Node.js (Vite) | Vitest | `npm install -D vitest` |
+| Python | pytest | `pip install pytest` |
+| Go | testing | Built-in |
+| Rust | cargo test | Built-in |
+
+**3. Create config if needed:**
+- Jest: `jest.config.js` with ts-jest preset
+- Vitest: `vitest.config.ts` with test globals
+- pytest: `pytest.ini` or `pyproject.toml` section
+
+**4. Verify setup:**
+```bash
+# Run empty test suite - should pass with 0 tests
+npm test  # Node
+pytest    # Python
+go test ./...  # Go
+cargo test    # Rust
+```
+
+**5. Create first test file:**
+Follow project conventions for test location:
+- `*.test.ts` / `*.spec.ts` next to source
+- `__tests__/` directory
+- `tests/` directory at root
+
+Framework setup is a one-time cost included in the first TDD plan's RED phase.
+</framework_setup>
+
+<error_handling>
+## Error Handling
+
+**Test doesn't fail in RED phase:**
+- Feature may already exist - investigate
+- Test may be wrong (not testing what you think)
+- Fix before proceeding
+
+**Test doesn't pass in GREEN phase:**
+- Debug implementation
+- Don't skip to refactor
+- Keep iterating until green
+
+**Tests fail in REFACTOR phase:**
+- Undo refactor
+- Commit was premature
+- Refactor in smaller steps
+
+**Unrelated tests break:**
+- Stop and investigate
+- May indicate coupling issue
+- Fix before proceeding
+</error_handling>
+
+<commit_pattern>
+## Commit Pattern for TDD Plans
+
+TDD plans produce 2-3 atomic commits (one per phase):
+
+```
+test(08-02): add failing test for email validation
+
+- Tests valid email formats accepted
+- Tests invalid formats rejected
+- Tests empty input handling
+
+feat(08-02): implement email validation
+
+- Regex pattern matches RFC 5322
+- Returns boolean for validity
+- Handles edge cases (empty, null)
+
+refactor(08-02): extract regex to constant (optional)
+
+- Moved pattern to EMAIL_REGEX constant
+- No behavior changes
+- Tests still pass
+```
+
+**Comparison with standard plans:**
+- Standard plans: 1 commit per task, 2-4 commits per plan
+- TDD plans: 2-3 commits for single feature
+
+Both follow same format: `{type}({phase}-{plan}): {description}`
+
+**Benefits:**
+- Each commit independently revertable
+- Git bisect works at commit level
+- Clear history showing TDD discipline
+- Consistent with overall commit strategy
+</commit_pattern>
+
+<context_budget>
+## Context Budget
+
+TDD plans target **~40% context usage** (lower than standard plans' ~50%).
+
+Why lower:
+- RED phase: write test, run test, potentially debug why it didn't fail
+- GREEN phase: implement, run test, potentially iterate on failures
+- REFACTOR phase: modify code, run tests, verify no regressions
+
+Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution.
+
+Single feature focus ensures full quality throughout the cycle.
+</context_budget>

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

@@ -0,0 +1,449 @@
+# Plan-Build-Run UI Brand & Formatting Reference
+
+> **Migration note:** Skills are being migrated to these patterns. See Phase 5 for skill-level updates.
+
+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`
+
+---
+
+## Invocation Banners
+
+**Every skill MUST display a branded banner as its very first output, BEFORE any file reads, state loading, or processing.** This is the user's immediate confirmation that their command was received.
+
+Format:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {SKILL NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+**Skill names (uppercase):**
+- `STARTING PROJECT` (begin)
+- `PLANNING PHASE {N}` (plan)
+- `BUILDING PHASE {N}` (build)
+- `REVIEWING PHASE {N}` (review)
+- `QUICK TASK` (quick)
+- `NEXT STEP` (continue)
+- `PROJECT STATUS` (status)
+- `RESUMING SESSION` (resume)
+- `PAUSING SESSION` (pause)
+- `HEALTH CHECK` (health)
+- `SETUP` (setup)
+- `CONFIGURATION` (config)
+- `COMMAND REFERENCE` (help)
+- `DISCUSSION` (discuss)
+- `EXPLORING` (explore)
+- `NOTE` (note)
+- `TODO` (todo)
+- `DEBUGGING` (debug)
+- `SCANNING CODEBASE` (scan)
+- `MILESTONE` (milestone)
+- `IMPORTING PLAN` (import)
+
+**Rules:**
+1. The banner MUST be output BEFORE any tool calls (Read, Glob, Bash, Task)
+2. The banner MUST be the first text the user sees
+3. After the banner, optionally show a 1-line context summary (e.g., "Phase 3 of 7 — API Layer")
+4. Then proceed to Step 1 (state loading, argument parsing, etc.)
+
+---
+
+## 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, verified |
+| Failed | `✗` | Failed verification, missing items, blocked |
+| In Progress | `◆` | Currently executing |
+| Pending | `○` | Not yet started |
+| Auto-approved | `⚡` | Automatically approved (gates) |
+| Warning | `⚠` | Warnings, non-blocking issues |
+| Milestone | `🎉` | Milestone complete (banner only) |
+
+---
+
+## 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 inner 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:execute-phase 3"    description: "Execute phase 3 plans"
+  - label: "/pbr:verify-work 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.
+
+### Cross-Reference
+
+For questioning philosophy, when to use/not use AskUserQuestion, freeform rule, and decision gate patterns, see `references/questioning.md`.
+
+---
+
+## 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-phase 4 — plan the next phase
+→ /pbr:verify-work 3 — review what was just built
+→ /pbr:progress — 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:settings 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-phase {N+1} — gather context and clarify approach
+
+<sub>/clear first → fresh context window</sub>
+
+**Also available:**
+- /pbr:plan-phase {N+1} — skip discussion, plan directly
+- /pbr:verify-work {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:audit-milestone
+
+<sub>/clear first → fresh context window</sub>
+
+**Also available:**
+- /pbr:verify-work — manual acceptance testing
+- /pbr:complete-milestone — archive milestone after audit passes
+```
+
+### 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-phase {N} --gaps
+
+<sub>/clear first → fresh context window</sub>
+
+**Also available:**
+- cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
+- /pbr:verify-work {N} — manual testing before planning
+```
+
+---
+
+## Session Banners
+
+Use for session lifecycle transitions (pause/resume):
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
+╚══════════════════════════════════════════════════════════════╝
+
+Position: Phase {N} — {phase name}, Plan {M}
+Paused: {ISO datetime}
+Duration: {time since pause}
+
+{Summary of where work left off}
+```
+
+Other session banners: `SESSION SAVED ✓` (pause), `RESUMING SESSION` (resume start).
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Use varying box/banner widths — always 62-character inner width
+- Use `━━━` heavy bars or `───` thin dividers for banners/sections — use `╔═╗║╚═╝` boxes
+- Mix banner styles (`===`, `---`, `***`) with double-line boxes
+- 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 `/pbr:*` commands)
+- Use non-Plan-Build-Run branding in banners