Maestro Init

• background: false is the default. Use foreground dispatch whenever the result determines the current answer or next action.
• Use background: true only for independent work. If this turn must consume a background result, call observe exactly once with action: "wait" and a bounded timeout before continuing; never continue independently while the result is pending.
• Otherwise end the turn and wait for the automatic teammate-complete notification. Do not rely on SendMessage, team_msg, or hook callbacks as completion signals.
• Never silently ignore an unfinished dispatch.

Flags:

Load project state if exists: Check for .workflow/state.json -- loads context if project already initialized.

Output boundary: ALL file writes MUST target .workflow/ (project.md, state.json, config.json, specs/) only. NEVER modify source code or files outside .workflow/.

Interaction mode: convergent menu-driven Decision tree (strict order): project type (greenfield / existing codebase onboarding) → tech stack detection and confirmation → directory structure preferences → initial configuration (specs categories, wiki bootstrap) Scope guard: only init decisions; do not prejudge roadmap structure or plan scope Writeback target: project.md (project description) + config.json (settings) + state.json (initial state) Additional skip conditions: --from source (upstream context pre-fills decisions) Exit condition: all configuration questions settled → proceed to workflow execution

Phase Gates (MANDATORY, BLOCKING)

GATE 1: Pre-flight → Interview

• REQUIRED: .workflow/ existence check completed.
• REQUIRED: --from source validated (if provided).
• BLOCKED if: E002 (greenfield conflict with existing .workflow/) unresolved.

GATE 2: Interview → Research

• REQUIRED: All interview decisions recorded in project.md and config.json.
• REQUIRED: .workflow/ directory created with initial structure.
• BLOCKED if: interview decisions not yet written to files.

GATE 3: Research → Completion

• REQUIRED: All 3 required artifacts exist (project.md, state.json, config.json).
• REQUIRED: .workflow/specs/ initialized.
• BLOCKED if: any artifact missing — write it before reporting completion.

Pre-flight

1. Check if .workflow/ already exists — if so, load state and warn (E002 for greenfield conflicts)
2. Validate --from source is accessible if provided

Follow '~/.maestro/workflows/init.md' completely.

Artifact Verification (before completion)

REQUIRED_ARTIFACTS = [
  ".workflow/project.md",    // Core Value, Requirements, Key Decisions
  ".workflow/state.json",    // artifacts[], initialized to idle state
  ".workflow/config.json"    // Workflow configuration
]

If any artifact is missing: DO NOT report completion. Write the missing file first.

=== WORKFLOW INITIALIZED ===
Project: {project_name}
State:   .workflow/state.json (active)

Created:
  .workflow/project.md
  .workflow/state.json
  .workflow/config.json
  .workflow/specs/

Ralph-invoked completion

End the step through the v3 Run lifecycle (no text block output):

maestro run complete {run_id} --session {session_id} --participant {actor_id} --actor {actor_id} --request-id {complete_request_id} --reason "complete init Run" --expected-orchestration-revision {orchestration_revision} --expected-run-revision {run_revision} --verdict {VERDICT} [--summary "<summary>"] --advance --json

(run-id 由 birth packet 提供 — 自动解析当前 running 步)

Verdicts (v3 surface):

• done — Normal completion
• done_with_concerns — Completed with concerns; pass --summary and put concerns in report.md frontmatter
• needs-retry / blocked — apply the exact structured continuation using fully fenced run transition or run cancel; retry only through a later fenced run next after Runtime reports the step pending

Next-step routing

Note: roadmap step is responsible for creating state.json.sessions[] entries and setting the first active_session_id. | Full spec package | route step blueprint through /maestro-next or the canonical receipt-chained self-start flow | | Explore ideas first | route step brainstorm through /maestro-next or the canonical receipt-chained self-start flow | | Quick ad-hoc task | /maestro-companion "{goal}" |