@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/cursor-pbr/references/config-reference.md

@@ -1,7 +1,6 @@
-<!-- canonical: ../../pbr/references/config-reference.md -->
 # Config Reference Guide
 
-Complete reference for `.planning/config.json` -- the file that controls all Plan-Build-Run workflow behavior. Created by `/pbr:begin`, modifiable via `/pbr:config` or direct editing. Validated against `config-schema.json`.
+Complete reference for `.planning/config.json` -- the file that controls all Plan-Build-Run workflow behavior. Created by `/pbr:new-project`, modifiable via `/pbr:settings` or direct editing. Validated against `config-schema.json`.
 
 ---
 
@@ -13,6 +12,7 @@ Complete reference for `.planning/config.json` -- the file that controls all Pla
 | `context_strategy` | string | `aggressive`, `conservative`, `balanced` | `aggressive` | How aggressively PBR manages the context budget |
 | `mode` | string | `interactive`, `autonomous` | `interactive` | Whether PBR pauses for user input or runs hands-free |
 | `depth` | string | `quick`, `standard`, `comprehensive` | `standard` | Controls thoroughness of research, planning, and verification |
+| `session_phase_limit` | integer | `0`-`20` | `3` | Maximum phases to complete per session before auto-pause. Set to `0` to disable. Only effective when `features.auto_continue` is `true`. |
 
 ### context_strategy
 
@@ -63,10 +63,11 @@ Boolean toggles that enable or disable specific workflow capabilities. All defau
 | `inline_verify` | `false` | Per-task verification after each executor commit; adds ~10-20s latency per plan |
 
 **Notable interactions:**
-- `goal_verification: false` skips post-build verification; the build skill suggests running `/pbr:review` manually.
-- `auto_continue: true` writes `.planning/.auto-next` containing the next command (e.g., `/pbr:plan 4`).
+- `goal_verification: false` skips post-build verification; the build skill suggests running `/pbr:verify-work` manually.
+- `auto_continue: true` writes `.planning/.auto-next` containing the next command (e.g., `/pbr:plan-phase 4`).
 - `auto_advance: true` requires `mode: autonomous` to function. Hard stops at checkpoints, verification gaps, errors, and milestone boundaries.
 - `inline_verify: true` spawns a haiku-model verifier after each plan within a wave, catching issues before dependent plans run.
+- `session_phase_limit: N` (top-level) triggers auto-pause after N phases when `auto_continue: true`. In TMUX, the pause auto-cycles to a fresh session.
 
 ---
 
@@ -151,26 +152,38 @@ Controls git integration and branching strategy.
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `branching` | string | `none` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
-| `commit_format` | string | `{type}({phase}-{plan}): {description}` | Commit message template |
+| `branching` | string | `none` | Branching strategy: `none`, `phase`, `milestone`, `disabled`. Recommended: `phase` -- enables safe undo via phase manifests and clean PR history |
+| `commit_format` | string | `{type}({scope}): {description}` | Commit message template. Use a short descriptive word as the scope (e.g., `auth`, `config`, `executor`) rather than phase-plan numbers. |
 | `phase_branch_template` | string | `plan-build-run/phase-{phase}-{slug}` | Phase branch name pattern |
 | `milestone_branch_template` | string | `plan-build-run/{milestone}-{slug}` | Milestone branch name pattern |
 | `mode` | string | `enabled` | Git mode: `enabled` or `disabled` |
+| `auto_pr` | boolean | `false` | Create a GitHub PR after successful phase verification when branching is enabled |
 
 When `git.mode` is `disabled`, no git commands run at all -- no commits, branching, or hook validation. Useful for prototyping or non-git projects. See `references/git-integration.md` for full branching strategy details.
 
 ---
 
+## ci
+
+Controls CI integration for build gates.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `ci.gate_enabled` | boolean | `false` | Block wave advancement until CI passes |
+| `ci.wait_timeout_seconds` | number | `120` | Max seconds to wait for CI completion |
+
+---
+
 ## gates
 
 Confirmation gates that pause execution to ask the user before proceeding. Setting a gate to `false` makes that step automatic.
 
 | Property | Default | When Triggered |
 |----------|---------|----------------|
-| `confirm_project` | `true` | Before creating a new PBR project (`/pbr:begin`) |
+| `confirm_project` | `true` | Before creating a new PBR project (`/pbr:new-project`) |
 | `confirm_roadmap` | `true` | Before finalizing a roadmap |
 | `confirm_plan` | `true` | Before finalizing plans for a phase |
