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 collaboration settings
• the prompt template rendered for each issue

Project-level source selection is no longer part of this file. WORKFLOW.md still controls orchestration for every project, while tracker.kind remains kanban, the local tracker.

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
  approval_policy: never
  initial_collaboration_mode: default
  turn_timeout_ms: 1800000
  read_timeout_ms: 10000
  stall_timeout_ms: 300000

Main knobs

• tracker.kind: orchestration tracker kind. This remains kanban, the local tracker.
• 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. per_project_serial effectively caps per-project concurrency at 1.
• codex.command: exact command Maestro launches.
• codex.approval_policy: keep this at never for unattended runs. Interactive approval and input requests are only queued for app_server runs when this is not never.
• codex.initial_collaboration_mode: controls the startup mode for fresh app_server threads. Use default for unattended execution-first runs, or plan when you explicitly want a plan-gated startup. Pair plan with approval_policy: on-request if you want the agent to ask clarifying questions and wait for approval. This does not affect stdio or resumed threads.
• codex.turn_timeout_ms, codex.read_timeout_ms, and codex.stall_timeout_ms: set the run budget and inactivity limits.

If you do not want to preinstall Codex, Maestro can automatically fall back to the pinned npx -y @openai/codex@0.120.0 app-server form when the configured direct Codex command does not match the supported schema version.

Permission selection is no longer configured in WORKFLOW.md. Maestro resolves runtime sandbox access from DB-backed permission profiles:

• issue permission_profile is authoritative
• issue default inherits the project profile
• project default maps to the normal safe baseline

Plan mode versus interrupts

These two settings solve different problems:

• initial_collaboration_mode: default starts a fresh unattended app_server thread in execution mode. Use plan only for explicitly plan-gated runs, and keep approval_policy: on-request if you want the turn to pause for questions or approval.
• The global interrupt queue only appears when a live app_server turn actually asks for approval or user input, which requires an approval policy other than never.
• Resumed threads keep their existing thread state and do not reapply the startup collaboration mode.
• stdio runs stay non-interactive for this feature.

Template variables

The issue prompt template can interpolate:

• {{ issue.identifier }}
• {{ issue.title }}
• {{ issue.description }}
• {{ issue.state }}
• {{ project.id }}
• {{ project.name }}
• {{ project.description }}
• {{ phase }}
• {{ attempt }}

If a project has a description, Maestro’s default implementation, review, and done prompts automatically add it as a Project context: section. Use project descriptions for standing guidance that should apply across every issue in that project, and use custom workflow templates when you want to move {{ project.description }} elsewhere.

Bootstrap behavior

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

• maestro workflow init creates it explicitly
• maestro init is a root-level alias for the same explicit bootstrap
• 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. maestro init [repo_path] is a root-level alias for the same flow. 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: ~/.maestro/worktrees
• hook stubs with a timeout_ms budget
• enabled review and done phases with starter prompt text already filled in, including done-phase guidance focused on merge-back, worktree cleanup, PR readiness, and blocker reporting
• 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, approval_policy: never, and initial_collaboration_mode: default
• 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. Codex command
3. Agent mode
4. Dispatch mode
5. Max concurrent agents
6. Max turns
7. Max automatic retries
8. If agent.mode is app_server, Approval policy
9. If agent.mode is app_server, Initial collaboration mode

Enum prompts render numbered menus. Press Enter to keep the default, or enter the number, an alias, a unique prefix, or the full value. Common shorthand includes server for app_server, serial or pps for per_project_serial, req for on-request, and def for default. Ambiguous prefixes such as on are rejected and reprompted.

--defaults remains the stable non-interactive scaffold, and the same setup knobs are also available as flags.

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 server --dispatch-mode pps --max-concurrent-agents 4 --max-turns 5 --max-automatic-retries 6 --approval-policy on_request --initial-collaboration-mode plan

• --workspace-root sets workspace.root
• --codex-command sets the exact command Maestro launches
• --agent-mode accepts numbered choices, aliases, unique prefixes, or app_server / stdio
• --dispatch-mode, --approval-policy, and --initial-collaboration-mode accept the same shorthand as the wizard and write canonical values into WORKFLOW.md
• --max-concurrent-agents, --max-turns, and --max-automatic-retries set the matching numeric fields
• --force overwrites an existing WORKFLOW.md

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 selected project or issue permission profile must still allow the access your tasks need