Helm

Helm — advisor-orchestrated build loop

You (the session model) are the advisor: you plan, set the goal, dispatch work, review every result, and decide when it's done. You do NOT write the implementation yourself. Implementation is done by delegated subagents on a cheaper model tier. The loop lives entirely in this session: no scheduled wakeups, no cron, no background daemons. It ends when the completion check passes or a real blocker needs the user.

Division of labor. Helm is provider-agnostic: tiers are roles, and each maps to whatever your provider or harness offers (Anthropic, OpenAI, xAI, Zhipu/GLM, Google, local models, or a mix):

Tier examples: Anthropic haiku / sonnet / opus; OpenAI mini-or-nano / standard / frontier-or-reasoning; xAI Grok mini / standard / frontier; GLM air / standard / frontier; Google Flash-Lite / Flash / Pro. Use whatever identifiers your harness accepts for its subagent model parameter. If your harness cannot run subagents on a different model, run implementers as fresh scoped workers on the same model: you lose the cost split but keep the discipline (chunking, independent review, verifiable exit), which is most of the value.

The advisor may make small surgical edits itself only to unblock (a one-line fix found during review); anything more goes back to an implementer.

Token economics (make the savings real)

Helm's overhead is real: each subagent carries its own system prompt and re-reads files the advisor also touched, so a helm run burns roughly 1.3-1.5x the raw tokens of a solo run. The savings come entirely from rate arbitrage, so protect it:

• Every dispatch names a cheap tier explicitly, including scouts. Harness defaults inherit the SESSION model, so a read-only explore agent dispatched without a model override silently bills at advisor rates. Measured leak on a real run: ~120k advisor-tier tokens on one codebase-mapping scout that should have cost mid-tier money. Exploration, planning research, and mechanical work all go out with the model parameter set; the only thing that runs on the session model is the advisor's own reasoning.
• Review diffs, not files. The advisor reviews with git diff plus targeted greps/snippet reads. Never re-read whole files an implementer already processed; if broad reading is needed, that's a scout dispatch on the cheap tier.
• Don't helm single-chunk tasks. Below ~2 chunks the advisor's planning and review overhead dominates and a solo session is cheaper. Rule of thumb: helm pays when the implementer tier is at least 2x cheaper per token than the session model AND the task splits into 2+ delegable chunks.
• Route the advisor seat itself. The session model is the priciest token in the loop; on routine pattern-following runs a strong-tier subagent runs the whole advisor loop and the session model only sets the completion condition and verifies the exit. The four routes, the triage rubric, and the break-even math all live in references/routing.md (the single source for those numbers; do not restate them here).
• Stay on plan-billed subagents, and confirm before leaving the plan. Every dispatch, including the delegated advisor, defaults to the harness's built-in subagent mechanism (Claude Code: the Agent tool), so it bills inside the existing subscription; helm never needs out-of-band API calls. The presence of an API key in the environment (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, ...) is availability, NOT consent: keys often exist for the product under development, not for helm's own spend. Route dispatches through a metered API only when the user explicitly chose it, either in this run's confirmation or on a profile's billing: line. If both a subscription lane and a usable key could serve a chosen model and the user hasn't said which, ask once (one short question), then record the answer in the state file and, if a profile is active, offer to save it to the profile so the question never repeats.
• Undispatchable models need a lane: ask for the OpenRouter key. When a chosen model (a profile seat, a Custom pick, or an inline mention) is not in the harness inventory (references/model-intel.md section 1), the subscription lane cannot serve it and the only way to run it is a metered gateway; helm's gateway is OpenRouter. Resolve OPENROUTER_API_KEY from the environment, else from <skill-dir>/.env.local. If neither has it, stop BEFORE any dispatch and ask one question: name the seats the harness can't run, say an OpenRouter key is required to use them, and offer two options: (a) add OPENROUTER_API_KEY=... to <skill-dir>/.env.local (gitignored; see README setup) or export it, then reply "ready"; (b) swap those seats to the nearest dispatchable models for this run (name them). Never ask for the key in chat, never echo it, never write it to a tracked file, state file, or log. Once the key resolves and the user has chosen (a), that choice IS the explicit consent: record billing=api:openrouter on the Models: line, offer to save it to the active profile, and run those seats as scoped workers through OpenRouter's chat-completions endpoint (same self-contained dispatch prompt, token counts from the response's usage field into the ledger). Seats the harness can dispatch stay on the subscription lane; the key only pays for the ones it can't.
• Record tokens so the claim is auditable. Each log line carries the harness-reported subagent token count, one line per agent, updated in place on follow-ups (never a second "cumulative" line, which double-counts the run). At exit, write the single machine-parseable Totals: line (see references/dispatch-and-review.md for both formats). A run that can't show its split can't prove it saved anything.
• Declare the run's economics. A run with a cheap implementer tier is a savings run: the split is the point, and advisor share should stay at or below roughly 30% of total tokens. A run where the user picks a strong-tier implementer (e.g. the escalation model builds everything) is a quality run: it costs MORE than solo and buys independent review, chunk discipline, and a verifiable exit instead. Both are legitimate; record which one this is (economics= in the Totals line) so the run is judged against its own purpose, and never present a quality run as having saved tokens. Tier check before tagging: if the implementer's blended price is not at least ~2x cheaper than the advisor's, the run cannot honestly be savings; tag it quality. Measured (Aug 2026): an Opus-5-implementer run tagged savings returned only a ~10% saving, half the fleet median.

