catlog22/maestro-odyssey

<required_reading> @~/.maestro/workflows/run-mode.md @~/.maestro/workflows/codex-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 — read after mode resolved for shared back-half (INTAKE gate → GENERALIZE → DISCOVER → RECORD → END)
• odyssey-debug.md — read when mode=debug
• odyssey-improve.md — read when mode=improve
• odyssey-planex.md — read when mode=planex
• odyssey-review.md — read when mode=review
• odyssey-security.md — read when mode=security
• 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 > request_user_input (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: request_user_input (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 | -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. If --mode conflicts with the 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-verify | planex | Skip post-execution validation gate | false |

--skip-fix applicability: security mode ignores (read-only, no fix phase); planex skips FIX loop but retains EXECUTE+VERIFY; debug/review/improve/ui skip FIX+VERIFY/CONFIRM. --skip-fix + --skip-verify on planex = PLAN only (no execution).

Mode-scoped flags passed to inapplicable mode: emit W008 warning and ignore the flag.

Session creation: follow run-mode.md exactly. Negotiate capabilities, then open a new Session with maestro session open "<objective>" --id {slug} --chain odyssey-<mode> --participant {participant_id} --actor {actor_id} --request-id {request_id} --reason "<reason>" [--evidence <ref> ...] --json (or resolve an existing compatible Session read-only via session status), then dispatch the mode step with fenced maestro run next --session {session_id} ... --json (chain) or self-start with maestro run create odyssey-<mode> [args...] --session {session_id} ... --json passing the mode arguments. Never abbreviate or omit the Session locator, the orchestration_revision/Run revision fence, or the --participant/--actor identity in an executable command.

Session: {run_dir}/outputs/ Output: session.json | evidence.ndjson | understanding.md | explore.json (debug/review only)

Output boundary: ALL session artifacts MUST target the run outputs directory ({run_dir}/outputs/) only. .workflow/state.json and all sessions/<sid>/ protocol files are runtime-owned — a workflow never writes them. Source code modifications during fix/execute phases are in-scope but MUST be committed per action. NEVER write session artifacts outside {run_dir}/outputs/.

session.json — shared core + mode fields:

json
{ "mode": "debug|improve|planex|review|security|ui",
  "target": "", "dimensions": [],
  "patterns": [], "confirmation": null, "generalization_stats": null,
  "cross_phase_loops": 0 }

Each mode extends the core — see the mode's workflow file for session fields.

Commit convention: "odyssey-{mode}({slug}): {STATE} — {summary}" (mode = active mode short name; review mode uses odyssey-review).

</context>

<invariants> All base invariants apply (evidence append-only, session-as-state, phase goal tracking, auto-commit per action). Additionally:

1. Evidence append-only — never delete or overwrite evidence.ndjson entries.
2. Phase goal tracking — mark each goal done/failed before transition; no silent skips.
3. Generalize is mandatory — GENERALIZE and DISCOVER execute unless skip_generalize == true. Prior-phase convergence, "no findings / all verified / zero remaining," or context pressure are NOT valid skip reasons. The phase itself determines whether patterns exist.
4. Zero-residual (improve/review/ui) — every finding MUST have a concrete action (fix / issue / decision). "Report and shelve" and blanket "pre-existing" skips are forbidden.
5. Read-only (security) — NEVER modify source code, configuration, or dependencies. Security audit produces reports only; fixes route to --mode improve.
6. Acceptance criteria are sacred (planex) — no "close enough", no manual override without explicit escalation.
7. Browser is truth (ui) — verify in real rendering, not just code review. Diverge before converge.
8. Goal tracking 与 session 双写 — 各 phase 进入/退出时同步创建/更新 goal，补充 session.json 的 UI 可见进度。

</invariants>

<task_tracking>

时机与操作（plan 是 session 权威状态的 UI 镜像，不替代 session 状态）：

| 时机 | 操作 | 示例 | |------|------|------| | Session 创建后 | update_plan 初始化步骤清单 | update_plan({ plan: [{ step: "Step {index}: {step.skill}", status: "pending" }, ...] }) | | Step 派发时 | update_plan 标记当前 step | update_plan({ plan: [..., 当前 step status: "in_progress"] }) | | Step 完成时 | update_plan 标记完成 | update_plan({ plan: [..., 该 step status: "completed"] }) | | Step 失败时 | update_plan + explanation 说明 | update_plan({ explanation: "Step {index} failed: {reason}", plan: [...] }) |

</task_tracking>

<self_iteration> Self-iteration (logic in odyssey-base.md) applies to each mode's discovery + audit + GENERALIZE stages:

| Mode | Self-iterating stages | |------|----------------------| | debug | S_ARCHAEOLOGY, S_EXPLORE, S_DIAGNOSE, S_GENERALIZE | | improve | S_SURVEY, S_AUDIT, S_DIAGNOSE, S_GENERALIZE | | planex | S_PLAN, S_VERIFY, S_GENERALIZE | | review | S_ARCHAEOLOGY, S_EXPLORE, S_REVIEW, S_FIX, S_GENERALIZE | | security | S_RECON, S_SCAN, S_GENERALIZE | | ui | S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE | </self_iteration>

<execution> Follow base execution discipline completely. On entry: resolve mode (§mode_dispatch), then read the deferred workflow file for that mode + odyssey-base.md, and run that mode's state machine. All modes converge on the Shared Back-Half in odyssey-base.md.

Shared Phase Gates (MANDATORY, BLOCKING)

• INTAKE gate: mode resolved, target/requirement resolved, SESSION_DIR created, session.json initialized (with baseline_metrics for improve; acceptance_criteria for planex), phase_goals] derived from flags, understanding.md §1 written. BLOCKED if no target (E001) / no requirement (planex E001) / target path not found (E002) / mode unresolved (E000).
• GENERALIZE gate: ALL 3 layers (syntax/semantic/structural) attempted with evidence logged; generalization_stats written with by_layer entries for all 3 layers; generalize goal marked. Any layer not attempted = thoroughness-floor violation (BLOCKED).
• DISCOVER gate: all hits triaged with per-item classification and reason; remaining_actionable == 0 OR loops >= max_loops with per-item reasons logged; discover goal marked. Unclassified hits = BLOCKED.

Mode-specific phase gates (Discovery, Audit, FIX, VERIFY/CONFIRM) are defined in each mode's workflow file.

</execution>

<error_codes> | Code | Severity | Condition | Recovery | |------|----------|-----------|----------| | E000 | error | Mode unresolved (-y, ambiguous intent, no --mode) | Provide --mode | | E001 | error | No target / no requirement (planex) / no issue (debug) | Provide target or -c | | E002 | error | Target path not found | Check path | | E003 | error | -c mode mismatch (resumed session is different mode) | Use correct --mode or omit -c | | E004 | error | Mode workflow file not found (~/.maestro/workflows/odyssey-{mode}.md) | Verify workflow installation or select another mode | | W001 | warning | No relevant git history / no dependency manifest / no design system | Proceed with defaults | | W002 | warning | Some dimension agents failed / 3 retries exhausted | Partial coverage / INCONCLUSIVE | | W003 | warning | Archaeology agent or delegate failure (debug/review) | Proceed with available results, log failed agent | | W004 | warning | Generalization 0 hits after full 3-layer scan | Advance to S_RECORD (requires all 3 layers attempted with evidence) | | W005 | warning | Pending decisions | Filter evidence phase=decision | | W006 | warning | No CLI tools (debug/review explore) | Skip explore | | W007 | warning | planex CLI review regression concern | Review before next iteration | | W008 | warning | Mode-scoped flag ignored (not applicable to resolved mode) | Remove flag or use correct mode | </error_codes>

<success_criteria>

• ] Mode resolved (explicit or auto-detected); session + output files created; prior knowledge searched
• ] Discovery phase(s) for the mode completed with evidence (archaeology/explore/survey)
• ] Domain audit completed with structured findings + severity matrix (or acceptance criteria + plan for planex)
• ] understanding.md sections written progressively per mode
• ] Fix + verify/confirm (unless --skip-fix); zero-residual for improve/review/ui; all criteria pass for planex
• ] Read-only invariant maintained for security mode — zero source modifications
• ] Multi-layer generalization + discovery triage (unless --skip-generalize); every unfixed finding individually justified
• ] phase_goals derived, tracked, and hardened-audited; goal_mode injected via prepare goal:true; -y no blocking prompts
• ] Session resumable via -c; mode-specific completion summary emitted

</success_criteria>

<next_step_routing> | Condition | Next | |-----------|------| | Single-file mechanical fix discovered | /maestro-companion "<fix>" | | Discovery issues created | /maestro-issue list --source {mode}-odyssey | | Deeper debug needed (from any mode) | /maestro-odyssey <finding> --mode debug | | Security findings need remediation | /maestro-odyssey <finding> --mode improve | | Formal review of changes | /maestro-odyssey <changed-files> --mode review | | UI-related findings | /maestro-odyssey <component> --mode ui | | Document pattern | /maestro-learn decompose <module> | | Second opinion | /maestro-learn consult <understanding.md> | | Related question | /maestro-learn investigate "<question>" | | Design/perf/arch pattern to persist | /maestro-spec add ui\|coding\|arch "..." | | Pending decisions | Filter evidence phase=decision status=pending | </next_step_routing>