@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plan-build-run/references/planning-config.md

@@ -0,0 +1,200 @@
+<planning_config>
+
+Configuration options for `.planning/` directory behavior.
+
+<config_schema>
+```json
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "branching_strategy": "none",
+  "phase_branch_template": "pbr/phase-{phase}-{slug}",
+  "milestone_branch_template": "pbr/{milestone}-{slug}"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `commit_docs` | `true` | Whether to commit planning artifacts to git |
+| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
+| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `git.phase_branch_template` | `"pbr/phase-{phase}-{slug}"` | Branch template for phase strategy |
+| `git.milestone_branch_template` | `"pbr/{milestone}-{slug}"` | Branch template for milestone strategy |
+</config_schema>
+
+<commit_docs_behavior>
+
+**When `commit_docs: true` (default):**
+- Planning files committed normally
+- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
+- Full history of planning decisions preserved
+
+**When `commit_docs: false`:**
+- Skip all `git add`/`git commit` for `.planning/` files
+- User must add `.planning/` to `.gitignore`
+- Useful for: OSS contributions, client projects, keeping planning private
+
+**Using pbr-tools.cjs (preferred):**
+
+```bash
+# Commit with automatic commit_docs + gitignore checks:
+node "$HOME/.claude/plan-build-run/bin/pbr-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+
+# Load config via state load (returns JSON):
+INIT=$(node "$HOME/.claude/plan-build-run/bin/pbr-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs is available in the JSON output
+
+# Or use init commands which include commit_docs:
+INIT=$(node "$HOME/.claude/plan-build-run/bin/pbr-tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs is included in all init command outputs
+```
+
+**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
+
+**Commit via CLI (handles checks automatically):**
+
+```bash
+node "$HOME/.claude/plan-build-run/bin/pbr-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+```
+
+The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**When `search_gitignored: false` (default):**
+- Standard rg behavior (respects .gitignore)
+- Direct path searches work: `rg "pattern" .planning/` finds files
+- Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
+
+**When `search_gitignored: true`:**
+- Add `--no-ignore` to broad rg searches that should include `.planning/`
+- Only needed when searching entire repo and expecting `.planning/` matches
+
+**Note:** Most PBR operations use direct file reads or explicit paths, which work regardless of gitignore status.
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+To use uncommitted mode:
+
+1. **Set config:**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **Add to .gitignore:**
+   ```
+   .planning/
+   ```
+
+3. **Existing tracked files:** If `.planning/` was previously tracked:
+   ```bash
+   git rm -r --cached .planning/
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**Branching Strategies:**
+
+| Strategy | When branch created | Branch scope | Merge point |
+|----------|---------------------|--------------|-------------|
+| `none` | Never | N/A | N/A |
+| `phase` | At `execute-phase` start | Single phase | User merges after phase |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+
+**When `git.branching_strategy: "none"` (default):**
+- All work commits to current branch
+- Standard PBR behavior
+
+**When `git.branching_strategy: "phase"`:**
+- `execute-phase` creates/switches to a branch before execution
+- Branch name from `phase_branch_template` (e.g., `pbr/phase-03-authentication`)
+- All plan commits go to that branch
+- User merges branches manually after phase completion
+- `complete-milestone` offers to merge all phase branches
+
+**When `git.branching_strategy: "milestone"`:**
+- First `execute-phase` of milestone creates the milestone branch
+- Branch name from `milestone_branch_template` (e.g., `pbr/v1.0-mvp`)
+- All phases in milestone commit to same branch
+- `complete-milestone` offers to merge milestone branch to main
+
+**Template variables:**
+
+| Variable | Available in | Description |
+|----------|--------------|-------------|
+| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
+| `{slug}` | Both | Lowercase, hyphenated name |
+| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
+
+**Checking the config:**
+
+Use `init execute-phase` which returns all config as JSON:
+```bash
+INIT=$(node "$HOME/.claude/plan-build-run/bin/pbr-tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
+```
+
+Or use `state load` for the config values:
+```bash
+INIT=$(node "$HOME/.claude/plan-build-run/bin/pbr-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
+```
+
+**Branch creation:**
+
+```bash
+# For phase strategy
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# For milestone strategy
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**Merge options at complete-milestone:**
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
+| Merge with history | `git merge --no-ff` | Preserves all individual commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling later |
+
+Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+
+**Use cases:**
+
+| Strategy | Best for |
+|----------|----------|
+| `none` | Solo development, simple projects |
+| `phase` | Code review per phase, granular rollback, team collaboration |
+| `milestone` | Release branches, staging environments, PR per version |
+
+</branching_strategy_behavior>
+
+</planning_config>

package/plan-build-run/references/questioning.md

@@ -0,0 +1,162 @@
+<questioning_guide>
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+</philosophy>
+
+<the_goal>
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+</the_goal>
+
+<how_to_question>
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+</how_to_question>
+
+<question_types>
+
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+**Motivation — why this exists:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+**Concreteness — what it actually is:**
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+**Clarification — what they mean:**
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+**Success — how you'll know it's working:**
+- "How will you know this is working?"
+- "What does done look like?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+- Headers longer than 12 characters (hard limit — validation will reject them)
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+**Tip for users — modifying an option:**
+Users who want a slightly modified version of an option can select "Other" and reference the option by number: `#1 but for finger joints only` or `#2 with pagination disabled`. This avoids retyping the full option text.
+
+</using_askuserquestion>
+
+<freeform_rule>
+
+**When the user wants to explain freely, STOP using AskUserQuestion.**
+
+If a user selects "Other" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
+
+1. **Ask your follow-up as plain text** — NOT via AskUserQuestion
+2. **Wait for them to type at the normal prompt**
+3. **Resume AskUserQuestion** only after processing their freeform response
+
+The same applies if YOU include a freeform-indicating option (like "Let me explain" or "Describe in detail") and the user selects it.
+
+**Wrong:** User says "let me describe it" → AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
+**Right:** User says "let me describe it" → "Go ahead — what are you thinking?"
+
+</freeform_rule>
+
+<context_checklist>
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+</context_checklist>
+
+<decision_gate>
+
+When you could write a clear PROJECT.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+
+Loop until "Create PROJECT.md" selected.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.
+
+</anti_patterns>
+
+</questioning_guide>

package/plan-build-run/references/reading-verification.md

@@ -0,0 +1,93 @@
+# Reading Verification Results
+
+Reference card for interpreting VERIFICATION.md files produced by the verifier agent.
+
+## Overall Status
+
+| Status | Meaning | Next Action |
+|--------|---------|-------------|
+| `passed` | All must-haves verified at all levels | Phase complete — proceed to next phase |
+| `gaps_found` | One or more must-haves failed | Gap closure needed — run `/pbr:verify-work N --auto-fix` or fix manually |
+| `human_needed` | Automated checks pass but items require manual verification | User must verify listed items, then re-run |
+
+Priority: `gaps_found` > `human_needed` > `passed`. Any single failure forces `gaps_found`.
+
+## Must-Have Categories
+
+| Category | What It Checks | Example |
+|----------|---------------|---------|
+| **Truths** | Observable conditions — can this behavior be observed? | "Login redirects to dashboard" |
+| **Artifacts** | Files/exports that must exist, be substantive, and not be stubs | "src/auth/middleware.ts" |
+| **Key Links** | Connections wired between components | "Auth middleware applied to /api routes" |
+
+## Verification Levels (Artifacts)
+
+| Level | Check | Pass | Fail |
+|-------|-------|------|------|
+| L1 — Existence | File exists on disk | `EXISTS` | `MISSING` |
+| L2 — Substantive | Not a stub or placeholder | `SUBSTANTIVE` | `STUB` / `PARTIAL` |
+| L3 — Wired | Imported and used by other code | `WIRED` | `IMPORTED-UNUSED` / `ORPHANED` |
+| L4 — Functional | Produces correct results when run | `FUNCTIONAL` | `RUNTIME_ERROR` / `LOGIC_ERROR` |
+
+L4 is optional — only applied when automated tests or build commands exist. Items passing L1-L3 without L4 show `PASSED (L3 only)`.
+
+## Truth Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `VERIFIED` | Truth holds, with evidence |
+| `FAILED` | Truth does not hold |
+| `PARTIAL` | Truth partially holds |
+| `HUMAN_NEEDED` | Cannot verify programmatically |
+
+## Key Link Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `WIRED` | Correct function called with correct arguments |
+| `ARGS_WRONG` | Correct function called but arguments are incorrect or missing |
+| `IMPORTED-UNUSED` | Symbol imported but never called |
+| `ORPHANED` | No import exists |
+
+## Gap Analysis
+
+Each gap in the `gaps` frontmatter array contains:
+
+- **must_have** — which must-have failed
+- **level** — which verification level failed (existence, substantive, wired, functional)
+- **evidence** — what the verifier found
+- **recommendation** — suggested fix action
+
+### Gap Annotations (Re-verification)
+
+| Annotation | Meaning |
+|------------|---------|
+| `[PREVIOUSLY KNOWN]` | Gap existed in prior verification run |
+| `[NEW]` | Gap appeared for the first time |
+| `[REGRESSION]` | Previously passing item now fails — high priority |
+
+## Acting on Results
+
+| Result | Action |
+|--------|--------|
+| All passed | Run `/pbr:verify-work N` to complete UAT, then advance |
+| Gaps found | Run `/pbr:verify-work N --auto-fix` for automated diagnosis and fix plans |
+| Human needed | Verify listed items manually, then re-run verification |
+| Override false positive | Use the override flow in `/pbr:verify-work` to accept specific gaps |
+| Persistent gaps (3+ attempts) | Escalation options: accept gaps, re-plan, debug, or retry |
+
+## Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | string | Overall result: passed, gaps_found, human_needed |
+| `checked_at` | ISO date | When verification ran |
+| `attempt` | integer | Verification attempt number (increments on re-verification) |
+| `must_haves_checked` | integer | Total must-haves evaluated |
+| `must_haves_passed` | integer | Must-haves that passed all levels |
+| `must_haves_failed` | integer | Must-haves that failed at any level |
+| `gaps` | array | List of gap objects (must_have, level, evidence, recommendation) |
+| `overrides` | array | Must-haves accepted as false positives by user |
+| `satisfied` | array | REQ-IDs satisfied by this phase |
+| `unsatisfied` | array | REQ-IDs not satisfied |
+| `is_re_verification` | boolean | Whether this is a re-verification run |

package/plan-build-run/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);
+});
+```