How it works

Every flow, mapped end to end

Maestro is a set of explicit, observable flows — not magic. Here is each one, step by step, exactly as the platform executes it.

The shape of the system

A browser talks to Studio over HTTP and WebSockets. Studio talks to each developer’s daemon over WSS carrying JSON-RPC 2.0 — one connection per project.

Browser

Livewire UI, dashboards, kanban, plan chat

HTTP / WS →

Maestro Studio

Laravel · planning, skill matcher, dispatcher, git providers, reporting · PostgreSQL + Redis

WSS · JSON-RPC 2.0 →

Client Daemon

One Rust process · N project connections · provider adapters · OS keyring

The core flows

Each diagram below corresponds to a real code path. Follow any of them in the documentation.

Workspace → Project → Plan
  1. 1

    Create workspace

    Your top-level container; invite members later.

  2. 2

    Create project

    /projects/create

    Link a git repo and provider.

  3. 3

    Create plan

    /plans/create

    AI plan chat drafts phases & tasks.

  4. Loops back until the verdict is approved
Full reference
CLI auth / onboarding
  1. 1

    Studio issues invite

    A one-time JWT invite token.

  2. 2

    Redeem on machine

    maestro auth <token>

    Returns identity + access (15 min) + refresh (30 day) tokens + project list.

  3. 3

    Stored securely

    Tokens in OS keyring; identity in config.toml; projects in projects.toml.

  4. 4

    Auto-detect & connect

    cd into a repo and maestro connect resolves it from the remote.

  5. Loops back until the verdict is approved
Full reference
Team spawn
  1. 1

    Operator requests a team

    maestro team --dev 2 --review 1 --test 1

    Roles parsed by the CLI itself.

  2. 2

    Studio allocates a team channel

    POST /api/v1/agent-sessions/{lead}/team

    Server records the shared channel and worker count.

  3. 3

    Lead spawns detached workers

    --role worker

    maestro connect --no-tui --role worker --with-skill <slugs>, one per role.

  4. 4

    Shared channel orchestration

    ⚑ N steering

    Lead and workers subscribe to the team channel; the lead shows steering directives and completion reports.

  5. 5

    Workers reaped

    When the agent session ends, all spawned workers are terminated.

  6. Loops back until the verdict is approved
Full reference
Planning flow
  1. 1

    Open plan chat

    /projects/{p}/plans/create

    Describe the goal in Studio.

  2. 2

    Architect run proposes

    POST /cli-runs/{uuid}/plan-proposal

    A planning agent run posts a proposal.

  3. 3

    Proposal parsed

    ProposalParser builds Plan → Phases → Tasks.

  4. 4

    Review & edit

    /plans/{plan}/edit

    Adjust phases and tasks in the plan editor.

  5. 5

    Activate

    bootstrap_epic

    Plan → active; the epic branch is pinned and bootstrapped, then level-0 tasks dispatch.

  6. Loops back until the verdict is approved
Full reference
Re-planning flow
  1. 1

    Trigger

    MAESTRO:SUBTASK{...}

    A plan edit, a scope change, or an executing agent emitting a subtask directive.

  2. 2

    Re-run / subtask

    POST /cli-runs/{uuid}/subtask

    Architect re-run or a routed child task is created.

  3. 3

    Plan updated

    New or changed phases and tasks; affected tasks re-dispatched.

  4. Loops back until the verdict is approved
Full reference
Auto dispatch
  1. 1

    Plan active

    Dispatchable tasks become available.

  2. 2

    Skill scoring

    SkillMatcher scores tasks against member/session skills + proficiency.

  3. 3

    Run created

    status=dispatched

    Dispatcher creates an AgentRun.

  4. 4

    Session picks up

    POST /agent-sessions/{uuid}/run

    A connected machine polls pending runs and starts.

  5. 5

    Execution begins

    Task → in_progress, TaskStartedBroadcast emitted.

  6. Loops back until the verdict is approved
Full reference
Manual dispatch
  1. 1

    Assign on the board

    A lead/architect assigns a task in kanban/list/timeline.

  2. 2

    Member notified

    Server sets `assignee_id` and notifies.

  3. 3

    Developer accepts

    maestro task accept

    CLI accepts and the run starts.

  4. 4

    Lead delegation (variant)

    POST /agent-sessions/{uuid}/delegate

    A lead sends a subtask packet straight to a worker.

  5. Loops back until the verdict is approved
Full reference
Knowledge ingestion
  1. 1

    Run analyze

    maestro analyze

    Architect permission required.

  2. 2

    Analysis run

    POST /projects/{id}/analysis

    Creates an AgentRun with purpose repo_analysis.

  3. 3

    Context emitted

    RepoContext + versioned ProjectContextFiles (prior version snapshotted on change).

  4. 4

    Artifacts indexed

    KnowledgeArtifacts written with embeddings; ContextFileUpdatedBroadcast fired.

  5. 5

    Reuse before writing

    Future tasks/agents query the catalog before coding.

  6. Loops back until the verdict is approved
Full reference
Review → merge / revision loop
  1. 1

    Work completes

    purpose=review

    On unattended completion the server auto-dispatches a review run (if the plan is active and no review is in flight).

  2. 2

    Reviewer verdict

    Reviewer agent returns `VERDICT: APPROVED` or `VERDICT: REJECTED —<reason>` in its output; the server parses it.

  3. 3

    Approved → merge

    purpose=merge

    review_approved_at set; a deterministic merge run is dispatched (epic ← task branch).

  4. 4

    Rejected → revision

    Auto reject comment posted; the developer is re-dispatched on the SAME branch, then auto re-reviewed. Capped at 3 cycles (REVISION_CAP) before operator action.

  5. Loops back until the verdict is approved
Full reference

Read the full documentation

Open the docs Get started