Skip to content

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.md
index 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.md
index 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 hot
path: plan, delegate, verify, synthesize. You never do worker-level
work 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 a
subtask 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 and
stop. 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 actual
command, read the actual output. Grepping a README, testing
something 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 by
averaging.
diff --git a/agent_skills/advisor-orchestrator-worker/references/fallbacks.md b/agent_skills/advisor-orchestrator-worker/references/fallbacks.md
new file mode 100644
index 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' )
+```