@sienklogic/plan-build-run 2.58.0 → 2.60.0

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

@@ -35,9 +35,12 @@ This skill runs **inline** (no Task delegation).
 
 ### Step 1: Parse Phase Number and Check for Existing Plans
 
-Parse `$ARGUMENTS` to get the phase number.
+Parse `$ARGUMENTS`:
+- If argument is `--project`: enter PROJECT mode (see Step 1-project below). Skip Steps 2-8.
+- If argument is a phase number: enter PHASE mode (existing flow — continue with Step 1 as-is).
+- If no argument: existing logic applies (read STATE.md for current phase).
 
-**Validation:**
+**Validation (PHASE mode):**
 - Must be a valid phase number (integer or decimal like `3.1`)
 - If no argument provided, read STATE.md to get the current phase
 - If no current phase and no argument: "Which phase do you want to discuss? Run `$pbr-status` to see available phases."
@@ -63,6 +66,53 @@ Phase {N} not found.
    - Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with `$pbr-plan {N}` after."
    - This is a **warning only** — do not block the discussion
 
+### Step 1-project: Project Discussion Mode (--project)
+
+When invoked with `--project`, discuss project-level cross-cutting decisions.
+This mode writes to `.planning/CONTEXT.md` (project-level), NOT a phase directory.
+
+**Check for existing project CONTEXT.md:**
+1. Use Glob to check if `.planning/CONTEXT.md` exists.
+2. If it exists, ask the user (using the context-handling pattern from
+   `skills/shared/gate-prompts.md`):
+   question: "Project CONTEXT.md already exists. How should we handle it?"
+   options: Overwrite | Append | Cancel
+3. If Cancel: stop and display the existing CONTEXT.md path.
+
+**Load project context:**
+- Read `.planning/PROJECT.md` (if exists) — project vision and scope
+- Read `.planning/REQUIREMENTS.md` (if exists) — requirements for constraint awareness
+- Read `.planning/CONTEXT.md` (if exists) — current locked decisions (for Append mode)
+
+**Run gray areas for project-level decisions (Steps 2.5-5 pattern):**
+- Identify 3-4 cross-cutting architectural decisions across ALL phases
+- Focus on: technology stack choices, infrastructure, security posture,
+  observability approach, deployment strategy, data storage decisions
+- Follow the same Steps 3-5 pattern (gray areas → options → follow-ups)
+
+**Write project CONTEXT.md:**
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from discussion decisions:
+   - Locked Decisions table: all decisions the user made (not "Let Claude decide")
+   - User Constraints: budget, team, timeline, hosting from the conversation
+   - Deferred Ideas: anything explicitly ruled out for this project
+   - Claude's Discretion: decisions marked "Let Claude decide"
+3. If Append mode: merge new decisions with existing CONTEXT.md content
+4. Write to `.planning/CONTEXT.md`
+
+**Update STATE.md pointer:**
+Add under Accumulated Context:
+```
+Project context: .planning/CONTEXT.md ({N} locked decisions, {N} deferred, {N} discretion)
+```
+
+**After writing:** Auto-sync to CLAUDE.md is handled by the post-write-dispatch hook.
+Display: `✓ Project CONTEXT.md written — locked decisions will auto-sync to CLAUDE.md`
+
+Skip to Cleanup step. Do NOT run Steps 2-8 of the phase flow.
+
+---
+
 ### Step 2: Load Phase Context
 
 Read the following files to understand what this phase needs to accomplish:
@@ -114,7 +164,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 +248,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.
 
 ---
 
@@ -61,6 +61,19 @@ Stop all further checks.
 - PASS: All three required files exist
 - FAIL: List each missing file — "Run `$pbr-begin` to re-initialize, or create the file manually."
 
+**Advisory checks — WARN if missing, do not FAIL:**
+
+- `.planning/PROJECT.md`
+  If missing: `⚠ PROJECT.md not found. Run $pbr-begin to generate it, or create from plugins/pbr/templates/PROJECT.md.tmpl.`
+
+- `.planning/REQUIREMENTS.md`
+  If missing: `⚠ REQUIREMENTS.md not found. Run $pbr-begin to generate it, or create from plugins/pbr/templates/REQUIREMENTS.md.tmpl.`
+
+- `.planning/CONTEXT.md` (project-level)
+  If missing: `⚠ CONTEXT.md not found. Run $pbr-discuss --project to capture locked decisions.`
+
+These files are generated by $pbr-begin. Absence is expected on projects created before v2.15.
+
 ### Check 2: Config Validity
 
 Parse `.planning/config.json` as JSON. Check required fields: `version`, `depth`. Check recommended fields: `features`, `models`.

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)
 
@@ -482,7 +484,17 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 - Or make small inline edits to plan files directly
 
 **If user selects 'Approve':**
