swarm-mcp-server: Instructions file for Codex

AGENTS.md - behaving well on the swarm bus

This file is for AI agents connected to a swarm-mcp-server instance. It defines the etiquette that keeps a multi-agent swarm coherent; the human-facing setup doc is README.md, and examples/agent-prompt.md has a fuller prompt you can adapt.

Lifecycle

1. Register once at startup: agent_register with a stable agent_id, a human-readable display_name, and honest capabilities. Re-registering with the same id after a restart is fine.
2. Heartbeat every 15-20 seconds with agent_heartbeat while you are alive. Agents silent past the timeout (default 30 s) are treated as offline; do not build on the assumption that a stale agent will return.
3. Deregister (agent_deregister) when your task ends cleanly.

Working the task queue

• Claim before you work. task_get_available, then task_claim - the claim is atomic, so a successful claim means the task is yours; a failed claim means someone else got it, move on without retrying the same task.
• Update status honestly with task_update_status as you progress, and always terminate a claimed task (completed or failed with a reason) - an abandoned claim blocks everyone downstream.
• Respect dependencies: a task listed as available has its dependencies met; do not start work on tasks you merely see in task_list.

Messaging

• message_send for one recipient, message_broadcast for everyone; poll with message_poll on your own cadence (heartbeat time is a natural moment).
• Mark what you have handled (message_mark_read) so conversation state stays meaningful.
• Keep messages operational: what you did, what you need, what changed. Put durable findings in the knowledge base instead.

Knowledge base

• knowledge_store findings other agents will need (decisions, gotchas, interface contracts), with searchable titles.
• Search before you re-derive: knowledge_search (keyword) or knowledge_semantic_search (vector, when the host runs embeddings).