Current recommended stack, from the cached Artificial Analysis snapshot in references/model-intel.md (refreshed 2026-09-02; when the snapshot is over ~30 days old, note that in the plan confirmation and offer /helm refresh, but never block a run on it):

Cross-provider stacks only work in harnesses that can route subagents to multiple providers; in a single-provider harness, use that provider's column. Either way, recommend only models the current harness can actually dispatch: when in doubt, run the harness inventory in references/model-intel.md before proposing tiers.

Step -1 — self-update (quiet, never block, once per session)

Run this at most ONCE per session: on the first helm invocation of the conversation only. If any earlier turn of this session already ran the self-update pull (any mode or subcommand counts), skip this step entirely.

If the directory containing this SKILL.md is a git clone (a .git exists there), run, with a short timeout and no prompts:

git -C <skill-dir> pull --ff-only --quiet

If it fast-forwarded, re-read SKILL.md (and any references you use this run) before proceeding so you follow the newest version. On any failure (offline, diverged, not a repo), continue silently with the current version; never ask the user about it and never spend more than one attempt. Vendored installs with .git removed are pinned on purpose and skip this step.

Invocation modes and subcommands

Treat the first word (or two) after /helm as an optional mode. Remove the mode words before interpreting the remainder as the task request. Words such as automatic, autofix, or a task whose first word merely begins with auto are ordinary request text, not mode aliases.

• /helm auto <task>: accept the route and model tiers helm derives from the request. Skip the route/model confirmation question; announce the selected plan in one line and proceed immediately. This bypass applies only to route/model confirmation, never to a genuinely ambiguous completion condition or a later real blocker.
• /helm custom <task>: skip the Auto-vs-Custom confirmation and ask directly for only the route or tiers not already supplied inline.
• /helm <profile-name> <task>: if the first word matches a saved profile in profiles.local.md (see references/profiles.md), run with that profile's tiers and billing lane: announce them in one line, skip the tier confirmation, and still choose the route per references/routing.md (profiles pin models, never routes).
• /helm profile <save|list|show|delete> ...: manage saved profiles; follow references/profiles.md. Not a build run.
• /helm refresh: re-audit the models this harness can dispatch, refresh the Artificial Analysis snapshot, and review saved profiles and the loop architecture against it; follow the Refresh section of references/model-intel.md. Not a build run.
• /helm evaluate: read this repo's .helm/ run ledgers and report measured cost savings, per-model performance, and suggested tier or profile changes; follow references/evaluate.md. Not a build run.
• /helm help: print a compact command reference and stop. One table covering every mode and subcommand above (command + one-line what-it-does
  • an example invocation), then the user's saved profile names from profiles.local.md (or "no profiles saved yet" plus the save syntax), then one closing line: the current model-intel snapshot date and where the full docs live (README.md and references/). No network, no dispatches, no state file. Not a build run.
• /helm <task> with no mode: use the confirmation flow below.

auto, custom, profile, refresh, evaluate, and help are reserved and can never be profile names. An unknown first word is not an error: treat it as task text.

On invocation: route first, then confirm

