@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/references/git-integration.md

@@ -7,23 +7,42 @@ Plan-Build-Run's commit conventions, commit points, branching strategy, and hook
 ## Commit Message Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 ### Components
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `{type}` | Conventional commit type | `feat`, `fix`, `test` |
-| `{phase}` | Phase number (zero-padded) | `02` |
-| `{plan}` | Plan number | `01` |
-| `{description}` | Imperative, lowercase description | `implement discord oauth client` |
-
-The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({phase}-{plan}): {description}`.
+| `{type}` | Conventional commit type | `feat`, `fix`, `chore` |
+| `{scope}` | Component name for the area of change | `hooks`, `skills`, `agents` |
+| `{description}` | Imperative, lowercase description | `add drift detection to state sync` |
+
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({scope}): {description}`.
+
+### Component Scopes
+
+Use these scopes to indicate which part of PBR the change affects. git-cliff uses these to group changelog entries by component.
+
+| Scope | What It Covers | Example |
+|-------|---------------|---------|
+| `hooks` | Hook scripts in `hooks/` and `plugins/pbr/scripts/` | `feat(hooks): add drift detection to state sync` |
+| `skills` | SKILL.md files and skill logic | `feat(skills): add velocity metrics to status` |
+| `agents` | Agent definitions in `agents/` | `fix(agents): scale executor budget for 1M context` |
+| `cli` | `pbr-tools.js` and `bin/lib/` modules | `feat(cli): implement stateRederive command` |
+| `dashboard` | Dashboard UI and server | `fix(dashboard): handle missing phases in chart` |
+| `templates` | `.tmpl` template files | `feat(templates): add XML sections to CONTEXT.md` |
+| `plugin` | Plugin manifests, CLAUDE.md, commands | `chore(plugin): bump version to 2.9.0` |
+| `config` | Config schema, validation, defaults | `feat(config): add node_repair_budget setting` |
+| `ci` | GitHub Actions, lint, coverage | `fix(ci): lower branch coverage threshold` |
+| `tests` | Test files and fixtures | `test(tests): add resolve-root macOS symlink test` |
+| `refs` | Reference docs in `references/` | `docs(refs): document hook ordering expectations` |
+| `commands` | Command registration files | `feat(commands): add autonomous command` |
 
 ### Full Example
+
 ```
-feat(02-01): implement discord oauth client
+feat(hooks): implement stateRederive with drift detection
 ```
 
 ---
@@ -32,26 +51,60 @@ feat(02-01): implement discord oauth client
 
 | Type | When to Use | Example |
 |------|------------|---------|
-| `feat` | New feature or functionality | `feat(02-01): implement discord oauth client` |
-| `fix` | Bug fix (including during execution) | `fix(02-01): handle null user profile from discord api` |
-| `refactor` | Code restructuring, no behavior change | `refactor(02-01): extract token validation into helper` |
-| `test` | Adding or modifying tests | `test(02-01): add failing tests for discord oauth flow` |
-| `docs` | Documentation changes | `docs(03-02): add api endpoint documentation` |
-| `chore` | Build config, dependencies, tooling | `chore(01-01): configure typescript and eslint` |
-| `style` | Formatting, whitespace (no logic change) | `style(02-01): fix import ordering` |
+| `feat` | New feature or functionality | `feat(skills): add velocity metrics to status` |
+| `fix` | Bug fix (including during execution) | `fix(hooks): resolve MSYS path bridging on Windows` |
+| `refactor` | Code restructuring, no behavior change | `refactor(cli): extract state mutations to lib/state.cjs` |
+| `test` | Adding or modifying tests | `test(hooks): add resolve-root tests for walk-up discovery` |
+| `docs` | Documentation changes | `docs(refs): document hook ordering expectations` |
+| `chore` | Build config, dependencies, tooling | `chore(plugin): bump version to 2.9.0` |
+| `wip` | Work in progress (use sparingly) | `wip(skills): partial checkpoint routing` |
+| `revert` | Reverting a previous commit | `revert(hooks): revert auto-continue signal file change` |
+| `perf` | Performance improvement | `perf(cli): cache resolveProjectRoot result` |
+| `ci` | CI/CD changes | `ci(ci): add markdownlint job to test workflow` |
+| `build` | Build system changes | `build(plugin): update hooks.json paths` |
+
+---
+
+## Commit Type Discipline
+
+| Type | Use For | Appears in Changelog |
+|------|---------|---------------------|
+| `feat` | User-visible features ONLY (new commands, new config options, changed behavior users notice) | YES |
+| `fix` | Bug fixes users would notice | YES |
+| `refactor` | Internal restructuring, TDD GREEN commits, code cleanup | No |
+| `test` | Test additions including TDD RED commits | No |
+| `docs` | Documentation (hidden — mostly planning artifacts) | No |
+| `chore` | Build config, deps, tooling, internal scaffolding | No |
+| `wip` | Work in progress (use sparingly) | No |
+| `revert` | Reverting a previous commit | YES |
+
+**TDD commits**: RED phase → `test({scope}): RED - ...`, GREEN phase → `refactor({scope}): GREEN - ...`, REFACTOR phase → `refactor({scope}): REFACTOR - ...`
 
 ---
 
