claude-dev-env 1.88.1 → 1.90.0

package/scripts/gh_artifact_upload.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""Upload a file to a repo's durable 'artifacts' release and print its URL.
+
+A durable GitHub post (issue, PR, comment, review) must not link a file under a
+job scratch directory or worktree, because that scratch is cleaned soon after
+the run while the post lives forever. Binary artifacts belong in a permanent
+place instead. This tool ensures the repo has a prerelease tagged ``artifacts``,
+uploads the given file under a timestamped asset name, and prints the permanent
+download URL a post can safely link. The timestamped name keeps each upload a
+distinct asset. An upload never overwrites an earlier one. A same-name collision
+fails loudly instead of replacing the bytes an existing URL already serves.
+
+Usage::
+
+    python3 gh_artifact_upload.py <file-path> <owner/repo>
+    -> https://github.com/<owner>/<repo>/releases/download/artifacts/20260707_140233_contact_sheet.png
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from dev_env_scripts_constants.gh_artifact_upload_constants import (
+    ARTIFACTS_RELEASE_NOTES,
+    ARTIFACTS_RELEASE_TAG,
+    ARTIFACTS_RELEASE_TITLE,
+    ASSET_CREATED_AT_JSON_KEY,
+    ASSET_NAME_TEMPLATE,
+    ASSET_NAME_TIMESTAMP_FORMAT,
+    ASSET_URL_JSON_KEY,
+    GH_BINARY_NAME,
+    NOTES_FILE_SUFFIX,
+    RELEASE_ASSETS_JSON_KEY,
+    UTF8_ENCODING,
+)
+
+
+class ArtifactUploadError(Exception):
+    """Raised when creating the release or uploading the asset fails."""
+
+
+def _run_gh(all_arguments: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [GH_BINARY_NAME, *all_arguments],
+        capture_output=True,
+        text=True,
+        encoding=UTF8_ENCODING,
+        check=False,
+    )
+
+
+def artifacts_release_exists(repository: str) -> bool:
+    """Return whether the durable artifacts release already exists in the repo.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        True when ``gh release view`` finds the ``artifacts`` release.
+    """
+    completion = _run_gh(
+        [
+            "release",
+            "view",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--json",
+            "tagName",
+        ]
+    )
+    return completion.returncode == 0
+
+
+def ensure_artifacts_release(repository: str) -> None:
+    """Create the artifacts prerelease when the repo does not already have it.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Raises:
+        ArtifactUploadError: When the release cannot be created.
+    """
+    if artifacts_release_exists(repository):
+        return
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=NOTES_FILE_SUFFIX, delete=False, encoding=UTF8_ENCODING
+    ) as notes_file:
+        notes_file.write(ARTIFACTS_RELEASE_NOTES)
+        notes_path = notes_file.name
+    completion = _run_gh(
+        [
+            "release",
+            "create",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--prerelease",
+            "--title",
+            ARTIFACTS_RELEASE_TITLE,
+            "--notes-file",
+            notes_path,
+        ]
+    )
+    Path(notes_path).unlink(missing_ok=True)
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+
+
+def timestamped_asset_name(file_path: str) -> str:
+    """Return ``YYYYMMDD_HHMMSS_<basename>`` for the given file path.
+
+    Args:
+        file_path: The source file to be uploaded.
+
+    Returns:
+        The asset name that prefixes the basename with the current timestamp.
+    """
+    current_timestamp = datetime.datetime.now().strftime(ASSET_NAME_TIMESTAMP_FORMAT)
+    return ASSET_NAME_TEMPLATE.format(
+        timestamp=current_timestamp, basename=Path(file_path).name
+    )
+
+
+def _uploaded_asset_download_url(repository: str) -> str:
+    """Read the just-uploaded asset's real download URL back from GitHub.
+
+    ::
+
+        upload "My Report.png" -> GitHub stores "..._My.Report.png"
+        read-back -> the URL GitHub serves for that sanitized name
+
+    GitHub sanitizes an asset filename on upload: spaces and other characters
+    become periods. The stored name, and so the download URL, can differ from
+    the local name. Reading the release back returns the URL GitHub actually
+    serves for the most recently created asset, which is the one just uploaded.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        The browser download URL of the newest artifacts-release asset.
+
+    Raises:
+        ArtifactUploadError: When the read-back fails, the response cannot be
+            parsed, or no asset carries a download URL.
+    """
+    completion = _run_gh(
+        [
+            "release",
+            "view",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--json",
+            RELEASE_ASSETS_JSON_KEY,
+        ]
+    )
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+    try:
+        parsed_release = json.loads(completion.stdout)
+    except json.JSONDecodeError as decode_error:
+        raise ArtifactUploadError(f"could not read release assets: {decode_error}")
+    all_assets = (
+        parsed_release.get(RELEASE_ASSETS_JSON_KEY, [])
+        if isinstance(parsed_release, dict)
+        else []
+    )
+    all_dated_assets = [
+        each_asset
+        for each_asset in all_assets
+        if isinstance(each_asset, dict) and each_asset.get(ASSET_CREATED_AT_JSON_KEY)
+    ]
+    if not all_dated_assets:
+        raise ArtifactUploadError("uploaded asset not found on read-back")
+    newest_asset = max(
+        all_dated_assets,
+        key=lambda each_asset: each_asset[ASSET_CREATED_AT_JSON_KEY],
+    )
+    asset_url = newest_asset.get(ASSET_URL_JSON_KEY)
+    if not isinstance(asset_url, str) or not asset_url:
+        raise ArtifactUploadError("uploaded asset carries no download URL on read-back")
+    return asset_url
+
+
+def upload_artifact(file_path: str, repository: str) -> str:
+    """Upload a file to the artifacts release and return its permanent URL.
+
+    Args:
+        file_path: The source file to upload.
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        The permanent download URL for the uploaded asset.
+
+    Raises:
+        ArtifactUploadError: When the file is missing or the upload fails.
+    """
+    source_path = Path(file_path)
+    if not source_path.is_file():
+        raise ArtifactUploadError(f"file not found: {file_path}")
+    ensure_artifacts_release(repository)
+    asset_name = timestamped_asset_name(file_path)
+    with tempfile.TemporaryDirectory() as staging_directory:
+        staged_asset_path = Path(staging_directory) / asset_name
+        shutil.copyfile(source_path, staged_asset_path)
+        completion = _run_gh(
+            [
+                "release",
+                "upload",
+                ARTIFACTS_RELEASE_TAG,
+                str(staged_asset_path),
+                "--repo",
+                repository,
+            ]
+        )
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+    return _uploaded_asset_download_url(repository)
+
+
+def main() -> int:
+    """Parse arguments, upload the file, and print the permanent asset URL.
+
+    Returns:
+        ``0`` when the upload succeeds, ``1`` when it fails.
+    """
+    parser = argparse.ArgumentParser(
+        description="Upload a file to a repo's durable 'artifacts' release."
+    )
+    parser.add_argument("file_path", help="Path to the file to upload.")
+    parser.add_argument(
+        "repository", metavar="owner/repo", help="Target GitHub repository slug."
+    )
+    parsed_arguments = parser.parse_args()
+    try:
+        asset_url = upload_artifact(
+            parsed_arguments.file_path, parsed_arguments.repository
+        )
+    except ArtifactUploadError as upload_error:
+        print(f"gh-artifact-upload failed: {upload_error}", file=sys.stderr)
+        return 1
+    print(asset_url)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/tests/test_gh_artifact_upload.py

