@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/references/model-profiles.md

@@ -0,0 +1,182 @@
+# Model Profiles Reference
+
+How Plan-Build-Run maps agents to models and how to configure model selection.
+
+---
+
+## Session Model (Orchestrator)
+
+The orchestrator is your main Claude Code session -- it reads skills, manages state, and routes work to agents. Its model is whatever you selected in Claude Code (not controlled by PBR's `config.json`).
+
+**Cost impact:** The orchestrator accounts for roughly 40% of total session cost. Agents set to `inherit` (planner, executor, debugger, general in the `balanced` profile) also use this model. Switching your session from Opus to Sonnet reduces cost for both the orchestrator and all `inherit` agents.
+
+**Recommendations:**
+
+| Goal | Session Model | Config Adjustment |
+|------|---------------|-------------------|
+| Maximum quality | Opus | None needed -- `inherit` agents get Opus |
+| Balanced cost/quality | Sonnet | None needed -- `inherit` agents get Sonnet, which handles most tasks well |
+| Cheap orchestration, Opus agents | Sonnet | Set `planner: "opus"`, `executor: "opus"`, `debugger: "opus"` to override inherit |
+
+Sonnet 4.6 handles orchestration tasks (state reading, routing decisions, context assembly) effectively. Reserve Opus for agents doing complex reasoning, architecture, or novel code generation.
+
+---
+
+## Agent-to-Model Mapping
+
+Each Plan-Build-Run agent's model is controlled by `config.json models.*`. When no config entry exists for an agent, the agent inherits the session model.
+
+The `model:` frontmatter field has been removed from PBR agent definitions — `config.json` is now the sole source of truth for agent model assignment.
+
+### Default Agent Models
+
+| Agent | Default Model | Rationale |
+|-------|---------------|-----------|
+| `researcher` | `sonnet` | Research requires strong reasoning for source evaluation and synthesis |
+| `planner` | `inherit` | Planning is complex; inherits the session's primary model |
+| `executor` | `inherit` | Execution needs the full capability of the session model |
+| `verifier` | `sonnet` | Verification needs solid reasoning but not the heaviest model |
+| `integration-checker` | `sonnet` | Cross-phase analysis requires strong pattern matching |
+| `plan-checker` | `sonnet` | Plan quality analysis needs good analytical capability |
+| `debugger` | `inherit` | Debugging is complex; inherits session model |
+| `codebase-mapper` | `sonnet` | Codebase analysis requires thorough reasoning |
+| `synthesizer` | `haiku` | Synthesis is mechanical combination; speed over depth |
+| `general` | `inherit` | Lightweight utility; inherits session model |
+| `audit` | `inherit` | Session log analysis inherits session model |
+| `dev-sync` | `inherit` | Cross-plugin sync is mechanical; inherits session model |
+
+The `inherit` value means the agent uses whatever model the parent session is running (typically the user's configured Claude model). Defaults listed above are the effective values from the `balanced` profile in `config.json`.
+
+---
+
+## Model Profile Presets
+
+The `/pbr:settings model-profile {preset}` command sets all agent models at once using a preset:
+
+| Profile | Researcher | Planner | Executor | Verifier | Int-Checker | Debugger | Mapper | Synthesizer |
+|---------|-----------|---------|----------|----------|-------------|----------|--------|-------------|
+| `quality` | opus | opus | opus | opus | sonnet | opus | sonnet | sonnet |
+| `balanced` | sonnet | inherit | inherit | sonnet | sonnet | inherit | sonnet | haiku |
+| `budget` | haiku | haiku | haiku | haiku | haiku | haiku | haiku | haiku |
+| `adaptive` | sonnet | sonnet | inherit | sonnet | haiku | inherit | haiku | haiku |
+
+### Preset Descriptions
+
+- **quality**: Maximum capability across all agents. Best results but highest token cost. Use for critical projects or complex architectures.
+- **balanced**: The default preset. Front-loads intelligence in research and verification, inherits session model for planning and execution. Good general-purpose choice.
+- **budget**: All agents use haiku. Fastest and cheapest, but reduced quality for complex reasoning tasks. Suitable for well-defined, mechanical work.
+- **adaptive**: Front-loads intelligence in research and planning (where decisions matter most), uses lighter models for mechanical execution and verification. Good cost-quality tradeoff.
+
+### context_window_tokens per Profile
+
+| Profile | context_window_tokens |
+|---------|----------------------|
+| `quality` | `1000000` |
+| `balanced` | `200000` |
+| `budget` | `200000` |
+| `adaptive` | `200000` |
+
+The `quality` profile targets Claude models with 1M context windows (e.g., Claude Opus with extended context). All other profiles default to 200000, matching Claude Sonnet and Haiku context windows. Adjust manually via `/pbr:settings` or by editing `config.json` if your model has a different context window size.
+
+### 1M Context Feature Defaults per Profile
+
+When using `/pbr:settings model-profile {preset}`, these feature defaults are also applied:
+
+| Feature | quality | balanced | budget | adaptive |
+|---------|---------|----------|--------|----------|
+| `workflow.inline_execution` | `true` | `false` | `false` | `false` |
+| `features.inline_verify` | `true` | `false` | `false` | `false` |
+| `features.extended_context` | `true` | `false` | `false` | `false` |
+| `workflow.phase_boundary_clear` | `"recommend"` | `"off"` | `"off"` | `"off"` |
+| `workflow.autonomous` | `false` | `false` | `false` | `false` |
+| `workflow.speculative_planning` | `false` | `false` | `false` | `false` |
+| `workflow.phase_replay` | `false` | `false` | `false` | `false` |
+| `planning.multi_phase` | `false` | `false` | `false` | `false` |
+| `intel.enabled` | `false` | `false` | `false` | `false` |
+| `intel.auto_update` | `false` | `false` | `false` | `false` |
+| `intel.inject_on_start` | `false` | `false` | `false` | `false` |
+| `context_ledger.enabled` | `true` | `false` | `false` | `false` |
+| `context_ledger.stale_after_minutes` | `60` | `60` | `60` | `60` |
+| `learnings.enabled` | `true` | `false` | `false` | `false` |
+| `learnings.read_depth` | `5` | `3` | `3` | `3` |
+| `context_budget.threshold_curve` | `"adaptive"` | `"linear"` | `"linear"` | `"linear"` |
+| `verification.confidence_gate` | `false` | `false` | `false` | `false` |
+| `verification.confidence_threshold` | `1.0` | `1.0` | `1.0` | `1.0` |
+| `gates.checkpoint_auto_resolve` | `"none"` | `"none"` | `"none"` | `"none"` |
+
+**Quality profile rationale:** Enables safe 1M-native features (learnings, inline execution, adaptive thresholds, context ledger, phase boundary recommendations). Keeps experimental features disabled (intel, autonomous, speculative planning, confidence gate, multi-phase planning) -- these require explicit opt-in via `/pbr:settings` or config.json.
+
+---
+
+## Configuring Models
+
+### Per-Agent Configuration
+
+Set an individual agent's model via `/pbr:settings`:
+
+```
+/pbr:settings model executor sonnet
+/pbr:settings model verifier opus
+```
+
+Or edit `config.json` directly:
+
+```json
+{
+  "models": {
+    "researcher": "sonnet",
+    "planner": "inherit",
+    "executor": "inherit",
+    "verifier": "sonnet",
+    "integration_checker": "sonnet",
+    "debugger": "inherit",
+    "mapper": "sonnet",
+    "synthesizer": "haiku"
+  }
+}
+```
+
+### Valid Model Values
+
+| Value | Meaning |
+|-------|---------|
+| `sonnet` | Claude Sonnet (4.5/4.6) -- balanced speed and capability |
+| `opus` | Claude Opus (4.6) -- highest capability, slower |
+| `haiku` | Claude Haiku (4.5) -- fastest, lower capability |
+| `inherit` | Use the session's primary model (whatever the user is running) |
+
+Note: Claude Code 2.1.45+ supports Sonnet 4.6. Model values are abstract names — Claude Code resolves them to the latest available version.
+
+---
+
+## Custom Profiles
+
+The `model_profiles` key in `config.json` lets you define named profiles beyond the four built-in presets. Each profile is a partial map of agent names to model strings — omitted agents fall back to the active profile defaults.
+
+```json
+{
+  "model_profiles": {
+    "my-profile": {
+      "executor": "opus",
+      "planner": "opus",
+      "synthesizer": "sonnet"
+    }
+  }
+}
+```
+
+Activate a custom profile with `/pbr:settings model-profile my-profile`. The profile merges with the `balanced` preset: any agent not listed in your custom profile uses its `balanced` default.
+
+Partial profiles are allowed — you can override just the agents you care about. This is useful for temporarily upgrading a single agent without specifying the rest.
+
+---
+
+## Model Selection in Skill Orchestration
+
+Skills that spawn subagents use the `model` parameter in `Task()` calls. Some skills hardcode a lighter model for specific tasks:
+
+- **Build skill**: Spawns inline verifiers with `model: "haiku"` for quick spot-checks
+- **Build skill**: Spawns codebase mapper updates with `model: "haiku"` for incremental map refreshes
+- **Plan skill**: Uses the configured `planner` model for main planning work
+
+The `subagent_type` parameter automatically loads the agent definition, and the model from `config.json` takes precedence over any agent-level model setting.

package/plan-build-run/references/model-selection.md

@@ -0,0 +1,53 @@
+# Runtime Model Selection
+
+Models are resolved at runtime through a priority chain. The highest-priority source that provides a value wins.
+
+## Resolution Chain (highest to lowest)
+
+| Priority | Source | When Used |
+|----------|--------|-----------|
+| 1 | `--model <value>` flag | User passes flag to `/pbr:execute-phase` or `/pbr:plan-phase` |
+| 2 | Task `model="..."` attribute | Planner specifies per-task model in PLAN.md |
+| 3 | `config.models.executor` | Project-level override in `.planning/config.json` |
+| 4 | Task `complexity` attribute | Adaptive selection via `config.models.complexity_map` |
+| 5 | `config.model_overrides.{agent}` | Per-agent override in config.json |
+| 6 | Profile table lookup | `config.model_profile` (quality/balanced/budget) |
+| 7 | Default | `sonnet` |
+
+## Complexity-Based Selection
+
+When no explicit model is set, task complexity drives selection:
+
+| Complexity | Default Model | Override Key |
+|-----------|---------------|--------------|
+| `simple` | haiku | `config.models.complexity_map.simple` |
+| `medium` | sonnet | `config.models.complexity_map.medium` |
+| `complex` | inherit | `config.models.complexity_map.complex` |
+
+If a plan has multiple tasks, the build skill uses the most capable model among them.
+
+## What "inherit" Means
+
+`inherit` tells the Task() spawn to use whatever model the current session is running. This avoids hardcoding a specific model version (e.g., `claude-sonnet-4-20250514`) that may be blocked or deprecated. The session model is determined by the user's Claude Code configuration.
+
+## Per-Agent Assignment
+
+Set in `.planning/config.json`:
+
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "pbr-executor": "opus",
+    "pbr-verifier": "haiku"
+  }
+}
+```
+
+Overrides take precedence over profile table lookups. See `references/model-profiles.md` for the full profile table.
+
+## Valid Model Values
+
+`sonnet`, `opus`, `haiku`, `inherit`
+
+The `--model` flag accepts the same values. Invalid values produce an error listing valid options.

package/plan-build-run/references/phase-argument-parsing.md

@@ -0,0 +1,61 @@
+# Phase Argument Parsing
+
+Parse and normalize phase arguments for commands that operate on phases.
+
+## Extraction
+
+From `$ARGUMENTS`:
+- Extract phase number (first numeric argument)
+- Extract flags (prefixed with `--`)
+- Remaining text is description (for insert/add commands)
+
+## Using pbr-tools
+
+The `find-phase` command handles normalization and validation in one step:
+
+```bash
+PHASE_INFO=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" find-phase "${PHASE}")
+```
+
+Returns JSON with:
+- `found`: true/false
+- `directory`: Full path to phase directory
+- `phase_number`: Normalized number (e.g., "06", "06.1")
+- `phase_name`: Name portion (e.g., "foundation")
+- `plans`: Array of PLAN.md files
+- `summaries`: Array of SUMMARY.md files
+
+## Manual Normalization (Legacy)
+
+Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
+
+```bash
+# Normalize phase number
+if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
+  # Integer: 8 → 08
+  PHASE=$(printf "%02d" "$PHASE")
+elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  # Decimal: 2.1 → 02.1
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+## Validation
+
+Use `roadmap get-phase` to validate phase exists:
+
+```bash
+PHASE_CHECK=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" roadmap get-phase "${PHASE}")
+if [ "$(printf '%s\n' "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
+  echo "ERROR: Phase ${PHASE} not found in roadmap"
+  exit 1
+fi
+```
+
+## Directory Lookup
+
+Use `find-phase` for directory lookup:
+
+```bash
+PHASE_DIR=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" find-phase "${PHASE}" --raw)
+```

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