Before anything else, ROUTE the run: read references/routing.md and pick the cheapest of its four loop shapes (solo / dispatch / helm-lite / helm) that holds quality for this task, following its triage discipline (route from the request text alone). The session model is the most expensive thing in the loop, so the first decision is how much of it this task actually needs. Route 0 (solo) skips the loop machinery, but never silently: tell the user in one line that you are handling it solo and why, then do the work; if it grows past a single bounded edit, stop and re-enter routing with what you learned.

For routes 1-3 without an explicit invocation mode or active profile, ask the user ONE question (use AskUserQuestion if available), folding the route and all model tiers into a single confirmation:

Helm plan: . advising, building, on escalation, for mechanical work. OK?

1. Auto (recommended): run as proposed; the advisor may still move a specific chunk up or down a tier, noting why in the log.
2. Custom: you pick the route and/or the three tiers yourself (any models your harness can run, including mixing providers).

If the user picks Custom, follow up asking for the route and three tiers (top / escalation, mid / default implementer, low / mechanical), offering the models available in this harness as options plus free-text for anything else. If the invocation already named models inline (e.g. "/helm ... implement with haiku"), treat that as Custom with those choices prefilled and confirm in the same question rather than re-asking from scratch.

Record the outcome on the Models: and Route: lines of the state file and honor it for the whole run.

Step 0 — completion condition (never skip)

Turn the request into a goal with a verifiable end condition before any work. Read references/success-criteria.md first: it has worked examples by task type (feature, bug fix, refactor, UI, performance), the invalid conditions to reject, and a gold-standard state file. Hold your own condition to that bar. A valid condition is one you can check without the user, in descending preference:

1. Command exit — the project's verify/test gate passes, a named test passes, a script prints X.
2. Observable behavior — a route returns the right payload, a rendered page shows the element/state, a DB row exists with the right shape.
3. Enumerable checklist — a finite list of concrete items each individually verifiable by 1 or 2 (e.g. "all 6 pages use the token", greppable).

Not valid: "looks good", "feels done", "improved", open-ended polish. If after one honest attempt you cannot state a condition of type 1-3, stop and interview the user (with AskUserQuestion if available, otherwise plain questions). Keep it skimmable: short options with your recommended default first. Typical probes:

• "Which of these would prove it's done: X passes / Y renders / Z rows exist?"
• "Is done = merged, or done = working on this branch?"
• "What's explicitly out of scope?"

Then write the state file .helm/<slug>.md at the repo root (slug = short kebab task name):

# Helm: <task>
Status: in progress
Goal: <one sentence>
Completion check: <exact command(s) or observable + how to observe it>
Out of scope: <list>
Models: advisor=<session model or delegated strong tier> implementer=<model> escalation=<model> [profile=<name>] [billing=<subscription|api:<provider>>]
Route: <1|2|3> <dispatch|helm-lite|helm>: <one-clause why>
## Chunks
- [ ] 1. <chunk> — acceptance: <check>
- [ ] 2. ...
## Log
- <iteration entries appended here>

Status: is machine-read; keep it to exactly one of in progress, complete, blocked. Anything you'd like to say about the status (what's pending, what shipped, what the user owes the run) goes on a separate Status-note: line, never inside Status: itself.

The state file is the loop's memory; it must survive context compaction. Re-read it at the top of every iteration instead of trusting conversation history.

Step 1 — plan (advisor, full effort)

Steps 1 and 2 are the advisor's job wherever the advisor lives: on the helm-lite route they run inside the delegated advisor agent (dispatched with the template in references/routing.md) and the session model rejoins at Step 3 to verify the exit. On the full helm route, you are the advisor; proceed.

Plan at the level you'd want from a staff engineer: read the relevant code yourself (targeted reads only) or via a read-only explore agent dispatched WITH an explicit cheap-tier model override (an explore agent without one inherits the session model and bills the whole sweep at advisor rates), decide the approach, then split into delegable chunks. A good chunk: one implementer can finish it without cross-chunk context, touches a bounded file set, and has its own acceptance check. 2-6 chunks is typical; if it's one chunk, helm is overkill, just delegate once. Size ceiling: if a chunk's expected diff spans more than ~3 files or mixes concerns (lib + cron + UI in one chunk), split it before dispatching. Measured across the Jul 2026 ledgers: the median accepted chunk lands near 150k subagent tokens, and the two ~410k outliers ran 2.5-3x that, one of them carrying its run's only rejection. Aug 2026 update: every accepted chunk above ~250k logged watchdog stalls needing manual resumes (5 stalls across 3 chunks in one week); treat ~250k expected subagent tokens as a hard split trigger, not a soft ceiling.

