catlog22/maestro-next

<required_reading> @~/.maestro/workflows/run-mode.md @~/.maestro/workflows/codex-run-mode.md </required_reading>

<purpose> Unified interactive entry for all development intents. Pure router: parse intent + project state → classify → assess complexity → route to the appropriate channel:

• Companion (lightweight): route to /maestro-companion "<intent>" — minimal run lifecycle, continuous evidence recording
• Standard (single run): recommend a step → confirm → execute via a v3 Session (maestro session open + maestro run next)
• Multi-step: route to /maestro "<intent>" (manual stepwise control) or /maestro-ralph "<intent>" (orchestrated closed-loop)

This command is the single entry point. It classifies and routes. Multi-step execution loops live in /maestro (manual) and /maestro-ralph (orchestrated). </purpose>

<context> $ARGUMENTS — intent text + optional flags.

Flags:

| Flag | Effect | |------|--------| | -y / --yes | Skip confirmation. Auto-executes only the standard channel; for companion/multi-step it emits the target invocation (router semantics — the target command owns execution) |

Mode detection (priority order):

1. Intent text present → S_STATE → S_RANK → route by complexity verdict
2. "continue"/"next"/"go" → lifecycle inference for natural next step
3. No arguments at all → 1 clarify round

Candidate pool: All 14 first-tier steps registered in prepare/ + workflows/. Companion is a routing channel, not a first-tier step. Pipeline orchestrators (maestro, maestro-ralph*) are NEVER in the candidate pool. </context>

<invariants>

1. Pure router for multi-step — this command never runs execution loops (manual chain or orchestrated). Multi-step execution is delegated to /maestro (manual) or /maestro-ralph (orchestrated)
2. Pipeline orchestrators excluded — only recommend registered steps as single-run targets
3. Lifecycle continuation — "continue"/"next"/"go" are explicit continuation signals → lifecycle_position inference (S_STATE). Truly empty arguments (no text at all) → 1 clarify round via request_user_input; still empty → S_FALLBACK (E001)
4. Literal match priority — keyword match takes precedence; lifecycle is tie-breaker
5. Argument pass-through — the intent phrase is Session metadata only (the objective to session open); when a chain step needs domain inputs, store them with repeatable --arg <value> on maestro session chain insert|replace. A fully specified machine-protocol run create passes domain text positionally; --input <ART-id> is only for sealed same-Session Artifact IDs. The user can modify command inputs at confirmation; -y only passes through when the user provided it
6. Manual campaigns excluded — team-* and maestro-odyssey never enter the executable candidate pool and are never executed in this turn; they may only be emitted as suggest-only invocations (see the odyssey campaign rows in the intent routing table)
7. Retained commands are suggest-only — route retained commands to an exact slash command. Never execute them in this turn; -y applies only to first-tier steps
8. Companion routing is suggest-or-execute — when complexity == lightweight, output /maestro-companion "<intent>" invocation. With -y, emit the invocation directly (/maestro-companion "<intent>" -y); the companion command owns its own execution. Without -y, present it as the recommended channel for user confirmation
9. Multi-step routes to the orchestrators — when intent spans ≥2 steps or needs orchestration, output /maestro "<intent>" (manual stepwise) or /maestro-ralph "<intent>" (orchestrated closed-loop). This command never creates sessions or manages chains itself
10. Cross-category keyword priority — when an intent keyword matches both a first-tier step and a retained command, the first-tier step wins for candidate selection; complexity assessment still applies independently. Auxiliary clusters are advisory grouping for display, never routing overrides
11. -y means skip-confirmation, not auto-execute — for standard channel, skipping confirmation proceeds to S_EXECUTE (this command runs the step). For companion/multi-step channels, this command is a router: skipping confirmation means outputting the target invocation text directly. The target command owns its own execution semantics

</invariants>

<state_machine>

<states> S_PARSE — Parse arguments, extract flags, detect mode S_STATE — Read project state, infer lifecycle_position S_RANK — Score candidates, assess complexity, determine channel S_PRESENT — Show top pick + alternatives + reasoning + channel verdict S_CONFIRM — request_user_input for confirmation (skipped by -y) S_EXECUTE — Open Session + dispatch the selected single step Run S_FALLBACK — Intent empty after clarification </states>

