odyssey-planex

S_INTAKE

1. Parse requirement and flags, create SESSION_DIR
2. Define acceptance criteria — analyze requirement → derive testable criteria. Each gets verify_method: test | grep | cli-review | manual
   • Normal: request_user_input to confirm/edit
   • -y: auto-derive, record {"phase":"decision","type":"criteria-confirmation","status":"deferred"}
3. Search prior knowledge: maestro search, related sessions
4. Write session.json + understanding.md §1. Mark G1 done. Display Goal Prompt (see Appendix).

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-planex({slug}): S_INTAKE — 目标解析"

S_PLAN

1. Decompose requirement into ordered tasks mapped to acceptance criteria
2. CLI-assisted planning (optional):

   maestro delegate "PURPOSE: Create plan for: {requirement}
   TASK: Decompose into subtasks | Map to acceptance criteria | Identify dependencies
   MODE: analysis
   CONTEXT: @**/* | Criteria: {criteria_summary}
   EXPECTED: JSON [{task_id, title, description, criteria_refs, deps}]
   " --role analyze --mode analysis
   

   Execute with run_in_background: true, then wait for callback (do NOT halt the Odyssey flow).
3. Write session.json.plan, append evidence (planning), update understanding.md §2. Mark G2 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-planex({slug}): S_PLAN — 计划"

S_EXECUTE

1. Execute tasks sequentially — implement code changes
2. Per task: record evidence (execution), update task status
3. Update understanding.md §3. Mark G3 done.

📌 Auto-commit: git add -A && git commit -m "odyssey-planex({slug}): S_EXECUTE — 执行"

S_VERIFY

Iron gate — every acceptance criterion verified.

Verify each criterion by method:

Wave 1 — cli-review verification via spawn_agents_on_csv:

"verify-AC1","Verify AC1","Review against criterion: {AC1.criterion}","verification","AC1","","1","pending","","",""

spawn_agents_on_csv({ csv_path: "tasks.csv", id_column: "id",
  instruction: VERIFICATION_INSTRUCTION + TERMINATION_CONTRACT,
  max_concurrency: 4, max_runtime_seconds: 300,
  output_csv_path: "wave-1-results.csv", output_schema: SHARED_OUTPUT_SCHEMA })

Record per criterion to evidence (verification). Update acceptance_criteria[].status. Append to iterations[]. Update understanding.md §4 with pass/fail table.

Route: all passed → mark G4 done → next state. Some failed + iteration < max → S_FIX. Fundamental plan flaw → S_PLAN (cross_phase_loops++, re-plan). Some failed + iteration >= max → Normal: request_user_input (continue/lower/accept) / -y: deferred, proceed S_RECORD.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-planex({slug}): S_VERIFY — 验证"

S_FIX

1. Increment current_iteration
2. For each failed criterion: diagnose gap → targeted code fix
3. CLI fix review (optional): maestro delegate --role review --mode analysis for regression check
4. Append evidence (fix), update understanding.md §5 → S_VERIFY (loop)

📌 Auto-commit: git add -A && git commit -m "odyssey-planex({slug}): S_FIX — 修复"

S_GENERALIZE

Skip if --skip-generalize. Extract reusable patterns, scan codebase for similar sites.

Pattern extraction (3 layers):

Wave 2 — 4-agent scan via spawn_agents_on_csv:

"gen-syntax","Syntax Grep","Grep patterns across project","generalization","syntax","","2","pending","","",""
"gen-semantic","Semantic Scan","Check related modules for anti-pattern","generalization","semantic","","2","pending","","",""
"gen-structural","Structural Match","Find files needing same treatment","generalization","structural","","2","pending","","",""
"gen-historical","Historical Grep","git log -S for similar patterns","generalization","historical","","2","pending","","",""

Each returns: [{pattern_id, file, line, context, risk_level, layer, confidence}]

Cross-layer dedup: multi-layer hit on same file:line → boost confidence. Historical hit with existing fix → already_handled. Single layer only → needs_review.

Quality Gate (self-iteration) → evaluate coverage/depth/actionability.

Write understanding.md §6, generalization_stats. Mark G5 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-planex({slug}): S_GENERALIZE — 泛化"

S_DISCOVER

1. Triage: per hit, read context (+-10 lines), classify as already_handled | needs_treatment | low_risk
2. Route:

   Classification	Normal	-y
   needs_treatment	request_user_input: create issue / plan next iter	auto create issue, deferred
   low_risk	Record only	Record only
   already_handled	Skip	Skip

3. Cross-phase loop / exit transitions:
   • S_DISCOVER → S_EXECUTE: needs_treatment area → cross_phase_loops++
   • S_DISCOVER → S_RECORD: triage complete AND remaining_actionable == 0
   • S_DISCOVER → S_RECORD: loops >= max_loops → MUST log each unfixed item with specific reason (blanket "pre-existing" is forbidden)
4. Append evidence (discovery + decision), update understanding.md §7. Mark G6 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-planex({slug}): S_DISCOVER — 发现"

S_RECORD

1. Finalize understanding.md §8 — iteration summary, what worked, what needed rework
2. Write learnings to understanding.md §8: 按 Knowledge Persistence 表分类记录（临时），completion summary 列出建议的后续命令
3. Pending decisions: Normal → request_user_input. -y → display deferred count.
4. Goal audit: check all phase_goals[*].completion_confirmed. Mark G7 done.
5. Output completion summary:

   --- PLANEX ODYSSEY COMPLETE ---
   Requirement: {requirement}
   Criteria:    {passed}/{total} passed
   Iterations:  {N} cycles
   Patterns:    {patterns_extracted} ({by_layer} distribution)
   Scan hits:   {total_hits} ({cross_layer_confirmed} cross-layer confirmed)
   Issues:      {N} created | Decisions: {N} resolved, {M} pending, {K} deferred
   Learnings:   {N} spec entries
   Self-iter:   {N} rounds across {M} stages
   Goals:       {done}/{total} confirmed ({skipped} skipped)
   Status:      {ALL_PASSED|PARTIAL|ESCALATED}
   ---
   

Next steps: $odyssey-review-test-fix <changed-files>, $odyssey-debug "<failing>", $quality-review, $manage-issue list --source odyssey-planex

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-planex({slug}): S_RECORD — 总结"

📋 Planex Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：

/goal 穷尽迭代：直到 acceptance_criteria[*] 全部 status==passed
且 phase_goals_all_done=true 才停。verify 失败自动 fix→re-verify 循环。
每轮修复后重新验证，新发现的标准违反继续修，不超过 max_iterations。
遇到 phase=decision 的 pending 必须 request_user_input，不得自行 resolve。

S_EXECUTE → S_VERIFY ──all pass──→ S_GENERALIZE → S_DISCOVER ──remaining_actionable==0──→ S_RECORD
                │                       │               │
           some fail + iter < max       no hits ─→ S_RECORD
                ▼                                       │
             S_FIX ──→ S_VERIFY (loop)          needs_treatment → S_EXECUTE (cross_phase_loops++)