claude-dev-env 2.4.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,6 +15,7 @@ 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 |
@@ -22,7 +23,7 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 
 ## 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

@@ -2,7 +2,6 @@
 name: code-verifier
 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
 ---
 

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/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"
+    )