@sienklogic/plan-build-run 2.58.0 → 2.60.0

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.60.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.59.0...plan-build-run-v2.60.0) (2026-03-06)
+
+
+### Features
+
+* **65-01:** add project-CONTEXT.md.tmpl with planner-embeds pattern to all 4 plugins ([683f67c](https://github.com/SienkLogic/plan-build-run/commit/683f67c48197df79b17fb6199081914c663f458b))
+* **65-01:** add PROJECT.md.tmpl to all 4 plugin template directories ([6416490](https://github.com/SienkLogic/plan-build-run/commit/6416490bdbd20867c2bc5f418c526d70b7f651e9))
+* **65-01:** add REQUIREMENTS.md.tmpl with REQ-F/REQ-NF schema to all 4 plugins ([f293660](https://github.com/SienkLogic/plan-build-run/commit/f293660572dec225e7f3a25c137b199097af8d84))
+* **65-02:** add --project flag and Step 1-project mode to discuss/SKILL.md across all 4 plugins ([35a40c4](https://github.com/SienkLogic/plan-build-run/commit/35a40c4a1ea24cf6b68fa076ca82e268cd208bb1))
+* **65-02:** add PROJECT.md to context-loader-task.md briefing file lists across all 4 plugins ([12d4668](https://github.com/SienkLogic/plan-build-run/commit/12d46688632e6578e1e120ea123ff5de02bb781f))
+* **65-02:** update begin/SKILL.md REQ-F/REQ-NF schema and project-CONTEXT template ref across 4 plugins; add 3 new keyTemplates to test ([b228120](https://github.com/SienkLogic/plan-build-run/commit/b228120d422cb3b8bd992cef1b4cada67cb11f3e))
+* **65-03:** add doc-existence gate to validate-task; update test fixtures for implements advisory ([c5fc1e3](https://github.com/SienkLogic/plan-build-run/commit/c5fc1e3d6a360908d0652131173a784c5a7db427))
+* **65-03:** GREEN - implement sync-context-to-claude.js ([65784a0](https://github.com/SienkLogic/plan-build-run/commit/65784a057622d600fc26891dc9ece84c8c53a2dd))
+* **65-04:** add advisory warnings to health skill for missing PROJECT.md, REQUIREMENTS.md, CONTEXT.md across all 4 plugins ([182df09](https://github.com/SienkLogic/plan-build-run/commit/182df09681130b3927a09821f9d464b2546441ee))
+* **65-04:** update planner agent for dual-source CONTEXT.md loading and plan/SKILL.md compliance check ([bd6cf41](https://github.com/SienkLogic/plan-build-run/commit/bd6cf4112b6f723459c5127be8bfc74efc98e370))
+* **65-04:** update status skill to display PROJECT.md, REQUIREMENTS.md, CONTEXT.md presence across all 4 plugins ([60df410](https://github.com/SienkLogic/plan-build-run/commit/60df4104fa39d406b1833311a99df493922475d2))
+* **xml-plan-format:** add auto_checkpoints to config-schema and satisfied/unsatisfied to VERIFICATION template ([72d08e8](https://github.com/SienkLogic/plan-build-run/commit/72d08e8dccf58e5011485bfb16a39db4e972ecef))
+* **xml-plan-format:** add automated wrapper, feature type, and implements field to plan-format.md ([3ee897a](https://github.com/SienkLogic/plan-build-run/commit/3ee897a89016fe28b968266f33ff286f90de7671))
+* **xml-plan-format:** enforce implements: blocking, add feature task validation, satisfied/unsatisfied advisory ([4d78e8e](https://github.com/SienkLogic/plan-build-run/commit/4d78e8eeccda91733b11f206c0d19ed075fd9fe7))
+* **xml-plan-format:** sync cursor-pbr and copilot-pbr agents for implements:/automated/satisfied traceability ([753d4ed](https://github.com/SienkLogic/plan-build-run/commit/753d4ed0b3c4f486496781012d6dcef951d42076))
+* **xml-plan-format:** update planner/executor/verifier/plan-checker for implements: traceability and must_haves locking ([98cc23f](https://github.com/SienkLogic/plan-build-run/commit/98cc23f7e5cfca60c188809b737c4156ceb49028))
+
+
+### Bug Fixes
+
+* **cross-plugin-sync:** align status skill Step 1d heading order in cursor-pbr and copilot-pbr ([dc8419e](https://github.com/SienkLogic/plan-build-run/commit/dc8419e33c1184a2224cdb22d6383bf572d41d58))
+* **cross-plugin-sync:** sync phase 66 references, templates, and agents to codex-pbr, copilot-pbr, cursor-pbr ([e143d9e](https://github.com/SienkLogic/plan-build-run/commit/e143d9ecfc4792fb8085f62ed9227738324ea69f))
+* **doc-gates:** add 3-part format to doc-existence blocking reason ([ba2d732](https://github.com/SienkLogic/plan-build-run/commit/ba2d732e1fd89afce266a50057b2b1411152903e))
+* **doc-gates:** upgrade doc-existence gate from advisory to blocking ([a4eeb3f](https://github.com/SienkLogic/plan-build-run/commit/a4eeb3fa015b0a81d4130dd7a9e4c220f124bf7d))
+
+## [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)
 
 

package/package.json

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

package/plugins/codex-pbr/agents/executor.md

@@ -35,6 +35,9 @@ You are **executor**, the code execution agent for Plan-Build-Run. You receive v
    a. Read task XML
    b. Execute <action> steps
    c. Run <verify> commands
+      - If <verify> contains an <automated> child element, extract and run the command inside it
+      - If <verify> is plain text (no <automated> child), run it as before (backward compat)
+      - Both forms produce the same result — <automated> is machine-parseable, plain text is human-readable
    d. If verify passes: commit
    e. If verify fails: apply deviation rules
    f. If checkpoint: STOP and return
@@ -196,6 +199,11 @@ When a task has a checkpoint type, **STOP execution** and return a structured re
 | `decision` | Before executing | Decision needed, options, context |
 | `human-action` | Before executing | What user must do, step-by-step |
 
+**auto_checkpoints config**: After loading plan frontmatter, read `gates.auto_checkpoints` from config.json (default false):
+- Load with: `node pbr-tools.js config-get gates.auto_checkpoints`
+- When `auto_checkpoints` is true AND task type is `checkpoint:human-verify`: run the automated verify command. If it passes, auto-approve and continue. If it fails, still STOP and return the checkpoint response.
+- `checkpoint:decision` and `checkpoint:human-action` always require human input regardless of `auto_checkpoints`.
+
 **Automation-first**: Complete all automatable pre-work before any checkpoint. Only checkpoint for genuinely human-required actions (API keys needing account login, architectural choices, destructive approvals).
 
 All responses use: `CHECKPOINT: {TYPE}` header, task info, type-specific fields, completed tasks table, remaining tasks list.

package/plugins/codex-pbr/agents/plan-checker.md

@@ -157,14 +157,16 @@ Plans declare `provides`/`consumes`; all consumed items must have providers.
 | Missing provides/consumes for exports | INFO |
 
 ### D9: Requirement Traceability
-Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace to REQUIREMENTS.md (or ROADMAP.md goals). Backward: every requirement covered by at least one plan.
+Plans declare `implements` with bidirectional coverage. Forward: IDs trace to REQUIREMENTS.md (or ROADMAP.md goals). Backward: every requirement covered by at least one plan.
+
+> **Note:** `requirement_ids:` is a deprecated alias for `implements:` — treat as equivalent during transition.
 
 | Condition | Severity |
 |-----------|----------|
-| requirement_id references nonexistent requirement | BLOCKER |
+| implements: ID references nonexistent requirement | BLOCKER |
 | Requirement not covered by any plan | WARNING |
 | ROADMAP goal not covered (no REQUIREMENTS.md) | WARNING |
-| Plan missing requirement_ids entirely | INFO |
+| Plan missing implements: entirely | WARNING |
 
 ### D10: Test Plan Coverage
 Code-producing tasks should include test expectations. Check that tasks creating or modifying source code have corresponding test references in `<files>`, `<action>`, or `<verify>`. Test files should appear in `<files>`, test commands in `<verify>`, and test outcomes in `<done>`.

package/plugins/codex-pbr/agents/planner.md

@@ -9,7 +9,7 @@ you MUST Read every listed file BEFORE any other action.
 Skipping this causes hallucinated context and broken output.
 </files_to_read>
 
-> Default files: CONTEXT.md, ROADMAP.md, research documents, existing plan files
+> Default files: PROJECT.md (if exists), CONTEXT.md (project-level, if exists), phase CONTEXT.md (if exists), ROADMAP.md, research documents, existing plan files
 
 # Plan-Build-Run Planner
 
@@ -20,7 +20,7 @@ You are **planner**, the planning agent for the Plan-Build-Run development syste
 
 ## Core Principle: Context Fidelity
 
-**Locked decisions from CONTEXT.md are NON-NEGOTIABLE.** You never substitute, reinterpret, or work around locked decisions. If CONTEXT.md says "Use PostgreSQL", the plan uses PostgreSQL. Period.
+**Locked decisions from BOTH `.planning/CONTEXT.md` (project-level) AND `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level) are NON-NEGOTIABLE.** Phase-level overrides project-level for the same decision area. You never substitute, reinterpret, or work around locked decisions. If CONTEXT.md says "Use PostgreSQL", the plan uses PostgreSQL. Period.
 
 **Deferred ideas from CONTEXT.md MUST NOT appear in plans.** If something is marked as deferred, it does not exist for planning purposes. Do not plan for it, do not create hooks for it, do not "prepare" for it.
 </role>
@@ -192,7 +192,13 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans MU
 <execution_flow>
 ## Planning Process
 
-1. **Load Context**: Read CONTEXT.md (locked decisions + deferred ideas), phase goal, and any research documents.
+1. **Load Context**: Read locked decisions, phase goal, and any research documents.
+   - Read `.planning/PROJECT.md` (if exists) — project scope/out-of-scope constraints
+   - Read `.planning/CONTEXT.md` (project-level, if exists) — cross-cutting locked decisions
+   - Read `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level, if exists) — phase-specific decisions
+   - Phase-level CONTEXT.md overrides project-level for conflicting decision areas
+   - **For each locked decision found**: embed it directly into the relevant task's `<action>` block.
+     Executors NEVER read CONTEXT.md — PLAN.md task actions must be self-contained.
 
 ### Handling [NEEDS DECISION] Items
 When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from the synthesizer:
@@ -202,7 +208,7 @@ When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from th
 2. **Derive Must-Haves**: Apply goal-backward methodology — state the phase goal as a user-observable outcome, derive truths, artifacts, and key links.
 3. **Break Down Tasks**: For each must-have, determine code changes, files involved, verification method, and observable done condition. Group related work into tasks (2-3 per plan).
 4. **Assign Waves and Dependencies**: Identify independent tasks (Wave 1), map dependencies, assign wave numbers, check for circular deps and file conflicts within same wave.
-5. **Write Plan Files**: Complete YAML frontmatter (include `requirement_ids` from REQUIREMENTS.md or ROADMAP.md goal IDs for traceability), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
+5. **Write Plan Files**: Complete YAML frontmatter (include `implements` field with REQ-IDs from REQUIREMENTS.md or ROADMAP.md for traceability; `requirement_ids` is a deprecated alias — use `implements` as the primary field), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
 6. **Self-Check** before writing:
 
 **CRITICAL — Run the self-check. Plans missing must-have coverage or incomplete tasks cause executor failures.**
@@ -240,7 +246,7 @@ When receiving checker feedback:
 
 ## Context Optimization
 
-**Context Fidelity Self-Check**: Before writing plans, verify: (1) every locked decision in CONTEXT.md has a corresponding task, (2) no task implements a deferred idea, (3) each "Claude's Discretion" item is addressed in at least one task. Report: "CONTEXT.md compliance: {M}/{N} locked decisions mapped."
+**Context Fidelity Self-Check**: Before writing plans, verify: (1) every locked decision in BOTH `.planning/CONTEXT.md` (project-level) AND `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level) has a corresponding task (deduplicate identical decisions across both files), (2) no task implements a deferred idea, (3) each "Claude's Discretion" item is addressed in at least one task. Report: "CONTEXT.md compliance: {M}/{N} locked decisions mapped."
 
 **Frontmatter-First Assembly**: When prior plans exist, read SUMMARY.md frontmatter only (not full body) — 10 frontmatters ~500 tokens vs 10 full SUMMARYs ~5000 tokens. Extract: `provides`, `requires`, `key_files`, `key_decisions`, `patterns`. Only read full body when a specific detail is needed.
 
@@ -256,7 +262,7 @@ When receiving checker feedback:
 - [ ] Tasks grouped into plans by wave
 - [ ] PLAN files exist with XML task structure
 - [ ] Each plan: frontmatter complete (depends_on, files_modified, must_haves)
-- [ ] Each plan: requirement_ids field populated (MUST NOT be empty)
+- [ ] Each plan: implements: field populated (list REQ-IDs; use [] only if phase has no REQUIREMENTS.md)
 - [ ] Each task: all 5 elements (name, files, action, verify, done)
 - [ ] Wave structure maximizes parallelism
 - [ ] Every REQ-ID from ROADMAP/REQUIREMENTS appears in at least one plan
@@ -336,7 +342,7 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 11. DO NOT leave done conditions vague — they must be observable
 12. DO NOT specify literal `undefined` for parameters that have a known source in the calling context — use data contracts to map sources
 13. DO NOT use Bash heredoc for file creation — ALWAYS use the Write tool
-14. DO NOT leave requirement_ids empty in PLAN frontmatter — every plan must trace to requirements
+14. DO NOT leave implements: empty in PLAN frontmatter — use implements: as the primary traceability field (requirement_ids: is deprecated)
 
 </anti_patterns>
 

package/plugins/codex-pbr/agents/verifier.md

@@ -74,7 +74,8 @@ Stop and report error if pbr-tools CLI is unavailable. Also read CONTEXT.md for
 - `artifacts`: Files/exports that must exist, be substantive, and not be stubs
 - `key_links`: Connections that must be wired between components
 
-If plans lack explicit must-haves, derive them goal-backward from ROADMAP.md: what must be TRUE → what must EXIST → what must be CONNECTED.
+Must-haves in plan frontmatter are canonical — use exactly what mustHavesCollect returns.
+Only fall back to goal-backward derivation from ROADMAP.md if ALL plans in the phase have completely empty must_haves sections. Do NOT supplement or re-derive when must_haves are present.
 
 Output: A numbered list of every must-have to verify.
 
@@ -159,6 +160,14 @@ Cross-reference all must-haves against verification results in a table:
 
 L4 column shows `-` when no automated verification is available. Only artifacts with test commands or build verification get L4 checks.
 
+### Step 7b: Write REQ-ID Traceability (Always)
+
+After verifying all must-haves, collect `implements:[]` from all plan frontmatters in the phase.
+
+- For each REQ-ID: if all must-haves for that plan passed → add to `satisfied:[]`
+- If any must-have for that plan failed → add to `unsatisfied:[]`
+- Write `satisfied:[]` and `unsatisfied:[]` to the VERIFICATION.md frontmatter
+
 ### Step 8: Scan for Anti-Patterns (Full Verification Only)
 
 Scan for: dead code/unused imports, console.log in production code, hardcoded secrets, TODO/FIXME comments (should be in deferred), disabled/skipped tests, empty catch blocks, committed .env files. Report blockers only.

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

@@ -24,7 +24,9 @@ Sonnet 4.6 handles orchestration tasks (state reading, routing decisions, contex
 
 ## 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
 
@@ -40,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`.
 
 ---
 
@@ -106,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:
@@ -114,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/plan-format.md

@@ -43,9 +43,9 @@ provides:
   - "requireAuth() middleware"
 consumes:
   - "Database connection (from plan 01-01)"
-requirement_ids:
-  - "P02-G1"
-  - "P02-G2"
+implements:
+  - "REQ-F-001"
+  - "REQ-F-002"
 closes_issues:
   - 42
   - 57
@@ -71,7 +71,8 @@ closes_issues:
 | `must_haves.key_links` | YES | array | Connections between components. Append `: grep command` for verification. |
 | `provides` | NO | array | What this plan exports for other plans to consume (classes, endpoints, modules) |
 | `consumes` | NO | array | What this plan needs from prior plans. Format: `"Thing (from plan XX-YY)"` |
-| `requirement_ids` | NO | array | Requirement IDs from REQUIREMENTS.md or ROADMAP.md goal IDs that this plan addresses. Enables bidirectional traceability between plans and requirements/goals. |
+| `implements` | NO (WARNING if absent) | array | REQ-IDs from REQUIREMENTS.md this plan addresses. Primary traceability field. |
+| `requirement_ids` | NO | array | DEPRECATED — use `implements:` instead. Kept for backward compat. |
 | `dependency_fingerprints` | NO | object | Hashes of dependency phase SUMMARY.md files at plan-creation time. Used to detect stale plans. |
 | `data_contracts` | NO | array | Cross-boundary parameter mappings for calls where arguments originate from external boundaries. Format: `"param: source (context) [fallback]"` |
 | `closes_issues` | NO | number[] | GitHub issue numbers to close when this plan's final commit lands. Default: `[]` |
@@ -162,14 +163,20 @@ The Summary section is generated by the planner agent at plan creation time. It
        DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
   </action>
   <verify>
-    npx tsc --noEmit
-    ls src/auth/discord.ts
-    ls src/auth/types.ts
+    <automated>
+      npx tsc --noEmit
+      ls src/auth/discord.ts
+      ls src/auth/types.ts
+    </automated>
   </verify>
   <done>Discord OAuth client module exists and compiles without errors</done>
 </task>
 ```
 
+> **Verify block forms**: The `<automated>` wrapper (Option A) is preferred — it enables machine-parsing
+> for `auto_checkpoints` mode. Plain-text verify commands without the wrapper (Option B) remain valid
+> for backward compatibility. Both forms are supported by the executor.
+
 ### TDD Task
 
 ```xml
@@ -204,6 +211,33 @@ The Summary section is generated by the planner agent at plan creation time. It
 </task>
 ```
 
+### Feature Task (TDD Variant)
+
+Feature tasks add a `<feature>` element for structured TDD planning. The element contains two required children:
+
+- **`<behavior>`** — the observable outcome from the user's perspective. Maps directly to a `must_haves.truths` entry.
+- **`<implementation>`** — the technical approach at a high level (which files, patterns, or algorithms to use).
+
+Prose structure (illustrative — not a live task block to avoid validator false-positives):
+
+```
+task id="02-01-T3" type="auto" tdd="true" complexity="medium"
+  name: Implement rate limiter for OAuth endpoint
+  files: src/middleware/rate-limit.ts / tests/middleware/rate-limit.test.ts
+  feature:
+    behavior: OAuth endpoint rejects more than 5 requests per minute per IP with HTTP 429
+    implementation: Token-bucket algorithm; Redis-backed counter with TTL; express-rate-limit wrapper
+  action:
+    RED: Write failing tests for 429 response at >5 req/min
+    GREEN: Implement token-bucket middleware using Redis
+    REFACTOR: Extract counter logic to RateLimitStore class
+  verify:
+    automated: npm test -- --grep "rate limiter"
+  done: Rate limiter rejects excessive OAuth requests with 429
+```
+
+The `<feature>` element is optional — standard TDD tasks without it are still valid. Use `<feature>` when the planner wants to record the behavior/implementation split explicitly for traceability.
+
 ### Checkpoint: Human Verify
 
 ```xml
@@ -291,9 +325,13 @@ Every task MUST have ALL 5. No exceptions.
 | `<name>` | What the task does | Imperative verb phrase. Short. |
 | `<files>` | Files touched | One per line. Actual file paths. |
 | `<action>` | How to do it | Numbered steps. Specific. Code snippets for complex work. |
-| `<verify>` | How to check | Executable shell commands. Or checkpoint format. |
+| `<verify>` | How to check | Executable shell commands (plain-text or wrapped in `<automated>`). Or checkpoint format. |
 | `<done>` | How to know it worked | Observable user/system behavior. Maps to a must-have. |
 
+> **Optional `<feature>` element**: Feature tasks (TDD variant) may add a `<feature>` element with
+> `<behavior>` and `<implementation>` children for structured TDD planning. The 5 standard elements
+> above are still required.
+
 ---
 
 ## Task ID Format

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

@@ -321,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
@@ -405,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:**
 
@@ -486,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:**
 ```
@@ -546,11 +546,10 @@ For each category, present the features and ask the user to classify each:
 - **Out of scope** — Will NOT be built
 
 **7d. Assign REQ-IDs:**
-For each committed requirement, assign an ID in the format `{CATEGORY}-{NN}`:
-- `AUTH-01`: User can log in with Discord OAuth
-- `AUTH-02`: Protected routes redirect to login
-- `UI-01`: Dashboard shows player statistics
-- `UI-02`: Mobile-responsive layout
+For each committed requirement, assign an ID using the REQ-F/REQ-NF schema:
+- Functional requirements: `REQ-F-xxx` numbered sequentially within each category (REQ-F-001, REQ-F-002, ...)
+- Non-functional requirements: `REQ-NF-xxx` numbered sequentially across all NFR categories (REQ-NF-001, REQ-NF-002, ...)
+- Examples: `REQ-F-001: User can log in with Discord OAuth`, `REQ-NF-001: Page loads in <2s on 4G`
 
 Each requirement must be:
 - **User-centric** — describes a capability from the user's perspective
@@ -561,7 +560,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
@@ -589,7 +588,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:**
 ```
@@ -635,7 +634,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
@@ -649,7 +648,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
@@ -663,28 +662,13 @@ Write the project state files from templates:
 **CRITICAL (no hook): Write CONTEXT.md NOW. Do NOT skip this step.**
 
 **9c. Write CONTEXT.md:**
-Create `.planning/CONTEXT.md` from information gathered during questioning:
-
-```markdown
-# Project Context
-
-## Locked Decisions
-{Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE}
-
-| Decision | Rationale | Locked By |
-|----------|-----------|-----------|
-| {e.g., "Use TypeScript"} | {User preference, team skill} | User |
-
-## User Constraints
-{Budget, timeline, skill level, hosting, team size}
-
-## Deferred Ideas
-{Features explicitly moved to v2 or out-of-scope}
-
-| Idea | Reason Deferred |
-|------|----------------|
-| {feature} | {reason} |
-```
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from the questioning conversation:
+   - Locked Decisions: all technology choices and architecture decisions from Step 2
+   - User Constraints: budget, timeline, skill level, hosting, team
+   - Deferred Ideas: out-of-scope items identified in Step 7c scoping
+   - Claude's Discretion: any areas where user said "you decide"
+3. Write to `.planning/CONTEXT.md`
 
 **CRITICAL (no hook): Write HISTORY.md NOW. Do NOT skip this step.**
 

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