@@ -0,0 +1,246 @@
+# Plan Authoring Guide
+
+Quality guidelines for writing executable plans. Used by planner and plan-checker.
+
+---
+
+## Action Writing Guidelines
+
+The `<action>` element is the most important part of the plan. It must be specific enough that the executor agent can follow it mechanically without making design decisions.
+
+### Good Action
+```xml
+<action>
+1. Create file `src/auth/discord.ts`
+2. Import `OAuth2Client` from `discord-oauth2` package
+3. Export async function `authenticateWithDiscord(code: string): Promise<User>`
+   - Create OAuth2Client with env vars: DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET
+   - Exchange authorization code for access token
+   - Fetch user profile from Discord API: GET /api/users/@me
+   - Return User object with fields: id, username, avatar, email
+4. Export function `getDiscordAuthUrl(): string`
+   - Build OAuth2 authorization URL with scopes: identify, email
+   - Include redirect URI from env: DISCORD_REDIRECT_URI
+   - Return the URL string
+5. Add to `.env.example`:
+   DISCORD_CLIENT_ID=
+   DISCORD_CLIENT_SECRET=
+   DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
+</action>
+```
+
+### Bad Action
+```xml
+<action>
+Set up Discord OAuth authentication.
+</action>
+```
+
+### Action Rules
+
+1. **Number the steps** -- executor follows them in order
+2. **Name specific files** -- never say "create necessary files"
+3. **Name specific functions/exports** -- never say "implement the auth logic"
+4. **Include type signatures** -- when the project uses TypeScript
+5. **Reference existing code** -- when modifying files, say what to modify
+6. **Include code snippets** -- for complex patterns or configurations
+7. **Specify environment variables** -- with example values
+8. **Note error handling** -- only when it's a critical part of the task
+
+---
+
+## Verify Command Guidelines
+
+The `<verify>` element must contain commands that the executor can run to check the task is complete.
+
+### Good Verify
+```xml
+<verify>
+npx tsc --noEmit
+npm run test -- --grep "discord auth"
+ls -la src/auth/discord.ts
+</verify>
+```
+
+### Bad Verify
+```xml
+<verify>
+Check that authentication works.
+</verify>
+```
+
+### Verify Rules
+
+1. **Must be executable** -- actual shell commands, not descriptions
+2. **Must be deterministic** -- same result every time if code is correct
+3. **Prefer automated checks** -- type checking, tests, linting
+4. **Include existence checks** -- `ls` for created files
+5. **Include build checks** -- `npx tsc --noEmit` for TypeScript
+6. **Avoid interactive commands** -- no commands requiring user input
+
+---
+
+## Done Condition Guidelines
+
+The `<done>` element describes the observable outcome, not the implementation activity.
+
+### Good Done
+- "User can authenticate via Discord OAuth and is redirected to dashboard"
+- "Auth middleware rejects invalid tokens and passes valid tokens"
+- "All 12 unit tests pass for the auth module"
+
+### Bad Done
+- "Code was written"
+- "File was created"
+- "Feature is implemented"
+
+### Done Rules
+
+1. **Maps to a must-have** -- every done condition traces back to a frontmatter must-have
+2. **Observable** -- describes a state of the system, not an activity
+3. **Falsifiable** -- you can check whether it's true or false
+4. **User-oriented** -- prefer "user can..." over "code does..."
+
+---
+
+## Scope Limits
+
+### Per-Plan Limits
+
+| Constraint | Limit | Rationale |
+|-----------|-------|-----------|
+| Tasks per plan | **2-3** | Keeps plans atomic and recoverable |
+| Files per plan | **5-8** | Limits blast radius of failures |
+| Dependencies | **3 max** | Avoids deep dependency chains |
+
+### When to Split
+
+- More than 3 tasks? Split.
+- More than 8 files? Split.
+- Tasks in different functional areas? Split.
+- Some tasks need human checkpoints, others don't? Split into autonomous and checkpoint plans.
+
+### Split Signals
+
+| Signal | Action |
+|--------|--------|
+| >3 tasks needed | Split by subsystem -- one plan per subsystem |
+| Multiple unrelated subsystems | One plan per subsystem |
+| >5 files per task | Task is too big -- break it down |
+| Checkpoint + implementation in same plan | Separate the checkpoint into its own plan |
+| Discovery research + implementation | Separate plans -- research plan first |
+
+---
+
+## Discovery Levels
+
+When a plan requires research before execution, set the `discovery` field in plan frontmatter. Default is 1 for most plans.
+
+| Level | Name | Description | Executor Behavior |
+|-------|------|-------------|-------------------|
+| 0 | Skip | No research needed | Execute immediately |
+| 1 | Quick | Fast verification | Check official docs for 1-2 specific questions |
+| 2 | Standard | Normal research | Spawn researcher for phase research |
+| 3 | Deep | Extensive investigation | Full research cycle before execution |
+
+### Level 0 -- Skip
+**When to use**: Simple refactors, documentation updates, file renames, configuration tweaks, or any task where the implementation approach is unambiguous from the plan's `<action>` steps alone.
+
+### Level 1 -- Quick (default)
+**When to use**: Standard feature work where the technology is known but specific API signatures, config options, or version-specific behavior need a quick check.
+
+### Level 2 -- Standard
+**When to use**: Work involving unfamiliar libraries, new integration patterns, or approaches the executor hasn't seen in this codebase before.
+
+### Level 3 -- Deep
+**When to use**: High-risk or architecturally significant work where getting the approach wrong would require substantial rework.
+
+---
+
+## TDD Decision Heuristic
+
+When assigning `tdd="true"` or `tdd="false"` on a task, apply this test:
+
+> **Can you write `expect(fn(input)).toBe(output)` before writing `fn`?**
+> Yes → `tdd="true"`. No → `tdd="false"`.
+
+### When TDD Adds Value
+
+- Pure functions and data transformations
+- Business logic with defined inputs/outputs
+- API response parsing and validation
+- State machines and workflow transitions
+- Utility functions and helpers
+
+### When to Skip TDD
+
+- UI rendering and layout (test after)
+- Configuration and environment setup
+- Glue code wiring modules together
+- Simple CRUD with no business logic
+- File system operations and I/O plumbing
+- One-off scripts and migrations
+
+When the global config `features.tdd_mode: true` is set, all tasks default to TDD. The planner should still set `tdd="false"` on tasks matching the skip list above — the global flag is a project preference, not a mandate for every task.
+
+---
+
+## Dependency Graph Rules
+
+### File Conflict Detection
+
+Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans:
+- MUST be in different waves (cannot run in parallel)
+- MUST have explicit `depends_on` relationship
+- Later plan's `<action>` must reference what the earlier plan produces
+
+### Circular Dependencies
+
+**NEVER create circular dependencies.** If you detect a potential cycle, restructure the plans to break it. Common resolution: merge the circular plans into one, or extract the shared dependency into its own plan.
+
+---
+
+## @file: Output Pattern (Large Payloads)
+
+When a `pbr-tools` CLI command produces output exceeding 50,000 characters, the tool writes
+the JSON payload to a temporary file instead of emitting it inline. It then prints a single
+line of the form:
+
+```
+@file:/tmp/pbr-1234567890.json
+```
+
+This prevents stdout overflow in environments with limited buffer sizes (hooks, Task() runners).
+
+### Verify Step Pattern
+
+If a plan's `<verify>` step calls `pbr-tools` and inspects the output, guard against the
+`@file:` case:
+
+```bash
+OUT=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load)
+if echo "$OUT" | grep -q '^@file:'; then
+  OUT=$(cat "${OUT#@file:}")
+fi
+echo "$OUT" | grep '"status"'
+```
+
+### Agent Prompt Handling
+
+When an agent receives `@file:` output from a spawned tool call, it must read the referenced
+file to obtain the actual JSON payload. The `@file:` prefix is a signal — not a path fragment
+to be appended to another command.
+
+Plan actions that spawn `pbr-tools` subcommands should instruct the agent:
+
+> If the output starts with `@file:`, read the file at that path to get the full JSON response.
+
+---
+
+## Context Fidelity Checklist
+
+Before writing plan files, verify context compliance:
+
+1. **Locked decision coverage**: For each locked decision in CONTEXT.md, identify the task that implements it.
+2. **Deferred idea exclusion**: Scan all tasks -- no task should implement a deferred idea.
+3. **Discretion area handling**: Each "Claude's Discretion" item should be addressed in at least one task.