mirror of
https://github.com/hesamsheikh/awesome-openclaw-usecases.git
synced 2026-02-20 01:35:11 +00:00
122 lines
4.1 KiB
Markdown
122 lines
4.1 KiB
Markdown
# Autonomous Project Management with Subagents
|
|
|
|
Managing complex projects with multiple parallel workstreams is exhausting. You end up context-switching constantly, tracking status across tools, and manually coordinating handoffs.
|
|
|
|
This use case implements a decentralized project management pattern where subagents work autonomously on tasks, coordinating through shared state files rather than a central orchestrator.
|
|
|
|
## Pain Point
|
|
|
|
Traditional orchestrator patterns create bottlenecks—the main agent becomes a traffic cop. For complex projects (multi-repo refactors, research sprints, content pipelines), you need agents that can work in parallel without constant supervision.
|
|
|
|
## What It Does
|
|
|
|
- **Decentralized coordination**: Agents read/write to a shared `STATE.yaml` file
|
|
- **Parallel execution**: Multiple subagents work on independent tasks simultaneously
|
|
- **No orchestrator overhead**: Main session stays thin (CEO pattern—strategy only)
|
|
- **Self-documenting**: All task state persists in version-controlled files
|
|
|
|
## Core Pattern: STATE.yaml
|
|
|
|
Each project maintains a `STATE.yaml` file that serves as the single source of truth:
|
|
|
|
```yaml
|
|
# STATE.yaml - Project coordination file
|
|
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"
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **Main agent receives task** → spawns subagent with specific scope
|
|
2. **Subagent reads STATE.yaml** → finds its assigned tasks
|
|
3. **Subagent works autonomously** → updates STATE.yaml on progress
|
|
4. **Other agents poll STATE.yaml** → pick up unblocked work
|
|
5. **Main agent checks in periodically** → reviews state, adjusts priorities
|
|
|
|
## Skills You Need
|
|
|
|
- `sessions_spawn` / `sessions_send` for subagent management
|
|
- File system access for STATE.yaml
|
|
- Git for state versioning (optional but recommended)
|
|
|
|
## Setup: AGENTS.md Configuration
|
|
|
|
```text
|
|
## PM Delegation Pattern
|
|
|
|
Main session = coordinator ONLY. All execution goes to subagents.
|
|
|
|
Workflow:
|
|
1. New task arrives
|
|
2. Check PROJECT_REGISTRY.md for existing PM
|
|
3. If PM exists → sessions_send(label="pm-xxx", message="[task]")
|
|
4. If new project → sessions_spawn(label="pm-xxx", task="[task]")
|
|
5. PM executes, updates STATE.yaml, reports back
|
|
6. Main agent summarizes to user
|
|
|
|
Rules:
|
|
- Main session: 0-2 tool calls max (spawn/send only)
|
|
- PMs own their STATE.yaml files
|
|
- PMs can spawn sub-subagents for parallel subtasks
|
|
- All state changes committed to git
|
|
```
|
|
|
|
## Example: Spawning a PM
|
|
|
|
```text
|
|
User: "Refactor the auth module and update the docs"
|
|
|
|
Main agent:
|
|
1. Checks registry → no active pm-auth
|
|
2. Spawns: sessions_spawn(
|
|
label="pm-auth-refactor",
|
|
task="Refactor auth module, update docs. Track in STATE.yaml"
|
|
)
|
|
3. Responds: "Spawned pm-auth-refactor. I'll report back when done."
|
|
|
|
PM subagent:
|
|
1. Creates STATE.yaml with task breakdown
|
|
2. Works through tasks, updating status
|
|
3. Commits changes
|
|
4. Reports completion to main
|
|
```
|
|
|
|
## Key Insights
|
|
|
|
- **STATE.yaml > orchestrator**: File-based coordination scales better than message-passing
|
|
- **Git as audit log**: Commit STATE.yaml changes for full history
|
|
- **Label conventions matter**: Use `pm-{project}-{scope}` for easy tracking
|
|
- **Thin main session**: The less the main agent does, the faster it responds
|
|
|
|
## Based On
|
|
|
|
This pattern is inspired by [Nicholas Carlini's approach](https://nicholas.carlini.com/) to autonomous coding agents—let agents self-organize rather than micromanaging them.
|
|
|
|
## Related Links
|
|
|
|
- [OpenClaw Subagent Docs](https://github.com/openclaw/openclaw)
|
|
- [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)
|