Quick Start

This guide gets you from zero to a running multi-agent plan in under 5 minutes. You’ll write a simple plan, execute it, and watch agents collaborate in real-time.

Run a Plan

1. Create a plan directory

   Every plan lives in its own directory. The engine reads PLAN.md as the entry point.

   mkdir -p my-first-plan

2. Write your plan

   Create my-first-plan/PLAN.md with the following content:

   # Build a CLI Todo App
   
   ## Config
   provider: anthropic
   model: claude-sonnet-4-20250514
   
   ## Goal
   Build a command-line todo application in Python with add, list,
   complete, and delete operations. Data persists to a JSON file.
   
   ## Epic 1: Core Todo Logic
   ### DoD
   - Todo CRUD operations working with JSON persistence
   ### Acceptance Criteria
   - Can add a todo with a title
   - Can list all todos with status
   - Can mark a todo as complete
   - Can delete a todo by ID
   ### Tasks
   - TASK-001: Implement Todo model and JSON storage layer
   - TASK-002: Implement add, list, complete, delete operations
   - TASK-003: Write unit tests for all operations
   
   ## Epic 2: CLI Interface
   **depends_on: Epic 1**
   ### DoD
   - CLI accepts commands and delegates to core logic
   ### Tasks
   - TASK-001: Build argparse-based CLI with subcommands
   - TASK-002: Add colored output and error handling

3. Run the engine

   pwsh Engine.ps1 -PlanPath ./my-first-plan/PLAN.md

   The engine will parse your plan, build a dependency graph, and start executing.

4. Watch the execution

   The engine logs progress to the terminal. You’ll see output like:

   [ENGINE] Parsed 2 epics from PLAN.md
   [ENGINE] DAG: Wave 1 → [Epic 1: Core Todo Logic]
   [ENGINE] DAG: Wave 2 → [Epic 2: CLI Interface]
   [ENGINE] Spawning war-room: room-001 (Epic 1)
   [ENGINE] room-001: engineer assigned, developing...
   [ENGINE] room-001: engineer done, qa reviewing...
   [ENGINE] room-001: PASSED
   [ENGINE] Spawning war-room: room-002 (Epic 2)
   ...
   [ENGINE] All epics completed. Plan finished.

5. Check the results

   After execution, inspect the output:

   # See what was created
   ls my-first-plan/
   
   # Check war-room status
   cat .agents/war-rooms/room-001/status
   
   # Read the channel log
   cat .agents/war-rooms/room-001/channel.jsonl
   
   # Check agent progress
   cat .agents/war-rooms/room-001/progress.json

What Happens Under the Hood

When you run Engine.ps1, the following pipeline executes:

PLAN.md
  │
  ▼
Parse ── extract epics, config, goal
  │
  ▼
DAG ──── resolve depends_on → topological sort
  │
  ▼
Waves ── group independent epics for parallel execution
  │        Wave 1: [Epic 1]     ← no dependencies
  │        Wave 2: [Epic 2]     ← depends on Epic 1
  ▼
War-Rooms ── create isolated directory per epic
  │            ├── channel.jsonl   (message log)
  │            ├── status          (lifecycle state)
  │            ├── progress.json   (completion %)
  │            ├── brief.md        (epic brief)
  │            └── lifecycle.json  (state machine)
  ▼
Agents ── compose Role + Skills + MCP tools
  │         manager → assigns tasks
  │         engineer → implements
  │         qa → reviews
  ▼
Done ──── all rooms passed → plan complete

Plan Anatomy

Section	Required	Purpose
# Title	Yes	Plan name, used in dashboard and logs
## Config	Yes	Provider, model, and engine settings
## Goal	Yes	High-level objective guiding all agents
## Epic N: Name	Yes	Unit of work assigned to a war-room
### DoD	Yes	Definition of Done — when is the epic complete?
### Acceptance Criteria	No	Specific testable conditions for QA
### Tasks	Yes	Ordered task list for the engineer
**depends_on:**	No	Declares dependency on another epic

Tip

Start with 1–3 epics in your first plan. Each epic should be a self-contained unit of work that one agent can complete in a single session. If an epic takes more than 15 minutes, it’s too big — split it.

Note

The engine creates war-rooms under .agents/war-rooms/. Each run generates new room directories. Previous runs are not automatically cleaned up — you can inspect them for debugging.

Next Steps

• Set up the full development environment with live monitoring in Dev Mode
• Learn how to write detailed plans in Your First Plan