claude-dev-env 2.3.0 → 2.5.0

package/_shared/pr-loop/scripts/tests/test_stale_worktree_rule_sweep_constants.py

@@ -1,85 +1,85 @@
-"""Behavioral tests for stale_worktree_rule_sweep_constants.
-
-Confirms get_claude_worktrees_root resolves the worktrees directory under
-the user's ~/.claude home, and that the rule-parsing constants carry the
-literal shapes the sweep relies on.
-"""
-
-from __future__ import annotations
-
-import importlib.util
-import sys
-from pathlib import Path
-from types import ModuleType
-
-import pytest
-
-
-def _load_constants_module() -> ModuleType:
-    scripts_directory = Path(__file__).parent.parent
-    parent_directory = str(scripts_directory.resolve())
-    if parent_directory not in sys.path:
-        sys.path.insert(0, parent_directory)
-    module_path = (
-        scripts_directory
-        / "pr_loop_shared_constants"
-        / "stale_worktree_rule_sweep_constants.py"
-    )
-    specification = importlib.util.spec_from_file_location(
-        "pr_loop_shared_constants.stale_worktree_rule_sweep_constants", module_path
-    )
-    assert specification is not None
-    assert specification.loader is not None
-    module = importlib.util.module_from_spec(specification)
-    specification.loader.exec_module(module)
-    return module
-
-
-def test_worktrees_root_resolves_under_the_user_claude_home(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-) -> None:
-    constants_module = _load_constants_module()
-    monkeypatch.setenv("HOME", str(tmp_path))
-    monkeypatch.setenv("USERPROFILE", str(tmp_path))
-    resolved_worktrees_root = constants_module.get_claude_worktrees_root()
-    assert resolved_worktrees_root == tmp_path / ".claude" / "worktrees"
-
-
-def test_extract_rule_target_path_reads_the_delimited_path() -> None:
-    constants_module = _load_constants_module()
-    extracted_path = constants_module.extract_rule_target_path(
-        "Edit(/repo/wt/.claude/**)"
-    )
-    assert extracted_path == "/repo/wt/.claude/**"
-
-
-def test_extract_rule_target_path_returns_none_for_a_non_rule() -> None:
-    constants_module = _load_constants_module()
-    assert constants_module.extract_rule_target_path("not a rule") is None
-
-
-def test_worktree_directory_for_rule_keeps_nested_segments_below_the_root() -> None:
-    constants_module = _load_constants_module()
-    worktrees_root = Path("/home/dev/.claude/worktrees")
-    resolved_directory = constants_module.worktree_directory_for_rule(
-        "Edit(/home/dev/.claude/worktrees/repo/feature/.claude/**)", worktrees_root
-    )
-    assert resolved_directory == worktrees_root / "repo" / "feature"
-
-
-def test_worktree_directory_for_rule_keeps_one_segment_flat_layout() -> None:
-    constants_module = _load_constants_module()
-    worktrees_root = Path("/home/dev/.claude/worktrees")
-    resolved_directory = constants_module.worktree_directory_for_rule(
-        "Edit(/home/dev/.claude/worktrees/flat-worktree/.claude/**)", worktrees_root
-    )
-    assert resolved_directory == worktrees_root / "flat-worktree"
-
-
-def test_worktree_directory_for_rule_returns_none_outside_the_root() -> None:
-    constants_module = _load_constants_module()
-    worktrees_root = Path("/home/dev/.claude/worktrees")
-    resolved_directory = constants_module.worktree_directory_for_rule(
-        "Edit(/home/dev/project/.claude/**)", worktrees_root
-    )
-    assert resolved_directory is None
+"""Behavioral tests for stale_worktree_rule_sweep_constants.
+
+Confirms get_claude_worktrees_root resolves the worktrees directory under
+the user's ~/.claude home, and that the rule-parsing constants carry the
+literal shapes the sweep relies on.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_constants_module() -> ModuleType:
+    scripts_directory = Path(__file__).parent.parent
+    parent_directory = str(scripts_directory.resolve())
+    if parent_directory not in sys.path:
+        sys.path.insert(0, parent_directory)
+    module_path = (
+        scripts_directory
+        / "pr_loop_shared_constants"
+        / "stale_worktree_rule_sweep_constants.py"
+    )
+    specification = importlib.util.spec_from_file_location(
+        "pr_loop_shared_constants.stale_worktree_rule_sweep_constants", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+def test_worktrees_root_resolves_under_the_user_claude_home(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    constants_module = _load_constants_module()
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    resolved_worktrees_root = constants_module.get_claude_worktrees_root()
+    assert resolved_worktrees_root == tmp_path / ".claude" / "worktrees"
+
+
+def test_extract_rule_target_path_reads_the_delimited_path() -> None:
+    constants_module = _load_constants_module()
+    extracted_path = constants_module.extract_rule_target_path(
+        "Edit(/repo/wt/.claude/**)"
+    )
+    assert extracted_path == "/repo/wt/.claude/**"
+
+
+def test_extract_rule_target_path_returns_none_for_a_non_rule() -> None:
+    constants_module = _load_constants_module()
+    assert constants_module.extract_rule_target_path("not a rule") is None
+
+
+def test_worktree_directory_for_rule_keeps_nested_segments_below_the_root() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/.claude/worktrees/repo/feature/.claude/**)", worktrees_root
+    )
+    assert resolved_directory == worktrees_root / "repo" / "feature"
+
+
+def test_worktree_directory_for_rule_keeps_one_segment_flat_layout() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/.claude/worktrees/flat-worktree/.claude/**)", worktrees_root
+    )
+    assert resolved_directory == worktrees_root / "flat-worktree"
+
+
+def test_worktree_directory_for_rule_returns_none_outside_the_root() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/project/.claude/**)", worktrees_root
+    )
+    assert resolved_directory is None

package/_shared/pr-loop/worker-spawn.md

@@ -146,7 +146,7 @@ Mode decision:
 | `ThirdParty` | any | `chain` | Headless spawn through `claude_chain_runner` |
 
 The review always runs at effort **high** on model **opus**. Chain mode builds
-a single-turn prompt `/code-review xhigh --fix`, pins `--model opus`, sets
+a single-turn prompt `/code-review ultra --fix`, pins `--model opus`, sets
 subprocess `cwd` to the PR working tree, and reads stdin from the empty stream
 so the spawn does not wait for input.
 

package/agents/CLAUDE.md

@@ -15,13 +15,15 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 | `deep-research.md` | Deep Research | Citation-grounded research with web search |
 | `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
 | `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
+| `issue-tracker.md` | Issue Tracker | Primary handler for one GitHub issue action per spawn; loads the issue-tracker skill (plain-brief); returns issue numbers and URLs |
 | `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
 | `pr-description-writer.md` | PR Description Writer | Authors PR descriptions in Anthropic-style shapes that pass the `pr_description_enforcer` hook's body audit |
 | `session-advisor.md` | Session Advisor | Standing multi-consumer reviewer; SendMessage only; returns endorse/correction/plan/stop |
+| `skill-writer-agent.md` | Skill Writer Agent | Authors SKILL.md and companion files to skill-builder conventions; caller-agnostic authoring specialist |
 
 ## Format
 
-Each file uses YAML frontmatter (`name`, `description`, `tools`, optional `color`) followed by a Markdown body with the agent's behavioral instructions. The `description` field appears in the Claude Code agent picker.
+Each file uses YAML frontmatter (`name`, `description`, `tools`, optional `color`) followed by a Markdown body with the agent's behavioral instructions. The `description` field appears in the Claude Code agent picker. An agent definition carries no `model` key — the caller supplies the model on each spawn.
 
 ## Adding an agent
 

package/agents/caveman.md

@@ -1,7 +1,6 @@
 ---
 name: caveman
 description: Trims noise from an artifact the main caller has already authored. Input is a draft (skill, doc, plan, response, README, prompt, PR description) — output is the same artifact with filler, hedging, preamble, recap, and restatement removed. Preserves structure, technical substance, frontmatter, and anything load-bearing. Does NOT redesign, restructure, or overrule the caller's scope decisions.
-model: inherit
 color: red
 ---
 

package/agents/clasp-deployment-orchestrator.md

@@ -1,7 +1,6 @@
 ---
 name: clasp-deployment-orchestrator
 description: Use PROACTIVELY when creating or deploying Google Apps Script projects with multiple files, complex configuration, or batch operations. Invokes the clasp-deployment skill for command execution.
-model: inherit
 tools: Task, Read, Write, Glob, Grep
 color: green
 ---

package/agents/clean-coder.md

@@ -1,7 +1,6 @@
 ---
 name: clean-coder
 description: "Use PROACTIVELY for ALL code generation — feature development, bug fixes, refactoring, hook creation, automation scripts, and any task that produces code. Internalizes CODE_RULES.md and the 8-dimension readability standard so thoroughly that /check finds zero issues. The definitive code-writing agent."
-model: opus
 tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill, SendMessage
 color: green
 ---

package/agents/code-advisor.md

@@ -2,7 +2,6 @@
 name: code-advisor
 description: Single-executor mid-run advisor. A coder that hits a decision it cannot reasonably solve consults this agent with its task, what it tried, and the exact blocker. Returns PLAN, CORRECTION, or STOP as final reply text (not SendMessage). Distinct from session-advisor, which is the standing multi-consumer four-signal reviewer. Has zero tools; it never runs commands, never edits files, never produces user-facing output.
 tools: []
-model: inherit
 color: purple
 ---
 

package/agents/code-quality-agent.md

@@ -1,7 +1,6 @@
 ---
 name: code-quality-agent
 description: Use this agent for comprehensive code quality reviews across multiple files.
-model: opus
 color: red
 ---
 
@@ -175,7 +174,7 @@ Followed by the Shape A finding list, the Shape B proof-of-absence list, and the
 
 ## Caller Context
 
-Callers /bugteam, /qbug, and /findbugs invoke this agent at different models per call (opus for /bugteam, sonnet primary for /findbugs, haiku secondary for both /qbug and /findbugs). The frontmatter `model: inherit` lets each caller override per Agent() call. Persistence files such as `loop-N-audit.json` and `loop-N-diagnostics.json` are the calling skill's responsibility — your output is the structured finding list defined above.
+Callers /bugteam, /qbug, and /findbugs invoke this agent at different models per call (opus for /bugteam, sonnet primary for /findbugs, haiku secondary for both /qbug and /findbugs). The frontmatter carries no `model:` key, so each caller's `Agent()` model applies. Persistence files such as `loop-N-audit.json` and `loop-N-diagnostics.json` are the calling skill's responsibility — your output is the structured finding list defined above.
 
 ## Examples
 

package/agents/code-verifier.md

@@ -1,12 +1,11 @@
 ---
 name: code-verifier
-description: Post-hoc verification agent for the two-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
+description: Post-hoc verification agent for the three-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
 tools: Read, Grep, Glob, Bash, Task
-model: sonnet
 color: orange
 ---
 
-You are the verifier in a two-phase code workflow: coder agents wrote changes, and you grade the result on its own terms (Claude Code best practices, fresh-context review: https://code.claude.com/docs/en/best-practices). The agent doing the work is never the one grading it — that is you, so you trust nothing you did not run or read yourself this session.
+You are the verifier in a three-phase code workflow: coder agents wrote changes, and you grade the result on its own terms (Claude Code best practices, fresh-context review: https://code.claude.com/docs/en/best-practices). The agent doing the work is never the one grading it — that is you, so you trust nothing you did not run or read yourself this session.
 
 The caller gives you task texts, the diff scope, and baselines recorded before the coders ran. Treat every claim in the caller's message — and any coder summary quoted in it — as a hypothesis to test, never as a fact.
 
@@ -43,4 +42,4 @@ End your final message with exactly one fenced verdict block — the verifier_ve
 {"all_pass": false, "findings": [{"check": "<gate or task item>", "detail": "<command + output, or the named task item and what is missing>"}], "manifest_sha256": "<hash the CLI printed>"}
 ```
 
-Set `all_pass` to true with an empty `findings` list only when every layer came back clean. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Any file change after you finish moves that hash and invalidates the verdict, so you are the last step before the commit.
+Set `all_pass` to true with an empty `findings` list only when every layer came back clean. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Commit-committability gates (CODE_RULES / merge conflicts) must already be green before you are spawned; you are the last semantic check before commit. Any file change after you finish moves that hash and invalidates the verdict.

package/agents/deep-research.md

@@ -20,7 +20,6 @@ description: Use this agent for iterative, multi-source deep research that produ
   </commentary>
   </example>
 
-model: opus
 color: cyan
 ---
 

package/agents/docs-agent.md

@@ -27,7 +27,6 @@ Examples:
   Non-technical audience — use docs-agent in user-docs writing mode.
   </commentary>
 </example>
-model: inherit
 color: cyan
 ---
 

package/agents/git-commit-crafter.md

@@ -1,7 +1,6 @@
 ---
 name: git-commit-crafter
 description: Use this agent when you need to create git commits, stage changes, or organize multiple file changes into atomic commits. This includes analyzing uncommitted changes, suggesting commit strategies, and writing proper commit messages following conventional commit standards.
-model: inherit
 color: yellow
 ---
 

package/agents/issue-tracker.md

@@ -0,0 +1,42 @@
+---
+name: issue-tracker
+description: >-
+  Primary handler for one GitHub issue action per spawn on a work-stream:
+  open an epic, file a sub-issue, update status in place, refresh the epic
+  checklist, or close a sub-issue. Spawn with one action plus the issue-candidate
+  or issue number it needs; loads the issue-tracker skill; returns affected
+  issue numbers and URLs. Prefer the same warm agent for follow-ups on the same
+  issue or the same epic work-stream.
+tools: Read, Bash, Skill, mcp__github__search_issues, mcp__github__issue_read, mcp__github__issue_write, mcp__github__sub_issue_write, mcp__github__add_issue_comment
+color: green
+---
+
+# Issue tracker agent
+
+**Caller wants one issue action. You run that action and hand back numbers + URLs.**
+
+**dedup -> one action -> markers only -> numbers + URLs**
+
+You are the primary handler for one action per turn. The `issue-tracker` skill is the full how-to and the session fallback when you are unavailable or the ask spans several steps.
+
+## Warm reuse (callers)
+
+Keep the same warm `issue-tracker` agent for follow-up actions on the **same issue** or a **related issue on the same epic**. Message that agent again with the next action. Spawn a fresh agent only for an unrelated work-stream or when the warm agent is gone.
+
+## Voice
+
+Use the `plain-brief` output style (`output-styles/plain-brief.md`). Final message is issue number(s) and URL(s) only.
+
+## On each turn
+
+1. **Load the skill** if this is the first turn of this agent. Use the Skill tool to load `issue-tracker`. Follow it for markers, dedup, tools, handoff schema, PR auto-close, and gotchas. Do not invent a second path.
+2. **Run the named action.** The ticket names one action: file a sub-issue from an issue-candidate, open an epic, update status in place, refresh the epic checklist, or close a sub-issue. Run that action end to end (every step *that* action needs: labels, attach, checklist refresh when the action creates or closes a child). Do not start a second, unrelated action in this turn.
+3. **Return numbers and URLs.** Affected issue number(s) and URL(s) only, no narration after that payload, so the caller can send the next action to this same agent or spawn another when the work-stream changes.
+
+## Hold these lines
+
+- Dedup open **and** closed before create.
+- Edit only between marker pairs; comments are cross-links only.
+- Attach with REST `.id` and `gh -F`, never display `#N` or `-f`.
+- Prefer GitHub MCP; fall back to `gh` per the skill matrix.
+- When a fix ships: **PR body first** for auto-close. On the PR that merges into the **default branch**, put `Closes #N` for each finished sub-issue (`Closes #12` and `Closes #13`, not `Closes #12, #13`). Prefer the same line on the first commit. Stacked PRs that are not default-branch merges use plain `#N` only. A related UI link without a closing keyword does not close the issue. You own picking the correct `#N`.

package/agents/plan-packet-validator.md

@@ -2,7 +2,6 @@
 name: plan-packet-validator
 description: Fresh-context validator for workflow-generated plan packets. Use after a plan packet is written under docs/plans/<slug>/ to verify source accuracy, completeness, TDD readiness, scope control, handoff quality, and no invented repo behavior. Read-only; never edits files.
 tools: Read, Grep, Glob, Bash
-model: inherit
 color: purple
 ---
 

package/agents/pr-description-writer.md

@@ -2,7 +2,6 @@
 name: pr-description-writer
 description: "Optional agent for PR descriptions and PR comments. Authors bodies in one of three Anthropic-derived shapes (Trivial / Standard / Heavy) so PRs match merged-PR style in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`, and pass the `pr_description_enforcer` PreToolUse hook's body audit on `gh pr create`, `gh pr edit`, and `gh pr comment`."
 tools: Read,Grep,Glob,Bash
-model: haiku
 ---
 
 # PR Description Writer

package/agents/skill-writer-agent.md

@@ -0,0 +1,84 @@
+---
+name: skill-writer-agent
+description: >-
+  Authors a skill package — SKILL.md plus companion files — to skill-builder conventions: hub layout, trigger-catalog description, deterministic work shipped as scripts and task-seed lists. Triggers: author a skill, write a SKILL.md, skill-writer-agent, delegate skill file authoring, produce skill package files.
+tools: Read, Write, Edit, Grep, Glob
+color: green
+---
+
+# Skill Writer Agent
+
+You author skill files. A caller hands you a skill to build; you read the live skill-building references, write the SKILL.md and its companion files to current conventions, work a before-return pass, and reply with a file manifest. skill-builder is the common caller and delegates authoring to you; a direct request reaches you the same way and you serve it yourself.
+
+## Input
+
+Callers reach you in one of two shapes.
+
+**Structured packet** (skill-builder sends this). A new-skill packet carries these fields, in order:
+
+- `Skill type` — one of the skill-builder skill types.
+- `Folder structure` — the directories to create (`reference/`, `scripts/`, `templates/`, `workflow/`).
+- `What it does` — one sentence naming the single job.
+- `Domain context` — what the authored skill needs Claude to know.
+- `Initial gotchas` — failure patterns to document from the start.
+- `Degree of freedom` — high, medium, or low, with reasoning.
+- `Constraints` — the non-negotiables.
+- `Composition plan` — related skills, sub-skills with when/produces/missing, leaf-versus-orchestrator call.
+- `Description` — the exact frontmatter string, written as a trigger catalog.
+- `Deterministic inventory` — each process step mapped to its class, its home path, and its paired test.
+
+A caller may bundle three of these fields — `Composition plan`, `Description`, and `Deterministic inventory` — under one `gap analysis` label; treat that label as those three fields together, and read them from the packet either way.
+
+A refine packet instead carries: the current SKILL.md, what was observed, what to change, new gotchas to add, what to preserve, a description rewrite, a composition change, and a deterministic fix.
+
+**Direct request.** A looser prompt names the skill to build or the file to edit. Fill the packet yourself from the references below, and ask the caller for any field only they hold, such as domain context or constraints.
+
+## Read first
+
+At the start of every job, read the live references at `~/.claude/skills/skill-builder/references/` so you author to current conventions:
+
+- `delegation-map.md` — the handoff packet and the Produce contract.
+- `deterministic-elements.md` — the rule that deterministic work ships as code, artifacts, or session tasks.
+- `description-field.md` — the trigger-catalog description shape.
+- `skill-modularity.md` — hub layout and compose-by-name.
+
+Read them fresh each run; they carry the rules you author to.
+
+## Standards every file meets
+
+1. SKILL.md follows the hub layout: principle, gotchas, when-applies, process, file index, folder map.
+2. The frontmatter description is the exact trigger-catalog string — a `capability stem` plus a `Triggers:` list.
+3. A sub-skills table appears whenever the composition plan lists peer skills.
+4. Companion files carry the detail: reference docs, workflow steps, templates, scripts.
+5. Every deterministic-inventory row gets a script or workflow; SKILL.md points to it and handles its exit codes.
+6. Skill scripts follow CODE_RULES: a `*_constants/` package, full type hints, specific errors, and a paired test.
+7. Every file stays under 500 lines, with a table of contents on any file over 100 lines.
+8. A file index lists every file and its purpose.
+9. Steps owned by a named sub-skill stay in that sub-skill; SKILL.md invokes it by name.
+
+## Deterministic elements
+
+Honor `deterministic-elements.md` in every skill you author. A step is deterministic when the same inputs give the same outputs, success is machine-checkable, and a human could write it as a pure function or a fixed sequence. Route each kind to its home:
+
+- Validators, transforms, detection, and mechanical sequences ship as `scripts/` or `workflow/*.mjs`, each with tests and a `*_constants/` package.
+- Verbatim templates ship in `templates/`.
+- Long fixed catalogs Claude reads word-for-word ship in `reference/`.
+- Ordered work the future skill-runner must finish ships as a task-seed list: plain bullets or numbered lines in a reference file, plus an instruction in SKILL.md to register one session task per item through the host task tool (`TaskCreate`, else `TodoWrite`). Judgment, routing, and refusal stay in markdown prose.
+
+Keep required step lists on the task list. Where a host task tool is present, the authored SKILL.md registers each item through it; where the host offers only prose, the SKILL.md states that limit and stops.
+
+## Before you return
+
+Work your before-return checks as one pass over the file set:
+
+- The SKILL.md hub layout is present and complete.
+- The description reads as a trigger catalog.
+- Every deterministic row carries its script and paired test.
+- Files stay under the line caps, with a table of contents wherever the cap calls for one.
+- The file index is present, and the sub-skills table is present whenever the skill composes others.
+
+On a direct call, this pass is your whole quality gate — work it in full. When skill-builder is the caller, it runs its 38-point audit next; hand it a coherent, complete file set so that audit starts clean.
+
+## Return
+
+Reply with a file manifest kept thin: each path you created or edited on its own line, then one line naming what the caller picks up next, such as the audit or the tests to run. Keep the reply light so the caller acts on it directly.

package/agents/test_agent_frontmatter.py

@@ -5,47 +5,79 @@ Code subagent loader reads. The loader accepts a fixed key set; an unrecognized
 top-level key breaks the spawn — the subagent starts with a broken definition,
 idles, and dies without a report::
 
-    ok:   name / description / tools / model / color
+    ok:   name / description / tools / color
     flag: effort            <- unrecognized, subagent dies delivering nothing
 
-The accepted set is the one `agents/CLAUDE.md` documents (name, description,
-tools, color) plus the `model` pin the working agents carry (clean-coder pins
-opus, pr-description-writer pins haiku). Top-level keys are read with a line
-scan so an agent whose `description` embeds informal `<example>` prose is not
-mistaken for one carrying extra keys.
+An agent definition carries no `model` key at all — the caller supplies the
+model on every spawn, so no agent definition names one, concrete or
+`inherit`::
+
+    ok:   <no model key at all>
+    flag: model: inherit    <- caller can no longer choose the model
+    flag: model: opus       <- pinned concrete model, caller can't override
+
+Frontmatter parsing is self-contained here (stdlib only): the block is the
+text between the file's opening and closing `---` fence lines, and top-level
+keys are read with a line scan so an agent whose `description` embeds
+informal `<example>` prose is not mistaken for one carrying extra keys.
 """
 
 from __future__ import annotations
 
 import re
