Odyssey Planex

---
name: odyssey-planex
description: Requirement-driven iterative cycle — plan, execute, strict verify, fix loop until acceptance criteria met
argument-hint: "<requirement> [--template <name>] [--max-iterations N] [--skip-generalize] [--auto] [--method agent|cli|auto] [--executor <tool>] [--skip-verify] [--heartbeat] [-y] [-c]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
---
<base>@~/.maestro/workflows/odyssey-base.md</base>

<purpose>
Requirement-to-delivery closed loop: parse requirement → define acceptance criteria →
plan → execute → verify → fix gaps → iterate until ALL criteria pass.
</purpose>

<boundary>
**In scope:** Single requirement delivery loop — from requirement parsing to all acceptance criteria passing + generalization.
**Out of scope:** Multi-requirement orchestration → `/maestro-roadmap` | Deep debugging → `/odyssey-debug` | Code review → `/odyssey-review-test-fix` | UI optimization → `/odyssey-ui`

**`--template <name>`:**

| Template | Criteria pattern | Use case |
|----------|-----------------|----------|
| `feature` | User story acceptance + boundary tests + UI verification | New feature |
| `bugfix` | Regression tests + root cause confirmation + boundary coverage | Bug fix |
| `refactor` | Behavior preservation + performance baseline + API compatibility | Refactoring |
| `migration` | Data consistency + rollback verification + performance comparison | Data/API migration |
| `api-endpoint` | Request/response contract + error handling + permission checks | API development |
</boundary>

<context>
$ARGUMENTS

**Flags:**

| Flag | Description | Default |
|------|-------------|---------|
| `--template <name>` | Predefined requirement template | — |
| `--max-iterations N` | Max verify-fix cycles before escalation | 3 |
| `--skip-generalize` | Skip S_GENERALIZE + S_DISCOVER | false |
| `--auto` | CLI delegate calls without confirmation | false |
| `--method agent\|cli\|auto` | Execution method | `auto` |
| `--executor <tool>` | Explicit executor tool for CLI delegate | First enabled |
| `--skip-verify` | Skip post-execution validation gate | false |
| `--heartbeat` | Enable periodic progress heartbeat | false |
| `-y` | Auto-confirm — decisions recorded as `deferred` | false |
| `-c` | Resume most recent session | — |

**Session**: `.workflow/scratch/{YYYYMMDD}-planex-odyssey-{slug}/`
**Output**: `session.json` | `evidence.ndjson` | `understanding.md`

**session.json — planex-specific fields:**
```json
{ "requirement": "",
  "acceptance_criteria": [{"id":"AC1","criterion":"","verify_method":"test|grep|cli-review|manual","status":"pending","evidence":"","passed_at":null}],
  "plan": {"tasks":[{"id":"T1","title":"","description":"","criteria_refs":["AC1"],"status":"pending","files_modified":[],"domain":"general","executor":"agent"}],"created_at":""},
  "execution_config": {"method":"auto","default_executor":"","domain_routing":{"frontend":"","backend":"","default":"agent"},"code_review_tool":"Skip","verification_tool":"Auto","confirmed":false},
  "iterations": [{"iteration":1,"started_at":"","completed_at":"","criteria_before":{"passed":0,"total":0},"criteria_after":{"passed":0,"total":0},"gaps_fixed":[],"files_modified":[]}],
  "current_iteration": 0,
  "patterns": [{"id":"P1","source":"AC1 fix","layer":"syntax|semantic|structural","signature":"","description":"","risk":"","fix_template":""}],
  "generalization_stats": "-> base shared_schemas" }

evidence.ndjson phases: planning|execution|verification|fix|decision|generalization|discovery|self-iteration

understanding.md — 8 sections:

1. Requirement & Criteria <- S_INTAKE | 2. Plan <- S_PLAN | 3. Execution <- S_EXECUTE
2. Verification <- S_VERIFY | 5. Fix Log <- S_FIX | 6. Generalization <- S_GENERALIZE
3. Discoveries <- S_DISCOVER | 8. Learnings <- S_RECORD

phase_goals[]:

ID	Goal	done_when	phase	skip_when
G1	Acceptance criteria defined	>=1 criterion in acceptance_criteria[]	S_INTAKE	—
G2	Plan created	session.json.plan populated	S_PLAN	—
G3	Implementation complete	all plan tasks executed	S_EXECUTE	—
G4	All criteria pass	all acceptance_criteria[].status == passed	S_VERIFY	—
G5	Pattern generalized	patterns[] >=1 entry	S_GENERALIZE	skip_generalize
G6	Discoveries triaged	all scan hits classified	S_DISCOVER	skip_generalize
G7	Learnings persisted	spec entries created OR no actionable	S_RECORD	—

Knowledge Persistence (written to understanding.md section 8):

Category	Content	Follow-up
Multi-round fix cycle pattern	Problem scenario + fix iteration + final approach	/spec-add debug
Reusable implementation pattern	Pattern + applicable scope + code template	/spec-add coding
Acceptance criteria template	Standard template + verify_method suggestion	/spec-add review
Generalization pattern	Signature + risk + fix template	/spec-add coding

Base execution_discipline #1-5. 6. **Acceptance criteria are sacred** — no "close enough", no manual override without explicit escalation Applies to: **S_PLAN, S_VERIFY, S_GENERALIZE**. Logic in base. S_INTAKE → S_PLAN → S_EXECUTE → S_VERIFY → S_FIX → S_GENERALIZE → S_DISCOVER → S_RECORD → END S_INTAKE → S_INTAKE : -c + session found (resume) S_INTAKE → S_PLAN : requirement + criteria defined S_INTAKE → S_INTAKE : no requirement → AskUserQuestion

S_PLAN → S_EXECUTE S_EXECUTE → S_VERIFY

S_VERIFY → S_GENERALIZE : all passed AND NOT skip_generalize S_VERIFY → S_RECORD : all passed AND skip_generalize S_VERIFY → S_FIX : some failed AND iteration < max S_VERIFY → S_PLAN : fundamental plan flaw → cross_phase_loops++ (replan). **Criteria ```