-- **CONTEXT.md compliance reporting**: If `.planning/CONTEXT.md` exists, compare all locked decisions against the generated plans. Print: "CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks" where M = locked decisions that are reflected in at least one task, N = total locked decisions. If any locked decisions are unmapped, list them as warnings.
+- **CONTEXT.md compliance reporting**: Check locked decisions from BOTH sources:
+  a. Project-level: `.planning/CONTEXT.md` (if exists) — cross-cutting decisions for all phases
+  b. Phase-level: `.planning/phases/{NN}-{slug}/CONTEXT.md` (if exists) — phase-specific decisions
+     Phase-level decisions override project-level for the same decision area.
+
+  Collect ALL locked decisions from both files (deduplicate identical decision text).
+  Compare against the generated plan tasks. Print:
+  `CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks`
+  where M = locked decisions reflected in at least one task action, N = total unique locked decisions.
+  If any locked decisions are unmapped, list them as warnings.
+  If neither CONTEXT.md exists: skip this check silently.
 - **Dependency fingerprinting**: For each dependency phase (phases that this phase depends on, per ROADMAP.md):
   1. Find all SUMMARY.md files in the dependency phase directory
   2. Compute a fingerprint string for each: `"len:{bytes}-mod:{mtime}"` and add as a `dependency_fingerprints` map in each plan's YAML frontmatter — this allows the build skill to detect stale plans if dependencies were rebuilt.
@@ -529,7 +541,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 +585,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 +658,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).

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

@@ -0,0 +1,171 @@
+---
+name: profile
+description: "Switch the active model profile. Presets: quality, balanced, budget, adaptive. Supports custom profiles from config.json model_profiles."
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing Step 0 immediately.**
+
+# $pbr-profile — Model Profile Manager
+
+You are running the **profile** skill. Your job is to show the current model profile or switch to a new one by writing model assignments to `.planning/config.json`.
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MODEL PROFILE                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+## Step 1 — Load Config
+
+Read `.planning/config.json`.
+
+If the file does not exist, output:
+
+```
+Error: .planning/config.json not found. Run $pbr-begin first.
+```
+
+Stop immediately.
+
+## Step 2 — Parse Arguments
+
+Extract the first word from `$ARGUMENTS` as the profile name. Trim whitespace.
+
+- If `$ARGUMENTS` is empty or blank → **show-mode** (go to Step 3).
+- If a profile name is present → **switch-mode** (go to Step 4).
+
+## Step 3 — Show Mode (no argument)
+
+Display the current profile status and available options.
+
+1. Read `config.json` key `model_profile`. If absent, treat as `"balanced"`.
+2. Read `config.json` key `models` (object). If absent, use empty object.
+3. Read `config.json` key `model_profiles` (object, optional custom profiles). If absent, use empty object.
+
+Output the following (fill in actual values):
+
+```
+Active profile: <model_profile value>
+
+Current model assignments:
+  researcher          : <models.researcher or "not set">
+  planner             : <models.planner or "not set">
+  executor            : <models.executor or "not set">
+  verifier            : <models.verifier or "not set">
+  integration_checker : <models.integration_checker or "not set">
+  debugger            : <models.debugger or "not set">
+  mapper              : <models.mapper or "not set">
+  synthesizer         : <models.synthesizer or "not set">
+
+Available presets:
+  quality   — all agents use opus (maximum capability)
+  balanced  — mix of sonnet/inherit/haiku (default)
+  budget    — all agents use haiku (minimum cost)
+  adaptive  — sonnet for planning/verification, inherit/haiku for execution
+```
+
+If `model_profiles` has any keys, also display:
+
+```
+Custom profiles:
+  <profile-name>  — <key count> model overrides
+```
+
+Output: "Run `$pbr-profile <name>` to switch profiles."
+
+Stop. Do not write anything.
+
+## Step 4 — Switch Mode (argument provided)
+
+### Step 4a — Validate Profile Name
+
+Built-in preset names: `quality`, `balanced`, `budget`, `adaptive`.
+
+Custom profile names: keys in `config.json model_profiles` (if any).
+
+If the provided name does not match any of the above:
+
+```
+Error: Unknown profile "<name>".
+
+Valid presets: quality, balanced, budget, adaptive
+<list any custom profile names from config.json model_profiles, if any>
+
+Run `$pbr-profile` to see the current status.
+```
+
+Stop immediately.
+
+### Step 4b — Resolve Model Values
+
+Use the preset table to resolve model values:
+
+| Agent               | quality | balanced | budget | adaptive |
+|---------------------|---------|----------|--------|----------|
+| researcher          | opus    | sonnet   | haiku  | sonnet   |
+| planner             | opus    | inherit  | haiku  | sonnet   |
+| executor            | opus    | inherit  | haiku  | inherit  |
+| verifier            | opus    | sonnet   | haiku  | sonnet   |
+| integration_checker | sonnet  | sonnet   | haiku  | haiku    |
+| debugger            | opus    | inherit  | haiku  | inherit  |
+| mapper              | sonnet  | sonnet   | haiku  | haiku    |
+| synthesizer         | sonnet  | haiku    | haiku  | haiku    |
+
+For a **custom profile** (name found in `config.json model_profiles`):
+- Start with the `balanced` defaults from the table above.
+- Overlay any keys present in `config.json model_profiles[<name>]`.
+- Any agents not specified in the custom profile use the balanced default.
+
+### Step 4c — Write to config.json
+
+Update `config.json` using the Bash tool with `node -e` inline script:
+
+```bash
+node -e "
+const fs = require('fs');
+const cfg = JSON.parse(fs.readFileSync('.planning/config.json', 'utf8'));
+cfg.model_profile = '<name>';
+cfg.models = cfg.models || {};
+cfg.models.researcher = '<value>';
+cfg.models.planner = '<value>';
+cfg.models.executor = '<value>';
+cfg.models.verifier = '<value>';
+cfg.models.integration_checker = '<value>';
+cfg.models.debugger = '<value>';
+cfg.models.mapper = '<value>';
+cfg.models.synthesizer = '<value>';
+fs.writeFileSync('.planning/config.json', JSON.stringify(cfg, null, 2));
+console.log('OK');
+"
+```
+
+Replace each `<value>` with the resolved model string for that agent. Replace `<name>` with the profile name.
+
+### Step 4d — Confirm
+
+Output:
+
+```
+Active profile set to: <name>
+
+Model assignments updated:
+  researcher          : <value>
+  planner             : <value>
+  executor            : <value>
+  verifier            : <value>
+  integration_checker : <value>
+  debugger            : <value>
+  mapper              : <value>
+  synthesizer         : <value>
+
+Config written to .planning/config.json.
+Run $pbr-profile to verify.
+```
+
+Stop. Done.

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

