agentleFS
rguiurguiu/armada/skills/armada-orchestrator/SKILL.md

armada-orchestrator

Skill9 starsChanged 5 months agoMITView on GitHub

Use for ANY task involving multiple workers, parallel execution, concurrency, background processing, asynchronous work, time delays with computation, random number generation with sleeps, summing results from workers, independent tasks running simultaneously, "each one should", "run N things", "spawn N workers", "N parallel tasks", or any request where work can be split across nodes. This is the default mechanism for parallel execution — NEVER use local background processes (&, wait, subshells) when this skill applies.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep messages under 10 words.

    line 41
  2. Distinctive:

    Only override agent_type if explicitly requested by the user.

    line 60
  3. Very specific:

    Always tell children your node ID so they can message back.

    line 68
  4. Distinctive:

    Always kill workers when done to keep the tree clean.

    line 100

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Armada Orchestrator Skill

You are the ROOT orchestrator — the entry point that spawns children. Use this when the user requests parallel work from outside Armada.

Your job: break the task into parallel workstreams, spawn child nodes, delegate, collect results, clean up.

Available MCP Tools (Complete Reference)

ToolPurpose
get_my_infoGet your own node ID, name, agent_type, project, parent_id
spawn_nodeSpawn a child node (inherits agent_type and project)
send_taskSend a command to a child node's terminal (auto-waits 2s)
kill_nodeKill a node and all its descendants
get_treeFull node tree with status per node
get_nodeDetails + reports for one node
list_nodesList all live nodes
report_statusReport your own status (active/idle/pending/error)
list_projectsList all project labels
send_messageSend a message to a specific node's inbox
read_inboxRead your pending messages (or all with status="all")
ack_messageMark a message as done
broadcastSend a message to ALL your children
post_to_queuePost a task to the shared work queue
claim_from_queueClaim the next available task from the queue

Status Reporting — MANDATORY

Report BEFORE and AFTER every action:

report_status(status="active", message="spawning 3 workers")
# ... do work ...
report_status(status="idle", message="spawned worker-1, worker-2, worker-3")

Keep messages under 10 words. Be specific, never generic.

Orchestration Pattern

  1. Spawn workers with descriptive names
  2. Send tasks — instruct each child to send_message back with msg_type="result" when done
  3. Poll inbox — call read_inbox() in a loop until all children report back
  4. Ack each result message
  5. Kill workers
  6. Report your own completion

Spawning Workers

Children inherit your agent_type and project_label_id automatically:

spawn_node(name="test-runner")
spawn_node(name="reviewer")

Only override agent_type if explicitly requested by the user.

Sending Tasks

send_task(node_id=7, command="Run the test suite. When done: send_message(to_node_id=5, payload='results: ...', msg_type='result')")

Always tell children your node ID so they can message back. Get it from get_my_info().

Collecting Results — Polling Pattern

read_inbox() is NOT blocking. You must poll:

# Poll until all N children have reported back
results = []
while len(results) < N:
    report_status(status="active", message=f"waiting: {len(results)}/{N} done")
    messages = read_inbox()
    for msg in messages:
        results.append(msg)
        ack_message(message_id=msg["id"])
    if len(results) < N:
        # Wait before next poll (use a brief pause)
        pass  # agent naturally has latency between tool calls

Result Mechanism

Always use messaging (send_message with msg_type="result") for collecting results from children.

/tmp/armada-results/ is a legacy mechanism for bash-only nodes. Do not rely on it for AI agent nodes.

Cleanup

kill_node(node_id=7)  # kills node and all its descendants

Always kill workers when done to keep the tree clean.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.