Workflow config

What WORKFLOW.md controls

When the default handoff is close but not quite right, WORKFLOW.md is where you tighten it. This file decides how much autonomy the loop gets and what guardrails stay in place when you are not actively driving.

WORKFLOW.md is the repo-local source of truth for orchestration. It covers:

• tracker settings
• workspace root
• hook commands and timeout
• agent concurrency, mode, and dispatch behavior
• optional review and done phase prompts
• Codex command and sandbox settings
• the prompt template rendered for each issue

Project-level provider selection is separate from this file. WORKFLOW.md still controls orchestration for every project, while tracker.kind remains kanban even if a project is configured to sync issues from Linear.

Typical Codex-backed section

agent:
  max_concurrent_agents: 3
  max_turns: 4
  max_retry_backoff_ms: 60000
  max_automatic_retries: 8
  mode: app_server
  dispatch_mode: parallel
codex:
  command: codex app-server
  expected_version: 0.111.0
  approval_policy: never
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite
    networkAccess: true
  turn_timeout_ms: 1800000
  read_timeout_ms: 10000
  stall_timeout_ms: 300000

Main knobs

• tracker.kind: orchestration tracker kind. This remains kanban.
• agent.mode: use app_server for the Codex app-server protocol or stdio for codex exec style runners.
• agent.max_concurrent_agents: cap simultaneous issues per project when dispatch is parallel.
• agent.max_turns: limit how many turns Maestro gives the agent before ending an attempt.
• agent.dispatch_mode: use parallel by default or per_project_serial when only one issue per project should run at a time.
• codex.command: exact command Maestro launches.
• codex.expected_version: version Maestro expects from codex --version.
• codex.approval_policy: keep this at never for unattended runs.
• codex.thread_sandbox and codex.turn_sandbox_policy: define where Codex can write and whether network access stays on.
• codex.turn_timeout_ms, codex.read_timeout_ms, and codex.stall_timeout_ms: set the run budget and inactivity limits.

Template variables

The issue prompt template can interpolate:

• {{ issue.identifier }}
• {{ issue.title }}
• {{ issue.description }}
• {{ issue.state }}
• {{ phase }}
• {{ attempt }}

Bootstrap behavior

The workflow file is required for orchestration, but different commands treat a missing file differently:

• maestro workflow init creates it explicitly
• maestro run bootstraps a missing file automatically
• maestro verify checks readiness and returns remediation guidance
• maestro doctor runs the same readiness checks with a different presentation
• maestro spec-check is non-mutating and fails if the file is missing or invalid

Workflow init guide

maestro workflow init [repo_path] writes a fresh WORKFLOW.md and then immediately runs the same readiness verification used by maestro verify. If repo_path is omitted, Maestro resolves it to your current working directory.

Start with the non-interactive baseline when you want a predictable scaffold:

maestro workflow init . --defaults

That scaffold currently includes:

• the local kanban tracker with ready, in_progress, and in_review as active states
• workspace.root: ./workspaces
• hook stubs with a timeout_ms budget
• disabled review and done phases with starter prompt text already filled in
• agent.max_concurrent_agents: 3, max_turns: 4, max_automatic_retries: 8, and dispatch_mode: parallel
• codex.command: codex app-server, agent.mode: app_server, and approval_policy: never
• a careful sandbox by default: thread_sandbox: workspace-write with turn_sandbox_policy.type: workspaceWrite and networkAccess: true
• the default issue prompt template appended after the YAML front matter

When --defaults is not set and both stdin and stdout are TTYs, workflow init becomes interactive. The current implementation prompts in this order:

1. Workspace root
2. Runtime selection: recommended Codex setup or Custom / advanced
3. If you choose custom runtime, Codex command and Agent mode (app_server|stdio)
4. Sandbox profile

Use flags when you want to skip prompts but still override part of the scaffold:

maestro workflow init . --defaults --workspace-root ./tmp/workspaces --codex-command "codex app-server" --agent-mode app_server --sandbox-profile secure

• --workspace-root sets workspace.root
• --codex-command sets the exact command Maestro launches
• --agent-mode accepts app_server or stdio
• --sandbox-profile accepts careful, secure, or yolo
• --force overwrites an existing WORKFLOW.md

The sandbox presets map directly onto the generated Codex settings:

• careful: workspace-write with network access enabled
• secure: workspace-write with network access disabled
• yolo: danger-full-access with network access enabled

Overwrite behavior is intentional. In non-interactive mode, an existing WORKFLOW.md is left alone unless you pass --force. In interactive mode, Maestro asks for confirmation before replacing the file.

After the file is written, the CLI prints:

• the initialized file path
• a Verification block with readiness status and any warnings
• Next steps

If verification is clean, the suggested next steps are to register the repo, start the orchestrator, and re-run readiness checks later. If verification reports warnings, the next steps change to reviewing the warnings first, then re-running readiness checks before starting maestro run.

Codex access requirements

For reliable unattended orchestration:

• Codex must already be installed and logged in
• the configured command must resolve on PATH, or you should use an absolute path
• the sandbox must still allow reads from the repo and writes inside the per-issue workspace
• network access should stay enabled when tasks depend on package registries, Git remotes, or APIs