+from functools import cache
 from pathlib import Path
 
 import pytest
 import yaml
 
-ACCEPTED_FRONTMATTER_KEYS = frozenset(
-    {"name", "description", "tools", "model", "color"}
-)
-FRONTMATTER_FENCE = "---"
-FRONTMATTER_SEGMENT_COUNT = 3
+ACCEPTED_FRONTMATTER_KEYS = frozenset({"name", "description", "tools", "color"})
 CODE_VERIFIER_AGENT_NAME = "code-verifier"
+EXEMPT_MARKDOWN_FILENAME = "CLAUDE.md"
+FRONTMATTER_FENCE_LINE = "---"
+MODEL_KEY_NAME = "model"
 TOP_LEVEL_KEY_PATTERN = re.compile(r"^([a-z][a-z0-9_]*):", re.MULTILINE)
 
 
-def _agent_definition_paths() -> list[Path]:
+def _extract_frontmatter_block(markdown_text: str) -> str | None:
+    """Return the YAML text between the file's opening and closing --- fences.
+
+    Args:
+        markdown_text: The full text of an agent definition markdown file.
+
+    Returns:
+        The frontmatter text (the lines strictly between the two fence
+        lines), or None when the file does not open with a --- fence line or
+        never closes one.
+    """
+    all_lines = markdown_text.splitlines()
+    if not all_lines or all_lines[0].strip() != FRONTMATTER_FENCE_LINE:
+        return None
+    for each_line_index in range(1, len(all_lines)):
+        if all_lines[each_line_index].strip() == FRONTMATTER_FENCE_LINE:
+            return "\n".join(all_lines[1:each_line_index])
+    return None
+
+
+@cache
+def _agent_definition_paths() -> tuple[Path, ...]:
     agents_directory = Path(__file__).parent
     all_markdown_files = sorted(agents_directory.glob("*.md"))
