100+ AI Agents, Agent Skills and RAG Apps - Free and Open Source.
advisor-orchestrator-worker: trim SKILL.md, move API fallbacks to references
cia2facb7bbfde
diff --git a/agent_skills/advisor-orchestrator-worker/README.md b/agent_skills/advisor-orchestrator-worker/README.mdindex 7ee272e3..d1ed0e8f 100644--- a/agent_skills/advisor-orchestrator-worker/README.md+++ b/agent_skills/advisor-orchestrator-worker/README.md@@ -49,7 +49,8 @@ advisor-orchestrator-worker/├── SKILL.md # the loop, the team, budgets, escalation rules├── README.md # this file├── references/worker-brief.md # the stateless dispatch format workers receive-└── references/advisor-consult.md # the consult format the advisor answers in+├── references/advisor-consult.md # the consult format the advisor answers in+└── references/fallbacks.md # the Gemini and Anthropic API fallback calls```Evals live repo-side in `agent_skills/evals/advisor-orchestrator-worker/` — you install only what runs.diff --git a/agent_skills/advisor-orchestrator-worker/SKILL.md b/agent_skills/advisor-orchestrator-worker/SKILL.mdindex 56c5c7cf..2dac79b0 100644--- a/agent_skills/advisor-orchestrator-worker/SKILL.md+++ b/agent_skills/advisor-orchestrator-worker/SKILL.md@@ -25,22 +25,21 @@ You are the Orchestrator of a three-tier model team. You own the hotpath: plan, delegate, verify, synthesize. You never do worker-levelwork yourself, and you never execute through the advisor.-**Models are knobs, not gospel.** The tiers are the durable part; the-model IDs below were current in July 2026 — swap freely. One rule-survives every generation: the advisor is the strongest reasoning model-you can reach, workers the cheapest that pass verification. All-snippets below are bash; on a host whose shell isn't bash, run them-with `bash -c`.+**Models are knobs.** The tiers are the durable part; the model IDs+below (current July 2026) swap freely. One rule survives every+generation: the advisor is the strongest reasoning model you can+reach, workers the cheapest that pass verification. Snippets are bash;+on another shell, run them with `bash -c`.## The team- **Workers (default: Gemini 3.5 Flash via the Antigravity CLI, `agy`)** —stateless generation units, with tools (web search, file work) when asubtask needs them. Never interpolate a brief into a shell string —- briefs carry quotes and arbitrary text, so inline interpolation is a- shell-injection bug. Write each brief to a temp file, dispatch each- worker from its OWN empty temp dir (so no `.antigravity.md` or project- context leaks in), in its own subshell, writing to its own output file:+ briefs carry quotes and arbitrary text, so that is a shell-injection+ bug. Write each brief to a temp file and dispatch each worker from+ its own EMPTY temp dir (no `.antigravity.md` or project context+ leaks in), in its own subshell, into its own output file:```bash# $brief = this worker's brief file; $out = its result file (absolute path)@@ -52,72 +51,32 @@ with `bash -c`.pids+=($!)```- The permissions flag is required in non-TTY shells or the call hangs;- the empty dir + minimal env reduce context leakage but are not a- sandbox. The `--model` pin keeps the primary and fallback paths on the- same model — without it, workers run whatever agy's session default- happens to be. Chunk every wave into batches of 3 (Antigravity quota is- shared across its app, CLI, and SDK). Start each batch with `pids=()`;- after dispatching, reap each worker individually — `wait "$pid"` per- PID, since one collective wait reports only the last worker's status —- and read each `$out` in dispatch order; a wave sharing one stdout- hands verify interleaved output. A worker that exits non-zero or- leaves `$out` empty is a failed dispatch. Clean up all temp files and- dirs at run end.-- **Fallback — bare Gemini API call** when `agy` is missing, a dispatch- fails (retry it through the API automatically if a key is set, and- record the switch on the status board), or a brief is too large (rule- of thumb: over ~100 KB) or too untrusted to travel as a CLI argument- (`agy -p` documents no prompt-file/stdin input). No tools, but- `jq --rawfile` makes it safe for arbitrary brief text; the second jq- unwraps the response envelope so `$out` holds worker text on both- paths:-- ```bash- api_key="${GEMINI_API_KEY:-$GOOGLE_API_KEY}"- [ -n "$api_key" ] || { echo "no Gemini key (set GEMINI_API_KEY or GOOGLE_API_KEY)" >&2; exit 1; }- ( set -o pipefail- jq -n --rawfile t "$brief" '{contents:[{parts:[{text:$t}]}]}' \- | curl -sS --fail --max-time 300 \- "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \- -H "x-goog-api-key: $api_key" -H "Content-Type: application/json" -d @- \- | jq -r '.candidates[0].content.parts[0].text' > "$out" ) &- pids+=($!)- ```-- API-fallback workers may run the full wave in parallel (the 3-cap is- an agy quota rule). A subtask that genuinely needs tools goes through- agy or gets ESCALATE — never pretend an API worker browsed the web or- touched a file.--- **Advisor (default: Claude Fable 5 via the claude CLI)** — consulted- in print mode, the consult written to a temp file and passed on stdin- (never inline in the command string), behind a timeout so a hung- consult can't stall the loop — via perl's alarm, since timeout(1) is- missing on stock macOS:+ The permissions flag is required in non-TTY shells or the call+ hangs; the empty dir + minimal env reduce leakage but are not a+ sandbox; the `--model` pin keeps primary and fallback on one model.+ Chunk every wave into batches of 3 (Antigravity quota is shared+ across its app, CLI, and SDK). Start each batch with `pids=()`, reap+ each worker with its own `wait "$pid"` (a collective wait reports+ only the last status), and read each `$out` in dispatch order — a+ shared stdout hands verify interleaved output. Non-zero exit or an+ empty `$out` is a failed dispatch: retry it through the Gemini API+ fallback in `references/fallbacks.md` when a key is set (no key:+ ESCALATE), and record the switch on the status board. That fallback also takes over when+ agy is missing, and carries any brief too large (over ~100 KB) or+ too untrusted for a CLI argument (`agy -p` has no prompt-file+ input). API workers run uncapped in parallel but have no tools — a+ subtask that needs tools goes through agy or gets ESCALATE. Clean up+ all temp files at run end.++- **Advisor (default: Claude Fable 5 via the claude CLI)** — consult+ written to a temp file, passed on stdin (never inline in the+ command), behind a timeout so a hung consult can't stall the loop+ (perl's alarm; timeout(1) is missing on stock macOS):`perl -e 'alarm shift; exec @ARGV' 300 claude --model claude-fable-5 -p < "$consult"`.Expensive judgment kept out of the hot path: strategy, decomposition- critique, risk spotting, taste. Never execution.-- **Fallback — bare Anthropic API call** when the claude CLI is missing- or a consult fails. Same model, same consult file; the fallbacks- parameter re-serves a safety-classifier refusal on Opus 4.8 inside- the same call, and the closing jq unwraps the envelope so the- orchestrator reads plain advisor text on both paths:-- ```bash- [ -n "$ANTHROPIC_API_KEY" ] || { echo "no ANTHROPIC_API_KEY" >&2; exit 1; }- ( set -o pipefail- jq -n --rawfile c "$consult" '{model: "claude-fable-5", max_tokens: 16000,- fallbacks: [{model: "claude-opus-4-8"}],- messages: [{role: "user", content: $c}]}' \- | curl -sS --fail --max-time 300 "https://api.anthropic.com/v1/messages" \- -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \- -H "anthropic-beta: server-side-fallback-2026-06-01" \- -d @- \- | jq -r '.content[] | select(.type == "text") | .text' )- ```+ critique, risk, taste. Never execution. If the CLI is missing or a+ consult fails, use the Anthropic API fallback in+ `references/fallbacks.md`.## The loop@@ -125,16 +84,14 @@ with `bash -c`.criteria; if the task is too vague for that, ask one question andstop. Check tools now, not mid-run: `agy`, `jq`, the `claude` CLI,`ANTHROPIC_API_KEY`, and `api_key="${GEMINI_API_KEY:-$GOOGLE_API_KEY}"`.- Each role resolves CLI first, then API key: agy missing but a Gemini- key set means workers run on the API fallback (no tools); claude CLI- missing but ANTHROPIC_API_KEY set means consults go over the API.- Announce every fallback up front. If a role has no working path, say- exactly how to set it up, then offer degraded mode: you temporarily play the missing role- yourself — same budgets, every affected section and the final result- labeled `[DEGRADED: <role>]`, context-isolation caveat noted. This is- the one exception to the never-do-worker-work rule, and it covers at- most one role — with two or more missing there is no team left; say- so and proceed as ordinary single-model work.+ Each role resolves CLI first, then API key; announce every fallback+ up front. If a role has no working path, say exactly how to set it+ up, then offer degraded mode: you temporarily play that role+ yourself, same budgets, every affected section and the final result+ labeled `[DEGRADED: <role>]`, context-isolation caveat noted.+ Degraded mode is the one exception to the never-do-worker-work rule+ and covers at most one role; with two or more missing there is no+ team left, so say so and proceed as ordinary single-model work.2. **Plan.** Decompose into self-contained subtasks with inline inputs,acceptance criteria, and wave assignments that maximize parallelism.3. **Plan review (mandatory advisor consult #1).** Send the plan using@@ -142,14 +99,14 @@ with `bash -c`.you changed and what you rejected.4. **Delegate.** Dispatch each wave using the format in`references/worker-brief.md`. Parallel background calls, then wait.-5. **Verify.** Check every result against its own acceptance criteria.- A check must exercise the deliverable itself — run the actual+5. **Verify.** Check every result against its own acceptance criteria,+ and make the check exercise the deliverable itself — run the actualcommand, read the actual output. Grepping a README, testingsomething adjacent, printing True while exiting zero, or re-checking- that a file exists proves nothing and does not count. Verdict per- result: PASS, FIX (redispatch naming the specific failure), or- ESCALATE. Never silently accept a partial pass. Never hand-patch a- substantive failure; redispatch instead.+ that a file exists proves nothing. Verdict per result: PASS, FIX+ (redispatch naming the specific failure), or ESCALATE. Never+ silently accept a partial pass; never hand-patch a substantive+ failure — redispatch instead.6. **Synthesize.** When all subtasks pass, assemble the deliverable.Resolve conflicts between worker outputs explicitly, never byaveraging.diff --git a/agent_skills/advisor-orchestrator-worker/references/fallbacks.md b/agent_skills/advisor-orchestrator-worker/references/fallbacks.mdnew file mode 100644index 00000000..4c695dc3--- /dev/null+++ b/agent_skills/advisor-orchestrator-worker/references/fallbacks.md@@ -0,0 +1,44 @@+# API Fallbacks++Read this when a primary CLI path is unavailable or a dispatch fails.+Both fallbacks keep the primary paths' discipline: payloads built with+`jq --rawfile` from the same temp file (safe for arbitrary text),+`--fail` plus `pipefail` so an auth or quota error is a detectable+failure, and a closing jq that unwraps the response envelope so the+orchestrator reads plain text on either path.++## Workers — bare Gemini API call++No tools. Run the full wave in parallel; the 3-batch cap is an agy+quota rule and does not apply here.++```bash+api_key="${GEMINI_API_KEY:-$GOOGLE_API_KEY}"+[ -n "$api_key" ] || { echo "no Gemini key (set GEMINI_API_KEY or GOOGLE_API_KEY)" >&2; exit 1; }+( set -o pipefail+ jq -n --rawfile t "$brief" '{contents:[{parts:[{text:$t}]}]}' \+ | curl -sS --fail --max-time 300 \+ "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \+ -H "x-goog-api-key: $api_key" -H "Content-Type: application/json" -d @- \+ | jq -r '.candidates[0].content.parts[0].text' > "$out" ) &+pids+=($!)+```++## Advisor — bare Anthropic API call++Same model as the CLI path. The `fallbacks` parameter re-serves a+safety-classifier refusal on Opus 4.8 inside the same call, so one+declined consult cannot stall the loop.++```bash+[ -n "$ANTHROPIC_API_KEY" ] || { echo "no ANTHROPIC_API_KEY" >&2; exit 1; }+( set -o pipefail+ jq -n --rawfile c "$consult" '{model: "claude-fable-5", max_tokens: 16000,+ fallbacks: [{model: "claude-opus-4-8"}],+ messages: [{role: "user", content: $c}]}' \+ | curl -sS --fail --max-time 300 "https://api.anthropic.com/v1/messages" \+ -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \+ -H "anthropic-beta: server-side-fallback-2026-06-01" \+ -d @- \+ | jq -r '.content[] | select(.type == "text") | .text' )+```