<transitions>

S_PARSE: → S_STATE WHEN: intent present / "continue"/"next"/"go" → S_PARSE WHEN: no arguments at all (1 clarify round via request_user_input) → S_FALLBACK WHEN: clarification still empty

S_STATE: → S_RANK DO: A_INFER_LIFECYCLE

S_RANK: → S_PRESENT DO: A_SCORE_CANDIDATES (channel verdict embedded in presentation)

S_PRESENT: → END WHEN: target_kind == retained-command DO: display exact slash command; suggest only → S_EXECUTE WHEN: -y AND channel == standard → END WHEN: -y AND channel == companion DO: output /maestro-companion "<intent>" -y → END WHEN: -y AND channel == multi-step DO: output the selected orchestrator: /maestro "<intent>" -y (manual) or /maestro-ralph "<intent>" -y (orchestrated) → S_CONFIRM WHEN: interactive

S_CONFIRM: → S_EXECUTE WHEN: user confirms standard step / selects alternative / modifies args → END WHEN: user picks companion → output /maestro-companion "<intent>" → END WHEN: user picks multi-step → output the selected orchestrator: /maestro "<intent>" (manual) or /maestro-ralph "<intent>" (orchestrated) → END WHEN: user cancels

S_EXECUTE: → END DO: A_EXECUTE_STEP

S_FALLBACK: → END DO: raise E001

</transitions>

<actions>

A_INFER_LIFECYCLE

Read canonical Session/Run state to infer lifecycle_position; never inspect .workflow/state.json or choose by mtime:

bash
maestro session list --json
maestro session status --session {session_id} --json
maestro session resume-view --session {session_id} --json

Canonical state → lifecycle_position → natural next step:

| State | lifecycle_position | Natural next | |-------|-------------------|-------------| | No .workflow/ + no source code | brainstorm | brainstorm | | No .workflow/ + has source code | init | (maestro-init, not a step) | | No compatible Session | analyze-macro | analyze | | Session objective spans multiple releases and has no roadmap Artifact | roadmap | roadmap | | Pending chain starts before feature analysis | analyze | analyze --session {session_id} | | Latest eligible same-Session Artifact = analysis | plan | plan --session {session_id} | | Latest eligible same-Session Artifact = plan | execute | execute --session {session_id} | | Latest eligible same-Session Artifact = execution | review | review --session {session_id} | | Review verdict = PASS | auto-test | auto-test --session {session_id} | | Tests green + chain terminal | session-manage --complete | (maestro-session-manage --complete, not a step) | | Any stage has gaps/failures | debug | debug {gap} |

Lifecycle main line:

init → {brainstorm | blueprint | analyze-macro} → roadmap
  → [per session] analyze → plan → execute
  → [quality gate] review → auto-test → test
  → session-manage --complete → next dep-ready session

Multi-Session resolution: historical similarity is read-only evidence. Resolve an exact compatible Session from session list plus session status; multiple compatible Sessions require user selection. Use resume-view and same-Session sealed Artifacts for lifecycle inference. Never select a Session from a local projection, directory order, or modification time.

A_SCORE_CANDIDATES

Scoring signals (high → low):

| Signal | Weight | Description | |--------|--------|-------------| | Intent keyword match | High | Literal match against routing table | | Lifecycle natural next | High | Decisive when intent is empty/"continue" | | Step name keyword match | Medium | Intent contains "test" → test/auto-test boosted | | Workflow cluster match | Medium | Learning/knowledge/issue clusters | | Recent activity avoidance | Low | Recently completed steps demoted | | Precondition unmet | Exclude | Remove from pool entirely |

Complexity assessment (determines channel):

| Complexity | Channel | Criteria | |-----------|---------|----------| | Lightweight | /maestro-companion | Mechanically clear intent, no design decisions, no artifact handoff, no gate value | | Standard | Single step (one run) | Produces typed artifacts, needs downstream handoff or gate checks | | Multi-step (manual) | /maestro | Intent spans ≥2 distinct steps, user wants stepwise control, no auto-retry needed | | Multi-step (orchestrated) | /maestro-ralph | Intent needs closed-loop: decision nodes, drift analysis, auto-retry, decomposition |