-## Special Commit Scopes
+## Special Commit Patterns
 
-Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these additional patterns:
+Beyond component scopes, Plan-Build-Run recognizes these additional patterns:
 
 | Pattern | When Used | Example |
 |---------|-----------|---------|
 | `{type}(quick-{NNN})` | Quick-task commits via `/pbr:quick` | `feat(quick-001): add health endpoint` |
 | `docs(planning)` | Planning document commits | `docs(planning): add phase 3 plans` |
-| `wip: {desc}` or `wip({area}): {desc}` | Work-in-progress (use sparingly) | `wip(auth): partial oauth implementation` |
-| Merge commits | Git merge operations | `Merge branch 'plan-build-run/phase-02-auth'` |
+| `wip: {desc}` or `wip({area}): {desc}` | Work-in-progress (use sparingly) | `wip(skills): partial checkpoint routing` |
+| Merge commits | Git merge operations | `Merge branch 'feature/auth-rework'` |
+
+---
+
+## Session Affinity Metadata
+
+When a session ID is available, append a `[session:{short_id}]` suffix to the commit description. The `short_id` is the first 8 characters of the session_id. This enables conflict tracing across concurrent sessions.
+
+Example:
+```
+feat(auth): implement discord oauth client [session:a1b2c3d4]
+```
+
+When no session ID is available (e.g., manual commits), omit the suffix.
 
 ---
 
@@ -60,7 +113,7 @@ Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these addi
 For commits that need explanation, add a body after a blank line:
 
 ```
-feat(02-01): implement discord oauth client
+feat(02-01): implement discord oauth client [session:a1b2c3d4]
 
 - Uses discord-oauth2 library for token exchange
 - Stores tokens in httpOnly cookies for security
@@ -84,9 +137,9 @@ Each successfully completed plan task gets exactly one atomic commit. No more, n
 TDD tasks (`tdd="true"`) produce exactly 3 commits following Red-Green-Refactor:
 
 ```
-test(02-01): RED - add failing tests for auth middleware
-feat(02-01): GREEN - implement auth middleware to pass tests
-refactor(02-01): REFACTOR - extract token verification helper
+test(auth): RED - add failing tests for auth middleware
+refactor(auth): GREEN - implement auth middleware to pass tests
+refactor(auth): REFACTOR - extract token verification helper
 ```
 
 ### Commit Preconditions
@@ -125,15 +178,15 @@ When an executor applies a deviation rule during a task, the deviation is includ
 ```bash
 # Standard task
 git add src/auth/discord.ts src/auth/types.ts
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # Task that also installed a dependency (Rule 2)
 git add src/auth/discord.ts src/auth/types.ts package.json package-lock.json
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # TDD RED
 git add tests/auth/discord.test.ts