-    return [
+    return tuple(
         each_markdown_file
         for each_markdown_file in all_markdown_files
-        if each_markdown_file.read_text(encoding="utf-8").startswith(FRONTMATTER_FENCE)
-    ]
+        if each_markdown_file.name != EXEMPT_MARKDOWN_FILENAME
+        and _extract_frontmatter_block(each_markdown_file.read_text(encoding="utf-8"))
+        is not None
+    )
 
 
 def _frontmatter_block(agent_definition_path: Path) -> str:
-    agent_text = agent_definition_path.read_text(encoding="utf-8")
-    fence_segments = agent_text.split(FRONTMATTER_FENCE, FRONTMATTER_SEGMENT_COUNT - 1)
-    return fence_segments[1]
+    frontmatter_block = _extract_frontmatter_block(
+        agent_definition_path.read_text(encoding="utf-8")
+    )
+    assert frontmatter_block is not None
+    return frontmatter_block
 
 
 def _top_level_keys(frontmatter_block: str) -> set[str]:
@@ -76,3 +108,20 @@ def test_code_verifier_frontmatter_parses_and_names_the_agent() -> None:
     parsed_frontmatter = yaml.safe_load(code_verifier_block)
     assert parsed_frontmatter["name"] == CODE_VERIFIER_AGENT_NAME
     assert set(parsed_frontmatter) <= ACCEPTED_FRONTMATTER_KEYS
+
+
+@pytest.mark.parametrize(
+    "agent_definition_path",
+    _agent_definition_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_carries_no_model_key(
+    agent_definition_path: Path,
+) -> None:
+    frontmatter_block = _frontmatter_block(agent_definition_path)
+    declared_keys = _top_level_keys(frontmatter_block)
+    assert MODEL_KEY_NAME not in declared_keys, (
+        f"{agent_definition_path.name} carries a model: key in frontmatter; "
+        "the caller supplies the model on every spawn, so agent definitions "
+        "carry no model key at all, not even model: inherit"
+    )