-| `confirm_execute` | `false` | Before starting phase execution (`/pbr:build`) |
+| `confirm_execute` | `false` | Before starting phase execution (`/pbr:execute-phase`) |
 | `confirm_transition` | `true` | Before transitioning to the next phase |
 | `issues_review` | `true` | Before proceeding when issues are detected |
 
@@ -188,7 +201,7 @@ Safety controls for destructive or external operations.
 | `always_confirm_external_services` | boolean | `true` | Always ask before calling external APIs or services |
 | `enforce_phase_boundaries` | boolean | `true` | Prevent agents from working outside their assigned phase scope |
 
-The `always_confirm_destructive` and `always_confirm_external_services` flags cannot be disabled via `/pbr:config`; they require direct editing of `config.json` as a deliberate action.
+The `always_confirm_destructive` and `always_confirm_external_services` flags cannot be disabled via `/pbr:settings`; they require direct editing of `config.json` as a deliberate action.
 
 ---
 
@@ -220,6 +233,16 @@ This value is overridden by the active depth profile if a `depth_profiles` entry
 
 ---
 
+## deployment
+
+Controls post-milestone deployment verification.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `deployment.smoke_test_command` | string | `""` | Bash command to run after milestone completion (e.g., `"curl -sf https://myapp.com/health"`) |
+
+---
+
 ## depth_profiles
 
 Override the built-in depth profile defaults. Each key (`quick`, `standard`, `comprehensive`) maps to an object of settings that take effect when that depth is active.
@@ -251,6 +274,23 @@ User overrides in `depth_profiles` merge on top of these defaults. For example,
 
 ---
 
+## session_phase_limit
+
+Controls how many phases PBR completes in a single session before suggesting a pause-and-resume cycle. This prevents context degradation in long autonomous runs.
+
+| Value | Behavior |
+|-------|----------|
+| `0` | Disabled -- PBR never auto-pauses for session cycling |
+| `1`-`20` | After completing this many phases, PBR writes `/pbr:pause-work` to `.auto-next` and triggers a session cycle |
+
+**Interaction with TMUX:** When running inside a TMUX session, the auto-pause automatically sends `/clear` and `/pbr:resume-work` to the current pane after a 3-second delay, creating a seamless session cycle. Outside TMUX, a banner instructs the user to manually run `/clear` then `/pbr:resume-work`.
+
+**Tracking:** Phase completions are tracked in `.planning/.session-tracker` (reset each session start). The counter increments when an executor subagent completes successfully.
+
+See `references/tmux-setup.md` for TMUX environment setup.
+
+---
+
 ## spinner_tips
 
 Custom spinner tips shown during agent execution. Requires Claude Code 2.1.45+.
@@ -408,13 +448,29 @@ Hands-free execution with no gates and automatic phase chaining. Suitable for CI
 
 ---
 
+## Global Defaults File
+
+PBR supports user-level default preferences stored at `~/.claude/pbr-defaults.json`. When creating a new project via `/pbr:new-project` or `/pbr:settings` Quick Start, these defaults pre-populate configuration fields instead of hardcoded values.
+
+**Location:** `~/.claude/pbr-defaults.json` (created by `config save-defaults`)
+
+**Commands:**
+- `pbr-tools.js config save-defaults` -- Save current project config as global defaults (only portable keys: mode, depth, features, models, parallelization, planning, git, gates, safety, hooks, dashboard, status_line)
+- `pbr-tools.js config load-defaults` -- Load global defaults (returns JSON or `{ exists: false }`)
+
+**Portable keys saved:** mode, depth, context_strategy, features, models, parallelization, planning, git, gates, safety, hooks, dashboard, status_line. Project-specific state (version, schema_version) is excluded.
+
+**Precedence:** Global defaults < project config.json < CLI arguments. Global defaults only affect new project creation and Quick Start flow.
+
+---
+
 ## Troubleshooting
 
 ### Validation Errors
 
 Run validation with: `node plugins/pbr/scripts/pbr-tools.js config validate`
 
-**"config.json not found"** -- No `.planning/config.json` exists. Run `/pbr:begin` to create one, or create the file manually.
+**"config.json not found"** -- No `.planning/config.json` exists. Run `/pbr:new-project` to create one, or create the file manually.
 
 **"config.json is not valid JSON"** -- Syntax error in the JSON file. Check for trailing commas, missing quotes, or unescaped characters.
 