-git commit -m "test(02-01): add failing tests for Discord OAuth flow"
+git commit -m "test(auth): add failing tests for Discord OAuth flow"
 ```
 
 ---
@@ -174,6 +227,36 @@ Branch name templates are configured in `config.json`:
 - `git.phase_branch_template`: Default `plan-build-run/phase-{phase}-{slug}`
 - `git.milestone_branch_template`: Default `plan-build-run/{milestone}-{slug}`
 
+### PR Creation
+
+When `git.auto_pr: true` and `git.branching` is `phase` or `milestone`, the build skill creates a GitHub PR after verification passes:
+
+1. Push the phase branch to the remote
+2. Create a PR via `gh pr create` with structured title and body
+3. PR title follows the commit convention: `feat(phase-{N}): {phase slug}`
+4. PR body includes phase goal, key files changed, and must-have verification results
+
+When `git.auto_pr: false` (default), the build skill offers the user a choice after verification:
+- Create PR now
+- Skip PR creation
+- Push branch only (create PR later)
+
+PR creation requires `gh` CLI authenticated with repo write access.
+
+### CI Integration
+
+When `ci.gate_enabled: true`, the build skill checks GitHub Actions status after each wave completes:
+
+1. Run: `gh run list --branch $(git branch --show-current) --limit 1 --json status,conclusion,url`
+2. If `status == completed` and `conclusion == success`: proceed to next wave
+3. If `status == in_progress`: wait up to `ci.wait_timeout_seconds`, re-check
+4. If `conclusion != success` or timeout: surface warning with run URL and offer:
+   - **Wait**: continue polling
+   - **Continue anyway**: proceed despite CI failure (logged as deviation)
+   - **Abort**: stop the build
+
+CI gate requires `gh` CLI and GitHub Actions configured on the repository. The gate only activates when there are commits pushed to a remote branch (branching must be enabled).
+
 ### Git Mode
 
 The `git.mode` field controls whether git integration is active:
@@ -207,7 +290,7 @@ Plan-Build-Run uses Claude Code hooks (defined in `hooks/hooks.json`) to enforce
 
 The commit validation hook (`PreToolUse` on Bash commands) enforces the commit format:
 - Checks that `git commit -m "..."` messages match the pattern: `{type}({scope}): {description}`
-- Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`
+- Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`, `revert`
 - Allows merge commits (starting with "Merge")
 - Allows quick-task, planning, and WIP scope patterns
 - Blocks commits with sensitive file patterns (`.env`, `.key`, `.pem`, credentials) unless they match safe patterns (`.example`, `.template`, `.sample`, test directories)

package/plugins/pbr/references/git-planning-commit.md

@@ -0,0 +1,35 @@
+# Git Planning Commit
+
+Use git directly for `.planning/` file commits. Check `commit_docs` in config and `.gitignore` before committing. If `commit_docs: false` in config or `.planning/` is gitignored, skip committing planning files.
+
+## Commit via git
+
+```bash
+# Check if .planning/ is gitignored first
+git check-ignore -q .planning/ && echo "SKIP: .planning/ is gitignored" || git add .planning/STATE.md .planning/ROADMAP.md && git commit -m "docs({scope}): {description}"
+```
+
+## Amend previous commit
+
+To fold `.planning/` file changes into the previous commit:
+
+```bash
+git add .planning/codebase/*.md && git commit --amend --no-edit
+```
+
+## Commit Message Patterns
+
+| Command | Scope | Example |
+|---------|-------|---------|
+| plan-phase | phase | `docs(phase-03): create authentication plans` |
+| execute-phase | phase | `docs(phase-03): complete authentication phase` |
+| new-milestone | milestone | `docs: start milestone v1.1` |
+| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
+| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
+| add-phase | phase | `docs: add phase 07 (settings page)` |
+
+## When to Skip
+
+- `commit_docs: false` in config
+- `.planning/` is gitignored
+- No changes to commit (check with `git status --porcelain .planning/`)

package/plugins/pbr/references/model-profile-resolution.md

@@ -0,0 +1,34 @@
+# Model Profile Resolution
+
+Resolve model profile once at the start of orchestration, then use it for all Task spawns.
+
+## Resolution Pattern
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default: `balanced` if not set or config missing.
+
+## Lookup Table
+
+@${CLAUDE_PLUGIN_ROOT}/references/model-profiles.md
+
+Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
+
+```
+Task(
+  prompt="...",
+  subagent_type="pbr-planner",
+  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+)
+```
+
+**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+
+## Usage
+
+1. Resolve once at orchestration start
+2. Store the profile value
+3. Look up each agent's model from the table when spawning
+4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)

package/plugins/pbr/references/model-profiles.md

@@ -4,9 +4,29 @@ 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 has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.
+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
 
@@ -22,14 +42,16 @@ Each Plan-Build-Run agent has a default model specified in its agent definition
 | `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).
+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:config model-profile {preset}` command sets all agent models at once using a preset:
+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 |
 |---------|-----------|---------|----------|----------|-------------|----------|--------|-------------|
@@ -45,17 +67,56 @@ The `/pbr:config model-profile {preset}` command sets all agent models at once u
 - **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:config`:
+Set an individual agent's model via `/pbr:settings`:
 
 ```
-/pbr:config model executor sonnet
-/pbr:config model verifier opus
+/pbr:settings model executor sonnet
+/pbr:settings model verifier opus
 ```
 
 Or edit `config.json` directly:
@@ -88,6 +149,28 @@ Note: Claude Code 2.1.45+ supports Sonnet 4.6. Model values are abstract names
 
 ---
 
+## 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:
@@ -96,4 +179,4 @@ Skills that spawn subagents use the `model` parameter in `Task()` calls. Some sk
 - **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 the agent's default `model:` frontmatter field.
+The `subagent_type` parameter automatically loads the agent definition, and the model from `config.json` takes precedence over any agent-level model setting.

package/plugins/pbr/references/model-selection.md

@@ -14,7 +14,7 @@ Plan-Build-Run uses adaptive model selection to balance cost and capability.
 |-----------|-------|-----------|
 | simple | haiku | Fast, cheap — sufficient for mechanical changes |
 | medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
+| complex | inherit | Uses session model — see `model-profiles.md` Session Model section for cost implications |
 
 ## Override Mechanisms
 

package/plugins/pbr/references/node-repair.md

@@ -0,0 +1,48 @@
+# Node Repair System
+
+When a task fails during execution, the executor follows this repair taxonomy:
+
+## RETRY (Attempt 1)
+
+**Trigger**: Task verification fails (test error, lint error, missing artifact).
+**Action**: Re-attempt with adjustment based on the error.
+**Budget**: 1 retry per task (2 total attempts before escalating).
+**What changes**: Fix the specific error, don't restructure.
+
+## DECOMPOSE (Attempt 2)
+
+**Trigger**: Retry failed. Task may be too complex.
+**Action**: Split the task into 2-3 sub-tasks and execute them sequentially.
+**Budget**: Sub-tasks get 1 attempt each (no recursion).
+**What changes**: Break down, don't change approach.
+
+## PRUNE (Skip with justification)
+
+**Trigger**: Decomposed sub-tasks also fail. Task is not critical-path.
+**Action**: Skip the task, document in SUMMARY.md deviations (Rule 3).
+**Condition**: Only if task is NOT in must_haves. Must-have tasks cannot be pruned.
+**What changes**: Remove from execution, add to deferred.
+
+## ESCALATE (Ask user)
+
+**Trigger**: Must-have task failed after retry+decompose, OR task requires decisions outside plan scope.
+**Action**: Stop execution. Present the failure with context. Ask user for direction.
+**What changes**: Nothing -- user decides next step.
+
+## Budget Summary
+
+- 2 attempts per task (original + 1 retry)
+- 1 decompose pass (2-3 sub-tasks, 1 attempt each)
+- Then PRUNE or ESCALATE
+- Total max attempts before giving up: ~5 per original task
+
+## Executor Integration
+
+The executor reads this reference before execution. For each task:
+
+1. Execute task
+2. Verify task (run tests, check artifacts)
+3. If verification fails -> RETRY
+4. If retry fails -> DECOMPOSE
+5. If sub-tasks fail -> PRUNE (if not must-have) or ESCALATE (if must-have)
+6. Record repair actions in SUMMARY.md deviations

package/plugins/pbr/references/plan-authoring.md

@@ -157,6 +157,34 @@ When a plan requires research before execution, set the `discovery` field in pla
 
 ---
 
+## 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
@@ -172,6 +200,43 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans:
 
 ---
 
+## @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: