orchestrate-agents

name

orchestrate-agents

description

Use this skill when the user asks you to coordinate work across multiple agent users (e.g., "have alice summarize the logs and bob analyze the result"), set up new agents, debug an agent that isn't responding, fan out a question to many agents at once, or compose multi-agent pipelines on a host running this `subdo` repo. Covers the `agnt`, `subdo`, `agent-ask`, `agent-chat`, `agent-broadcast`, and `agnt doctor` vocabulary and how to choose between them.

Orchestrating subdo agents

This host runs subdo: agents are real Unix users (agent_alice, agent_bob, ...), each with their own .profile, system prompt, model, and ~/bin/. You orchestrate them by composing a small set of CLIs. This skill is the decision tree.

The vocabulary in 30 seconds

Tool	Purpose
subdo <agent> <cmd> [args]	run <cmd> AS the agent (sources .profile, sets $HOME, $PATH, etc.). The only entry point that switches users.
agent-think (alias: agent-ask)	cognition ABI primitive. Reads stdin/argv, dispatches to the agent's chosen backend (pu.sh / ollama / pi / claude / apfel / ds4) per AGENT_BACKEND. Always invoked as the agent — typically via subdo agent_X agent-ask "task".
agnt <sub>	git-style dispatcher: agnt foo execs agent-foo on PATH. Subcommands: list, finger, id, log, export/import, service, doctor, card, plus the cognition family.
agent-chat <agent> [--session <id>]	interactive REPL with one agent. Wrapper that does subdo dispatch internally. With --session, multi-turn memory (backend handles storage).
agent-broadcast "task"	fan-out: ask the same question of every agent, gather replies. Iterates subdo internally.

agent-ask and agent-think are the same binary (one is a symlink to the other) — same ABI, two names. Use whichever reads better in context: subdo alice agent-ask "task" reads as a verb-object; agent-think reads as the primitive's true name. The canonical override surface is ~/bin/agent-think (per-agent customization).

Decision tree

The user wants to ask an agent something. → One-shot? subdo <agent> agent-ask "task" (the alias makes this read as "ask") → Multi-turn? agent-chat <agent> --session <id> (REPL wrapper) → Pipe data in? cat data | subdo <agent> agent-ask "task" (stdin = context, argv = task)

The user wants multiple agents to act. → Sequential pipeline (output of one feeds the next)? cat data | subdo agent_alice agent-ask "extract" | subdo agent_bob agent-ask "rank by severity" → Same task to all (gather opinions)? agent-broadcast "task" (or examples/02_fanout_vote.sh for vote-then-judge)

The user wants to inspect an agent without invoking it. → Identity / role / system prompt / .plan: agnt finger <agent> → UID, env, tools: agnt id <agent> → Recent activity: agnt log <agent> → List everything on the host: agnt list

Something's broken. → Always run agnt doctor [<agent>] first. It checks the common breakage points (AGENT_NAME mismatch, missing agents group, sudoers wrong mode, backend not on PATH, apfel-on-macOS per-user gating) and prints actionable fix: hints. --fix applies safe auto-repairs.

The user wants to create a new agent. → Linux: sudo scripts/new-agent.sh agent_<name> [--backend X --model Y] → macOS: sudo scripts/new-agent-macos.sh agent_<name> [--backend X] → Both create the user, sudoers drop-in, .profile, and add them to the agents group. Re-running is idempotent.

Patterns worth knowing about

The repo ships ~25 worked examples in examples/*.sh. The shapes you'll reach for most:

• 01_pipeline.sh — N-stage pipeline (cheap upstream → smart downstream)
• 02_fanout_vote.sh — many agents vote, judge picks
• 08_chunked_map.sh — split big input, map agents in parallel, reduce
• 09_chain_of_thought.sh — split-the-thinking across two cheap agents
• 13_agentic_task.sh — Tier 3 (Claude/pi) for multi-file refactors
• 16_mail_inbox.sh — fire-and-forget via mail(1) (drop-in, no daemon)
• 24_debate.sh — two agents argue, judge moderates

For inter-agent coordination beyond pipelines, drop files in $AGENT_SHARED_DIR (default /var/lib/agents/shared, group-writable to agents). For privacy, use the agent's own home (~agent_*/, mode 700).

Anti-patterns — don't do these

1. Don't call pu.sh / ollama / claude directly. Always go through agent-ask via subdo. The cognition ABI (docs/COGNITION-ABI.md) is what makes the system AI-agnostic; bypassing it bakes a backend into your scripts.
2. Don't sudo -iu agent_alice and run commands manually — subdo is the only entry point so audit logging works (docs/DECISIONS.md D7).
3. Don't edit ~agent_*/.profile by hand when the bootstrap script can do it. Re-running new-agent.sh is idempotent and fixes drift.
4. Don't put secrets in $AGENT_SHARED_DIR. Anyone in the agents group can read them. That dir is the coordination boundary, not a privacy boundary (docs/DECISIONS.md D22).
5. Don't try to backend-switch by passing --backend X to agent-ask. Backend is the agent's identity; change it in their .profile (or use subdo --env AGENT_BACKEND=X for a one-off).

When you're stuck

In order:

1. agnt doctor <agent> — surfaces ~10 of the most common issues with one-line fixes.
2. agnt finger <agent> — confirms identity, system prompt, .plan are what you expect.
3. subdo --list — does subdo see the agent at all? If not, the agent's home is missing one of .pu_prompt/AGENTS.md/.plan (subdo filters on those).
4. subdo --dry-run <agent> -- env — what env does the agent see when invoked?
5. cat ~agent_<name>/.profile — last resort; usually agnt doctor already reported what's wrong.

Where the docs live

• docs/COGNITION-ABI.md — the formal ABI contract (agent-think's stdin/argv/env/stdout/exit codes)
• docs/GUIDE.md — long-form patterns and recipes
• docs/DECISIONS.md — why each architectural choice was made (especially D15, D18, D19, D22, D24)
• docs/INSTALL.md — install, per-platform
• docs/TROUBLESHOOTING.md — keyed by literal error string
• examples/*.sh — copy-paste-ready patterns, each with a one-line "what + when" comment

A working session, end-to-end

Suppose the user says "have alice extract anomalies from /var/log/syslog, then bob rank them by severity":

# 1. Sanity check the agents involved.
agnt doctor agent_alice
agnt doctor agent_bob

# 2. Pipeline. Note the cognition tier escalates:
#    alice (cheap filter) → bob (slightly larger model) for ranking.
sudo cat /var/log/syslog \
  | subdo agent_alice agent-ask "extract anomaly lines, one per line" \
  | subdo agent_bob   agent-ask "rank these by severity, output as JSON"

If a step fails:

• 127 → backend tooling not installed; agnt doctor will say which.
• 2 → AGENT_BACKEND unset or backend rejected (e.g., session set on ollama). Look at stderr.
• 1 → reasoning failure; the agent ran but couldn't produce a coherent answer. Try the next tier (subdo agent_carla agent-ask "..." if she's on pi or claude).

If the user wants this on a schedule, wrap in cron with the agent's .profile env preserved — examples/cron.example shows the right shape.