/maestro-odyssey

name: maestro-odyssey
disable-model-invocation: true
description: "Long-running iterative cycle — one entry, six modes (debug|improve|planex|review|security|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|ui [--auto] [-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>

<deferred_reading>

• [odyssey-base.md](~/.maestro/workflows/odyssey-base.md) — read after mode resolved for shared back-half (A_INTAKE, A_RESUME, 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-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 six 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` | | 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 (6-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) | — | | `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 | `--auto` skip delegate/agent confirmation in execution phases only (decisions → `deferred`); does NOT affect mode selection or INTAKE interactions — mode ambiguity still triggers [@ask] or E000 | `-y` skip all confirmation interactions, use default choices; does NOT auto-mark decisions as deferred (use `--auto` for delegate confirmation skip); never bypasses mode ambiguity (E000), INTAKE gate blockers, escalation | `-c` resume most recent unfinished session of the SAME mode; if --mode conflicts with resumed session's mode → E003 (mode mismatch); no history → ignore -c, create new session | `--heartbeat` /loop periodic progress

**Mode-scoped flags:**

| Flag | Modes | Description | Default | |------|-------|-------------|---------| | `--template <name>` | debug, planex | Predefined strategy/criteria template | — | | `--dimensions <list>` | improve, review, ui | Audit dimension subset | all | | `--fix-threshold <sev>` | improve, review, ui | Severity cutoff (critical\|high\|medium\|low\|all) | all | | `--tier quick\|standard\|deep` | security | Audit depth tier | standard | | `--max-iterations N` | planex | Max verify-fix cycles before escalation | 3 | | `--method agent\|cli\|auto` | planex | Task execution method | auto | | `--executor <tool>` | planex | Explicit CLI executor | first enabled | | `--skip