claude-dev-env 2.2.1 → 2.4.0

package/skills/prototype/scripts/test_probe_sandbox_safety.py

@@ -0,0 +1,284 @@
+"""Tests for the sandbox safety-hook probe.
+
+The block-detection unit tests drive fixture hook scripts, and the
+integration tests point a settings file at the real installed safety hooks
+to prove they block their probe payloads end to end.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from prototype_scripts_constants.config.build_sandbox_settings_constants import (
+    ALL_SAFETY_HOOK_SCRIPT_BASENAMES,
+    COMMAND_KEY,
+    HOOKS_KEY,
+    MATCHER_KEY,
+    PRE_TOOL_USE_KEY,
+)
+from prototype_scripts_constants.config.probe_sandbox_safety_constants import (
+    DESTRUCTIVE_PROBE_COMMAND,
+    ENVELOPE_TOOL_INPUT_KEY,
+    ENVELOPE_TOOL_NAME_KEY,
+    PII_PROBE_TOKEN_PREFIX,
+    PII_PROBE_TOOL_NAME,
+    PROBE_FAILURE_EXIT_CODE,
+    PROBE_SUCCESS_EXIT_CODE,
+    TOOL_INPUT_COMMAND_KEY,
+    TOOL_INPUT_CONTENT_KEY,
+)
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+PROBE_PATH = SCRIPTS_DIRECTORY / "probe_sandbox_safety.py"
+HOOKS_BLOCKING_DIRECTORY = SCRIPTS_DIRECTORY.parents[2] / "hooks" / "blocking"
+
+PII_HOOK_BASENAME = ALL_SAFETY_HOOK_SCRIPT_BASENAMES[0]
+DESTRUCTIVE_HOOK_BASENAME = ALL_SAFETY_HOOK_SCRIPT_BASENAMES[1]
+
+DENY_HOOK_SOURCE = (
+    "import json, sys\n"
+    "sys.stdout.write(json.dumps("
+    '{"hookSpecificOutput": {"permissionDecision": "deny"}}))\n'
+)
+ASK_HOOK_SOURCE = (
+    "import json, sys\n"
+    "sys.stdout.write(json.dumps("
+    '{"hookSpecificOutput": {"permissionDecision": "ask"}}))\n'
+)
+ALLOW_HOOK_SOURCE = "import sys\nsys.exit(0)\n"
+
+
+def load_probe_module() -> ModuleType:
+    spec = importlib.util.spec_from_file_location("probe_sandbox_safety", PROBE_PATH)
+    assert spec is not None
+    assert spec.loader is not None
+    probe_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(probe_module)
+    return probe_module
+
+
+def quoted_command(script_path: Path) -> str:
+    return f'"{sys.executable}" "{script_path}"'
+
+
+def real_hook_settings_document() -> dict:
+    pii_hook_path = HOOKS_BLOCKING_DIRECTORY / PII_HOOK_BASENAME
+    destructive_hook_path = HOOKS_BLOCKING_DIRECTORY / DESTRUCTIVE_HOOK_BASENAME
+    return {
+        HOOKS_KEY: {
+            PRE_TOOL_USE_KEY: [
+                {
+                    MATCHER_KEY: "Write",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(pii_hook_path)}],
+                },
+                {
+                    MATCHER_KEY: "Bash",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(destructive_hook_path)}],
+                },
+            ]
+        }
+    }
+
+
+def real_hook_deny_mode_settings_document() -> dict:
+    settings_document = real_hook_settings_document()
+    settings_document["env"] = {"CLAUDE_DESTRUCTIVE_DENY_MODE": "1"}
+    return settings_document
+
+
+def write_settings_file(tmp_path: Path, settings_document: dict) -> Path:
+    settings_path = tmp_path / "sandbox-settings.json"
+    settings_path.write_text(json.dumps(settings_document), encoding="utf-8")
+    return settings_path
+
+
+def test_settings_environment_overrides_reads_the_env_block() -> None:
+    probe = load_probe_module()
+    environment_overrides = probe.settings_environment_overrides(
+        real_hook_deny_mode_settings_document()
+    )
+    assert environment_overrides == {"CLAUDE_DESTRUCTIVE_DENY_MODE": "1"}
+
+
+def test_settings_environment_overrides_empty_without_an_env_block() -> None:
+    probe = load_probe_module()
+    environment_overrides = probe.settings_environment_overrides(
+        real_hook_settings_document()
+    )
+    assert environment_overrides == {}
+
+
+def test_main_exits_zero_when_the_real_destructive_hook_denies_in_deny_mode(
+    tmp_path: Path,
+) -> None:
+    probe = load_probe_module()
+    settings_path = write_settings_file(
+        tmp_path, real_hook_deny_mode_settings_document()
+    )
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_SUCCESS_EXIT_CODE
+
+
+def test_pii_basename_probe_payload_carries_the_secret() -> None:
+    probe = load_probe_module()
+    probe_payload = probe.build_probe_payload_for_basename(PII_HOOK_BASENAME)
+    assert probe_payload[ENVELOPE_TOOL_NAME_KEY] == PII_PROBE_TOOL_NAME
+    content = probe_payload[ENVELOPE_TOOL_INPUT_KEY][TOOL_INPUT_CONTENT_KEY]
+    assert PII_PROBE_TOKEN_PREFIX in content
+
+
+def test_destructive_basename_probe_payload_carries_the_command() -> None:
+    probe = load_probe_module()
+    probe_payload = probe.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    command = probe_payload[ENVELOPE_TOOL_INPUT_KEY][TOOL_INPUT_COMMAND_KEY]
+    assert command == DESTRUCTIVE_PROBE_COMMAND
+
+
+def test_find_hook_command_for_basename_returns_the_matching_command() -> None:
+    probe = load_probe_module()
+    settings_document = real_hook_settings_document()
+    command = probe.find_hook_command_for_basename(settings_document, PII_HOOK_BASENAME)
+    assert command is not None
+    assert PII_HOOK_BASENAME in command
+    assert probe.find_hook_command_for_basename(settings_document, "absent.py") is None
+
+
+def test_parse_command_argv_splits_and_unquotes_the_command() -> None:
+    probe = load_probe_module()
+    command_argv = probe.parse_command_argv('"/usr/bin/python" "/a/b hook.py"')
+    assert command_argv == ["/usr/bin/python", "/a/b hook.py"]
+
+
+def test_hook_blocks_probe_reports_true_for_a_deny_hook(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    deny_hook_path = tmp_path / "deny_hook.py"
+    deny_hook_path.write_text(DENY_HOOK_SOURCE, encoding="utf-8")
+    command_argv = [sys.executable, str(deny_hook_path)]
+    probe_payload = probe.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    assert probe.hook_blocks_probe(command_argv, probe_payload, {}) is True
+
+
+def test_hook_blocks_probe_reports_false_for_an_ask_hook(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    ask_hook_path = tmp_path / "ask_hook.py"
+    ask_hook_path.write_text(ASK_HOOK_SOURCE, encoding="utf-8")
+    command_argv = [sys.executable, str(ask_hook_path)]
+    probe_payload = probe.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    assert probe.hook_blocks_probe(command_argv, probe_payload, {}) is False
+
+
+def test_hook_blocks_probe_reports_false_for_an_allow_hook(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    allow_hook_path = tmp_path / "allow_hook.py"
+    allow_hook_path.write_text(ALLOW_HOOK_SOURCE, encoding="utf-8")
+    command_argv = [sys.executable, str(allow_hook_path)]
+    probe_payload = probe.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    assert probe.hook_blocks_probe(command_argv, probe_payload, {}) is False
+
+
+def test_probe_safety_hook_blocks_against_the_real_pii_hook() -> None:
+    probe = load_probe_module()
+    settings_document = real_hook_settings_document()
+    assert probe.probe_safety_hook(settings_document, PII_HOOK_BASENAME) is True
+
+
+def test_main_exits_three_when_the_real_destructive_hook_only_asks(
+    tmp_path: Path,
+) -> None:
+    probe = load_probe_module()
+    settings_path = write_settings_file(tmp_path, real_hook_settings_document())
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_zero_when_both_real_hooks_hard_deny(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    deny_pii_hook_path = tmp_path / PII_HOOK_BASENAME
+    deny_pii_hook_path.write_text(DENY_HOOK_SOURCE, encoding="utf-8")
+    deny_destructive_hook_path = tmp_path / DESTRUCTIVE_HOOK_BASENAME
+    deny_destructive_hook_path.write_text(DENY_HOOK_SOURCE, encoding="utf-8")
+    settings_document = {
+        HOOKS_KEY: {
+            PRE_TOOL_USE_KEY: [
+                {
+                    MATCHER_KEY: "Write",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(deny_pii_hook_path)}],
+                },
+                {
+                    MATCHER_KEY: "Bash",
+                    HOOKS_KEY: [
+                        {COMMAND_KEY: quoted_command(deny_destructive_hook_path)}
+                    ],
+                },
+            ]
+        }
+    }
+    settings_path = write_settings_file(tmp_path, settings_document)
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_SUCCESS_EXIT_CODE
+
+
+def test_main_exits_three_when_a_hook_allows(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    allow_pii_hook_path = tmp_path / PII_HOOK_BASENAME
+    allow_pii_hook_path.write_text(ALLOW_HOOK_SOURCE, encoding="utf-8")
+    destructive_hook_path = HOOKS_BLOCKING_DIRECTORY / DESTRUCTIVE_HOOK_BASENAME
+    settings_document = {
+        HOOKS_KEY: {
+            PRE_TOOL_USE_KEY: [
+                {
+                    MATCHER_KEY: "Write",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(allow_pii_hook_path)}],
+                },
+                {
+                    MATCHER_KEY: "Bash",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(destructive_hook_path)}],
+                },
+            ]
+        }
+    }
+    settings_path = write_settings_file(tmp_path, settings_document)
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_three_when_the_settings_file_is_absent(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    absent_settings_path = tmp_path / "does-not-exist.json"
+    exit_code = probe.main(["--settings", str(absent_settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_three_when_the_settings_file_is_invalid_json(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    settings_path = tmp_path / "sandbox-settings.json"
+    settings_path.write_text("{not valid json", encoding="utf-8")
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_three_when_a_hook_script_is_bogus(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    bogus_pii_hook_path = tmp_path / PII_HOOK_BASENAME
+    destructive_hook_path = HOOKS_BLOCKING_DIRECTORY / DESTRUCTIVE_HOOK_BASENAME
+    settings_document = {
+        HOOKS_KEY: {
+            PRE_TOOL_USE_KEY: [
+                {
+                    MATCHER_KEY: "Write",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(bogus_pii_hook_path)}],
+                },
+                {
+                    MATCHER_KEY: "Bash",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(destructive_hook_path)}],
+                },
+            ]
+        }
+    }
+    settings_path = write_settings_file(tmp_path, settings_document)
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE

package/skills/prototype/workflows/promotion.md

@@ -0,0 +1,27 @@
+# Promotion workflow (Phase 2)
+
+Turn a successful proof-of-concept into a real, verified change. Run every step in the normal, fully-hooked session — never inside the `--bare` sandbox. The sandbox produced a reference build; promotion re-verifies it to standard and often rewrites parts of it.
+
+## Seed the task list first
+
+Register every item in `reference/promotion-tasks.md` as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool). Work only from the task list. Mark each complete with evidence — a command result, a path, a verdict, or a skill's return.
+
+## The clean-room protocol
+
+The task seeds carry the full ordered detail. The shape:
+
+1. **Confirm** the POC is worth promoting and the user wants it shipped.
+2. **Fresh branch** off freshly-fetched `origin/main` via `fresh-branch` — clean history, based on live upstream.
+3. **Bring content as an uncommitted diff.** Copy the POC's file changes into the new branch's working tree. Do not cherry-pick or merge the sandbox commits; the sandbox history stays behind.
+4. **Cleanup.** Remove scratch files, debug dumps, and temp helpers the POC created (`cleanup-temp-files` rule).
+5. **Privacy sweep** via `privacy-hygiene` over the diff.
+6. **Verify** with the `code-verifier` agent in a fresh context. This is where standards re-engage. Expect findings and a repair loop — the POC was un-TDD'd.
+7. **Commit and PR.** Only on a clean verdict, run `/commit`, then open a draft PR per the `git-workflow` rule.
+8. **State the honest limitations** from `reference/honest-limitations.md` in the PR body or to the user.
+9. **Converge** by handing the PR to `autoconverge` by default; use `pr-converge` for paced ticks or `bugteam` for an open-loop audit.
+
+## Why the clean room, not a push
+
+`code_rules_enforcer` is a write-time Write/Edit gate. Content that lands through `git apply`, `git checkout`, or cherry-pick never passes through it, so pushing the sandbox branch would ship code the rule engine never saw, carrying sandbox scratch along with it. Standards re-engage through the `code-verifier` agent, the `privacy-hygiene` sweep, and the PR review — not through a write-time hook. Steps 4-6 are hard gates: the honest claim on promoted POC code is code-verifier-passed, privacy-swept, review-passed, with TDD ordering waived.
+
+The `verified_commit_gate` hook is the backstop under all of this — it refuses a commit or push with no minted verdict — but the clean-room steps are the mechanism, not the gate firing.

package/skills/prototype/workflows/sandbox.md

@@ -0,0 +1,35 @@
+# Sandbox workflow (Phase 1)
+
+Stand up an isolated worktree where a hookless agent builds a proof-of-concept with zero standards friction. Only two safety gates stay live: personal-data blocking and destructive-command blocking.
+
+## Step 1 — Isolated worktree
+
+Invoke the `fresh-branch` skill to create a worktree off `origin/main`. Keep the returned `worktree_path` and `base_commit` for the promotion phase. If `fresh-branch` is not installed, stop with the refusal line from `SKILL.md`.
+
+## Step 2 — Minimal safety settings
+
+Run `scripts/build_sandbox_settings.py --out <worktree>/.prototype-sandbox-settings.json`.
+
+It reads the live `~/.claude/settings.json`, resolves each safety hook's command (the correct interpreter and absolute path for this machine), and registers it on the matchers the sandbox needs — personal-data on Write, Edit, MultiEdit, and Bash; destructive-command on Bash. The write file carries only those two gates, plus an `env` block that sets `CLAUDE_DESTRUCTIVE_DENY_MODE`, so the destructive gate hard-denies a match. A hard deny holds under `--dangerously-skip-permissions`; an `ask` there is auto-resolved.
+
+- Exit 0 → continue with the printed settings path.
+- Exit 2 → one of the two safety hooks could not be resolved from the live settings. Stop; the sandbox cannot be contained without both. Report which one is missing.
+
+## Step 3 — Prove containment
+
+Run `scripts/probe_sandbox_safety.py --settings <settings path>`.
+
+It feeds each safety hook a payload the hook is proven to block and confirms a hard-deny decision — the block that holds even under `--dangerously-skip-permissions`, unlike an `ask` prompt the flag auto-resolves. It runs each hook under the settings' `env` block, so the destructive gate runs in deny mode, the same way the launched session runs it.
+
+- Exit 0 → both gates hard-deny their probe; the sandbox is contained.
+- Exit 3 → a gate allowed its probe, returned an `ask`, or errored. Stop; do not launch an uncontained sandbox. This is a runtime check, not a code read (verify-runtime-state) — do not skip it.
+
+## Step 4 — Launch the hookless session
+
+Run `scripts/launch_sandbox.py --worktree <worktree_path> --settings <settings path> --task-file <task file>`.
+
+It starts a headless `claude -p --bare --dangerously-skip-permissions --settings <settings path>` session in the worktree, so every standards gate is skipped and the two safety gates from the settings file are the only containment. Write the proof-of-concept task to the task file first; the sandbox agent cannot invoke other skills, so the task must be self-contained.
+
+## Step 5 — Judge the result
+
+Read what the sandbox built and decide whether the proof-of-concept proves the idea. On success, move to `promotion.md`. To discard, remove the worktree with `git worktree remove --force <worktree_path>`.

package/skills/skill-builder/CLAUDE.md

@@ -1,12 +1,12 @@
 # skill-builder
 
-Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via `skill-writer`, enforce modularity (sub-skills / composition), write description as a trigger catalog, require deterministic steps as code, self-audit, and refine from real usage.
+Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via the `skill-writer-agent` agent, enforce modularity (sub-skills / composition), write description as a trigger catalog, require deterministic steps as code, self-audit, and refine from real usage.
 
 **Trigger:** build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, description trigger catalog, deterministic skill scripts.
 
 ## Purpose
 
-Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context (composition plan, description triggers, deterministic inventory), delegates writing, and self-audits.
+Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, spawn the `skill-writer-agent` agent directly. This skill classifies, scaffolds, gathers context (composition plan, description triggers, deterministic inventory), delegates writing, and self-audits.
 
 ## Key files
 
@@ -45,5 +45,5 @@ Enforces craft standards for new and existing skills. For quick one-off SKILL.md
 
 - Every build ends with the self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
 - Modularity items, description trigger-catalog items, and deterministic-element classification are mandatory on every delivery.
-- `skill-builder` orchestrates; `skill-writer` authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, deterministic inventory, degree-of-freedom assessment, and constraints.
+- `skill-builder` orchestrates; the `skill-writer-agent` agent authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, deterministic inventory, degree-of-freedom assessment, and constraints.
 - Claude A / Claude B: Claude A (this session) designs; Claude B (subagents) tests the built skill on real tasks.

package/skills/skill-builder/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: skill-builder
 description: >-
-  Skill lifecycle: classify, scaffold, write via skill-writer, self-audit, compose
+  Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose
   sub-skills, polish description triggers, enforce deterministic scripts. Triggers:
   build a skill, new skill workflow, improve this skill, optimize skill description,
   skill development lifecycle, skill modularity, skill composition, description
@@ -28,9 +28,9 @@ Highest-signal content. Append a bullet each time a skill build fails in a new w
 
 ## When this skill applies
 
-Trigger for requests to **build**, **improve**, or **polish** a skill. This skill orchestrates the process — it classifies, scaffolds, gathers context, delegates writing to `/skill-writer`, and self-audits the result.
+Trigger for requests to **build**, **improve**, or **polish** a skill. This skill orchestrates the process — it classifies, scaffolds, gathers context, delegates writing to the `skill-writer-agent` agent, and self-audits the result.
 
-For quick skill syntax questions or one-off SKILL.md edits, use `/skill-writer` directly instead.
+For quick skill syntax questions or one-off SKILL.md edits, spawn the `skill-writer-agent` agent directly.
 
 **Refusal cases — first match wins:**
 
@@ -161,9 +161,9 @@ Also: story-form descriptions; monolith multi-capability skills; silent reimplem
 
 After every build, improvement, or polish pass, load `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`, **register every bullet as a session task**, and complete each with evidence. Every item must pass before delivery. Fix failures, then re-audit.
 
-## Delegation to skill-writer
+## Delegation to skill-writer-agent
 
-skill-builder orchestrates; skill-writer authors. The handoff packet from Step 4 must include:
+skill-builder orchestrates; the `skill-writer-agent` agent authors. The caller spawns it with `Agent(subagent_type="skill-writer-agent", ...)`. The handoff packet from Step 4 must include:
 
 - Skill type and folder structure
 - Gap analysis or observation findings (composition plan + description triggers + deterministic inventory)

package/skills/skill-builder/references/CLAUDE.md

@@ -12,7 +12,7 @@ Best-practice specifications and the mandatory self-audit checklist for the `/sk
 | `skill-modularity.md` | Cross-skill modularity: one capability, sub-skills by name, composition plan, anti-monolith. |
 | `description-field.md` | Frontmatter description as trigger catalog (capability stem + Triggers). No story prose. |
 | `deterministic-elements.md` | Classify process steps; deterministic ones ship as code, task seeds, or fixed artifacts under CODE_RULES. |
-| `delegation-map.md` | Subagent handoff patterns and transcript guidance for skill-builder → skill-writer. |
+| `delegation-map.md` | Subagent handoff patterns and transcript guidance for skill-builder → skill-writer-agent. |
 | `thariq-x-post-skills.json` | Source reference data from Anthropic lessons on building Claude Code skills. |
 
 ## Conventions

package/skills/skill-builder/references/delegation-map.md

@@ -1,10 +1,10 @@
 # Delegation Map
 
-How skill-builder delegates work to subagents and `/skill-writer`.
+How skill-builder delegates authoring to the `skill-writer-agent` agent.
 
-## Delegating to skill-writer (Step 4)
+## Delegating to skill-writer-agent (Step 4)
 
-skill-builder orchestrates; skill-writer authors the SKILL.md and companion files. The handoff must be structured so skill-writer has everything it needs.
+skill-builder orchestrates; the `skill-writer-agent` agent authors the SKILL.md and companion files. The caller spawns it with `Agent(subagent_type="skill-writer-agent", ...)`. The handoff must be structured so the agent has everything it needs.
 
 ### New skill handoff
 

package/skills/skill-builder/references/description-field.md

@@ -44,7 +44,7 @@ description: >-
 
 ```yaml
 description: >-
-  Skill lifecycle: classify, scaffold, write via skill-writer, self-audit, compose sub-skills, polish description triggers. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity.
+  Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose sub-skills, polish description triggers. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity.
 ```
 
 ```yaml

package/skills/skill-builder/references/skill-modularity.md

@@ -54,7 +54,7 @@ sibling-skill-a/             # one capability
 sibling-skill-b/             # one capability
 ```
 
-The orchestrator owns sequence and gates. Sub-skills own domain detail. skill-builder itself follows this shape: it orchestrates and delegates writing to `/skill-writer`.
+The orchestrator owns sequence and gates. Sub-skills own domain detail. skill-builder itself follows this shape: it orchestrates and delegates writing to the `skill-writer-agent` agent (spawned via the Agent tool).
 
 ### Within-skill vs split
 
@@ -85,12 +85,11 @@ In Process or a dedicated **Sub-skills** section:
 | Skill | When | Produces |
 |---|---|---|
 | `/reviewer-gates` | Step 1 — gate external reviewers | opt-out, Copilot quota, Bugbot trigger decisions |
-| `/skill-writer` | Step 4 — author SKILL.md | skill package files |
 
 If a listed skill is not installed, respond: `[exact refusal or degrade line]`.
 ```
 
-Self-audit requires this table (or equivalent) whenever the skill composes others.
+Self-audit requires this table (or equivalent) whenever the skill composes others. skill-builder itself delegates SKILL.md authoring to the `skill-writer-agent` agent, spawned via the Agent tool.
 
 ## Anti-patterns
 

package/skills/skill-builder/workflows/CLAUDE.md

@@ -6,7 +6,7 @@ Step-by-step workflow files for each skill lifecycle phase, loaded on demand by
 
 | File | Purpose |
 |---|---|
-| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers + deterministic inventory), write via skill-writer, self-audit, deliver. |
+| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers + deterministic inventory), write via the skill-writer-agent agent, self-audit, deliver. |
 | `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality/deterministic prose, targeted fix, re-audit. |
 | `polish-skill.md` | Description trigger-catalog audit; progressive disclosure + modularity + deterministic audit; task-seeded self-audit. |
 

package/skills/skill-builder/workflows/improve-skill.md

@@ -83,7 +83,7 @@ For each diagnosis from Step 2:
 6. For checkbox/tracker failures: replace markdown `- [ ]` boards with a plain task-seed list and a seed instruction (`TaskCreate` / `TodoWrite`).
 7. Verify the fix doesn’t break anything that was working.
 
-Delegate larger rewrites to `/skill-writer` using the refine-skill handoff from delegation-map.md.
+Spawn the `skill-writer-agent` agent for larger rewrites, using the refine-skill handoff from delegation-map.md.
 
 **Output:** Modified skill files with targeted fixes.
 

package/skills/skill-builder/workflows/new-skill.md

@@ -125,11 +125,11 @@ Register each task seed under **Required task seeds** in `deterministic-elements
 
 **Goal:** Produce the skill package — SKILL.md and companion files.
 
-Delegate to `/skill-writer` using the structured handoff from `${CLAUDE_SKILL_DIR}/references/delegation-map.md`.
+Spawn the `skill-writer-agent` agent (`Agent(subagent_type="skill-writer-agent", ...)`) with the structured handoff from `${CLAUDE_SKILL_DIR}/references/delegation-map.md`.
 
 The handoff must include: skill type, folder structure, gap analysis (composition plan + description triggers + deterministic inventory), initial gotchas, degree of freedom, constraints, sub-skills to name in SKILL.md, exact description string to put in frontmatter, script/test paths for every deterministic step.
 
-After skill-writer produces the draft:
+After the `skill-writer-agent` agent produces the draft:
 
 1. Verify it follows the hub layout (principle → gotchas → when-applies → process → file index → folder map).
 2. Verify SKILL.md body is under 500 lines.

package/skills/team-advisor/SKILL.md

@@ -17,8 +17,8 @@ One warm, addressable advisor available at the strongest model tier the session
 
 **Detect the host profile first** (Host profiles in
 [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
-— e.g. `ADVISOR_HOST_PROFILE` or `THIRD_PARTY`). Do not start a model-floor
-walk until the host is known.
+— e.g. %USERPROFILE%\.claude\_shared\advisor\advisor-protocol.md). Do not start a model-floor
+walk until the host is known. 
 
 This session is the shared advisor's sole consumer, so its model floor is
 simply this session's own tier — no routing table to take a max against.
@@ -30,8 +30,9 @@ the only consumer (skip the "who you are and your assignment" opener in each
 consult; a single-consumer session doesn't need it).
 
 **Third-party host:** bind a max-tier Claude advisor through the shared CLI Claude-chain
-in the protocol (Fable max, then Opus max; `claude_chain_runner.py` walks
-`~/.claude/claude-chain.json` for account usage failover). Consult via
+in the protocol (Fable max, then Opus max; `claude_chain_runner.py` ranks
+`~/.claude/claude-chain.json` accounts by weekly remaining via `claude_chain_usage`
+and fails over on usage limits). Consult via
 `--resume <session_id>` on that bind. This session is the sole consumer of that
 CLI advisor; skip the multi-consumer opener. When the chain cannot bind or
 reply, fail closed and report to the user — do **not** answer ENDORSE /