Routing preference: prefer the lightest channel that satisfies the task. Default to Companion for anything that looks like a quick fix/lookup/exploration. Only upgrade to Standard when there is concrete evidence the task produces artifacts a downstream step will consume, or needs a gate/verdict for lifecycle tracking. Only route to /maestro when the intent genuinely spans ≥2 distinct lifecycle steps. When in doubt between Companion and Standard, ask the user via the confirmation menu rather than auto-upgrading.

Lightweight signals (all must hold):

• Intent specifies a concrete, bounded action — the user names what to change and where (file, function, error message). "Fix the login bug" is NOT lightweight (unbounded diagnosis); "change the timeout from 30s to 60s in auth.ts" IS lightweight. File count is irrelevant; a 20-file rename with a known pattern is still lightweight
• No typed artifact needs to be consumed by a downstream step
• No gate/verdict needs to be recorded for lifecycle tracking
• Task does not require pre-task thinking (prepare) or structured brief to execute correctly
• Single concern — intent does not span multiple lifecycle phases (e.g., analyze+plan, execute+review)

Multi-step detection: intent matches keywords of ≥2 distinct steps in the routing table → classify the relationship before setting multi_step:

| Pattern | Classification | Channel | |---------|---------------|--------| | Sequential lifecycle steps ("analyze then plan", "review and fix") | Multi-step | /maestro or /maestro-ralph | | Single action with multiple aspects ("review and improve the auth module") | Single intent, pick dominant step | Standard or Companion | | Ambiguous compound ("test and deploy") | Present both as alternatives in S_CONFIRM | — |

Dominant step = the step whose keyword appears first or carries the primary verb. When in doubt, present both as alternatives rather than auto-selecting.

Orchestrator selection (for multi-step routing):

• /maestro (manual): user explicitly asks for stepwise/per-step control ("one step at a time", "confirm each step"), or intent is a simple sequential pipeline of ≤3 steps without quality gates
• /maestro-ralph (orchestrated, default): intent implies iterative quality convergence — broad refactoring (>5 files), migration, "end-to-end", "full lifecycle", or needs decision gates/drift analysis/auto-retry. When in doubt, default to /maestro-ralph

Override flags:

• Channel is auto-detected from the signals above; the verdict is shown to the user before routing, and the user may override the channel at the confirmation menu (S_CONFIRM).

Intent routing table: first-tier rows enter the executable candidate pool. Retained-command rows are advisory routes: show the exact slash command and stop.

> Cross-category priority: first-tier step keywords take precedence over retained-command keywords when both match. Example: "security test" → test (first-tier) wins over security/OWASP (odyssey campaign), unless the intent explicitly says "security audit" or "OWASP". Auxiliary cluster triggers are the lowest priority — they group retained commands for display but never override individual keyword matches.

> Scope guard: keyword match identifies the candidate step, but the complexity verdict still applies independently. A keyword hit does NOT override lightweight signals. Example: "rename this variable" matches execute/implement keywords → candidate = execute step, but complexity = lightweight (1 file, no handoff) → channel = /maestro-companion. The routing table answers "which step?", the complexity assessment answers "which channel?".

