Maestro

Repo-native orchestration, Codex runtime assets, and maintainer harnesses for autonomous coding agents.

Maestro is the single repository for both runtime orchestration and the packaged Codex-facing assets that runtime expects to use. Runtime authority stays in the Rust orchestration code plus normative workflow specs, while reusable skills, plugins, agent-role configs, and maintainer smoke tests live in the same repository so the runtime and the packaged methods can evolve together.

Status

The repository is still in active bootstrap, but its scope is broader than the original runtime-only MVP:

• retained-lane orchestration and tracker integration continue to live under src/ and docs/spec/
• Codex runtime assets now live under .codex/
• local plugin marketplace metadata now lives under .agents/
• maintainer-only smoke tests and validation helpers live under dev/

The CLI surface remains early-stage, but the repository is now intended to be the single home for both Maestro runtime behavior and the Codex-facing assets that runtime expects to use.

Repository Layout

• src/ holds the Maestro runtime, orchestration logic, tracker integrations, and authoritative implementation behavior.
• docs/spec/ holds normative runtime and workflow contracts.
• docs/guide/ holds operator runbooks and procedural documents.
• .codex/ holds installable Codex runtime assets: skills, plugins, agent-role configs, themes, and config examples.
• .agents/ holds local plugin marketplace metadata used for install and iteration flows.
• dev/ holds maintainer-only smoke tests and validation helpers for shipped skills and plugins.
• scripts/ holds repository-level helper scripts that are not part of the Rust runtime binary.
• WORKFLOW.md holds repo-local execution defaults such as validation commands and tracker-state routing.

Representative Shipped Assets

• scout-skeptic remains the additive evidence-gathering and adversarial-checkpoint skill for non-trivial tasks after the first local probe.
• The research plugin remains the bounded, method-first research package built around one authoritative JSON run file and one unified runner.
• execution-state is the Linear-backed execution-memory skill for durable phase, focus, blocker, and verification snapshots on the routed issue.

Issue Lifecycle

One Maestro-owned issue moves through one retained lane from initial selection through review handoff, post-review follow-up, landing, closeout, and cleanup. This section uses the neutral term retained lane; the visible lane path naming is being aligned separately.

