@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/references/questioning.md

@@ -0,0 +1,214 @@
+# Deep Questioning Guide
+
+Techniques for understanding a user's project vision during `/pbr:begin`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
+
+---
+
+## Core Questioning Techniques
+
+### Challenge Vagueness
+
+When the user says something abstract or general, push for specifics.
+
+| They say | You ask |
+|----------|---------|
+| "It should be fast" | "Fast how? Page load under 1 second? API response under 200ms? What's the baseline today?" |
+| "A dashboard" | "What's on the dashboard? What data? What can users do with it?" |
+| "User management" | "What can users do? Sign up, log in, reset password? Roles? Permissions? Teams?" |
+| "It needs to scale" | "Scale to what? 100 users? 100,000? What's the growth timeline?" |
+
+### Make Abstract Concrete
+
+Ask for examples and walk-throughs.
+
+- "Walk me through what a user does when they first open this."
+- "Give me an example of [that feature] in action."
+- "If I were a user right now, what would I see?"
+- "What does a typical session look like from start to finish?"
+
+### Surface Assumptions
+
+Expose hidden assumptions the user hasn't stated.
+
+- "Why do you assume [X]? Is that a hard requirement?"
+- "Have you considered [alternative]? What made you choose [their approach]?"
+- "What if [assumption] turns out to be wrong?"
+- "Is that because of a technical constraint, or a preference?"
+
+### Find Edges
+
+Probe for edge cases and boundary conditions.
+
+- "What happens when [unexpected input]?"
+- "What if two users do [action] at the same time?"
+- "What about offline/slow connections?"
+- "What if the user has [unusual state]?"
+- "What's the maximum [items/users/data] this needs to handle?"
+
+### Reveal Motivation
+
+Understand the WHY behind features.
+
+- "Why does that matter?"
+- "What problem does that solve for the user?"
+- "What happens if we don't build that?"
+- "Who specifically needs this? Why?"
+- "What's the cost of getting this wrong?"
+
+### Prioritize Ruthlessly
+
+Force ranking and trade-off decisions.
+
+- "If you could only ship three features, which three?"
+- "Would you rather have [A] done well or [A and B] done halfway?"
+- "What's the minimum that would make this useful?"
+- "What would you cut if you had to ship in half the time?"
+
+### Surface Implications
+
+When the user states a preference or makes a choice, surface what it implies before moving on. This avoids surprises later and reveals whether the user has thought through the consequences.
+
+- "You want real-time updates. That typically means WebSockets, which adds deployment complexity. Are you prepared for that, or would polling work?"
+- "Card-based layout with sort/filter usually means client-side state management. How complex are your filtering needs?"
+- "You mentioned multi-tenant. That affects database design, auth, billing — have you thought through isolation boundaries?"
+- "Self-hosted deployment means you own uptime. Do you have monitoring and on-call plans?"
+
+The pattern: **[stated preference] implies [consequence]. Is that acceptable, or should we reconsider?**
+
+### Frame Trade-offs, Not Menus
+
+Replace "Do you want A or B?" with trade-off framing that shows real consequences.
+
+| Instead of | Ask |
+|------------|-----|
+| "SQL or NoSQL?" | "SQL gives you strong consistency and relationships but needs schema migrations. NoSQL gives you flexible documents but makes joins painful. What matters more for your data?" |
+| "SSR or SPA?" | "SSR gives you better SEO and initial load, but adds server cost. SPA gives you snappier interactions but hurts discoverability. What's the priority?" |
+| "Monolith or microservices?" | "A monolith ships faster and is simpler to debug, but gets harder to scale independently. Microservices scale cleanly but add deployment and coordination overhead. Where are you on that spectrum?" |
+
+The pattern: **A gives you X but costs Y. B gives you Z but costs W. What matters more to you?**
+
+This produces better answers than binary choices because users reveal their actual priorities.
+
+---
+
+## Required Context Checklist
+
+By the end of questioning, you should have clear answers for ALL of these:
+
+### The Problem
+- [ ] What problem is being solved?
+- [ ] Who has this problem? (specific users/personas)
+- [ ] How are they solving it today? (current state)
+- [ ] Why is the current solution inadequate?
+
+### The Solution
+- [ ] What is being built? (concrete description)
+- [ ] What does "done" look like? (at least 3 success criteria)
+- [ ] What are the core features? (prioritized)
+- [ ] What is explicitly NOT being built? (scope boundaries)
+
+### Constraints
+- [ ] Technology choices already made (language, framework, hosting)
+- [ ] Budget constraints (money, time, resources)
+- [ ] Team constraints (size, skill level, availability)
+- [ ] Integration constraints (existing systems, APIs, databases)
+- [ ] Timeline expectations (deadlines, milestones)
+
+### Decisions Already Made
+- [ ] Architecture preferences or requirements
+- [ ] Deployment environment (cloud, self-hosted, serverless)
+- [ ] Authentication approach
+- [ ] Data storage approach
+- [ ] Third-party services to use
+
+### Edge Cases and Concerns
+- [ ] What keeps them up at night about this project?
+- [ ] What's the hardest part?
+- [ ] What might go wrong?
+- [ ] What are they unsure about?
+
+---
+
+## Progressive Depth Layers
+
+Structure the conversation as deepening layers. Each layer builds on the previous one. You do not need to complete every layer in every project, but the order matters — do not jump to Layer 3 before Layer 1 is solid.
+
+### Layer 1: Shape — "What are you building?"
+Establish the broad outline. What is it, who is it for, what does it do?
+- Core purpose and user personas
+- Primary features and workflows
+- Technology preferences or constraints
+
+### Layer 2: Feel — "How should users experience this?"
+Move from structure to experience. How does it feel to use?
+- UI expectations, interaction patterns, responsiveness
+- Tone, branding, visual direction
+- Performance expectations from the user's perspective
+
+### Layer 3: Edges — "What happens when things go wrong?"
+Probe failure modes, edge cases, and the unexpected.
+- Error handling, empty states, data conflicts
+- Permission boundaries, rate limits, abuse scenarios
+- What the user has NOT thought about yet
+
+### Layer 4: System — "How does this fit into the bigger picture?"
+Zoom out to the surrounding ecosystem.
+- Integrations, data flows, deployment environment
+- Operational concerns — monitoring, backups, migrations
+- Future evolution and extensibility
+
+---
+
+## Conversation Flow
+
+The conversation should feel natural, not like an interrogation. Follow this general arc:
+
+### Opening (1-2 exchanges)
+Start broad and let them paint the picture:
+- "What are you building?"
+- "Tell me about this project."
+
+### Exploration (3-5 exchanges)
+Dive into specifics on each area they mention:
+- Follow their energy — explore what they're excited about
+- Circle back to areas they glossed over
+- Use "tell me more about..." and "what does that mean exactly?"
+
+### Constraints (2-3 exchanges)
+Shift to practical matters:
+- "What are you working with? Language, framework, hosting?"
+- "Any hard constraints I should know about?"
+- "What's the timeline looking like?"
+
+### Prioritization (1-2 exchanges)
+Force trade-offs:
+- "Of everything we discussed, what's the core? What MUST be in v1?"
+- "What can wait for v2?"
+
+### Confirmation (1 exchange)
+Summarize back what you heard and confirm:
+- "Let me play this back: you're building [X] that [does Y] for [users Z]. The core features are [A, B, C]. You're using [stack]. The biggest risk is [concern]. Did I get that right?"
+
+---
+
+## Domain-Aware Probing
+
+When the user mentions a specific technology area (e.g., "React app", "REST API", "real-time chat"), use domain-specific follow-up questions to go deeper. General questions miss critical details that only matter in that domain.
+
+See **[skills/shared/domain-probes.md](../shared/domain-probes.md)** for technology-specific probing patterns organized by domain (frontend frameworks, databases, APIs, auth, deployment, etc.). Reference those patterns when the conversation enters a technology-specific area rather than relying on generic follow-ups.
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** present a form and ask users to fill it in
+2. **DO NOT** ask all questions at once — have a conversation
+3. **DO NOT** assume you know what they want — ask
+4. **DO NOT** suggest technologies before understanding the problem
+5. **DO NOT** skip edge case exploration
+6. **DO NOT** accept vague answers — push for specifics
+7. **DO NOT** rush through questioning to get to planning
+8. **DO NOT** ignore concerns or hand-wave them away
+9. **DO NOT** lead the user toward a particular solution
+10. **DO NOT** forget to summarize and confirm understanding
+11. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"

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

