claude-dev-env 1.89.0 → 1.92.0

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.

package/skills/team-advisor-refresh/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: team-advisor-refresh
+description: >-
+  Fired by the /team-advisor loop reminder about every 20 minutes to
+  re-assert the advisor discipline mid-run. A compressed restatement of
+  /team-advisor: orchestrate rather than execute, answer a blocked executor
+  with a plan, correction, or stop, and reuse warm agents before spawning new
+  ones. Triggers: '/team-advisor-refresh'.
+---
+
+# Team 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.

package/skills/usage-pause/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: usage-pause
+description: Waits out the account's 5-hour usage window in ScheduleWakeup stages that keep every agent context warm. Resolves the window's reset time and remaining headroom by probing the OAuth usage endpoint, or takes a manual override ('/usage-pause 10:20pm', '/usage-pause 74m'). Warns and stops when the weekly limit is near its cap. Each wakeup pings live and idle-warm agents with a one-line no-new-work checkpoint and records finished results; the final wakeup restores the crons the skill cancelled at pause time. Triggers: '/usage-pause', 'pause until the usage window resets', 'wait out the usage limit', 'usage limit pause'.
+argument-hint: "[reset time like 10:20pm | duration like 74m]"
+---
+
+# /usage-pause
+
+Pause on purpose before a usage limit kills in-flight work. The skill reads the 5-hour session window's reset time and remaining headroom, breaks the wait into ScheduleWakeup stages, keeps every agent context warm through the pause with checkpoint pings, and hands control back after the reset.
+
+## Step 1 — resolve the usage window
+
+Run the bundled resolver:
+
+```
+python "${CLAUDE_SKILL_DIR}/scripts/resolve_usage_window.py"
+```
+
+With an argument (`/usage-pause 10:20pm`, `/usage-pause 74m`), skip the probe and pass it through:
+
+```
+python "${CLAUDE_SKILL_DIR}/scripts/resolve_usage_window.py" --override "10:20pm"
+```
+
+On exit 0 the script prints one JSON object:
+
+| Field | Meaning |
+|---|---|
+| `source` | `probe` or `override` |
+| `reset_at` | When the 5-hour window resets (ISO-8601, local zone) |
+| `seconds_until_reset` | The wait the stage plan covers |
+| `stages_seconds` | The ScheduleWakeup stage durations, in firing order |
+| `session_utilization` | Percent of the 5-hour window spent (null on override) |
+| `weekly_utilization` | Percent of the weekly window spent (null on override) |
+| `weekly_resets_at` | When the weekly window resets (null on override) |
+| `weekly_near_cap` | True when the weekly meter is at or past 90 percent |
+
+On exit 2 the script prints `{"error": ...}`. Ask the user for a manual reset time via AskUserQuestion (offer clock-time and duration examples), then rerun with `--override`.
+
+### Probe mechanism
+
+The resolver reads the Claude Code CLI's OAuth access token from `~/.claude/.credentials.json` (`claudeAiOauth.accessToken`, honored only while its `expiresAt` sits in the future) and sends `GET https://api.anthropic.com/api/oauth/usage` with `Authorization: Bearer <token>` and `anthropic-beta: oauth-2025-04-20`. This is the same endpoint the interactive `/usage` panel reads. The response carries a `five_hour` bucket and a `seven_day` bucket, each with `utilization` (percent spent) and `resets_at`.
+
+Fallbacks, in order: an expired or unreadable stored token, a failed request, or a response with no readable `five_hour` reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when the credential file is stale.
+
+Why this probe and not the others:
+
+- The interactive `/usage` panel shows the same data but has no scriptable output.
+- `claude -p --output-format json` spends usage to answer and its metadata reports per-call token counts, not the account window clock.
+- `anthropic-ratelimit-*` response headers cover API-key Messages traffic, not the subscription session window, and reading them also costs a request.
+- Refreshing the OAuth token from a script is out of scope: token rotation would desync the refresh token the CLI has on disk and log the CLI out. The resolver only ever reads the credential file.
+
+## Weekly limit guard
+
+When `weekly_near_cap` is true, WARN the user — report `weekly_utilization` and `weekly_resets_at` — and stop. No pause choreography runs around the weekly limit; waiting out a weekly window is its own later build.
+
+## Step 2 — the pause chain
+
+Before the first sleep:
+
+1. List active recurring loops (CronList). Record each one's schedule and prompt, then cancel it (CronDelete). Carry the recorded list inside the wakeup prompts so the state survives every stage.
+2. Schedule the first stage with ScheduleWakeup, using the first duration in `stages_seconds` and the stage prompt template below.
+
+The stage plan keeps every stage at or under 58 minutes (3480 seconds, inside the 3600-second clamp) and ends with a roughly 2-minute tail stage so the final firing lands just past the reset. A leftover too short to stand alone folds into the tail.
+
+Every wakeup does exactly three things — ping, record, schedule — and dispatches no new work. The cache rationale: an unpinged idle agent left past the cache window resumes cold and re-reads its whole transcript, so pings run tighter than the cache lifetime and keep each agent's next real invocation cheap.
+
+### Stage wakeup prompt template
+
+```
+/usage-pause stage <stage_number> of <stage_total>: pausing until <reset_time_local>.
+Remaining chain (seconds): <remaining_stage_durations>. Cancelled crons: <cancelled_crons_json>.
+1. Ping every live agent AND every idle-but-warm agent with exactly this one line:
+   "status checkpoint: reply with where you stand, do not start new work"
+   An unpinged idle agent past the cache window resumes cold and re-reads its whole
+   transcript; the ping keeps its next real invocation cheap.
+2. Record any finished agent results on the task list. Dispatch nothing.
+3. Take the first duration off the remaining chain and ScheduleWakeup it, passing this
+   same prompt with that duration removed and the stage number advanced. When the
+   remaining chain is empty, schedule nothing further and treat the next firing as final.
+```
+
+### Final wakeup prompt template
+
+```
+/usage-pause final stage: the 5-hour window reset at <reset_time_local>.
+1. Ping every live and idle-but-warm agent with exactly:
+   "status checkpoint: reply with where you stand, do not start new work"
+2. Record any finished agent results on the task list.
+3. Restore every cron in <cancelled_crons_json>: CronCreate each one with its recorded
+   schedule and prompt.
+4. Hand control back to normal orchestration and resume work from the task list.
+```
+
+Fill each `<slot>` at schedule time: `<remaining_stage_durations>` is the tail of `stages_seconds` after the stage being scheduled, and `<cancelled_crons_json>` is the recorded cron list from pause time, carried verbatim through every stage.
+
+## Layout
+
+| File | Role |
+|---|---|
+| `SKILL.md` | This flow: resolve, weekly guard, stage chain, templates |
+| `scripts/resolve_usage_window.py` | The window resolver and stage planner CLI |
+| `scripts/test_resolve_usage_window.py` | Behavioral tests for parsing, staging, token reading, extraction, CLI |
+| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, stage sizing, thresholds, result keys |
+
+## Gotchas
+
+- The stored access token lives about 8 hours and the CLI rewrites it on its own schedule, so a mid-afternoon probe can find it expired even while the CLI itself still works. That is the designed exit-2 path: give a manual time.