Skip to content
OSTwin

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.

    Terminal window
    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
    ### Definition of Done
    - 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**
    ### Definition of Done
    - 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

    Terminal window
    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:

     [PRE-FLIGHT] Checking skill coverage...
     [PRE-FLIGHT] All required skills and roles verified.
    

     === Ostwin Plan Launcher ===]
       Plan: /Users/paulaan/bk.ostwin/.agents/plans/11b7dcac8cc8.md
       Plan ID: 11b7dcac8cc8
       Project: /Users/paulaan/.ostwin/projects/kiemtoan-dvctt
       War-rooms to create: 4
    

       room-000 β†’ PLAN-REVIEW β€” Unified Plan Negotiation (Roles: architect)
       room-001 β†’ EPIC-001 β€” QuΓ©t & PhΓ’n loαΊ‘i Kho `/audit-docs` (Roles: engineer, audit, DoD: 0, AC: 0) [depends_on: PLAN-REVIEW]
       room-002 β†’ EPIC-002 β€” ETL & Tα»•ng hợp Dα»― liệu PL02–PL06 (Roles: engineer, audit, DoD: 0, AC: 0) [depends_on: PLAN-REVIEW, EPIC-001]
       room-003 β†’ EPIC-003 β€” Dashboard & KαΊΏt x

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

SectionRequiredPurpose
# TitleYesPlan name, used in dashboard and logs
## ConfigYesProvider, model, and engine settings
## GoalYesHigh-level objective guiding all agents
## Epic N: NameYesUnit of work assigned to a war-room
### Definition of DoneYesDefinition of Done β€” when is the epic complete?
### Acceptance CriteriaNoSpecific testable conditions for QA
### TasksYesOrdered task list for the engineer
**depends_on:**NoDeclares dependency on another epic

Next Steps

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