@@ -440,3 +496,92 @@ Run validation with: `node plugins/pbr/scripts/pbr-tools.js config validate`
 | `tdd_mode: true` + `depth: quick` | quick depth skips verification, which conflicts with TDD's verify-first approach |
 | `git.mode: disabled` + `atomic_commits: true` | atomic_commits has no effect when git is disabled |
 | `git.branching: phase` + `git.mode: disabled` | Branching settings are ignored when git is disabled |
+
+---
+
+## local_llm
+
+Offloads selected PBR inference tasks to a locally running Ollama instance, reducing frontier model usage and latency for fast classification calls. The key `enabled` defaults to `false`, so users without Ollama see no change — all LLM calls continue routing to Claude as normal. When enabled, PBR uses a `local_first` routing strategy: fast tasks (artifact classification, task validation) go to the local model; complex tasks (planning, execution) stay on the frontier model.
+
+### Quick setup
+
+1. Install Ollama:
+   - **Linux/macOS**: `curl -fsSL https://ollama.com/install.sh | sh`
+   - **Windows**: Download from [ollama.com/download](https://ollama.com/download) and run the installer
+2. Pull the recommended model: `ollama pull qwen2.5-coder:7b`
+3. Add to `.planning/config.json`:
+
+   ```json
+   "local_llm": {
+     "enabled": true,
+     "model": "qwen2.5-coder:7b"
+   }
+   ```
+
+4. Verify connectivity: `node /path/to/plugins/pbr/scripts/pbr-tools.js llm health`
+
+### Field reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `local_llm.enabled` | boolean | `false` | Enable local LLM offloading; `false` = all calls use frontier |
+| `local_llm.provider` | string | `"ollama"` | Backend provider; only `"ollama"` is supported |
+| `local_llm.endpoint` | string | `"http://localhost:11434"` | Ollama API base URL |
+| `local_llm.model` | string | `"qwen2.5-coder:7b"` | Model tag to use for local inference |
+| `local_llm.timeout_ms` | integer | `3000` | Per-request timeout in milliseconds; >= 500 |
+| `local_llm.max_retries` | integer | `1` | Number of retry attempts on failure before falling back |
+| `local_llm.fallback` | string | `"frontier"` | What to use when local LLM fails: `"frontier"` or `"skip"` |
+| `local_llm.routing_strategy` | string | `"local_first"` | `"local_first"` sends fast tasks local; `"always_local"` routes everything |
+
+### features sub-table
+
+Controls which PBR tasks are eligible for local LLM offloading.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `artifact_classification` | `true` | Classify artifact types (PLAN, SUMMARY, VERIFICATION) locally |
+| `task_validation` | `true` | Validate task scope and completeness locally |
+| `context_summarization` | `false` | Summarize context windows locally (higher token demand) |
+| `source_scoring` | `false` | Score source files by relevance locally |
+
+### advanced sub-table
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `confidence_threshold` | `0.9` | Minimum confidence (0–1) for local output to be accepted; below this, falls back to frontier |
+| `shadow_mode` | `false` | Run local LLM in parallel with frontier but discard local results — useful for tuning confidence thresholds without affecting output |
+| `max_input_tokens` | `2000` | Truncate inputs longer than this before sending to local model |
+| `keep_alive` | `"30m"` | How long Ollama keeps the model loaded between requests (Ollama format: `"5m"`, `"1h"`) |
+| `num_ctx` | `4096` | Context window size passed to Ollama; **must be 4096 on Windows** (see Windows gotchas) |
+| `disable_after_failures` | `3` | Automatically disable local LLM for the session after this many consecutive failures |
+
+### Hardware requirements
+
+| Tier | Hardware | Notes |
+|------|----------|-------|
+| Recommended | RTX 3060+ with 8 GB VRAM | Full GPU acceleration; qwen2.5-coder:7b loads entirely in VRAM |
+| Functional | GTX 1660+ with 6 GB VRAM | GPU acceleration with slight layer offload to RAM |
+| Marginal | CPU only, 32 GB RAM | Works but adds 5-20s latency per call; disable context-heavy features |
+
+For GPU acceleration, ensure NVIDIA drivers are 520+ and CUDA 11.8+ is installed. AMD GPU support is available via ROCm on Linux only.
+
+### Windows gotchas
+
+- **Smart App Control**: May block `ollama_llama_server.exe` on first run. Allow it via Security settings or disable Smart App Control.
+- **Windows Defender**: Add an exclusion for `%LOCALAPPDATA%\Programs\Ollama\ollama_llama_server.exe` to prevent Defender from scanning inference calls in real time.
+- **`num_ctx` must be 4096**: Higher values cause GPU memory fragmentation on Windows and result in OOM errors mid-session. Always set `advanced.num_ctx: 4096` in your config.
+- **Firewall**: Ollama listens on `localhost:11434` by default. If you see connection refused errors, check that Windows Firewall is not blocking loopback connections.
+
+### Viewing metrics
+
+After enabling local LLM, PBR logs per-call metrics to `.planning/logs/local-llm-metrics.jsonl`. Use the built-in subcommands to inspect them:
+
+```bash
+# Show session summary (calls routed, latency, token savings)
+node plugins/pbr/scripts/pbr-tools.js llm metrics
+
+# Suggest routing threshold adjustments based on recent accuracy
+node plugins/pbr/scripts/pbr-tools.js llm adjust-thresholds
+```
+
+Metrics include: routing decision, model used, latency ms, confidence score, whether the frontier fallback was triggered, and estimated tokens saved.

package/plugins/cursor-pbr/references/continuation-format.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/continuation-format.md -->
 # Continuation Protocol
 
 How to spawn a fresh executor agent to continue from a checkpoint or partial completion.

package/plugins/cursor-pbr/references/deviation-rules.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/deviation-rules.md -->
 # Deviation Rules
 
 When execution doesn't go exactly as planned, these 5 rules govern what the executor can do on its own versus what requires user approval.

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

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/git-integration.md -->
 # Git Integration Reference
 
 Plan-Build-Run's commit conventions, commit points, branching strategy, and hook scripts.
@@ -8,23 +7,22 @@ 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` |
+| `{type}` | Conventional commit type | `feat`, `fix`, `chore` |
+| `{scope}` | Descriptive word for the area of change | `auth`, `executor`, `changelog` |
+| `{description}` | Imperative, lowercase description | `add discord oauth flow` |
 
-The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({phase}-{plan}): {description}`.
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({scope}): {description}`.
 
 ### Full Example
 ```
-feat(02-01): implement discord oauth client
+feat(auth): implement discord oauth client
 ```
 
 ---
@@ -33,19 +31,35 @@ 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(auth): implement discord oauth client` |
+| `fix` | Bug fix (including during execution) | `fix(api): handle null user profile from discord` |
+| `refactor` | Code restructuring, no behavior change | `refactor(auth): extract token validation into helper` |
+| `test` | Adding or modifying tests | `test(auth): add failing tests for oauth flow` |
+| `docs` | Documentation changes | `docs(planning): add api endpoint documentation` |
+| `chore` | Build config, dependencies, tooling | `chore(deps): configure typescript and eslint` |
+| `style` | Formatting, whitespace (no logic change) | `style(auth): fix import ordering` |
+
+---
+
+## 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 |
+
+**TDD commits**: RED phase → `test({scope}): RED - ...`, GREEN phase → `refactor({scope}): GREEN - ...`, REFACTOR phase → `refactor({scope}): REFACTOR - ...`
 
 ---
 
 ## Special Commit Scopes
 
-Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these additional patterns:
+Beyond descriptive scopes, Plan-Build-Run recognizes these additional patterns:
 
 | Pattern | When Used | Example |
 |---------|-----------|---------|
@@ -56,12 +70,25 @@ Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these addi
 
 ---
 
+## 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.
+
+---
+
 ## Commit Body (Optional)
 
 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
@@ -85,9 +112,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
@@ -126,15 +153,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"
 ```
 
 ---
@@ -175,6 +202,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:

package/plugins/cursor-pbr/references/integration-patterns.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/integration-patterns.md -->
 # Integration Patterns Reference
 
 Technology-specific grep/search patterns and E2E flow templates for integration-checker.

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

@@ -1,13 +1,32 @@
-<!-- canonical: ../../pbr/references/model-profiles.md -->
 # 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 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
 
@@ -23,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 |
 |---------|-----------|---------|----------|----------|-------------|----------|--------|-------------|
@@ -52,11 +73,11 @@ The `/pbr:config model-profile {preset}` command sets all agent models at once u
 
 ### 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:
@@ -89,6 +110,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:
@@ -97,4 +140,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/cursor-pbr/references/model-selection.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/model-selection.md -->
 # Model Selection Reference
 
 Plan-Build-Run uses adaptive model selection to balance cost and capability.
@@ -15,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