OpenClaw Autonomous Project Management: STATE.yaml Coordination Pattern
Coordinate multi-agent projects using a shared STATE.yaml pattern so parallel subagents stay aligned.
0) TL;DR (3-minute launch)
- In multi-agent projects, a single orchestrator quickly becomes a bottleneck.
- Workflow in short: Main session receives new project task → spawn PM subagent (label: pm-{project}-{scope}) → PM reads/writes STATE.yaml (todo/in_progress/blocked/done) → PM optionally spawns specialists for parallel subtasks → specialists publish outputs + update state ownership fields → main session reviews snapshots and reports status to user
- Start fast: Create a STATE.yaml template with task id, owner, status, blocker, output, and timestamps.
- Guardrail: Define explicit ownership rules for state edits to prevent concurrent overwrite.
1) What problem this solves
In multi-agent projects, a single orchestrator quickly becomes a bottleneck. This pattern replaces constant coordination chatter with a shared STATE.yaml contract, so parallel subagents can self-coordinate, unblock each other, and keep the main session focused on strategy-level decisions.
2) Who this is for
- Operators responsible for team coordination decisions
- Builders who need repeatable delivery ops workflows
- Teams that want automation with explicit human checkpoints
3) Workflow map
Main session receives new project task
-> spawn PM subagent (label: pm-{project}-{scope})
-> PM reads/writes STATE.yaml (todo/in_progress/blocked/done)
-> PM optionally spawns specialists for parallel subtasks
-> specialists publish outputs + update state ownership fields
-> main session reviews snapshots and reports status to user4) MVP setup
- Create a
STATE.yamltemplate with task id, owner, status, blocker, output, and timestamps - Adopt a stable PM label convention (for example:
pm-auth-refactor) - Keep main session in CEO mode: spawn/send/review; execution happens in PM agents
- Version state transitions in git (or an append-only changelog) for auditability
- Pilot with one project and 2 parallel subagents before scaling further
5) Prompt template
You are PM agent [pm-project-scope]. Operate via STATE.yaml as source of truth. Loop: 1) Read STATE.yaml and pick your assigned or unblocked task. 2) Execute task and save concrete output path(s). 3) Update STATE.yaml fields: status, owner, notes, blockers, completed time. 4) If blocked, write exact unblock condition and stop. Rules: - Do not hide work outside state file. - Keep updates small and frequent. - Escalate to main session when priority conflict appears.
6) Cost and payoff
Cost
Primary costs are model calls, integration maintenance, and periodic prompt tuning.
Payoff
Faster execution cycles, fewer context switches, and clearer decision quality over time.
Scale
Add role-specific subagents, stronger evaluation metrics, and staged automation permissions.
7) Risk boundaries
- Define explicit ownership rules for state edits to prevent concurrent overwrite
- Require output paths/evidence for every completed task to avoid "phantom done" states
- Escalate blocked tasks after a fixed timeout instead of infinite retry loops
- Use version control for state changes so rollback and audit are always possible
9) FAQ
How quickly can this workflow deliver value?
Most teams see meaningful results within 1-2 weeks when they keep the initial scope narrow and measurable.
What should stay manual at the beginning?
Keep ambiguous, high-risk, or customer-impacting actions behind explicit human approval until quality is proven.
How do we prevent automation drift over time?
Review logs weekly, sample outputs, and tune prompts/rules as data patterns and business goals change.
What KPI should we track first?
Track one leading metric (speed or coverage) plus one quality metric (accuracy, escalation rate, or user satisfaction).