@@ -0,0 +1,127 @@
+# Reading Verification Reports
+
+A user-friendly guide to understanding verification results. For agent-facing patterns, see `verification-patterns.md`.
+
+---
+
+## What Verification Checks
+
+After building a phase, Plan-Build-Run runs automated verification to check whether the code actually delivers what was planned. It checks every "must-have" from the plan through three layers:
+
+### Layer 1: Existence
+
+**Question**: Does the file/function/route exist at all?
+
+This is the most basic check. If the plan said "create `src/auth.ts`" — does that file exist on disk? If it said "add a `/login` route" — can we find it in the codebase?
+
+**Common failures**: File was planned but never created, renamed to a different path, or deleted by a later task.
+
+### Layer 2: Substantiveness
+
+**Question**: Is the code real, or just a stub/placeholder?
+
+A file can exist but contain nothing useful — an empty function, a `throw new Error('Not implemented')`, or a component that just renders its own name. This layer catches those cases.
+
+**Common failures**: Function body is empty, returns hardcoded test data, or only has a TODO comment.
+
+### Layer 3: Wiring
+
+**Question**: Are the pieces connected to each other?
+
+Code can exist and be real, but if nothing imports it or calls it, it's dead code. This layer checks that modules are imported where needed, middleware is applied to routes, and components are rendered in the right places.
+
+**Common failures**: Module created but never imported, route handler exists but not registered in the router, component built but not used in any page.
+
+---
+
+## Reading the Verification Report
+
+A `VERIFICATION.md` file looks like this:
+
+```
+Status: passed (or gaps_found)
+Must-haves checked: 8
+Passed: 7
+Gaps: 1
+```
+
+### When status is "passed"
+
+All must-haves passed all three layers. The phase is complete and you can move on.
+
+### When status is "gaps_found"
+
+One or more must-haves failed verification. Each gap includes:
+
+- **Must-have**: What was expected (from the plan)
+- **Failed layer**: Which check failed (existence, substantiveness, or wiring)
+- **Evidence**: The specific command output or file content that shows the failure
+- **Suggested fix**: What to do about it
+
+---
+
+## Common Gap Types and What They Mean
+
+### "File not found"
+**Layer**: Existence
+**Meaning**: A planned file was never created or was created at a different path.
+**Fix**: Usually a simple oversight — the executor may have created it with a slightly different name. Check the phase directory for similar files.
+
+### "Function is a stub"
+**Layer**: Substantiveness
+**Meaning**: The file exists but the implementation is incomplete. Common indicators: empty function bodies, `TODO` comments, placeholder return values.
+**Fix**: The executor may have run out of context before finishing. Re-running the build usually resolves this.
+
+### "Module not imported"
+**Layer**: Wiring
+**Meaning**: The code was written correctly but nothing uses it. The import statement is missing from the consuming file.
+**Fix**: Usually a one-line fix — add the import statement to the right file.
+
+### "Test has no assertions"
+**Layer**: Substantiveness
+**Meaning**: A test file exists but doesn't actually test anything — empty `it()` blocks or `expect(true).toBe(true)`.
+**Fix**: Real test assertions need to be written. This usually happens when TDD mode is off and the executor generates placeholder tests.
+
+### "Route not registered"
+**Layer**: Wiring
+**Meaning**: A route handler function was created but never mounted on the Express/Fastify/etc. router.
+**Fix**: Add the route registration (usually `app.use()` or `router.get()`) to the main app file.
+
+---
+
+## How to Close Gaps
+
+You have several options:
+
+### Option 1: Re-run the build (most common)
+```
+/pbr:build <N>
+```
+The executor will detect what's already complete and only fix what's missing.
+
+### Option 2: Create a gap-closure plan
+```
+/pbr:plan <N> --gaps
+```
+This creates a focused plan that targets only the specific gaps found during verification.
+
+### Option 3: Manual fix
+For small gaps (like a missing import), you can fix the code yourself and then re-run verification:
+```
+/pbr:review <N>
+```
+
+### Option 4: Override (for false positives)
+If verification flagged something that's actually correct (e.g., a function intentionally returns an empty array), you can override the gap during review. The override is recorded in the verification report.
+
+---
+
+## Understanding Verification Attempts
+
+The verification report tracks `attempt` count. If a phase has been verified multiple times:
+
+- **Attempt 1**: Normal first verification
+- **Attempt 2**: Gaps were found and fixed, re-verifying
+- **Attempt 3+**: Escalation — Plan-Build-Run will offer additional options like accepting with gaps, switching to debug mode, or re-planning the phase
+
+Multiple attempts don't mean something is wrong — complex phases often need a round of gap-closure before passing.

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