flowchart TD
    A["Linear issue in Todo"] --> B["Eligibility check"]
    B -->|eligible| C["Acquire retained lane + lease"]
    B -->|not eligible| X["Skip / wait"]
    C --> D["Agent run
optionally execution-state tracked"]
    D --> E["Issue -> In Progress
start comment"]
    E --> F{"Turn outcome"}
    F -->|continue| D
    F -->|manual attention| G["Todo + needs-attention
stop automation"]
    F -->|review handoff| H["Validate PR + validated HEAD"]
    H --> I["Issue -> In Review"]
    I --> J{"Post-review classification"}
    J -->|wait| K["Wait for review/checks"]
    J -->|repair| L["Re-enter same retained lane
review repair
optionally execution-state tracked"]
    J -->|ready_to_land| M["Merge"]
    J -->|manual intervention| G
    L --> I
    M --> N["Delivery closeout"]
    N --> O["Issue -> completed_state
mirror / finalize"]
    O --> P["Cleanup lane"]
    P --> Q["Finished"]

Loading

The lifecycle boundaries are:

• Repo policy lives in WORKFLOW.md.
• Runtime and ownership decisions live in docs/spec/maestro_runtime.md, docs/spec/maestro_owned_lane_policy.md, and docs/spec/maestro_post_review_lifecycle.md.
• Issue-scoped tracker writes are constrained by docs/spec/tracker_tool_contract.md.
• execution-state, when present, is a durable execution-memory overlay inside Agent run, review repair, or delivery closeout, not a separate Maestro lifecycle state.
• In Review is a PR-backed handoff state, not the final completed state.
• Landing, delivery closeout, and cleanup remain part of the same owned lane after review handoff succeeds.

Lifecycle Walkthrough

1. Candidate selection

   maestro looks at one configured Linear project and selects only issues that are currently eligible under repo policy. In the current WORKFLOW.md, that means the issue must be in Todo, must not be terminal, must not carry maestro:manual-only or maestro:needs-attention, and must not be blocked by non-terminal dependencies.

2. Retained lane setup

   Once selected, the issue is bound to one retained lane with a deterministic branch and filesystem path. That same lane is reused for retries, review repair, landing, closeout, and cleanup instead of opening a fresh implementation lane for each phase.

3. Live execution

   The agent runs inside that retained lane. On the normal path it uses issue-scoped tracker tools to move the issue to In Progress, leave a start comment, implement the change, run the repo-native validation commands, push the lane branch, and create or update a non-draft PR. When durable execution memory is useful, execution-state stays inside this step as an overlay: the issue remains the generic work item, and issue_progress_checkpoint comments record the current phase, focus, next action, blockers, evidence, and verification state.

4. Turn completion signaling

   At the end of a turn, maestro accepts only one explicit terminal path for the leased issue:

   • review_handoff for PR-backed success
   • manual_attention for a human-required stop

   Both paths must be finalized explicitly through issue_terminal_finalize(...). A summary message or an execution-state checkpoint is not enough.

5. PR-backed handoff

   If the agent records review_handoff, maestro revalidates that the PR still belongs to the same repository, lane branch, and validated HEAD. Only after that service-side validation succeeds does maestro transition the issue into In Review and write the completion comment.

6. Post-review ownership

   In Review is a handoff state, not the final completed state. After handoff, the issue stays on the same owned lane. maestro keeps classifying the lane using authoritative tracker, PR, check, and retained-lane signals.

7. Review wait, repair, or ready-to-land

   While the issue stays in In Review, the retained lane moves among these post-review phases:

   • review_wait while reviews or checks are still pending
   • review_repair when actionable review feedback requires code changes in the same retained lane
   • ready_to_land when approvals are satisfied, checks are green, blocking review work is gone, and the PR is mergeable

   If the issue uses execution-state, that same overlay may also continue inside review_repair. issue_progress_checkpoint still does not decide review_handoff, In Review, merge readiness, or closeout; those remain Maestro lifecycle decisions.

8. Landing and closeout

   Once the lane is ready_to_land, maestro can execute the repository-approved merge step. After merge becomes authoritative, the same lane continues into delivery_closeout, which moves the tracker issue from In Review to the resolved completed state and performs any mirror updates required by policy.

9. Cleanup

   Cleanup is the final deterministic tail step. Only after successful delivery or an explicit terminal cancellation does maestro remove the retained lane and finish local branch or worktree cleanup. Cleanup is not a separate human-only ceremony; it is part of the same owned issue lifecycle.

Current CLI Shape

cargo run -- protocol probe
cargo run -- status --config ./tmp/maestro.toml
cargo run -- run --once --dry-run --config ./tmp/maestro.toml
cargo run -- run --once --config ./tmp/maestro.toml
cargo run -- daemon --poll-interval-s 60 --config ./tmp/maestro.toml

These commands are intentionally early-stage entrypoints. The protocol probe command is the first contract check for app-server compatibility before the full orchestrator loop depends on it.

When you need a shorter operator snapshot, pass --limit to cargo run -- status --config ./tmp/maestro.toml. That limit only truncates the Recent Runs section; Active Runs remain fully visible so the currently leased lanes never disappear from the status view.

The status snapshot now carries operator-facing liveness fields in both text and JSON output. In addition to run_id, issue_id, thread_id, branch, and worktree_path, each run reports a coarse phase, optional wait_reason, the last observed run and protocol activity timestamps, idle seconds, and any queued retry schedule that is still holding the lane.

If you need remote read-only inspection while daemon mode is running, configure [operator_http] in maestro.toml. The listener is disabled by default; when enabled it serves the same JSON status snapshot model from GET /state.

Pilot Guide

For the first real pilot, target maestro itself before onboarding another repository. Keep the live service config at ./tmp/maestro.toml, and keep issue worktrees under the repo-local .worktrees/ directory. If you need a tracked template, start from ./maestro.example.toml. Each lane is now a linked Git worktree that shares the repository's common Git administrative storage through .git/worktrees/* while keeping an isolated working tree per issue. Configure secret authority through TOML by naming the required environment variables in [tracker].api_key_env_var and [github].token_env_var; maestro does not infer GitHub auth from ambient shell state.

Recommended order:

cargo run -- protocol probe
cargo run -- status --config ./tmp/maestro.toml
cargo run -- run --once --dry-run --config ./tmp/maestro.toml
cargo run -- run --once --config ./tmp/maestro.toml

After those bounded checks pass, switch to cargo run -- daemon --poll-interval-s 60 --config ./tmp/maestro.toml when you want the long-running poll loop for the pilot. Daemon mode currently requires a Unix target because the parent process hands the single project dispatch-slot lock to the spawned run --once child via file-descriptor inheritance.

The detailed operator runbook, including sample config, filesystem layout, and failure inspection, lives in docs/guide/pilot.md.

Documentation

• Repository overview: docs/index.md
• Specifications: docs/spec/index.md
• Operational guides: docs/guide/index.md
• Plugin design guidance: docs/guide/plugin_design_principles.md
• Repository workflow contract: WORKFLOW.md
• Pilot runbook: docs/guide/pilot.md

Development

Build and verify from the repository root:

cargo run -- --help
cargo make fmt-check
cargo make lint
cargo make test

cargo make is the source of truth for repo-native verification and formatting entrypoints.

License

Licensed under GPL-3.0.