@sienklogic/plan-build-run 2.57.0 → 2.59.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.59.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.58.0...plan-build-run-v2.59.0) (2026-03-06)
+
+
+### Features
+
+* **63-01:** implement worktree-create.js hook script ([195c9e0](https://github.com/SienkLogic/plan-build-run/commit/195c9e0c03d5ebaecdddfb9df647a165eba6a199))
+* **63-01:** implement worktree-remove.js hook script ([3928168](https://github.com/SienkLogic/plan-build-run/commit/392816846f29a58e58e09f72fd9f976428a4c46b))
+* **64-03:** add profile command registration to derivative plugins ([f12d4af](https://github.com/SienkLogic/plan-build-run/commit/f12d4af9f8762ed34e99659bc0edde12d2071477))
+* **config:** add Platform Settings step to /pbr:setup in all three plugins ([60e17bd](https://github.com/SienkLogic/plan-build-run/commit/60e17bdb8dc1ca0fbdeb285442c3a82f250f6962))
+* **config:** add platform_settings block to config fixture ([8af55e6](https://github.com/SienkLogic/plan-build-run/commit/8af55e6d4ffbde1b13b9c8f4889acfb7563069e9))
+* **model-profiles:** add --model CLI override to build/plan/review skills ([f09d4de](https://github.com/SienkLogic/plan-build-run/commit/f09d4de90348daf8ef0f7ae85718a15057fc202e))
+* **model-profiles:** add /pbr:profile skill and command to pbr plugin ([310719b](https://github.com/SienkLogic/plan-build-run/commit/310719b76fc6cc2bef3cc156baa22c212c566be1))
+* **model-profiles:** add /pbr:profile skill to cursor-pbr, copilot-pbr, codex-pbr ([02ae4d4](https://github.com/SienkLogic/plan-build-run/commit/02ae4d41f19b897ce9a5af6ff0c13d19a222730d))
+* **model-profiles:** add model_profiles to config-schema and update reference doc with config-only authority ([03f7009](https://github.com/SienkLogic/plan-build-run/commit/03f7009b3405c38aa1fc8222fffaa1a18c06ba9c))
+* **model-profiles:** sync --model argument-hint to cursor-pbr/copilot-pbr and add overrideModel to init.js ([cdba92f](https://github.com/SienkLogic/plan-build-run/commit/cdba92f7de3e33b54d190a8d4a6536e510d88cd2))
+* **worktree-hooks:** add worktree hooks to cursor-pbr and copilot-pbr ([954ddac](https://github.com/SienkLogic/plan-build-run/commit/954ddac1b492edaf9625fba23d5363ffd3503cb1))
+* **worktree-hooks:** add WorktreeCreate/WorktreeRemove to cross-plugin-compat test maps ([6dd2dd6](https://github.com/SienkLogic/plan-build-run/commit/6dd2dd61720651aaecd6a5eaf7cacee508cd4d94))
+* **worktree-hooks:** add WorktreeCreate/WorktreeRemove to pbr hooks.json ([23791ed](https://github.com/SienkLogic/plan-build-run/commit/23791ed181e66921bbb954cb7424fa339e4bf582))
+
+
+### Bug Fixes
+
+* **64-01:** add default model: sonnet in cursor derivative generator ([a51a2bf](https://github.com/SienkLogic/plan-build-run/commit/a51a2bf8fa2a6284f7f697a99de89c2649c95f12))
+* **64-01:** restore model: sonnet to cursor-pbr agent frontmatter ([bcaef58](https://github.com/SienkLogic/plan-build-run/commit/bcaef584abb962ad7ff17033f6ac714e29f3df9d))
+* **model-profiles:** restore model to derivative agents, update tests for config-only model ([ed8ab09](https://github.com/SienkLogic/plan-build-run/commit/ed8ab092c9084a9835efa07dd71e2acc50734f40))
+
+## [2.58.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.57.0...plan-build-run-v2.58.0) (2026-03-05)
+
+
+### Features
+
+* **hook-events:** add native agent_type support, continue:false halt signals, and InstructionsLoaded hook ([8f09dcb](https://github.com/SienkLogic/plan-build-run/commit/8f09dcbad39c4f0e19d7f26f4f5fa694bc2b5f2e))
+
+
+### Bug Fixes
+
+* **hook-events:** add InstructionsLoaded to hooks schema and valid events list ([cd6601c](https://github.com/SienkLogic/plan-build-run/commit/cd6601c66ac806e1c884e86b829596001fc81c3f))
+* **hook-events:** fix sessionLoad bug in halt conditions, add missing agent_type and halt tests ([aab8ec6](https://github.com/SienkLogic/plan-build-run/commit/aab8ec6b9346a66fcb6e9a1f038ec5bef4c8cf6f))
+
 ## [2.57.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.56.3...plan-build-run-v2.57.0) (2026-03-05)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.57.0",
+  "version": "2.59.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/codex-pbr/commands/profile.md

@@ -0,0 +1,7 @@
+---
+name: profile
+description: "Switch the active model profile. Presets: quality, balanced, budget, adaptive. Supports custom profiles from config.json model_profiles."
+skill: profile
+---
+
+This command is provided by the `pbr:profile` skill.

package/plugins/codex-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,8 +42,10 @@ 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`.
 
 ---
 
@@ -88,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:config 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 +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/codex-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/codex-pbr/skills/begin/SKILL.md

@@ -132,6 +132,7 @@ Use AskUserQuestion:
       description: "Walk through model selection, features, and preferences step by step."
 
 **If user selects "Quick start":**
+- Tell the user: "Tip: Agents set to `inherit` use your Claude Code session model. For cost savings, run on Sonnet -- orchestration and inherit agents work well at that tier. See `references/model-profiles.md` for details."
 - Write `.planning/config.json` immediately using the default config below (no further questions):
   ```json
   {
@@ -213,6 +214,8 @@ Use AskUserQuestion:
 After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
 **3-model. Model Profile:**
+Note: These profiles control agent models. The orchestrator uses your Claude Code session model. For cost optimization, consider running on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md`.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"
@@ -318,7 +321,7 @@ This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run)
 
 **CRITICAL (no hook): You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
 
-1. Read the config template from `skills/begin/templates/config.json.tmpl`
+1. Read the config template from `${CLAUDE_SKILL_DIR}/templates/config.json.tmpl`
 2. Apply the user's choices to the template (including 3d-claude CLAUDE.md integration)
 3. Create `.planning/` directory
 4. Write `.planning/config.json` with the user's preferences
@@ -402,7 +405,7 @@ Task({
 
 For each researcher, construct the prompt by reading the template and filling in placeholders:
 
-Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure.
+Read `${CLAUDE_SKILL_DIR}/templates/researcher-prompt.md.tmpl` for the prompt structure.
 
 **Prepend this block to the researcher prompt before sending:**
 
@@ -483,7 +486,7 @@ Task({
 
 #### Synthesis Prompt Template
 
-Read `skills/begin/templates/synthesis-prompt.md.tmpl` for the prompt structure.
+Read `${CLAUDE_SKILL_DIR}/templates/synthesis-prompt.md.tmpl` for the prompt structure.
 
 **Prepend this block to the synthesizer prompt before sending:**
 ```
@@ -558,7 +561,7 @@ Each requirement must be:
 
 **CRITICAL (no hook): Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
 
-Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
+Read the template from `${CLAUDE_SKILL_DIR}/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
 - All v1 requirements grouped by category
 - All v2 requirements with deferral reasons
 - Out-of-scope items with rationale
@@ -586,7 +589,7 @@ Task({
 
 #### Roadmap Prompt Template
 
-Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
+Read `${CLAUDE_SKILL_DIR}/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 
 **Prepend this block to the roadmap planner prompt before sending:**
 ```
@@ -632,7 +635,7 @@ Write the project state files from templates:
 **CRITICAL (no hook): Write PROJECT.md NOW. Do NOT skip this step.**
 
 **9a. Write PROJECT.md:**
-1. Read `skills/begin/templates/PROJECT.md.tmpl`
+1. Read `${CLAUDE_SKILL_DIR}/templates/PROJECT.md.tmpl`
 2. Fill in:
    - `{project_name}` — from questioning
    - `{2-3 sentences}` — project description from questioning
@@ -646,7 +649,7 @@ Write the project state files from templates:
 **CRITICAL (no hook): Write STATE.md NOW. Do NOT skip this step.**
 
 **9b. Write STATE.md:**
-1. Read `skills/begin/templates/STATE.md.tmpl`
+1. Read `${CLAUDE_SKILL_DIR}/templates/STATE.md.tmpl`
 2. Fill in:
    - `{date}` — today's date
    - `{total}` — total phase count from roadmap

package/plugins/codex-pbr/skills/build/SKILL.md

@@ -48,6 +48,7 @@ Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
 | `3` | Build phase 3 |
 | `3 --gaps-only` | Build only gap-closure plans in phase 3 |
 | `3 --team` | Use Agent Teams for complex inter-agent coordination |
+| `3 --model opus` | Use opus for all executor spawns in phase 3 (overrides config and adaptive selection) |
 | (no number) | Use current phase from STATE.md |
 | `3 --preview` | Preview what build would do for phase 3 without executing |
 
@@ -318,6 +319,7 @@ This is a read-only presentation step — extract descriptions from plan frontma
 
 **Model Selection (Adaptive)**:
 Before spawning the executor for each plan, determine the model:
+0. If `--model <value>` was parsed from `$ARGUMENTS` (valid values: sonnet, opus, haiku, inherit), use that model for ALL executor Task() spawns in this run. Skip steps 1-4. The --model flag is the highest precedence override.
 1. Read the plan's task elements for `complexity` and `model` attributes
 2. If ANY task has an explicit `model` attribute, use the most capable model among them (inherit > sonnet > haiku)
 3. Otherwise, use the HIGHEST complexity among the plan's tasks to select the model:
@@ -325,6 +327,8 @@ Before spawning the executor for each plan, determine the model:
 4. If `config.models.executor` is set (non-null), it overrides adaptive selection entirely — use that model for all executors
 5. Pass the selected model to the Task() spawn
 
+If `--model <value>` is present in `$ARGUMENTS`, extract the value. Valid values: `sonnet`, `opus`, `haiku`, `inherit`. If an invalid value is provided, display an error and list valid values. Store as `override_model`.
+
 Reference: `references/model-selection.md` for full details.
 
 1. Extract the `## Summary` section from the PLAN.md (everything after the `## Summary` heading to end of file). If no ## Summary section exists (legacy plans), fall back to reading the full PLAN.md content. Note: The orchestrator reads the full PLAN.md once for narrative extraction AND summary extraction; only the ## Summary portion is inlined into the executor prompt. The full PLAN.md stays on disk for the executor to Read.
@@ -333,7 +337,7 @@ Reference: `references/model-selection.md` for full details.
 4. Read prior SUMMARY.md files from the same phase (completed plans in earlier waves)
 5. Read `.planning/config.json`
 
-Construct the executor prompt by reading `skills/build/templates/executor-prompt.md.tmpl` and filling in all `{placeholder}` values:
+Construct the executor prompt by reading `${CLAUDE_SKILL_DIR}/templates/executor-prompt.md.tmpl` and filling in all `{placeholder}` values:
 
 - `{NN}-{slug}` — phase directory (e.g., `02-authentication`)
 - `{plan_id}` — plan being executed (e.g., `02-01`)
@@ -455,7 +459,7 @@ For each plan that completed successfully in this wave:
 1. Read the plan's SUMMARY.md to get `key_files` (the files this plan created/modified)
 2. Display to the user: `◐ Spawning inline verifier for plan {plan_id}...`
 
-   Spawn `Task({ subagent_type: "pbr:verifier", model: "haiku", prompt: ... })`. Read `skills/build/templates/inline-verifier-prompt.md.tmpl` and fill in `{NN}-{slug}`, `{plan_id}`, and `{comma-separated key_files list}` (key_files from PLAN.md frontmatter). Use the filled template as the `prompt` value.
+   Spawn `Task({ subagent_type: "pbr:verifier", model: "haiku", prompt: ... })`. Read `${CLAUDE_SKILL_DIR}/templates/inline-verifier-prompt.md.tmpl` and fill in `{NN}-{slug}`, `{plan_id}`, and `{comma-separated key_files list}` (key_files from PLAN.md frontmatter). Use the filled template as the `prompt` value.
 
 3. If verifier reports FAIL for any file:
    - Present the failure to the user: "Inline verify failed for plan {plan_id}: {details}"
@@ -553,7 +557,7 @@ Checkpoint in Plan {id}, Task {N}: {checkpoint type}
 
 Reference: `references/continuation-format.md` for the continuation protocol.
 
-Read `skills/build/templates/continuation-prompt.md.tmpl` and fill in:
+Read `${CLAUDE_SKILL_DIR}/templates/continuation-prompt.md.tmpl` and fill in:
 
 - `{NN}-{slug}`, `{plan_id}` — current phase and plan
 - `{plan_summary}` — the ## Summary section from PLAN.md
@@ -662,7 +666,7 @@ After verifier completes, check for completion marker: `## VERIFICATION COMPLETE
 
 #### Verifier Prompt Template
 
-Use the same verifier prompt template as defined in `$pbr-review`: read `skills/review/templates/verifier-prompt.md.tmpl` and fill in its placeholders with the phase's PLAN.md must_haves and SUMMARY.md file paths. This avoids maintaining duplicate verifier prompts across skills.
+Use the same verifier prompt template as defined in `$pbr-review`: read `${PLUGIN_ROOT}/skills/review/templates/verifier-prompt.md.tmpl` and fill in its placeholders with the phase's PLAN.md must_haves and SUMMARY.md file paths. This avoids maintaining duplicate verifier prompts across skills.
 
 **Prepend this block to the verifier prompt before sending:**
 ```

package/plugins/codex-pbr/skills/debug/SKILL.md

@@ -183,7 +183,7 @@ Display to the user: `◐ Spawning debugger...`
 
 Spawn `Task(subagent_type: "pbr:debugger")` with the prompt template.
 
-Read `skills/debug/templates/initial-investigation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and symptom placeholders with values from the debug file created above.
+Read `${CLAUDE_SKILL_DIR}/templates/initial-investigation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and symptom placeholders with values from the debug file created above.
 
 ### Step 3b: Resume Flow
 
@@ -207,7 +207,7 @@ Continuing investigation...
 
    Spawn `Task(subagent_type: "pbr:debugger")` with the continuation prompt template.
 
-   Read `skills/debug/templates/continuation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and `{paste investigation log...}` placeholders with data from the debug file.
+   Read `${CLAUDE_SKILL_DIR}/templates/continuation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and `{paste investigation log...}` placeholders with data from the debug file.
 
 ### Step 4: Handle Debugger Results
 

package/plugins/codex-pbr/skills/discuss/SKILL.md

@@ -114,7 +114,7 @@ Before jumping into specific gray areas, give the user space to share their ment
 
 Analyze the phase goal, requirements, and what's already built. Identify **3-4 gray areas** where the user's preference matters. Gray areas fall into these categories:
 
-Read `skills/discuss/templates/decision-categories.md` for the category reference table.
+Read `${CLAUDE_SKILL_DIR}/templates/decision-categories.md` for the category reference table.
 
 **How to identify gray areas:**
 1. Look at the phase requirements — where are there multiple valid approaches?
@@ -198,7 +198,7 @@ Write the CONTEXT.md file to the phase directory:
 
 **Content:**
 
-Read `skills/discuss/templates/CONTEXT.md.tmpl` for the template structure.
+Read `${CLAUDE_SKILL_DIR}/templates/CONTEXT.md.tmpl` for the template structure.
 
 **Placeholders to fill:**
 - `{N}` -- the phase number

package/plugins/codex-pbr/skills/health/SKILL.md

@@ -33,9 +33,9 @@ Check if the user passed `--repair`:
 
 ## How Checks Work
 
-Each check follows the common pattern. Read `skills/health/templates/check-pattern.md.tmpl` for the shared execution flow: target files, validate against rules, classify as PASS/FAIL/WARN/INFO, and record the result with a fix suggestion for any failures.
+Each check follows the common pattern. Read `${CLAUDE_SKILL_DIR}/templates/check-pattern.md.tmpl` for the shared execution flow: target files, validate against rules, classify as PASS/FAIL/WARN/INFO, and record the result with a fix suggestion for any failures.
 
-Read `skills/health/templates/output-format.md.tmpl` for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.
+Read `${CLAUDE_SKILL_DIR}/templates/output-format.md.tmpl` for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.
 
 ---
 

package/plugins/codex-pbr/skills/milestone/SKILL.md

@@ -160,7 +160,7 @@ Start a new milestone cycle with new phases.
    docs(planning): start milestone "{name}" (phases {start}-{end})
    ```
 
-10. **Confirm** with branded output — read `skills/milestone/templates/new-output.md.tmpl` and fill in `{name}` (milestone name), `{count}` (phase count), `{N}` (first phase number).
+10. **Confirm** with branded output — read `${CLAUDE_SKILL_DIR}/templates/new-output.md.tmpl` and fill in `{name}` (milestone name), `{count}` (phase count), `{N}` (first phase number).
 
 ---
 
@@ -331,7 +331,7 @@ Archive a completed milestone and prepare for the next one.
 
    **Stats file content:**
 
-   Read `skills/milestone/templates/stats-file.md.tmpl` for the stats file format. Fill in all `{variable}` placeholders with actual data gathered in Steps 3-4.
+   Read `${CLAUDE_SKILL_DIR}/templates/stats-file.md.tmpl` for the stats file format. Fill in all `{variable}` placeholders with actual data gathered in Steps 3-4.
 
 6. **Update PROJECT.md:**
    - Move milestone from "Active" to "Completed"
@@ -448,7 +448,7 @@ If `config.deployment.smoke_test_command` is set and non-empty:
 
    This is advisory only — the milestone is already archived. Surface it as a potential issue for the user to investigate.
 
-10. **Confirm** with branded output — read `skills/milestone/templates/complete-output.md.tmpl` and fill in `{version}`, `{count}` (phases, plans, commits), `{lines}`, `{duration}`.
+10. **Confirm** with branded output — read `${CLAUDE_SKILL_DIR}/templates/complete-output.md.tmpl` and fill in `{version}`, `{count}` (phases, plans, commits), `{lines}`, `{duration}`.
 
 ---
 
@@ -471,7 +471,7 @@ Verify milestone completion with cross-phase integration checks.
 
    Display to the user: `◐ Spawning integration checker...`
 
-   Spawn `Task(subagent_type: "pbr:integration-checker")`. Read `skills/milestone/templates/integration-checker-prompt.md.tmpl`, fill in `{version or "current"}`, `{list of phase directories}`, and `{phase SUMMARY.md paths}`, then use the filled template as the Task() prompt.
+   Spawn `Task(subagent_type: "pbr:integration-checker")`. Read `${CLAUDE_SKILL_DIR}/templates/integration-checker-prompt.md.tmpl`, fill in `{version or "current"}`, `{list of phase directories}`, and `{phase SUMMARY.md paths}`, then use the filled template as the Task() prompt.
 
 4. **Check integration-checker completion:**
 
@@ -488,11 +488,11 @@ Verify milestone completion with cross-phase integration checks.
 
    Create `.planning/{version}-MILESTONE-AUDIT.md` using the template:
 
-   Read `skills/milestone/templates/audit-report.md.tmpl` for the audit report format. Fill in all `{variable}` placeholders with actual data from the audit.
+   Read `${CLAUDE_SKILL_DIR}/templates/audit-report.md.tmpl` for the audit report format. Fill in all `{variable}` placeholders with actual data from the audit.
 
    **Spot-check:** After writing, verify `.planning/{version}-MILESTONE-AUDIT.md` exists on disk using Glob. If missing, re-attempt the write. If still missing, display an error and include findings inline.
 
-7. **Report to user** using branded banners — read `skills/milestone/templates/audit-output.md.tmpl`. The template contains all 3 variants (PASSED, GAPS FOUND, TECH DEBT). Select the appropriate section based on audit result. Fill in `{version}`, `{count}`, `{gap 1}`, `{gap 2}` as applicable.
+7. **Report to user** using branded banners — read `${CLAUDE_SKILL_DIR}/templates/audit-output.md.tmpl`. The template contains all 3 variants (PASSED, GAPS FOUND, TECH DEBT). Select the appropriate section based on audit result. Fill in `{version}`, `{count}`, `{gap 1}`, `{gap 2}` as applicable.
 
 ---
 
@@ -572,7 +572,7 @@ Create phases to close gaps found during an audit.
    docs(planning): add gap-closure phases from milestone audit
    ```
 
-9. **Confirm** with branded output — read `skills/milestone/templates/gaps-output.md.tmpl` and fill in `{count}` (gap-closure phases created), `{N}` (first gap phase number), `{name}` (phase name).
+9. **Confirm** with branded output — read `${CLAUDE_SKILL_DIR}/templates/gaps-output.md.tmpl` and fill in `{count}` (gap-closure phases created), `{N}` (first gap phase number), `{name}` (phase name).
 
 ---
 
@@ -603,7 +603,7 @@ Tags (complete only):
 
 ## Edge Cases
 
-For all edge case handling, see `skills/milestone/templates/edge-cases.md`.
+For all edge case handling, see `${CLAUDE_SKILL_DIR}/templates/edge-cases.md`.
 Key scenarios: no ROADMAP.md, no phases, no gaps found, version collision, partially verified, large milestone (8+ phases).
 
 ---

package/plugins/codex-pbr/skills/pause/SKILL.md

@@ -128,7 +128,7 @@ Write the handoff file to the current phase directory:
 
 **Content:**
 
-Read `skills/pause/templates/continue-here.md.tmpl` for the handoff file format. Fill in all `{variable}` placeholders with actual session data gathered in Steps 1-3.
+Read `${CLAUDE_SKILL_DIR}/templates/continue-here.md.tmpl` for the handoff file format. Fill in all `{variable}` placeholders with actual session data gathered in Steps 1-3.
 
 ### Step 5: Update STATE.md
 

package/plugins/codex-pbr/skills/plan/SKILL.md

@@ -54,6 +54,7 @@ Parse the phase number and optional flags:
 | `3 --assumptions` | Surface assumptions before planning phase 3 |
 | `3 --gaps` | Create gap-closure plans for phase 3 (from VERIFICATION.md) |
 | `3 --teams` | Plan phase 3 using specialist agent teams |
+| `3 --model opus` | Use opus for all researcher, planner, and checker spawns in phase 3 |
 | (no number) | Use current phase from STATE.md |
 | `3 --preview` | Preview what planning would produce for phase 3 without spawning agents |
 
@@ -114,6 +115,7 @@ Execute these steps in order for standard `$pbr-plan <N>` invocations.
 Reference: `skills/shared/config-loading.md` for the tooling shortcut (`state load`, `plan-index`, `phase-info`) and config field reference.
 
 1. Parse `$ARGUMENTS` for phase number and flags
+   - If `--model <value>` is present in `$ARGUMENTS`, extract the value (sonnet, opus, haiku, inherit). Store as `override_model`. When spawning researcher, planner, and plan-checker Task() agents, use `override_model` instead of the config-derived model values. If an invalid value is provided, display an error and list valid values.
 2. Read `.planning/config.json` for settings (see config-loading.md for field reference)
    **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 3. Resolve depth profile: run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
@@ -227,7 +229,7 @@ NOTE: The pbr:researcher subagent type auto-loads the agent definition. Do NOT i
 
 #### Phase Research Prompt Template
 
-Read `skills/plan/templates/researcher-prompt.md.tmpl` and use it as the prompt template for spawning the researcher agent. Fill in the placeholders with phase-specific context:
+Read `${CLAUDE_SKILL_DIR}/templates/researcher-prompt.md.tmpl` and use it as the prompt template for spawning the researcher agent. Fill in the placeholders with phase-specific context:
 - `{NN}` - phase number (zero-padded)
 - `{phase name}` - phase name from roadmap
 - `{goal from roadmap}` - phase goal statement
@@ -352,7 +354,7 @@ After planner completes, check for completion markers: `## PLANNING COMPLETE`, `
 
 #### Planning Prompt Template
 
-Read `skills/plan/templates/planner-prompt.md.tmpl` and use it as the prompt template for spawning the planner agent. Fill in all placeholder blocks with phase-specific context:
+Read `${CLAUDE_SKILL_DIR}/templates/planner-prompt.md.tmpl` and use it as the prompt template for spawning the planner agent. Fill in all placeholder blocks with phase-specific context:
 
 - `<phase_context>` - phase number, directory, goal, requirements, dependencies, success criteria
 - `<project_context>` - locked decisions, user constraints, deferred ideas, phase-specific decisions
@@ -424,7 +426,7 @@ NOTE: The pbr:plan-checker subagent type auto-loads the agent definition. Do NOT
 
 #### Checker Prompt Template
 
-Read `skills/plan/templates/checker-prompt.md.tmpl` and use it as the prompt template for spawning the plan checker agent. Fill in the placeholders:
+Read `${CLAUDE_SKILL_DIR}/templates/checker-prompt.md.tmpl` and use it as the prompt template for spawning the plan checker agent. Fill in the placeholders:
 - `<plans_to_check>` - manifest table of PLAN.md file paths (checker reads each via Read tool)
 - `<phase_context>` - phase goal and requirement IDs
 - `<context>` - file paths to project-level and phase-level CONTEXT.md files (checker reads via Read tool)
@@ -452,7 +454,7 @@ After the plan checker returns, display its result:
 Reference: `skills/shared/revision-loop.md` for the full Check-Revise-Escalate pattern.
 
 Follow the revision loop pattern with:
-- **Producer**: planner (re-spawned with `skills/plan/templates/revision-prompt.md.tmpl`)
+- **Producer**: planner (re-spawned with `${CLAUDE_SKILL_DIR}/templates/revision-prompt.md.tmpl`)
 - **Checker**: plan-checker (back to Step 6)
 - **Escalation**: present issues to user, offer "Proceed anyway" or "Adjust approach" (re-enter Step 5)
 
@@ -529,7 +531,7 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 
 ### Subcommand: `insert <N>`
 
-Reference: `skills/plan/decimal-phase-calc.md` for decimal numbering rules.
+Reference: `${CLAUDE_SKILL_DIR}/decimal-phase-calc.md` for decimal numbering rules.
 
 **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 
@@ -573,7 +575,7 @@ When invoked with `--gaps`:
 2. Extract all gaps from the verification report
 3. Spawn planner Task() in Gap Closure mode:
 
-Read `skills/plan/templates/gap-closure-prompt.md.tmpl` and use it as the prompt template for the gap closure planner. Fill in the placeholders:
+Read `${CLAUDE_SKILL_DIR}/templates/gap-closure-prompt.md.tmpl` and use it as the prompt template for the gap closure planner. Fill in the placeholders:
 - `<verification_report>` - inline the FULL VERIFICATION.md content
 - `<existing_plans>` - inline all existing PLAN.md files for the phase
 - `<gap_closure_instructions>` - specify output path and gap_closure frontmatter flag
@@ -646,5 +648,5 @@ Delete `.planning/.active-skill` if it exists. This must happen on all paths (su
 
 After planning completes, present:
 
-Use the branded stage banner and next-up block from `skills/plan/templates/completion-output.md.tmpl`.
+Use the branded stage banner and next-up block from `${CLAUDE_SKILL_DIR}/templates/completion-output.md.tmpl`.
 Fill in: `{N}` (phase number), `{phase-name}`, `{plan_count}`, `{plan_list_lines}` (one line per plan with wave and task count), `{wave_table_lines}` (one line per wave).