claude-dev-env 1.90.0 → 1.92.0

package/scripts/test_claude_chain_runner.py

@@ -0,0 +1,472 @@
+"""Behavioral tests for the claude fallback-chain runner."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import claude_chain_runner as runner  # noqa: E402
+from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
+    ALL_USAGE_LIMIT_SIGNATURES,
+    ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
+    ATTEMPT_STATUS_NONZERO_EXIT,
+    ATTEMPT_STATUS_SERVED,
+    ATTEMPT_STATUS_TIMEOUT,
+    ATTEMPT_STATUS_USAGE_LIMITED,
+    ATTEMPT_SUMMARY_ENTRY_TEMPLATE,
+    ATTEMPT_SUMMARY_JOIN_SEPARATOR,
+    CHAIN_CONFIG_ERROR_EXIT_CODE,
+    CHAIN_EXHAUSTED_EXIT_CODE,
+    CHAIN_EXHAUSTED_MESSAGE_TEMPLATE,
+    CLAUDE_HOME_SUBDIRECTORY,
+    CLI_ARGUMENTS_SEPARATOR,
+    CLI_TIMEOUT_FLAG,
+    CONFIG_CHAIN_EMPTY_REASON,
+    CONFIG_CHAIN_KEY,
+    CONFIG_CHAIN_NOT_LIST_REASON,
+    CONFIG_COMMAND_KEY,
+    CONFIG_ENTRY_COMMAND_MISSING_REASON,
+    CONFIG_ENTRY_EXTRA_ARGS_INVALID_REASON,
+    CONFIG_ENTRY_NOT_OBJECT_REASON,
+    CONFIG_EXTRA_ARGS_KEY,
+    CONFIG_FILENAME,
+    CONFIG_INVALID_SHAPE_MESSAGE_TEMPLATE,
+    CONFIG_MALFORMED_MESSAGE_TEMPLATE,
+    CONFIG_MISSING_MESSAGE_TEMPLATE,
+    CONFIG_NOT_OBJECT_REASON,
+    CONFIG_UNREADABLE_MESSAGE_TEMPLATE,
+    DEFAULT_TIMEOUT_SECONDS,
+    EXAMPLE_CONFIG_FILENAME,
+    NO_COMPLETED_PROCESS_RETURN_CODE,
+    UTF8_ENCODING,
+)
+
+_A_SIGNATURE = ALL_USAGE_LIMIT_SIGNATURES[0]
+_PROMPT_ARGUMENTS = ["-p", "hello"]
+
+
+def _completed(command, returncode, stdout="", stderr=""):
+    return subprocess.CompletedProcess(
+        args=[command], returncode=returncode, stdout=stdout, stderr=stderr
+    )
+
+
+def _entry(command, extra_args=None):
+    return {
+        CONFIG_COMMAND_KEY: command,
+        CONFIG_EXTRA_ARGS_KEY: extra_args if extra_args is not None else [],
+    }
+
+
+def _write_chain_config(tmp_path, chain_entries):
+    config_file = tmp_path / CONFIG_FILENAME
+    config_file.write_text(
+        json.dumps({CONFIG_CHAIN_KEY: chain_entries}), encoding=UTF8_ENCODING
+    )
+    return config_file
+
+
+class _Recorder:
+    def __init__(self, behavior_by_command):
+        self.behavior_by_command = behavior_by_command
+        self.invocations = []
+        self.timeouts = []
+
+    def __call__(self, invocation, **keyword_arguments):
+        self.invocations.append(invocation)
+        self.timeouts.append(keyword_arguments.get("timeout"))
+        behavior = self.behavior_by_command[invocation[0]]
+        if isinstance(behavior, BaseException):
+            raise behavior
+        return behavior
+
+
+def _install(monkeypatch, config_file, behavior_by_command):
+    recorder = _Recorder(behavior_by_command)
+    monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    monkeypatch.setattr(runner, "chain_subprocess_runner", recorder)
+    return recorder
+
+
+def test_usage_limited_primary_falls_over_to_second(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 1, stderr=_A_SIGNATURE),
+            "claude-ev": _completed("claude-ev", 0, stdout="ok"),
+        },
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude-ev"
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "ok"
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude",
+        "claude-ev",
+    ]
+    assert chain_result.attempts[0].status == ATTEMPT_STATUS_USAGE_LIMITED
+    assert chain_result.attempts[1].status == ATTEMPT_STATUS_SERVED
+
+
+def test_nonzero_exit_without_signature_does_not_fall_over(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 2, stderr="unknown flag"),
+            "claude-ev": _completed("claude-ev", 0, stdout="should not run"),
+        },
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude"
+    assert chain_result.returncode == 2
+    assert len(chain_result.attempts) == 1
+    assert chain_result.attempts[0].status == ATTEMPT_STATUS_NONZERO_EXIT
+
+
+def test_timeout_on_primary_does_not_fall_over(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": subprocess.TimeoutExpired(cmd=["claude"], timeout=5),
+            "claude-ev": _completed("claude-ev", 0),
+        },
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command is None
+    assert chain_result.returncode == NO_COMPLETED_PROCESS_RETURN_CODE
+    assert len(chain_result.attempts) == 1
+    assert chain_result.attempts[0].status == ATTEMPT_STATUS_TIMEOUT
+
+
+def test_missing_primary_binary_does_not_fall_over(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": FileNotFoundError(),
+            "claude-ev": _completed("claude-ev", 0),
+        },
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command is None
+    assert len(chain_result.attempts) == 1
+    assert chain_result.attempts[0].status == ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND
+
+
+def test_missing_fallback_binary_is_skipped_and_walk_continues(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path, [_entry("claude"), _entry("claude-ev"), _entry("claude-editor")]
+    )
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 1, stderr=_A_SIGNATURE),
+            "claude-ev": FileNotFoundError(),
+            "claude-editor": _completed("claude-editor", 0, stdout="done"),
+        },
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude-editor"
+    assert [each_attempt.status for each_attempt in chain_result.attempts] == [
+        ATTEMPT_STATUS_USAGE_LIMITED,
+        ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
+        ATTEMPT_STATUS_SERVED,
+    ]
+
+
+def test_zero_exit_mentioning_usage_limit_is_success(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 0, stdout=f"note: {_A_SIGNATURE} earlier"),
+            "claude-ev": _completed("claude-ev", 0),
+        },
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude"
+    assert chain_result.returncode == 0
+    assert len(chain_result.attempts) == 1
+    assert chain_result.attempts[0].status == ATTEMPT_STATUS_SERVED
+
+
+def test_exhausted_chain_records_every_attempt(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 1, stderr=_A_SIGNATURE),
+            "claude-ev": _completed("claude-ev", 1, stderr=_A_SIGNATURE),
+        },
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command is None
+    assert chain_result.returncode == 1
+    assert [each_attempt.status for each_attempt in chain_result.attempts] == [
+        ATTEMPT_STATUS_USAGE_LIMITED,
+        ATTEMPT_STATUS_USAGE_LIMITED,
+    ]
+
+
+def test_reordering_config_changes_walk_order(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    behavior_by_command = {
+        "claude": _completed("claude", 0, stdout="from-claude"),
+        "claude-ev": _completed("claude-ev", 0, stdout="from-ev"),
+    }
+    first_config = tmp_path / "first"
+    first_config.mkdir()
+    config_a = _write_chain_config(
+        first_config, [_entry("claude"), _entry("claude-ev")]
+    )
+    _install(monkeypatch, config_a, behavior_by_command)
+    result_a = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert result_a.served_command == "claude"
+
+    second_config = tmp_path / "second"
+    second_config.mkdir()
+    config_b = _write_chain_config(
+        second_config, [_entry("claude-ev"), _entry("claude")]
+    )
+    _install(monkeypatch, config_b, behavior_by_command)
+    result_b = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert result_b.served_command == "claude-ev"
+
+
+def test_extra_args_are_appended_to_invocation(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path, [_entry("claude", extra_args=["--account", "ev"])]
+    )
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert recorder.invocations[0] == ["claude", "-p", "hello", "--account", "ev"]
+
+
+def test_signature_matching_is_case_insensitive(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 1, stderr=_A_SIGNATURE.upper()),
+            "claude-ev": _completed("claude-ev", 0),
+        },
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude-ev"
+
+
+def test_cli_passthrough_builds_argument_list_and_timeout(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    exit_code = runner.main(
+        [CLI_TIMEOUT_FLAG, "9", CLI_ARGUMENTS_SEPARATOR, "-p", "hi"]
+    )
+    assert exit_code == 0
+    assert recorder.invocations[0] == ["claude", "-p", "hi"]
+    assert recorder.timeouts[0] == 9
+
+
+def test_cli_uses_default_timeout_when_flag_omitted(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
+    assert recorder.timeouts[0] == DEFAULT_TIMEOUT_SECONDS
+
+
+def test_cli_served_nonzero_exit_is_passed_through(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    _install(
+        monkeypatch,
+        config_file,
+        {"claude": _completed("claude", 7, stdout="out", stderr="err")},
+    )
+    exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
+    captured = capsys.readouterr()
+    assert exit_code == 7
+    assert captured.out == "out"
+    assert "err" in captured.err
+
+
+def test_cli_exhausted_chain_exits_nonzero_with_attempt_summary(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 1, stderr=_A_SIGNATURE),
+            "claude-ev": _completed("claude-ev", 1, stderr=_A_SIGNATURE),
+        },
+    )
+    exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
+    captured = capsys.readouterr()
+    assert exit_code == CHAIN_EXHAUSTED_EXIT_CODE
+    expected_summary = ATTEMPT_SUMMARY_JOIN_SEPARATOR.join(
+        ATTEMPT_SUMMARY_ENTRY_TEMPLATE.format(
+            command=each_command, status=ATTEMPT_STATUS_USAGE_LIMITED
+        )
+        for each_command in ("claude", "claude-ev")
+    )
+    assert (
+        CHAIN_EXHAUSTED_MESSAGE_TEMPLATE.format(attempt_summary=expected_summary)
+        in captured.err
+    )
+
+
+def test_cli_missing_config_exits_config_error(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    missing_config = tmp_path / CONFIG_FILENAME
+    monkeypatch.setattr(runner, "chain_config_path", lambda: missing_config)
+    exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
+    captured = capsys.readouterr()
+    assert exit_code == CHAIN_CONFIG_ERROR_EXIT_CODE
+    assert EXAMPLE_CONFIG_FILENAME in captured.err
+
+
+def test_missing_config_raises_naming_path_and_example(tmp_path: Path) -> None:
+    missing_config = tmp_path / CONFIG_FILENAME
+    with pytest.raises(runner.ChainConfigurationError) as raised:
+        runner.load_chain(missing_config)
+    assert str(raised.value) == CONFIG_MISSING_MESSAGE_TEMPLATE.format(
+        config_path=missing_config, example_filename=EXAMPLE_CONFIG_FILENAME
+    )
+
+
+def test_malformed_json_raises_configuration_error(tmp_path: Path) -> None:
+    config_file = tmp_path / CONFIG_FILENAME
+    config_file.write_text("{ not valid json", encoding=UTF8_ENCODING)
+    with pytest.raises(runner.ChainConfigurationError) as raised:
+        runner.load_chain(config_file)
+    malformed_prefix = CONFIG_MALFORMED_MESSAGE_TEMPLATE.split("{config_path}")[0]
+    assert malformed_prefix in str(raised.value)
+    assert EXAMPLE_CONFIG_FILENAME in str(raised.value)
+
+
+def test_unreadable_config_raises_configuration_error(tmp_path: Path) -> None:
+    config_file = tmp_path / CONFIG_FILENAME
+    config_file.write_text("{}", encoding=UTF8_ENCODING)
+    with patch.object(Path, "read_text", side_effect=OSError("locked")):
+        with pytest.raises(runner.ChainConfigurationError) as raised:
+            runner.load_chain(config_file)
+    unreadable_prefix = CONFIG_UNREADABLE_MESSAGE_TEMPLATE.split("{config_path}")[0]
+    assert unreadable_prefix in str(raised.value)
+
+
+def test_top_level_not_object_raises_invalid_shape(tmp_path: Path) -> None:
+    config_file = tmp_path / CONFIG_FILENAME
+    config_file.write_text(json.dumps(["claude"]), encoding=UTF8_ENCODING)
+    with pytest.raises(runner.ChainConfigurationError) as raised:
+        runner.load_chain(config_file)
+    assert str(raised.value) == CONFIG_INVALID_SHAPE_MESSAGE_TEMPLATE.format(
+        config_path=config_file,
+        reason=CONFIG_NOT_OBJECT_REASON,
+        example_filename=EXAMPLE_CONFIG_FILENAME,
+    )
+
+
+def test_chain_key_not_list_raises_invalid_shape(tmp_path: Path) -> None:
+    config_file = tmp_path / CONFIG_FILENAME
+    config_file.write_text(
+        json.dumps({CONFIG_CHAIN_KEY: "claude"}), encoding=UTF8_ENCODING
+    )
+    with pytest.raises(runner.ChainConfigurationError) as raised:
+        runner.load_chain(config_file)
+    assert CONFIG_CHAIN_NOT_LIST_REASON in str(raised.value)
+
+
+def test_empty_chain_raises_invalid_shape(tmp_path: Path) -> None:
+    config_file = _write_chain_config(tmp_path, [])
+    with pytest.raises(runner.ChainConfigurationError) as raised:
+        runner.load_chain(config_file)
+    assert CONFIG_CHAIN_EMPTY_REASON in str(raised.value)
+
+
+def test_entry_not_object_raises_invalid_shape(tmp_path: Path) -> None:
+    config_file = _write_chain_config(tmp_path, ["claude"])
+    with pytest.raises(runner.ChainConfigurationError) as raised:
+        runner.load_chain(config_file)
+    assert CONFIG_ENTRY_NOT_OBJECT_REASON in str(raised.value)
+
+
+def test_entry_without_command_raises_invalid_shape(tmp_path: Path) -> None:
+    config_file = _write_chain_config(tmp_path, [{CONFIG_EXTRA_ARGS_KEY: []}])
+    with pytest.raises(runner.ChainConfigurationError) as raised:
+        runner.load_chain(config_file)
+    assert CONFIG_ENTRY_COMMAND_MISSING_REASON in str(raised.value)
+
+
+def test_entry_with_non_list_extra_args_raises_invalid_shape(tmp_path: Path) -> None:
+    config_file = _write_chain_config(
+        tmp_path, [{CONFIG_COMMAND_KEY: "claude", CONFIG_EXTRA_ARGS_KEY: "nope"}]
+    )
+    with pytest.raises(runner.ChainConfigurationError) as raised:
+        runner.load_chain(config_file)
+    assert CONFIG_ENTRY_EXTRA_ARGS_INVALID_REASON in str(raised.value)
+
+
+def test_extra_args_default_to_empty_when_omitted(tmp_path: Path) -> None:
+    config_file = _write_chain_config(tmp_path, [{CONFIG_COMMAND_KEY: "claude"}])
+    all_entries = runner.load_chain(config_file)
+    assert all_entries[0].command == "claude"
+    assert all_entries[0].extra_args == ()
+
+
+def test_load_chain_parses_command_and_extra_args(tmp_path: Path) -> None:
+    config_file = _write_chain_config(
+        tmp_path, [_entry("claude", extra_args=["--account", "ev"])]
+    )
+    all_entries = runner.load_chain(config_file)
+    assert all_entries == [
+        runner.ChainEntry(command="claude", extra_args=("--account", "ev"))
+    ]
+
+
+def test_chain_config_path_points_at_home_config() -> None:
+    config_path = runner.chain_config_path()
+    assert config_path.name == CONFIG_FILENAME
+    assert CLAUDE_HOME_SUBDIRECTORY in config_path.parts

package/skills/CLAUDE.md

@@ -26,6 +26,8 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `implement` — structured implementation from an existing plan packet
 - `bdd-protocol` — BDD depth: Example Mapping, scenario quality, outside-in layout
 - `verified-build` — build + test loop that gates on a verifier verdict
+- `team-advisor` — turns the session into the advisor-orchestrator: it spawns executor subagents to do the code edits and test runs, and answers a blocked executor with a plan, correction, or stop
+- `team-advisor-refresh` — sub-skill fired by the `/team-advisor` loop to re-assert the executor-advisor discipline mid-run
 
 **PR review and convergence**
 - `autoconverge` — autonomous single-run workflow that drives a PR to ready
@@ -66,6 +68,7 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `monitor-open-prs` — polls open PRs for status
 - `pre-compact` — compact-safe session handoff
 - `qbug` — required baseline PR audit; one clean-coder subagent loops audit → fix → commit → push until clean or stuck
+- `usage-pause` — waits out the 5-hour usage window in ScheduleWakeup stages that keep agent contexts warm; probes the OAuth usage endpoint or takes a manual reset override
 - `skill-builder` — complete skill-building lifecycle
 - `auditing-claude-config` — audits a Claude Code setup for context-budget waste and produces a migration table with savings
 - `log-audit` — background agent that audits this repo's own logs for recurring errors and timing regressions and files grouped fixes

package/skills/team-advisor/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: team-advisor
+description: >-
+  Turns the session into the advisor-orchestrator — the user's sole interface,
+  to plan
+  and delegate while workflow-backed agent spawns do the token-heavy
+  execution with the required agent type and model for each work category.
+  Executors do the code editing, verification, script driving, PR
+  descriptions, and searches; the advisor answers blockers with one of three
+  brief signals — a plan, a correction, or a stop. The advisor never edits
+  code or runs tests itself. Caps consultations per task (default 5), reuses
+  warm workflow agents before spawning new ones, and re-asserts the
+  discipline every 20 minutes through the /team-advisor-refresh loop. Adapts
+  Anthropic's coordinator pattern (plan big, execute small) to Claude Code.
+  Triggers: '/team-advisor', 'team advisor strategy', 'run with a team
+  advisor', 'executor-advisor mode', 'team advisor enforcement', 'agent
+  routing', 'orchestrate'.
+---
+
+# Team Advisor Strategy
+
+## Principle
+
+A frontier model plans and synthesizes while cheap workers do the
+token-heavy reading and doing — Anthropic's coordinator pattern, source:
+https://github.com/anthropics/claude-cookbooks/blob/main/managed_agents/CMA_plan_big_execute_small.ipynb
+("Coordinator pattern: big models for planning, small models for
+execution"). On the cookbook's own measured run, a coordinator
+delegating to Sonnet-5 workers came out cheaper and faster
+than a solo frontier agent held to the same verification rigor, with
+84-98% of the team's input tokens billed at the worker rate.
+
+Claude Code has no `multiagent` coordinator field or Managed-Agents-style
+`create_agent`/`send_to_agent` primitives; this skill reaches the same
+shape with the tools Claude Code already has. Under this skill the session
+is the advisor-orchestrator. In Claude Code the user always talks to the session and never to a
+subagent, so the session is the user's sole interface: all user-facing
+communication flows through it. It spawns and resumes executor subagents
+— `clean-coder` and the like — and those executors do every bit of the
+execution: the code edits, the build runs, the test runs. The advisor
+drives the plan and answers the executors when they get stuck.
+
+## Gotchas
+
+- **Double invocation duplicates the reminder loop.** A second `/team-advisor`
+  in the same session schedules a second refresh loop. Check whether the loop
+  is already running before you schedule one (see the invocation guard in
+  Process step 1).
+- **The advisor never executes.** The moment it edits a file or runs the tests
+  itself, the pairing breaks and the executor's warm context is wasted. Hand
+  every code edit and every build or test run to an executor; keep the
+  advisor's own tool use to orchestration and light verification reads.
+- **Flat ad hoc spawns bypass routing.** Every execution task goes through a
+  workflow-backed spawn or workflow resume so the required agent type, model,
+  prompt packet, and sidecar metadata stay attached to the work.
+- **Wrong agent or model is an enforcement failure.** If a task category maps
+  to `clean-coder` on `opus`, a `general-purpose` Sonnet spawn is not a cost
+  optimization; it is the wrong executor for the contract.
+- **Resuming an unnamed background agent needs its agentId.** A background
+  spawn returns an `agentId` (format `a...-...`); keep it so `SendMessage` can
+  reach that agent later. A named agent is reachable by name.
+- **Consultations past the cap signal a scoping problem.** When five
+  consultations do not clear the blocker, the task needs re-scoping or a
+  hand-off to the user — not a sixth round of advice.
+
+
+## Process
+
+1. **Check whether the refresh loop is already running this
+   session. If it is, skip straight to orchestration — do not schedule a
+   second loop.
+
+2. **Register the discipline reminder.** By default, schedule it with
+   `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/team-advisor-refresh`,
+   where each refresh re-schedules the next one — a 1200-second wakeup costs
+   one prompt-cache miss per firing and nothing more (see Gotchas). The loop
+   mechanism (`/loop 20m /team-advisor-refresh`) is the escape hatch when
+   `ScheduleWakeup` is not available. Either way the reminder is the
+   enforcement surface: each firing re-asserts the discipline while the run is
+   in flight.
+
+3. **Orchestrate the task.** Hold the plan and the user conversation. Execute
+   workflow-backed spawns or resumes using the routing table below, and keep
+   driving while they work. Your own tool use stays orchestration and light
+   verification reads. Keep your task list updated religiously.
+
+## Workflow Agent Routing
+
+Every delegated task runs through a workflow-backed agent invocation. Do not
+spawn a flat subagent directly when a workflow invocation or workflow resume is
+available.
+
+| Work | Agent type | Model |
+|---|---|---|
+| Feature, bug, and refactor coding | `clean-coder` | `opus` |
+| Verification passes | `code-verifier` | `opus` |
+| Script runs, GitHub posting, and backfill driving | `general-purpose` runner | `sonnet` |
+| PR descriptions | `pr-description-writer` | `sonnet`, with file-list grounding check |
+| Fan-out searches and checklist verification reads | `Explore` | `haiku`; use `sonnet` when judgment-heavy |
+| Escalated blockers needing a second opinion beyond the orchestrator's own judgment | `code-advisor` | Fable preferred (matches the orchestrating session); opus if Fable is unavailable. |
+
+Routing rules:
+
+- Use a workflow invocation or resume for each row above. The workflow prompt
+  must name the selected agent type, model, work category, task scope, and
+  expected output.
+- Resume a warm workflow agent before creating a new workflow run when the warm
+  agent holds the relevant context.
+- `clean-coder` owns code edits. `code-verifier` owns verification. The same
+  workflow agent never grades work it wrote.
+- PR-description workflows include the actual changed-file list in the prompt
+  and verify the final body against that file list before posting or returning
+  it.
+- Exploration workflows return file paths, line numbers, and direct evidence;
+  they do not write code or mutate repo state.
+
+4. **Executors consult at a hard decision.** Each executor's spawn prompt tells
+   it to stop and message you — with the task, what it tried, and the exact
+   blocker (plus any short code excerpt that helps) — when one of these holds:
+   - It has tried the same problem twice or more and it still fails.
+   - A decision changes the deliverable's scope or a contract that is hard to
+     reverse.
+   - Two constraints conflict and it cannot satisfy both.
+   - It is unsure whether to stop or keep going.
+
+5. **Answer with one signal.** On a consultation, reply with exactly one
+   signal, brief (about 400 to 700 tokens):
+   - **PLAN** — a different approach, as concrete ordered steps the executor
+     can run. When a warm agent fits the plan, name which one to resume.
+   - **CORRECTION** — the executor's approach is right, one thing is wrong;
+     name the wrong step and the fix.
+   - **STOP** — no path satisfies the task as assigned; say why so it can be
+     reported upward.
+   The executor resumes the moment your reply lands.
+
+   A worked consultation:
+
+   ```
+   Executor → advisor
+   Task: add a retry to the upload client.
+   Tried: wrapped upload() in a three-attempt loop; the second attempt
+   double-posts.
+   Blocker: the server takes no idempotency key, so a retry after a timeout
+   creates a duplicate record.
+
+   Advisor → executor
+   CORRECTION — the retry loop is right; the missing piece is a stable request
+   id. Generate one client-side on the first attempt and send the same id on
+   every retry, so the server treats the retries as one request.
+   ```
+
+   For a decision the advisor itself cannot settle, it may use a workflow
+   escalation to the tool-less `code-advisor` agent for a second opinion — an
+   optional escalation, not a required step.
+
+## Agent reuse (non-negotiable)
+
+- **Resume before you spawn, always.** A warm agent carries its context and
+  cached tokens; a fresh spawn starts cold and pays to rebuild both.
+  Resume the existing workflow agent by name or `agentId` when it holds
+  relevant context. Prefer that path every time an existing workflow agent
+  matches the routing table.
+- **Spawn a fresh agent only when** no existing agent holds relevant context,
+  or a genuine task switch needs a clean context.
+- **Name the agent to resume.** When you answer with a PLAN and a warm agent
+  fits, say which agent to resume and where.
+
+## Constraints
+
+- One `/team-advisor` per session; the invocation guard blocks a second
+  reminder loop.
+- The advisor orchestrates and advises but never edits code or runs a build or
+  test itself — executors do that.
+- Delegated execution uses workflow-backed agent invocations and follows the
+  Workflow Agent Routing table exactly.
+- Consultations are capped at five per task by default. At the cap, re-scope
+  or hand off; do not keep answering.
+- Reuse a warm agent over a cold spawn whenever one holds relevant context.
+
+## File Index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Advisor strategy, workflow routing contract, consultation protocol, reuse rules, and constraints. |
+
+## Folder Map
+
+- `SKILL.md` — complete advisor workflow instructions.