@@ -0,0 +1,205 @@
+"""Behavioral tests for gh_artifact_upload.py using a stubbed GitHub CLI."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import gh_artifact_upload as mod
+
+_DEFAULT_READBACK_ASSET = {
+    "name": "20260707_140233_contact_sheet.png",
+    "url": (
+        "https://github.com/owner/repo/releases/download/artifacts/"
+        "20260707_140233_contact_sheet.png"
+    ),
+    "createdAt": "2026-07-07T14:02:33Z",
+}
+
+
+def _make_gh_stub(
+    recorded_calls: list[list[str]],
+    view_return_code: int,
+    all_readback_assets: list[dict[str, str]] | None = None,
+) -> object:
+    readback_assets = (
+        [_DEFAULT_READBACK_ASSET] if all_readback_assets is None else all_readback_assets
+    )
+
+    def fake_run(
+        all_command_arguments: list[str],
+        **_keyword_arguments: object,
+    ) -> types.SimpleNamespace:
+        recorded_calls.append(all_command_arguments)
+        is_release_view = "view" in all_command_arguments
+        is_asset_read_back = is_release_view and "assets" in all_command_arguments
+        if is_asset_read_back:
+            return types.SimpleNamespace(
+                returncode=0,
+                stdout=json.dumps({"assets": readback_assets}),
+                stderr="",
+            )
+        return_code = view_return_code if is_release_view else 0
+        return types.SimpleNamespace(returncode=return_code, stdout="", stderr="")
+
+    return fake_run
+
+
+def test_timestamped_asset_name_prefixes_basename() -> None:
+    asset_name = mod.timestamped_asset_name(r"C:\stage\contact_sheet.png")
+    assert asset_name.endswith("_contact_sheet.png")
+    assert len(asset_name) > len("_contact_sheet.png")
+
+
+def test_upload_artifact_returns_the_readback_url(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    source_file = tmp_path / "contact_sheet.png"
+    source_file.write_bytes(b"binary")
+    recorded_calls: list[list[str]] = []
+    monkeypatch.setattr(
+        subprocess, "run", _make_gh_stub(recorded_calls, view_return_code=0)
+    )
+
+    asset_url = mod.upload_artifact(str(source_file), "owner/repo")
+
+    assert asset_url == _DEFAULT_READBACK_ASSET["url"]
+    assert any("assets" in call for call in recorded_calls)
+
+
+def test_upload_artifact_prints_the_sanitized_url_github_serves(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    source_file = tmp_path / "My Report.png"
+    source_file.write_bytes(b"binary")
+    sanitized_asset = {
+        "name": "20260707_140233_My.Report.png",
+        "url": (
+            "https://github.com/owner/repo/releases/download/artifacts/"
+            "20260707_140233_My.Report.png"
+        ),
+        "createdAt": "2026-07-07T14:02:33Z",
+    }
+    monkeypatch.setattr(
+        subprocess,
+        "run",
+        _make_gh_stub([], view_return_code=0, all_readback_assets=[sanitized_asset]),
+    )
+
+    asset_url = mod.upload_artifact(str(source_file), "owner/repo")
+
+    assert asset_url == sanitized_asset["url"]
+    assert " " not in asset_url
+
+
+def test_upload_artifact_returns_the_newest_asset_url(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    source_file = tmp_path / "out.png"
+    source_file.write_bytes(b"binary")
+    older_asset = {
+        "name": "20260707_140000_out.png",
+        "url": "https://github.com/owner/repo/releases/download/artifacts/old.png",
+        "createdAt": "2026-07-07T14:00:00Z",
+    }
+    newest_asset = {
+        "name": "20260707_140233_out.png",
+        "url": "https://github.com/owner/repo/releases/download/artifacts/new.png",
+        "createdAt": "2026-07-07T14:02:33Z",
+    }
+    monkeypatch.setattr(
+        subprocess,
+        "run",
+        _make_gh_stub(
+            [], view_return_code=0, all_readback_assets=[older_asset, newest_asset]
+        ),
+    )
+
+    asset_url = mod.upload_artifact(str(source_file), "owner/repo")
+
+    assert asset_url == newest_asset["url"]
+
+
+def test_upload_artifact_raises_when_asset_missing_on_readback(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    source_file = tmp_path / "out.png"
+    source_file.write_bytes(b"binary")
+    monkeypatch.setattr(
+        subprocess, "run", _make_gh_stub([], view_return_code=0, all_readback_assets=[])
+    )
+
+    with pytest.raises(mod.ArtifactUploadError):
+        mod.upload_artifact(str(source_file), "owner/repo")
+
+
+def test_upload_artifact_uploads_to_tag_without_clobber(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    source_file = tmp_path / "out.png"
+    source_file.write_bytes(b"binary")
+    recorded_calls: list[list[str]] = []
+    monkeypatch.setattr(
+        subprocess, "run", _make_gh_stub(recorded_calls, view_return_code=0)
+    )
+
+    mod.upload_artifact(str(source_file), "owner/repo")
+
+    upload_call = next(call for call in recorded_calls if "upload" in call)
+    assert "artifacts" in upload_call
+    assert "--clobber" not in upload_call
+
+
+def test_upload_artifact_creates_release_when_absent(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    source_file = tmp_path / "out.png"
+    source_file.write_bytes(b"binary")
+    recorded_calls: list[list[str]] = []
+    monkeypatch.setattr(
+        subprocess, "run", _make_gh_stub(recorded_calls, view_return_code=1)
+    )
+
+    mod.upload_artifact(str(source_file), "owner/repo")
+
+    assert any("create" in call for call in recorded_calls)
+
+
+def test_artifacts_release_exists_true_when_view_succeeds(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(subprocess, "run", _make_gh_stub([], view_return_code=0))
+    assert mod.artifacts_release_exists("owner/repo") is True
+
+
+def test_artifacts_release_exists_false_when_view_fails(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(subprocess, "run", _make_gh_stub([], view_return_code=1))
+    assert mod.artifacts_release_exists("owner/repo") is False
+
+
+def test_ensure_artifacts_release_skips_create_when_present(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    recorded_calls: list[list[str]] = []
+    monkeypatch.setattr(
+        subprocess, "run", _make_gh_stub(recorded_calls, view_return_code=0)
+    )
+    mod.ensure_artifacts_release("owner/repo")
+    assert not any("create" in call for call in recorded_calls)
+
+
+def test_upload_artifact_missing_file_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(subprocess, "run", _make_gh_stub([], view_return_code=0))
+    with pytest.raises(mod.ArtifactUploadError):
+        mod.upload_artifact("does_not_exist_9f3a.png", "owner/repo")

package/skills/CLAUDE.md

@@ -26,8 +26,6 @@ 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
-- `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
-- `advisor-refresh` — sub-skill fired by the `/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

package/skills/advisor/SKILL.md

@@ -1,185 +0,0 @@
----
-name: advisor
-description: >-
-  Turns the session into the advisor-orchestrator — the user's sole interface,
-  which routes execution through workflow-backed agent spawns 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 /advisor-refresh
-  loop. Adapts Anthropic's advisor strategy to Claude Code. Triggers:
-  '/advisor', 'advisor strategy', 'run with an advisor', 'executor-advisor
-  mode', 'advisor enforcement', 'agent routing'.
----
-
-# Advisor Strategy
-
-## Principle
-
-A cost-effective executor runs the primary work — it calls tools, reads
-results, and iterates — while a stronger model advises only at the hard
-decisions. Source: Anthropic's advisor strategy,
-https://claude.com/blog/the-advisor-strategy.
-
-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.
-
-This is the advisor-lite shape: the blog's pure pairing keeps the advisor
-tool-less and hidden from the user, but Claude Code routes every user message
-through the session, so the advisor here stays the user's interface while
-keeping execution out of its own hands. Consultations are capped (default 5
-per task) — the same guard the API's `max_uses` gives a tool.
-
-## Gotchas
-
-- **Double invocation duplicates the reminder loop.** A second `/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. **Invocation guard (once per session).** Before scheduling anything, 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 `/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 /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, plan-level design, and advisor signals | `code-advisor` or this session | Fable preferred; 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 `/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.

package/skills/advisor-refresh/SKILL.md

@@ -1,25 +0,0 @@
----
-name: advisor-refresh
-description: >-
-  Fired by the /advisor loop reminder about every 20 minutes to re-assert the
-  advisor discipline mid-run. A compressed restatement of /advisor: orchestrate
-  rather than execute, answer a blocked executor with a plan, correction, or
-  stop, and reuse warm agents before spawning new ones. Triggers:
-  '/advisor-refresh'.
----
-
-# Advisor Refresh
-
-1. **You are the advisor.** Orchestrate and hold the user conversation; spawn
-   executor subagents to do all the work — every code edit and build or test
-   run.
-2. **An executor blocked twice on the same thing?** Answer it with one signal
-   — a plan, a correction, or a stop — brief. Never take over the edit or the
-   tests yourself.
-3. **Resume before you spawn.** `SendMessage` an existing agent by name or
-   `agentId` to reuse its warm context; prefer that over a cold spawn.
-4. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
-   subagent's context, so a clean context comes from a fresh spawn — never tell
-   an agent to compact.
-5. **Re-schedule the next refresh** (about 1200 seconds out) when the loop
-   mechanism needs each firing to queue the following one.