Maestro Companion

• 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.

If any required file above was not expanded into context by the host, or its content is no longer in context, Read it explicitly before executing any step.

Use when:

• Intent is mechanically clear (no design decisions needed; file count irrelevant)
• No typed artifact consumed by downstream steps
• No gate/verdict needed for lifecycle tracking

Lightweight self-check (all must hold):

• Intent specifies a concrete, bounded action with named target (file, function, error message)
• No typed artifact consumed by downstream steps
• No gate/verdict for lifecycle tracking
• Single concern, no multi-phase span If self-check fails mid-execution, stop and suggest /maestro-next for re-routing.

Mode detection: intent → execute | empty → [@ask] user prompt: request intent text; if still empty → display usage hint and exit

Knowledge utilities (note/log/promote) are available via /maestro-knowledge.

Execute (default)

Linear: resolve Session identity -> dispatch Run -> explore -> confirm -> do -> check -> complete Run -> complete Session when the chain is terminal.

1. Create

Follow the self-start flow in run-mode.md. Negotiate capabilities, then execute the three receipt-chained mutations below. {open_request_id}, {insert_request_id}, and {next_request_id} are distinct stable IDs; use the exact session_id and orchestration_revision returned by each preceding receipt. Participant and actor are the same authorized identity.

maestro session open "<intent>" --id <slug> --participant {actor_id} --actor {actor_id} --request-id {open_request_id} --reason "open self-started Companion Session" --json
maestro session chain insert --session {session_id} --step-id {step_id} --command companion --arg "<intent>" --participant {actor_id} --actor {actor_id} --request-id {insert_request_id} --reason "add Companion task" --expected-orchestration-revision {open_orchestration_revision} --json
maestro run next --session {session_id} --participant {actor_id} --actor {actor_id} --request-id {next_request_id} --reason "dispatch Companion task" --expected-orchestration-revision {insert_orchestration_revision} --json

The Session objective is metadata; session chain insert --arg "<intent>" supplies Companion's positional domain text. Never pass task prose through --input; that option accepts only sealed same-Session Artifact IDs. Consume the run next birth packet's task and structured continuation, and retain its exact Run locator and revisions.

Init {run_dir}/evidence/companion-log.md:

# Companion Log: {intent}
> run_id: {run_id} | session: {session_id}

## Evidence

2. Explore

Locate targets and gather evidence before touching anything. Methods (pick what fits):

• teammate({ agent: "explorer", tasks: [{ prompt: "FIND: ...\\nSCOPE: ..." }] }) — codebase search
• maestro search "<keywords>" --type spec --type knowhow — knowledge recall
• Agent (subagent) — multi-file analysis, cross-reference, pattern discovery
• Direct Read/Grep/Glob — known targets, quick lookups

Record findings under ## Evidence:

## Evidence
- {file:line — what was found}
- {spec/knowhow entries loaded, or "none"}
- {subagent conclusions if used}

3. Confirm

Before executing, verify evidence is sufficient:

• Target files/locations identified?
• Change scope clear (what to modify, what to leave alone)?
• No ambiguity requiring design decisions?

If insufficient → continue exploring or ask user. If -y → skip user confirmation interaction, but still perform evidence sufficiency self-check. If critical targets are unlocated, continue exploring (without asking user); only the 'ask user' branch is skipped.

4. Do

Execute the task. After each meaningful action, append under ## Work Log:

### {HH:MM} — {summary}
{outcome, files touched if any}

Rules: batch trivial reads; 1-5 lines per entry; focus on outcome not process.

5. Seal

Append outcome:

## Outcome
**Status:** done | partial
**Summary:** {1-2 sentences}
**Files:** {modified/created, or "none"}

Before completion, put accepted decisions/locked constraints in report.md. If a reusable recipe or pitfall emerged, stage it now:

maestro knowledge stage knowhow "<title>" --content-file <path|-> --run <run_id>
# Then use the complete fenced `maestro run complete ... --advance` and, when the
# chain is terminal, `maestro session complete` from run-mode.md with the current
# locator, orchestration_revision, and identity.

Display: Companion done. Run: {run_id} | Evidence: {path}

If the completion receipt contains candidate IDs, display its review_command. Do not persist the same insight again through /maestro-spec or /maestro-knowhow.

If execution revealed the task requires multi-phase audit/diagnosis (e.g., root cause unknown, >3 files need coordinated changes), suggest: /maestro-odyssey "<scope>" --mode debug|improve for re-planning.