| Intent keywords | Recommended step | What it does | |----------------|-----------------|--------------| | brainstorm / ideate / what-if / perspectives / multi-role | brainstorm | Multi-role creative exploration with cross-role conflict resolution | | blueprint / PRD / architecture doc / formal spec / epic | blueprint | Generate formal specification package (Brief, PRD, Architecture, Epics) via 6-phase document chain | | analyze / assess / evaluate / multi-dimension / findings | analyze | Systematic multi-angle assessment producing findings + risk-matrix for plan consumption | | plan / decompose / breakdown / task split / DAG / waves | plan | Decompose confirmed analysis into executable task DAG with waves and collision avoidance | | execute / implement / build / code / develop | execute | Implement code changes following current-plan DAG+waves with smoke self-check | | verify / validate / acceptance / confirm implementation | verify | Independent verification of requirement coverage and behavioral correctness against plan | | debug / bug / error / root cause / failing / broken / trace | debug | Scientific-method root cause diagnosis — reproduction, hypothesis testing, backward tracing | | review / code review / audit / inspect / PR review | review | Layered multi-dimensional code review producing traceable review-findings | | test / UAT / manual test / browser test / acceptance test | test | Conversational UAT + coverage + optional browser acceptance on verified deliverables | | auto-test / automated test / CI test / pipeline test / L0-L3 | auto-test | Automated CSV-layered test pipeline iterating to convergence | | roadmap / milestone / phasing / session plan / work breakdown | roadmap | Decompose requirements into session DAG with scope, success criteria, dependency edges | | quick / small / ad-hoc / one-off / trivial | /maestro-companion "<intent>" | Lightweight direct execution with no typed artifact handoff | | retrospective / retro / lessons learned / post-mortem / reflect | retrospective | Post-phase four-lens review (technical/process/quality/decision) → spec/knowhow/issue routing | | grill / pressure test / stress test | grill | Socratic pressure-test of a plan/idea against codebase reality — adversarial questioning, terminology collision checks | | collab / cross-verify / multi-tool / second opinion | collab | Fan out one requirement to multiple CLI tools, cross-verify findings into a unified conclusion | | refactor / tech debt | /maestro-odyssey "<scope>" --mode improve (odyssey campaign) | Output invocation; user invokes it | | issue / defect | /maestro-issue "<intent>" (retained command) | Suggest exact slash command; user invokes it | | wiki / knowledge graph | /maestro-knowledge "<intent>" (retained command) | Suggest exact slash command; user invokes it | | spec / rule / constraint | /maestro-spec "<intent>" (retained command) | Suggest exact slash command; user invokes it | | init / project setup | /maestro-init ... (retained command) | Suggest exact slash command; user invokes it | | security / OWASP | /maestro-odyssey "<scope>" --mode security (odyssey campaign) | Output invocation; user invokes it | | defensive programming / exception swallowing / silent failure / fallback risk / 防御性编程 / 兜底风险 | /maestro-odyssey "<scope>" --mode defensive (odyssey campaign) | Output invocation; user invokes it | | learn / explore code / follow | /maestro-learn follow|investigate|decompose|consult ... (retained command) | Suggest exact slash command; user invokes it | | UI design / design system / polish / impeccable | /maestro-impeccable "<intent>" ... (retained command) | Suggest exact slash command; user invokes it | | harvest / extract knowledge | /maestro-knowledge "<intent>" (retained command) | Suggest exact slash command; user invokes it | | fork / parallel dev | /maestro-fork ... (retained command) | Suggest exact slash command; user invokes it | | note / record observation during active Run | write content to a temp file, then maestro knowledge stage knowhow "<title>" --content-file <path> --run <run-id> | Stage a reviewable candidate; do not direct-write project knowledge | | promote / distill insights | maestro knowledge review <session-id> → maestro knowledge promote ... | Review candidate receipts and evidence before explicit promotion |

Auxiliary workflow clusters:

| Cluster | Trigger | Chain | |---------|---------|-------| | Learning | New code / unknown module | maestro-learn follow → maestro-learn decompose → maestro-learn consult | | Knowledge | Review & promote experience | knowledge stage (--signal) → knowledge review --refresh --resolve → knowledge promote | | Issue | Defect management | maestro-issue discover → maestro-issue |

A_EXECUTE_STEP

Single-run path only. Multi-step execution is handled by /maestro (manual) and /maestro-ralph (orchestrated).

For first-tier steps (those with prepare/ + workflows/ files):

bash
# 1. Open an empty Session; --actor carries the authorized identity (--participant defaults to it).
maestro session open "<objective>" --id YYYYMMDD-<step>-<topic> --actor {actor_id} --json
#    Or attach an existing compatible Session read-only first: maestro session status --session {session_id} --json

# 2. Persist the selected step and each required positional command input.
maestro session chain insert --session {session_id} --step-id {step_id} --command <step> --arg "<domain input>" --actor {actor_id} --expected-orchestration-revision {open_orchestration_revision} --json

# 2a. LLM performs pre-task thinking using the prepare guidance embedded in the birth packet.

# 3. Dispatch with the exact revision returned by chain insert.
maestro run next --session {session_id} --actor {actor_id} --expected-orchestration-revision {insert_orchestration_revision} --json
#    Direct machine-protocol alternative (only for an existing exact step):
#    maestro run create <step> "<domain input>" --session {session_id} --run {run_id} --step {step_id} --goal "<goal>" --input <ART-id> --actor {actor_id} --expected-orchestration-revision {step_orchestration_revision} --json
#    Returns: run_id, run_dir, upstream, resolved task, entry blockers, and structured executable continuation