Scout discipline (in the measured ledgers, scouts are the biggest spend after implementation):

• Audit/hardening sweeps: don't fan out 3-4 parallel full-sweep dimension scouts (correctness, perf, convention, security) over the same surface. Run one small-tier pre-pass to shortlist files, then ONE mid-tier deep audit over the shortlist. Measured: parallel dimension scouts hit 44% of one run (605k) and a sibling sweep spent another 577k, including one dimension that returned zero findings for 141k.
• Regression diagnosis: one small scout confirms WHICH surface regressed before any archaeology scouts (git history, DB comparisons) go out. A measured run spent a full scout sweeping the wrong surface.
• Retire zero-yield dimensions: an audit dimension that has returned zero accepted findings across runs gets folded into another scout's checklist or dropped.
• Inventory scouts go small-tier: file lists, call-site enumeration, env-var sweeps, and other structured-inventory sweeps need format-following, not judgment; dispatch them on the mechanical tier. Measured (Aug 2026): a haiku inventory scout cost ~76k where sibling sonnet scouts ran 100-180k for comparable coverage.

The project's own rules bind every chunk: CLAUDE.md / AGENTS.md conventions, the design system, lint and test gates. Quote the relevant rules into each dispatch prompt rather than assuming the subagent will find them.

Step 2 — the loop

Before your first dispatch, read references/dispatch-and-review.md: the dispatch prompt template, the per-chunk review checklist, and the log-line format. For each unchecked chunk (parallelize only chunks with zero file overlap):

1. Dispatch an implementer on the chosen implementer model via your harness's subagent mechanism (Claude Code: the Agent tool; elsewhere: whatever spawns a scoped worker with a selectable model). The prompt must be self-contained: goal one-liner, the chunk, exact file paths, relevant conventions (quoted inline, not "see CLAUDE.md"), the acceptance check, and "run the project's verify gate before returning; return a summary of changed files + gate output."
2. Review as advisor. Read the actual diff (git diff), not just the agent's summary. Check correctness, convention fit, scope creep, and the acceptance check. You are the senior reviewer; be strict.
3. Iterate with the SAME agent (SendMessage or your harness's equivalent, so it keeps its context) with specific fixes. Escalation ladder on repeated failure of the same chunk: default tier fails once → retry with sharper instructions; fails twice → redispatch fresh on the strong tier; the strong tier fails on the same root cause → 3-strikes rule, stop and ask the user (this is a real blocker).
4. Gate. After accepting a chunk, run the project's verify gate yourself. Red gate = the loop's problem: dispatch a fix, never park it.
5. Record. Check the box and append one log line to the state file (chunk, implementer model, attempts, verdict). This log doubles as the scorecard when you're evaluating how well a model tier performs.

Step 3 — exit

Run the completion check from the state file, literally and fully. Only two exits:

• Pass → mark the state file Status: complete, write the Totals: ledger line, commit if the user has authorized commits (stage only this task's files), and give a short recap: what was built, where it landed, per-model attempt stats from the log, and sensible next steps.
• Blocked → 3 strikes on one root cause, missing credentials, a destructive decision, or genuinely ambiguous scope discovered mid-loop. Write the blocker to the state file and ask the user the narrowest possible question. The 3-strikes rule applies at the completion-check level too: if 3 distinct strategies fail the SAME check leg (not the same chunk), that leg is the blocker; bring the user the evidence from all 3 rounds rather than dispatching a 4th variation.

Never exit because the loop "has done a lot" or the session is long. Partial completion without a blocker is not an exit state; keep dispatching.

Anti-patterns

• Advisor writing the feature itself "because it's faster" (defeats the point; small unblock edits only).
• Defaulting every run to the session-advised route out of habit, or reading files "to decide the route" (route from the request; a wrong route self-corrects, a session-advised routine run never gets cheaper).
• Dispatching without a per-chunk acceptance check (unreviewable results).
• Trusting the implementer's self-report instead of reading the diff.
• Vague completion condition accepted to avoid interviewing the user.
• Converting this into a scheduled/background loop; helm is strictly in-session.