/maestro-odyssey

name: maestro-odyssey
disable-model-invocation: true
description: "Long-running iterative cycle — one entry, seven modes (debug|improve|planex|review|security|defensive|ui). Shared archaeology/audit → fix → verify → generalize → discover → persist skeleton with mode-specific dimensions. User-invoked campaign entry; single-step fixes route via /maestro-next"
argument-hint: "<intent> --mode debug|improve|planex|review|security|defensive|ui [-y] [-c]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
  - TaskCreate
  - TaskUpdate
session-mode: run
contract:
  discovery: self-described
  consumes: []
  produces: []

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

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.

<deferred_reading>

• [odyssey-base.md](~/.maestro/workflows/odyssey-base.md) — read after mode resolved for shared back-half (INTAKE gate → GENERALIZE → DISCOVER → RECORD → END)
• [odyssey-debug.md](~/.maestro/workflows/odyssey-debug.md) — read when mode=debug
• [odyssey-improve.md](~/.maestro/workflows/odyssey-improve.md) — read when mode=improve
• [odyssey-planex.md](~/.maestro/workflows/odyssey-planex.md) — read when mode=planex
• [odyssey-review.md](~/.maestro/workflows/odyssey-review.md) — read when mode=review
• [odyssey-security.md](~/.maestro/workflows/odyssey-security.md) — read when mode=security
• [odyssey-defensive.md](~/.maestro/workflows/odyssey-defensive.md) — read when mode=defensive
• [odyssey-ui.md](~/.maestro/workflows/odyssey-ui.md) — read when mode=ui

</deferred_reading>

<purpose> Long-running, evidence-driven iterative cycle. A single entry dispatches to one of seven modes; all share the same skeleton — discovery → domain audit → fix → verify → generalize → discover siblings → persist knowledge — and iterate exhaustively until the mode's exit condition is met or escalation is required. </purpose>

<mode_dispatch>

**Mode selection precedence:** explicit `--mode <name>` > intent keyword auto-detection > [@ask] AskUserQuestion (Normal) / error E000 (`-y`).

**Auto-detection from `<intent>` keywords** (first match wins, ordered):

Keyword matching: case-insensitive substring match against the intent text. Multi-word keywords require all words present (not necessarily adjacent). First matching row wins (ordered by specificity).

| Keywords in intent | Detected mode | |--------------------|---------------| | bug, crash, error, broken, fails, regression, race, leak, "why does" | `debug` | | requirement, implement, build, add feature, I need to implement, I need to build, I need to add, deliver feature, user story | `planex` | | ui, visual, layout, style, component, page, responsive, a11y, accessibility, UI design, visual design, design system, design tokens | `ui` | | security audit, OWASP, vulnerability, CVE, secrets scan, STRIDE, threat model, supply chain, dependency audit, dependencies, supply chain audit | `security` | | defensive programming, defensive code, exception swallowing, silent failure, fallback risk, default value risk, error suppression, 防御性编程, 防御性代码, 异常吞噬, 兜底风险 | `defensive` | | improve, optimize, performance, refactor quality, reliability, observability | `improve` | | review, audit, code check, check the code, inspect the code, inspect changes, "look over", zero-residual | `review` |

Ambiguous / no match → Normal: [@ask] AskUserQuestion (7-way mode pick) | `-y`: E000.

**Mode registry:**

| Mode | Purpose | Discovery phases | Audit phase | Fix→verify pair | Unique states | |------|---------|------------------|-------------|-----------------|---------------| | `debug` | Symptom → root cause → fix → confirm | ARCHAEOLOGY, EXPLORE | DIAGNOSE (hypothesis test) | FIX → CONFIRM | ESCALATE_DIAGNOSIS | | `improve` | 6-dimension quality audit → diagnose → fix | SURVEY | AUDIT (6 dims) + DIAGNOSE | FIX → VERIFY | ESCALATE_DIAGNOSIS | | `planex` | Requirement → plan → execute → verify loop | (none) | PLAN + EXECUTE | (EXECUTE) → VERIFY → FIX loop | — | | `review` | Multi-dimension deep review → zero-residual fix | ARCHAEOLOGY, EXPLORE | REVIEW (4+ dims) | FIX → CONFIRM | — | | `security` | Read-only tiered security audit → severity matrix | RECON | SCAN (OWASP + deps + secrets + CI/CD + STRIDE + git) | (none — read-only) | — | | `defensive` | Business-anchor → backward-slice → 8-pattern scan → forward-propagate → risk score | ANCHOR, SLICE | SCAN (8 defensive patterns) + PROPAGATE | (none — read-only) | — | | `ui` | Visual survey → 6-dim audit → diverge → fix | SURVEY | AUDIT (6 dims) + DIVERGE | FIX → VERIFY | — |

CONFIRM and VERIFY are synonymous — both refer to the post-fix validation phase. Mode workflow files use mode-specific naming; semantics are identical.

The **back half is identical across all modes**: `GENERALIZE → DISCOVER → RECORD → END` (see odyssey-base.md §Shared Back-Half).

On mode resolved: read the deferred workflow file for that mode + odyssey-base.md, then execute.

</mode_dispatch>

<context> $ARGUMENTS

**Universal flags:** `--mode <name>` mode selector | `--skip-fix` audit/diagnose only, skip fix+verify | `--skip-generalize` skip GENERALIZE+DISCOVER | `-y` skip all confirmation interactions (including delegate/agent confirmations in execution phases), use default choices; decisions skipped this way are recorded as `deferred`; never bypasses mode ambiguity (E000), INTAKE gate blockers, escalation | `-c` resume the most recent unfinished Session of the SAME mode via exact Session resolution: locate it with `maestro session list --json` + `maestro session status --session {session_id} --json` (both read-only), re-attach context with `maestro session resume-view` and the `brief-result/3.0` Resume Packet via `run brief` (exact invocation per run-mode.md), then continue the chain with fenced `maestro run next` / `run check` / `run complete --advance