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:

# 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

Main agent receives task → spawns subagent with specific scope
Subagent reads STATE.yaml → finds its assigned tasks
Subagent works autonomously → updates STATE.yaml on progress
Other agents poll STATE.yaml → pick up unblocked work
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

## 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

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 to autonomous coding agents—let agents self-organize rather than micromanaging them.

4.1 KiB Raw Blame History