@@ -0,0 +1,160 @@
+# Stub Detection Patterns
+
+Technology-aware patterns for detecting incomplete implementations. Used by the verifier during Layer 2 (Substantiveness) checks.
+
+Read the project's stack from `.planning/codebase/STACK.md` or `.planning/research/STACK.md` to determine which technology-specific patterns to apply. If no stack file exists, use universal patterns only.
+
+---
+
+## Universal Patterns (always check)
+
+- TODO, FIXME, HACK, PLACEHOLDER, "not implemented"
+- `return null`, `return {}`, `return []`, `return undefined`
+- Empty function bodies, functions that only console.log
+- `throw new Error('Not implemented')` or similar
+- Placeholder strings ("lorem ipsum", "sample data", "example")
+
+## React/Next.js Patterns (when stack includes React/Next)
+
+- `<div>ComponentName</div>` — component returning only its name
+- `onClick={() => {}}` — empty event handlers
+- `fetch()` without error handling or response processing
+- `useState` with no state updates
+- Components returning `null`, `<></>`, or single placeholder div
+
+## API/Express Patterns (when stack includes Express/Fastify/Koa)
+
+- `res.json({ message: "Not implemented" })`
+- Empty middleware: `(req, res, next) => next()`
+- Routes returning hardcoded test data
+- `res.status(501)` responses
+
+## Database Patterns (when stack includes any ORM/database)
+
+- Empty migration files
+- Models/schemas with no fields beyond id
+- Repository methods that return empty arrays
+
+## Python Patterns (when stack includes Python)
+
+- `pass` in function bodies
+- `raise NotImplementedError`
+- Functions returning `None` without logic
+- `# TODO` in function bodies
+
+## Go Patterns (when stack includes Go)
+
+- Functions returning zero values without logic
+- `panic("not implemented")`
+- Empty interface implementations
+
+---
+
+## Detailed Examples
+
+### TypeScript/JavaScript Stubs
+
+```typescript
+// STUB PATTERN: Empty function body
+export function processData() { }
+export function processData() { return; }
+export function processData() { return null; }
+export const processData = () => {};
+
+// STUB PATTERN: Placeholder implementation
+export function processData() {
+  throw new Error('Not implemented');
+}
+export function processData() {
+  throw new Error('TODO');
+}
+
+// STUB PATTERN: Hardcoded return value
+export function getUsers(): User[] {
+  return [];
+}
+export function getConfig(): Config {
+  return {} as Config;
+}
+
+// STUB PATTERN: Console.log instead of implementation
+export function saveUser(user: User): void {
+  console.log('TODO: implement saveUser', user);
+}
+
+// STUB PATTERN: Pass-through without logic
+export function validateInput(input: unknown): boolean {
+  return true;  // Always passes - no real validation
+}
+```
+
+### React Component Stubs
+
+```tsx
+// STUB: Null return
+export function Dashboard() { return null; }
+
+// STUB: Empty fragment
+export function Dashboard() { return <></>; }
+
+// STUB: Placeholder text
+export function Dashboard() { return <div>Dashboard</div>; }
+export function Dashboard() { return <div>Coming soon</div>; }
+
+// STUB: Div with just the name
+export function UserProfile() { return <div>UserProfile</div>; }
+
+// REAL (NOT a stub): Has actual JSX structure with data binding
+export function Dashboard({ data }: Props) {
+  return (
+    <div className="dashboard">
+      <h1>{data.title}</h1>
+      <MetricsGrid metrics={data.metrics} />
+    </div>
+  );
+}
+```
+
+### API Route/Handler Stubs
+
+```typescript
+// STUB: Empty response
+app.get('/api/users', (req, res) => { res.json({}); });
+
+// STUB: Not implemented status
+app.get('/api/users', (req, res) => { res.status(501).json({ error: 'Not implemented' }); });
+
+// STUB: Hardcoded test data
+app.get('/api/users', (req, res) => {
+  res.json([{ id: 1, name: 'Test User' }]);
+});
+
+// REAL: Database query, error handling, response
+app.get('/api/users', async (req, res) => {
+  const { page = 1, limit = 20 } = req.query;
+  const users = await db.users.findMany({ skip: (page - 1) * limit, take: limit });
+  res.json({ data: users, page, limit });
+});
+```
+
+### Test Stubs
+
+```typescript
+// STUB: No assertions
+it('should process data', () => {});
+
+// STUB: Trivial assertion
+it('should process data', () => { expect(true).toBe(true); });
+
+// STUB: Skipped
+it.skip('should process data', () => { /* ... */ });
+xit('should process data', () => { /* ... */ });
+
+// REAL: Actual test with meaningful assertions
+it('should process data and return transformed result', () => {
+  const input = createTestData();
+  const result = processData(input);
+  expect(result.items).toHaveLength(3);
+  expect(result.total).toBe(150);
+});
+```

