What you’ll learn: How to go from zero to a running multi-agent org in 3 commands — templates, ORG.md structure, MCP tool usage, error recovery, and the boot sequence protocol.
You are an AI agent that needs to coordinate other agents. OpenSpawn gives you an org chart, task routing, escalation protocols, and a credit system — defined in a single markdown file called ORG.md.
The core idea: One file defines your entire agent organization. Everything else — the CLI, the coordinator, the dashboard — exists to execute what’s in the ORG.md.
That’s it. The Python API boots with SQLite, seeds agents from your ORG.md, and spawns Claude Code CLI subprocesses for each agent. You now have an Onboarding Lead, Data Migration Specialist, Integration Engineer, and Success Agent — coordinated and visible in the dashboard.
Q: Do I need API keys?
No. Demo/simulation mode works out of the box with zero configuration.
Q: What just happened?
init scaffolded ORG.md (your org definition), agent workspaces, and config
start booted the FastAPI server, seeded agents into SQLite, and started the asyncio scheduler for background jobs (SLA monitoring, escalation, status sync)
Q: What prerequisites do I need?
Node.js 18+, Python 3.12+, and uv (Python package manager)
ORG.md is validated automatically when openspawn start boots the API. The seeder parses your org definition, checks hierarchy consistency, and reports errors before spawning agents.
Returns a full overview: all agents, task counts, budget status.
Q: How do agents coordinate work?
Via coordination tools. task_create assigns work, task_claim prevents duplicate effort, task_complete records results. message_send handles structured communication (TASK/RESULT/ESCALATION/DECISION types).
Q: Where’s the full tool reference?
See docs/llms.txt — the “Coordination Tools” section lists all 14 tools with parameters.
When openspawn start boots your org, the API seeds agents from ORG.md into SQLite, then spawns Claude Code CLI subprocesses (with a configurable concurrency cap). The lead agent follows a planning-first boot sequence:
2. Read PLAN.md → check if resuming a previous run
3. Write PLAN.md → break mission into phased tasks with assignments
4. Create tasks → task_create via MCP for current-phase items
5. Monitor → org_status every 5 minutes
6. Adapt → update PLAN.md when things change
7. Complete → escalate "mission complete" when done
Example for a SaaS onboarding org: The Onboarding Lead reads the ORG.md, sees the 48-hour track playbook, writes PLAN.md with phases (Migration, Integration, Config, Go-Live), creates tasks for each specialist, and monitors via org_status until the customer completes their first workflow.
Q: Why planning first?
Plans are cheaper than confusion. A 30-second PLAN.md prevents hours of rework, wasted tokens, and “what did you mean?” messages.
Q: What goes in PLAN.md?
Mission statement (from ORG.md)
Phase breakdown (what order to build)
Task table with assignments, priorities, dependencies, and status
Success criteria and definition of done
Q: How do workers know what to do?
Workers read PLAN.md on startup, then claim their assigned tasks via task_claim. They don’t wait for chat messages — the plan IS the assignment.
Q: What if the plan needs to change?
The lead updates PLAN.md first, then updates MCP tasks to match. PLAN.md is always the source of truth.
See templates/boot-sequence.md for the full protocol, templates/SOUL-lead.md for the lead agent template, and templates/SOUL-worker.md for the worker template.