@@ -50,6 +50,7 @@ Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
 | `3` | Review phase 3 |
 | `3 --auto-fix` | Review phase 3, automatically diagnose and create gap-closure plans for failures |
 | `3 --teams` | Review phase 3 with parallel specialist verifiers (functional + security + performance) |
+| `3 --model opus` | Use opus for all verifier spawns in phase 3 (overrides config verifier_model) |
 | (no number) | Use current phase from STATE.md |
 
 ---
@@ -65,6 +66,7 @@ Execute these steps in order.
 **Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init verify-work {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
 
 1. Parse `$ARGUMENTS` for phase number and `--auto-fix` flag
+   - If `--model <value>` is present in `$ARGUMENTS`, extract the value (sonnet, opus, haiku, inherit). Store as `override_model`. When spawning verifier Task() agents, use `override_model` instead of the config-derived verifier_model. If an invalid value is provided, display an error and list valid values.
 2. Read `.planning/config.json`
    **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "review" 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.
@@ -184,7 +186,7 @@ Task({
 
 #### Verifier Prompt Template
 
-Read `skills/review/templates/verifier-prompt.md.tmpl` and use its content as the verifier prompt.
+Read `${CLAUDE_SKILL_DIR}/templates/verifier-prompt.md.tmpl` and use its content as the verifier prompt.
 
 **Prepend this block to the verifier prompt before sending:**
 ```
@@ -426,7 +428,7 @@ Task({
 
 ##### Debugger Prompt Template
 
-Read `skills/review/templates/debugger-prompt.md.tmpl` and use its content as the debugger prompt.
+Read `${CLAUDE_SKILL_DIR}/templates/debugger-prompt.md.tmpl` and use its content as the debugger prompt.
 
 **Prepend this block to the debugger prompt before sending:**
 ```
@@ -458,7 +460,7 @@ Task({
 
 ##### Gap Planner Prompt Template
 
-Read `skills/review/templates/gap-planner-prompt.md.tmpl` and use its content as the gap planner prompt.
+Read `${CLAUDE_SKILL_DIR}/templates/gap-planner-prompt.md.tmpl` and use its content as the gap planner prompt.
 
 **Prepend this block to the gap planner prompt before sending:**
 ```

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

@@ -89,7 +89,7 @@ Before spawning agents, do a quick scan to identify what we're working with. Thi
 4. **Read existing docs** — README.md, architecture docs, .env.example
 5. **Write `.planning/codebase/RECON.md`** with project type, scale, key directories, entry points, and quick stats
 
-Refer to the "Reconnaissance Detection Reference" section of `skills/scan/templates/mapper-prompt.md.tmpl` for the full detection checklists.
+Refer to the "Reconnaissance Detection Reference" section of `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` for the full detection checklists.
 
 ### Step 3: Spawn Analysis Agents
 
@@ -118,7 +118,7 @@ Display to the user:
 
 Spawn `{mapper_count}` parallel `Task(subagent_type: "pbr:codebase-mapper")` agents, one for each area in `scan.mapper_areas`. All should be spawned in a single response for maximum parallelism.
 
-For each agent, read `skills/scan/templates/mapper-prompt.md.tmpl` and fill in the placeholders:
+For each agent, read `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` and fill in the placeholders:
 - `{focus_area}`: one of `tech`, `arch`, `quality`, `concerns`
 - `{project_path}`: the working directory
 - `{recon_data}`: contents of RECON.md

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

@@ -135,7 +135,69 @@ This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run)
 
 ---
 
-## Step 5: Write Updated Config
+## Step 5: Platform Settings
+
+Manage Claude Code platform settings that PBR recommends for optimal token usage.
+
+**Read `.planning/config.json`** (already loaded in Step 1). Check for a `platform_settings` block:
+- If absent, treat it as `{}` (no managed settings).
+
+**Check for existing `.claude/settings.json`**:
+- If it exists, read its contents. Parse as JSON (or `{}` if empty/missing).
+- If it does not exist, start from `{}`.
+
+**Compute the merge**:
+- Start with the existing `.claude/settings.json` content.
+- Apply each key from `platform_settings` in config.json on top.
+- If `platform_settings` is absent or empty, skip the write entirely.
+
+**Report drift** (compare before/after):
+- List keys being ADDED (were absent in .claude/settings.json)
+- List keys being CHANGED (differ from existing .claude/settings.json value)
+- List keys that MATCH (already correct — no change needed)
+
+Display the report:
+
+```
+Platform Settings:
+  Keys added:   includeGitInstructions → false
+  Keys matched: (none)
+  Keys changed: (none)
+
+Writing .claude/settings.json...
+```
+
+If all keys already match, display:
+
+```
+Platform Settings: .claude/settings.json is already in sync — no changes needed.
+```
+
+**Conflict detection**: If an existing `.claude/settings.json` has a key from `platform_settings` set to the OPPOSITE value (e.g., `"includeGitInstructions": true` when PBR wants `false`), display a WARNING before overwriting:
+
+```
+WARNING: .claude/settings.json has includeGitInstructions: true
+         PBR recommends false (removes redundant built-in git instructions).
+         Overwriting with PBR recommended value.
+```
+
+**Write the merged settings.json**:
+- Write to `.claude/settings.json` in the project root (alongside `.planning/`).
+- Ensure the directory `.claude/` exists (create it if needed with Bash `mkdir -p .claude`).
+- Write with 2-space indentation. Include a `$schema` key at the top:
+  ```json
+  {
+    "$schema": "https://json.schemastore.org/claude-code-settings.json",
+    "includeGitInstructions": false
+  }
+  ```
+  (Merge in any pre-existing keys from .claude/settings.json that are NOT managed by PBR — pass them through unchanged at the bottom of the object.)
+
+**Drift detection note**: On subsequent $pbr-setup runs, if `.claude/settings.json` has drifted from `platform_settings` (e.g., user manually changed it), this step will detect and re-apply the PBR values with a drift warning. This is by design — platform_settings in config.json is the source of truth.
+
+---
+
+## Step 6: Write Updated Config
 
 **CRITICAL: Write `.planning/config.json` NOW with all changes from Steps 2-3. Do NOT skip this step.**
 
@@ -143,13 +205,14 @@ Write the updated config.json to disk with all applied changes.
 
 ---
 
-## Step 6: Verification
+## Step 7: Verification
 
 Run a quick check:
 1. Verify `.planning/config.json` is valid JSON (read it back)
 2. Display updated settings summary
 
 Display:
+
 ```
 ╔══════════════════════════════════════════════════════════════╗
 ║  PLAN-BUILD-RUN ► RECONFIGURE COMPLETE ✓                     ║
@@ -159,6 +222,7 @@ Updated:
 - Model profile: {new profile}
 - Features changed: {list or "none"}
 - CLAUDE.md: {updated/skipped}
+- Platform settings: {".claude/settings.json updated" or "already in sync" or "no managed settings"}
 
 Run $pbr-status to see current project state.
 ```

package/plugins/codex-pbr/skills/shared/context-loader-task.md

@@ -28,6 +28,7 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision and scope)
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/research/SUMMARY.md (if exists)
@@ -65,6 +66,7 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision and scope)
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/HISTORY.md (if exists — scan for decisions relevant to '{topic}' only, do NOT summarize all history)