# 3a. Entry blocker degradation (execute-specific)
#    IF step == execute AND entry_blockers is non-empty (missing current-plan):
#      Inspect upstream for alternative artifacts (latest-review, latest-debug, latest-fix-directions).
#      Route per the degradation table in prepare/execute.md:
#        - Small scope (≤3 findings, ≤2 files each) → transition/cancel the attempt, surface /maestro-companion
#        - Larger scope → transition/cancel the attempt, surface /odyssey-planex
#        - No alternative upstream → `maestro run transition {run_id} blocked`, surface E001 + suggest /plan
#      The chain step returns to pending; a later fenced `maestro run next` may retry it.
#      Do NOT proceed to step 4 with a blocked execute run.

# 3b. Entry blocker handling (general, non-execute steps)
#    IF step != execute AND entry_blockers is non-empty:
#      Display each blocker with recovery suggestion:
#        - Missing upstream artifact → suggest the producing step (e.g., "run analyze first")
#        - Gate failure → suggest the gate step (review/verify/auto-test)
#      `maestro run transition {run_id} blocked` (or `maestro run cancel {run_id}`) — do NOT proceed to step 4.

# 4. Load the execution manual (follow the birth packet `guidance`/`brief.command` from step 3)
#    Execute the birth packet guidance verbatim — append no flag.
#    Returns: workflow content, run-mode summary, goal, gate status

# 5. LLM executes the workflow (core process)

# 6. Check and complete the run
maestro run check {run_id} --session {session_id} --json
maestro run complete {run_id} --session {session_id} --actor {actor_id} --expected-orchestration-revision {orchestration_revision} --expected-run-revision {run_revision} --verdict done --advance --json

After run complete --advance: re-infer lifecycle and surface the natural next step as a continuation hint — stepwise multi-step work proceeds by re-invoking /maestro-next or /maestro -c.

For retained commands, output the exact slash command as a suggest-only result. Do not execute it, including under -y; the user invokes it explicitly in a subsequent message.

</actions>

</state_machine>

<presentation>

Normal mode

[⚠ Multi-step intent detected]   ← only when multi_step

Target: /<step-name>
Kind: first-tier step | retained command | companion | multi-step
  <description>
  Reason: <match rule + lifecycle position>
  Channel: /maestro-companion | single run | /maestro (manual) | /maestro-ralph (orchestrated)
  Invocation:
    companion       → /maestro-companion "<intent>"
    single run      → Confirm to execute through Maestro Run lifecycle
    multi-step      → /maestro "<intent>" (manual) or /maestro-ralph "<intent>" (orchestrated)
    retained        → Run manually: /<command> <subcommand> <args> (suggest only)

Alternatives:
  2. /<alt-1> — <description> — <invocation method>
  3. /<alt-2> — <description> — <invocation method>

Args: <args>

Confirmation menu varies by channel verdict:

When channel == companion:

• Run as companion (Recommended) → /maestro-companion "<intent>"
• Upgrade to standard run → S_EXECUTE
• Cancel

When channel == standard:

• Execute recommendation (Recommended)
• Choose alternative
• Modify arguments
• Cancel

When multi_step:

• Hand off to orchestrator (Recommended) → /maestro "<intent>" (manual) or /maestro-ralph "<intent>" (orchestrated)
• Just this step (execute only the top pick as single run)
• Cancel

-y: execute/route immediately per channel.

</presentation>

<error_codes>

| Code | Severity | Condition | Recovery | |------|----------|-----------|----------| | E001 | error | Intent empty after clarification | Provide intent, or ask conversationally for available steps (e.g. run maestro skills). | | E002 | error | No steps found in registry | Check prepare/ and workflows/ directories | | E003 | error | Selected step has no prepare/workflow files | Verify step installation | | W001 | warning | Top-1 and top-2 score difference < 15% of max score | Force show top 3 for user decision — yields to -y: with -y, route/execute the top pick directly | | W002 | warning | No good match for intent | Suggest /maestro for orchestration |

</error_codes>