package/plugins/pbr/references/subagent-coordination.md

@@ -0,0 +1,119 @@
+# Subagent Coordination Reference
+
+Patterns for spawning, monitoring, and consuming output from Task() subagents. Used by skills that delegate work to specialized agents.
+
+---
+
+## When to Spawn vs Inline
+
+| Condition | Action |
+|-----------|--------|
+| >50 lines of analysis or code generation needed | Spawn a subagent |
+| Simple state read or file write | Do it inline |
+| Multiple files need reading for a decision | Spawn — protect orchestrator context |
+| User interaction needed (questions, confirmations) | Do it inline |
+| Work needs a fresh context window | Spawn |
+
+---
+
+## Spawning Pattern
+
+Always use the modern subagent_type syntax. Agent definitions are auto-loaded by Claude Code — never inline them.
+
+```
+Task({
+  subagent_type: "pbr:{agent-name}",
+  prompt: <structured prompt with context>
+})
+```
+
+### Structured Input Format
+
+Provide context to subagents using tagged blocks:
+
+```xml
+<phase_context>
+Phase: {NN}-{slug}
+Goal: {goal from ROADMAP.md}
+</phase_context>
+
+<prior_work>
+{Frontmatter from relevant SUMMARY.md files}
+</prior_work>
+
+<instructions>
+{Specific instructions for this agent invocation}
+</instructions>
+```
+
+### What NOT to Include in Spawn Prompts
+
+- Full agent definition text (auto-loaded via subagent_type)
+- Full SUMMARY.md bodies (agent reads from disk)
+- Full PLAN.md bodies unless the agent needs them (executor does, verifier doesn't)
+- Content from unrelated phases
+
+---
+
+## Reading Output
+
+After a subagent completes, read its output file — but only what you need.
+
+| Output Type | Orchestrator Reads | Agent Reads Full |
+|-------------|-------------------|-----------------|
+| SUMMARY.md | Frontmatter only (status, key_files, commits) | Yes, from disk |
+| VERIFICATION.md | Frontmatter only (status, must_haves_passed/failed) | Yes, from disk |
+| PLAN.md | Frontmatter only (wave, depends_on, files_modified) | Yes, from disk |
+| RESEARCH.md | Frontmatter + recommendations section | Yes, from disk |
+| Debug files | Latest hypothesis + result only | Yes, from disk |
+
+### Frontmatter-Only Read Pattern
+
+```
+Read the file, extract YAML frontmatter between --- markers.
+Parse: status, key_files, commits, provides.
+Do NOT read past the closing --- of frontmatter.
+```
+
+---
+
+## State Update After Agent Completion
+
+After reading agent output, update STATE.md with minimal information:
+1. Update phase/plan status
+2. Record completion timestamp
+3. Note any blockers or warnings from frontmatter
+4. Do NOT copy agent output into STATE.md
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Agent times out | Report to user, suggest retry |
+| Agent produces no output file | Report failure, check for partial work |
+| Output file has `status: failed` | Read failure details, present to user |
+| Agent reports warnings | Continue but show warnings in completion summary |
+
+### Retryable vs Fatal
+
+- **Retryable**: Timeout, transient file errors, partial completion
+- **Fatal**: Missing plan files, invalid state, circular dependencies
+- **User decision**: Verification failures, ambiguous requirements
+
+---
+
+## Context Budget Impact
+
+Each subagent coordination step has a token cost in the orchestrator:
+
+| Step | Approximate Cost |
+|------|-----------------|
+| Reading state before spawn | 200-500 tokens |
+| Constructing spawn prompt | 500-1000 tokens |
+| Reading output frontmatter | 100-300 tokens |
+| Updating STATE.md | 200-400 tokens |
+| **Total per agent cycle** | **1,000-2,200 tokens** |
+
+Compare to inlining the same work: 5,000-20,000 tokens. Delegation saves 3-10x.