OpenClaw Project Management: Coordinate Multi-Agent Projects with STATE.yaml

Managing complex projects with multiple workstreams is hard even with a great checklist. The real pain is coordination: context-switching, remembering what is blocked, and making sure parallel tasks do not collide. If you add AI agents to the workflow, the usual solution is an orchestrator: one "main" agent assigns tasks, polls updates, and routes handoffs.

That orchestrator becomes the bottleneck.

OpenClaw enables a better pattern for autonomous project management: decentralized coordination via a shared STATE.yaml file. Agents do not coordinate through endless chat messages. They coordinate through an explicit, version-controlled state document that any agent can read and update. The main session stays thin (the CEO role), while project PM subagents execute and self-organize.

This guide shows how to implement the pattern end-to-end: the file format, the delegation workflow, safe status taxonomies, git-backed audit trails, and practical prompts you can copy.

Internal links you may want later: OpenClaw use cases and the OpenClaw skills guide.

---

Why traditional project management breaks for multi-agent execution

Kanban boards and ticket systems work when humans keep them updated. In autonomous workflows, they often fail for predictable reasons:

• Orchestrator bottleneck: one agent becomes a traffic cop. Everything queues behind it.
• Context window pressure: a single agent cannot safely hold the full project state, plus all instructions, plus the work.
• Message loss: coordination that happens only in chat becomes unsearchable and easy to forget.
• Parallel collisions: two agents can unknowingly work the same task or change the same files.

What you need is:

1. A single source of truth that is easy for agents to parse.
2. A lightweight protocol for ownership, status changes, and handoffs.
3. An audit trail you can review in five minutes.

STATE.yaml is that protocol.

---

The core pattern: STATE.yaml as the project control plane

A STATE.yaml file lives inside your project folder and describes:

• The project identity
• The current tasks and their owners
• Dependencies and blockers
• Next actions (explicit handoff instructions)
• Optional metadata (repos, branches, milestones)

Example:

project: website-redesign
updated: 2026-02-10T14:30:00Z

tasks:
  - id: homepage-hero
    status: in_progress
    owner: pm-frontend
    started: 2026-02-10T12:00:00Z
    notes: "Working on responsive layout"

  - id: api-auth
    status: done
    owner: pm-backend
    completed: 2026-02-10T14:00:00Z
    output: "src/api/auth.ts"

  - id: content-migration
    status: blocked
    owner: pm-content
    blocked_by: api-auth
    notes: "Waiting for new endpoint schema"

next_actions:
  - "pm-content: Resume migration now that api-auth is done"
  - "pm-frontend: Review hero with design team"

The rule is simple: if it matters, it belongs in STATE.yaml. Status changes, blockers, outputs, and decisions should not be trapped in chat.

---

The CEO pattern: keep the main session thin

In this setup:

• The main OpenClaw session does almost no execution.
• PM subagents do the work, update state, and report back.

A healthy workflow:

1. User asks: "Refactor auth and update docs."
2. Main session spawns pm-auth-refactor.
3. PM creates/updates STATE.yaml, breaks work into tasks.
4. PM executes tasks (and can spawn its own subagents).
5. PM updates state and returns a concise report.

This keeps your main session fast and prevents tool-call waterfalls.

---

Skills and capabilities you need

This use case mostly relies on built-in OpenClaw capabilities:

• Subagent spawning and messaging
• File system read/write
• Optional: Git for history and review
• Optional: cron for periodic summaries

If you want to expand beyond file-based coordination, use the patterns from the OpenClaw skills guide to add integrations (GitHub, Linear, Slack).

---

Step-by-step setup

1) Create a folder structure

A simple structure that scales:

• projects/<project-name>/STATE.yaml
• projects/<project-name>/notes/ (optional)
• PROJECT_REGISTRY.md at workspace root

2) Create a PROJECT_REGISTRY.md

This avoids spawning duplicate PMs and helps the main agent find the right session label.

# Active Projects

| Project | PM Label | State File | Status |
|--------|----------|------------|--------|
| website-redesign | pm-website | projects/website-redesign/STATE.yaml | active |
| api-v2 | pm-api | projects/api-v2/STATE.yaml | active |

3) Add delegation rules to AGENTS.md

Main session = coordinator only.

Workflow:
1. New task arrives
2. Check PROJECT_REGISTRY.md
3. If PM exists -> send message
4. If new -> spawn PM
5. PM updates STATE.yaml and reports back

Rules:
- Main session: 0-2 tool calls max
- PM owns STATE.yaml for its project
- Commit state changes to git when possible

4) Initialize a project with a strong prompt

Copy/paste:

Create a project folder projects/website-redesign.
Create STATE.yaml as the single source of truth.
Break the project into 6-10 tasks.
Assign owners (pm-frontend, pm-backend, pm-content).
Add explicit dependencies and next_actions.
After every meaningful change, update STATE.yaml.

5) Set up a daily summary

Every day at 9 AM, summarize all active STATE.yaml files:
- done since yesterday
- in progress
- blockers
- next actions
Post to my #project-updates channel.

---

A practical task taxonomy (status, fields, and definitions)

STATE.yaml works best when you restrict statuses. Use:

• todo
• in_progress
• blocked (requires blocked_by)
• review
• done (requires output or link)

Add a lightweight definition of done:

definition_of_done:
  - "Code merged"
  - "Tests passing"
  - "Docs updated"
  - "STATE.yaml updated"

If tasks sit in in_progress for days, add last_touched and require agents to update it whenever they make progress. This prevents silent stalls and makes inactivity visible.

---

Multi-repo projects and branch awareness

For projects spanning multiple repos, include them explicitly:

repos:
  - name: frontend
    path: ~/projects/platform-frontend
    branch: feature/v2
  - name: backend
    path: ~/projects/platform-api
    branch: feature/v2

Then attach each task to a repo and optionally a path. This lets PM agents avoid conflicts and makes reviews faster.

---

Troubleshooting: when the pattern breaks

The main agent starts executing. Reinforce the CEO rule: main session delegates only.

STATE.yaml gets too big. Archive completed tasks weekly into STATE-archive.yaml.

Merge conflicts. Split ownership boundaries and encourage smaller updates.

Agents do not know what to do next. Keep next_actions explicit and actionable. If it is empty, the project is effectively stalled.

---

How ClawRapid fits in

You can run this on your own server, but you will spend time on setup: channels, cron jobs, and stable runtime.

ClawRapid is a fast path: deploy OpenClaw with the right defaults, then add your project folder and the prompts above. It is a practical way to get multi-agent project management running without infrastructure overhead.

---

FAQ

Do I need YAML specifically? No. JSON or Markdown can work. YAML is the best tradeoff: human readable, compact, and easy for agents to parse.

How many subagents should I run in parallel? Start with 2-4. Past that, coordination overhead rises quickly unless you split state by domain.

What if two agents update the same tasks? Define ownership and require agents to only update tasks they own. If conflicts still happen, split STATE.yaml by domain.

Can I sync this with Jira/Linear/Notion? Yes. Treat STATE.yaml as the control plane for agents and optionally sync outward for humans.

How do I keep state trustworthy? Require that every task marked done includes an output reference (file path, PR link, or commit hash).

Is this only for software projects? No. It works for content pipelines, research sprints, marketing launches, and any work with parallel tasks and dependencies.