self-evolving-workflow 0.0.0-stage → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (173) hide show
  1. package/LICENSE +27 -0
  2. package/README.md +90 -2
  3. package/dist/agent-memory-prompts.d.ts +13 -0
  4. package/dist/agent-memory-prompts.js +55 -0
  5. package/dist/cli.d.ts +2 -0
  6. package/dist/cli.js +6 -0
  7. package/dist/closeout.d.ts +105 -0
  8. package/dist/closeout.js +479 -0
  9. package/dist/code.d.ts +39 -0
  10. package/dist/code.js +124 -0
  11. package/dist/common.d.ts +9 -0
  12. package/dist/common.js +42 -0
  13. package/dist/context-envelope.d.ts +59 -0
  14. package/dist/context-envelope.js +23 -0
  15. package/dist/host-adapters.d.ts +34 -0
  16. package/dist/host-adapters.js +151 -0
  17. package/dist/http.d.ts +3 -0
  18. package/dist/http.js +90 -0
  19. package/dist/index.d.ts +16 -0
  20. package/dist/index.js +13 -0
  21. package/dist/knowledge-cli.d.ts +183 -0
  22. package/dist/knowledge-cli.js +654 -0
  23. package/dist/knowledge-reads.d.ts +71 -0
  24. package/dist/knowledge-reads.js +193 -0
  25. package/dist/memory.d.ts +97 -0
  26. package/dist/memory.js +250 -0
  27. package/dist/retrospective.d.ts +57 -0
  28. package/dist/retrospective.js +248 -0
  29. package/dist/search.d.ts +36 -0
  30. package/dist/search.js +112 -0
  31. package/dist/skill-addition.d.ts +25 -0
  32. package/dist/skill-addition.js +89 -0
  33. package/dist/skill-design.d.ts +96 -0
  34. package/dist/skill-design.js +226 -0
  35. package/dist/skill-replay.d.ts +55 -0
  36. package/dist/skill-replay.js +451 -0
  37. package/dist/skill-route.d.ts +30 -0
  38. package/dist/skill-route.js +75 -0
  39. package/dist/transcript-evidence.d.ts +3 -0
  40. package/dist/transcript-evidence.js +58 -0
  41. package/dist/upstream/chunker.d.ts +24 -0
  42. package/dist/upstream/chunker.js +96 -0
  43. package/dist/upstream/file-protocol.d.ts +45 -0
  44. package/dist/upstream/file-protocol.js +117 -0
  45. package/dist/upstream/frontmatter.d.ts +47 -0
  46. package/dist/upstream/frontmatter.js +86 -0
  47. package/dist/upstream/graph-search.d.ts +33 -0
  48. package/dist/upstream/graph-search.js +67 -0
  49. package/dist/upstream/l1-extraction.d.ts +26 -0
  50. package/dist/upstream/l1-extraction.js +405 -0
  51. package/dist/upstream/llm.d.ts +8 -0
  52. package/dist/upstream/llm.js +1 -0
  53. package/dist/upstream/merge.d.ts +50 -0
  54. package/dist/upstream/merge.js +153 -0
  55. package/dist/upstream/prompts.d.ts +53 -0
  56. package/dist/upstream/prompts.js +185 -0
  57. package/dist/upstream/search-utils.d.ts +34 -0
  58. package/dist/upstream/search-utils.js +55 -0
  59. package/dist/upstream/slug.d.ts +26 -0
  60. package/dist/upstream/slug.js +103 -0
  61. package/dist/upstream/template.d.ts +29 -0
  62. package/dist/upstream/template.js +80 -0
  63. package/dist/upstream/tokenize.d.ts +4 -0
  64. package/dist/upstream/tokenize.js +29 -0
  65. package/dist/wiki-change.d.ts +76 -0
  66. package/dist/wiki-change.js +299 -0
  67. package/dist/wiki-entry.d.ts +26 -0
  68. package/dist/wiki-entry.js +93 -0
  69. package/dist/wiki-ingest.d.ts +12 -0
  70. package/dist/wiki-ingest.js +126 -0
  71. package/dist/wiki-migration.d.ts +16 -0
  72. package/dist/wiki-migration.js +268 -0
  73. package/dist/wiki-tokens.d.ts +1 -0
  74. package/dist/wiki-tokens.js +46 -0
  75. package/dist/wiki.d.ts +103 -0
  76. package/dist/wiki.js +330 -0
  77. package/dist/workflow-cli.d.ts +2 -0
  78. package/dist/workflow-cli.js +258 -0
  79. package/dist/workflow-install.d.ts +36 -0
  80. package/dist/workflow-install.js +148 -0
  81. package/dist/workflow-knowledge.d.ts +16 -0
  82. package/dist/workflow-knowledge.js +24 -0
  83. package/dist/workflow-mcp.d.ts +2 -0
  84. package/dist/workflow-mcp.js +144 -0
  85. package/dist/workflow-names.d.ts +4 -0
  86. package/dist/workflow-names.js +18 -0
  87. package/dist/workflow-runtime.d.ts +622 -0
  88. package/dist/workflow-runtime.js +627 -0
  89. package/dist/workflow-skills.d.ts +48 -0
  90. package/dist/workflow-skills.js +141 -0
  91. package/package.json +76 -4
  92. package/skills/ew-odyssey/SKILL.md +237 -0
  93. package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
  94. package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
  95. package/skills/ew-odyssey/references/odyssey-base.md +278 -0
  96. package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
  97. package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
  98. package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
  99. package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
  100. package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
  101. package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
  102. package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
  103. package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
  104. package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
  105. package/skills/ew-odyssey/references/odyssey-review.md +251 -0
  106. package/skills/ew-odyssey/references/odyssey-security.md +249 -0
  107. package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
  108. package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
  109. package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
  110. package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
  111. package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
  112. package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
  113. package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
  114. package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
  115. package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
  116. package/skills/ew-orchestrate/SKILL.md +236 -0
  117. package/skills/ew-orchestrate/references/auto-policy.md +165 -0
  118. package/skills/ew-orchestrate/references/companion-route.md +52 -0
  119. package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
  120. package/skills/ew-orchestrate/references/goal.md +53 -0
  121. package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
  122. package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
  123. package/skills/ew-orchestrate/references/planning.md +137 -0
  124. package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
  125. package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
  126. package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
  127. package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
  128. package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
  129. package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
  130. package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
  131. package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
  132. package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
  133. package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
  134. package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
  135. package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
  136. package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
  137. package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
  138. package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
  139. package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
  140. package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
  141. package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
  142. package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
  143. package/skills/ew-skill-design/SKILL.md +28 -0
  144. package/skills/ew-skill-design/references/package-contract.md +28 -0
  145. package/skills/ew-skill-design/references/validation.md +7 -0
  146. package/skills/team-swarm/SKILL.md +231 -0
  147. package/skills/team-swarm/references/mcp-coordination.md +10 -0
  148. package/skills/team-swarm/roles/analyst/role.md +181 -0
  149. package/skills/team-swarm/roles/ant/role.md +149 -0
  150. package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
  151. package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
  152. package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
  153. package/skills/team-swarm/roles/coordinator/role.md +228 -0
  154. package/skills/team-swarm/roles/scorer/role.md +150 -0
  155. package/skills/team-swarm/scripts/aco.py +646 -0
  156. package/skills/team-swarm/scripts/pheromone.py +144 -0
  157. package/skills/team-swarm/scripts/scoring.py +111 -0
  158. package/skills/team-swarm/scripts/test_aco.py +606 -0
  159. package/skills/team-swarm/specs/ant-output-schema.md +127 -0
  160. package/skills/team-swarm/specs/convergence-criteria.md +108 -0
  161. package/skills/team-swarm/specs/pheromone-schema.md +125 -0
  162. package/skills/team-swarm/specs/swarm-config-template.json +71 -0
  163. package/skills/team-swarm/specs/swarm-protocol.md +123 -0
  164. package/skills/workflow-closeout/SKILL.md +10 -0
  165. package/skills/workflow-evolve/SKILL.md +79 -0
  166. package/skills/workflow-evolve/references/agy-gate.md +27 -0
  167. package/skills/workflow-evolve/references/auto-loop.md +20 -0
  168. package/skills/workflow-evolve/references/history-review.md +14 -0
  169. package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
  170. package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
  171. package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
  172. package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
  173. package/workflows/index.json +23 -0
@@ -0,0 +1,121 @@
1
+ ---
2
+ name: ew-odyssey-defensive
3
+ description: "Odyssey defensive mode — read-only defensive-programming risk audit driven by business anchors: identify critical business sinks, backward-slice to defensive nodes, scan 8 defensive patterns (broad catch, exception swallowing, defaults, null fallback, auto-correction/clamp, silent conversion, duplicate constraints, duplicate defaults), forward-propagate to business sinks, classify exception semantics, and score risk R=S×P×B×H. Produces severity matrix report with full propagation chains. No fix loop."
4
+ argument-hint: "<target: file|dir|HEAD|staged|phase#|PR#> [--tier quick|standard|deep] [--sink-depth <list>] [--skip-generalize] [-y] [-c]"
5
+ contract:
6
+ contract_version: 2.1
7
+ produces:
8
+ - path: outputs/session.json
9
+ kind: defensive-audit-result
10
+ schema: defensive-audit-result/1.0
11
+ role: primary
12
+ alias: defensive-session
13
+ required: true
14
+ - path: outputs/evidence.ndjson
15
+ kind: evidence
16
+ schema: evidence/1.0
17
+ role: evidence
18
+ alias: defensive-evidence
19
+ required: true
20
+ - path: outputs/understanding.md
21
+ kind: defensive-report
22
+ schema: defensive-report/1.0
23
+ role: primary
24
+ alias: defensive-understanding
25
+ required: true
26
+ - path: outputs/anchors.json
27
+ kind: defensive-anchors
28
+ schema: defensive-anchors/1.0
29
+ role: evidence
30
+ alias: defensive-anchors
31
+ required: false
32
+ goal: true
33
+ ---
34
+
35
+ # Pre-task Thinking: odyssey-defensive
36
+
37
+ ## Purpose
38
+
39
+ Odyssey defensive performs a systematic read-only audit of defensive-programming risk in a target module or project. Its core question is NOT "does defensive code exist", but:
40
+
41
+ > Does defensive logic transform an exception state, illegal state, or system error into an apparently-normal business state that then influences a critical business result?
42
+
43
+ The audit follows the canonical investigation path — **business-anchor driven + local program slicing + bidirectional propagation**:
44
+
45
+ ```
46
+ 业务关键结果 → 业务流恢复 → 反向数据追踪 → 识别防御性代码
47
+ → 识别状态转换 → 正向传播分析 → 业务影响判断 → 风险分级与定位
48
+ ```
49
+
50
+ It covers 8 defensive patterns (broad exception catch, exception swallowing, defaults, null fallback, auto-correction/clamp, silent conversion, duplicate constraints, duplicate defaults), 6 failure→value state transformations, exception semantic classification (A/B/C/D), and risk scoring `R = S × P × B × H`. Unlike other Odyssey modes, defensive is strictly read-only: it produces a severity matrix report with full propagation chains and remediation suggestions, but NEVER modifies source code. Before starting, establish the target scope, audit tier, and business anchors (critical variables + sink layering).
51
+
52
+ ## Input Interpretation
53
+
54
+ Target resolution determines what gets audited:
55
+
56
+ | Input | Resolution |
57
+ |-------|-----------|
58
+ | File/dir path | Audit those files |
59
+ | `--scope <path>` | Limit scan to directory |
60
+ | `HEAD` / `staged` | Review changes in diff for defensive patterns introduced/modified |
61
+ | Phase number | state.json → changed files for that phase |
62
+ | PR number | `git diff main...HEAD` |
63
+ | Project root (default) | Full project scan |
64
+ | continuation (`-c`) | Resume latest session, jump to `current_state` |
65
+
66
+ Tier selection (default: `standard`):
67
+
68
+ | Tier | ANCHOR | SLICE | SCAN | PROPAGATE | 一致性检查 | 异常分类 |
69
+ |------|--------|-------|------|-----------|-----------|---------|
70
+ | quick | ✓ (top sinks) | ✓ (shallow) | 4 类核心 (P1-P4) | ✓ (sink only) | — | — |
71
+ | standard | ✓ | ✓ | 全 8 类 (P1-P8) | ✓ | ✓ | ✓ (A/B/C/D) |
72
+ | deep | ✓ (全量) | ✓ (deep) | 全 8 类 + 历史考古 | ✓ + cross-module | ✓ + 单位校验 | ✓ 全 4 类 |
73
+
74
+ `--sink-depth <list>` explicitly constrains propagation analysis to given sink layers (1|2|3|all). Default `all` — full three-tier sink analysis.
75
+
76
+ ## Required Context
77
+
78
+ Context injection (optional, may continue if missing):
79
+
80
+ - Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → module boundaries, business-semantic layer, ownership
81
+ - Wiki: `agent-memory wiki references "<target keywords>"` → prior defensive audits, known failure→value patterns
82
+ - Specs: `agent-memory wiki constraints --category coding` → known defensive-programming patterns and standards
83
+ - Coding specs: `agent-memory wiki constraints --category review` → recurring review standards (e.g. degradation/fallback rules)
84
+ - Role knowledge: `agent-memory wiki references "<topic>" --category coding` → pick relevant items → `agent-memory wiki reference <id>`
85
+
86
+ When prior defensive-audit sessions of the same target exist, check their findings first to avoid re-reporting already-documented defensive patterns.
87
+
88
+ Use [read-only audit artifacts](../audit-artifacts.md) for the checkpoint and output metadata.
89
+
90
+ ## Boundaries and Invariants
91
+
92
+ - **Read-only** — NEVER modify source code, configuration, or dependencies during audit. Defensive audit produces reports only. All file writes target `{run_dir}/outputs/` exclusively. Fixes route to `--mode improve` or `--mode debug`.
93
+ - **Findings require a complete propagation chain** — every finding MUST reference a specific file:line, declare its trigger pattern (P1-P8), the original failure type, the failure→value state transformation, the full forward propagation chain, and the business impact. Vague or location-only findings are not actionable. The §14 standard report format is the mandatory template.
94
+ - **Risk scoring is mandatory** — every finding MUST carry the four-dimensional score `R = S × P × B × H` (S = defensive-code severity, P = propagation range, B = business criticality, H = error-hiding degree) and a final level (Critical/High/Medium/Low per §13 thresholds). Findings without a score are rejected.
95
+ - **8-pattern coverage is mandatory (standard+)** — all scan patterns required by the selected tier MUST complete. NEVER skip a tier-required pattern silently; failures are logged as W0xx warnings. quick tier covers only the 4 core patterns (P1-P4).
96
+ - **Exception semantic classification is mandatory (standard+)** — every swallowed exception MUST be classified as A (business illegal) / B (numerical/algorithm) / C (system environment) / D (program defect) per §9. Classifying all exceptions as "computation failure" is forbidden (it is the exact anti-pattern — 异常语义坍缩).
97
+ - **Q4 signal is mandatory** — for every finding, the §18 Q4 question ("can the downstream still know the upstream error occurred?") MUST be answered. Q4 = "不能" (cannot) is a high-risk signal and MUST be explicitly flagged in the report and the completion summary.
98
+ - **No fix loop** — this mode has NO S_FIX or S_CONFIRM states. Findings are reported with remediation suggestions; actual fixes route to `--mode improve` (fix defensive defect) or `--mode debug` (root-cause).
99
+ - **Local slicing, not full propagation graph** — per §2, do NOT construct a complete whole-repo propagation graph. A_SLICE is local to each critical_var; A_PROPAGATE forwards only along the sliced chain.
100
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
101
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
102
+
103
+ ## Risk Checklist
104
+
105
+ - Is every finding anchored to `file:line` with trigger pattern, original failure type, state transformation, full propagation chain, Q4 signal, and R=S×P×B×H score? Unanchored or unscored findings are not actionable.
106
+ - Were all tier-required scan patterns (P1-P8 for standard+) attempted? Missing patterns mean incomplete coverage.
107
+ - Was exception semantic classification (A/B/C/D) applied to every swallowed exception? Treating all exceptions as one class is the anti-pattern being audited for.
108
+ - Was the Q4 signal explicitly answered for every finding reaching a sink? "Cannot detect upstream error" must be flagged.
109
+ - Did the audit remain strictly read-only? Any source modification is a violation.
110
+ - Is every discovery hit individually classified with a reason? Blanket skips are forbidden.
111
+ - Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
112
+ - Did A_SLICE stay local to critical_vars instead of building a whole-repo propagation graph? Over-broad slicing violates the §2 methodology.
113
+ - Was the §14 standard report format used for every finding? Ad-hoc formats lose the propagation-chain evidence trail.
114
+ - Are duplicate constraints/defaults (P7/P8) cross-module aggregated when the tier requires it? Local-only aggregation misses the §10 consistency check.
115
+
116
+ ## Gate Intent
117
+
118
+ - `anchor-identified`: at least 1 critical variable identified AND at least 1 level-1 (business-critical) sink present in `sink_layers`. Evidence phase=anchor logged. Understanding.md §2 updated. Cannot audit without a business-critical result to protect — BLOCKED if no critical vars / no level-1 sink (E002).
119
+ - `scan-complete`: all tier-required scan patterns completed (P1-P4 for quick; P1-P8 for standard; + historical archaeology for deep). Evidence phase=scan logged per pattern. Findings merged into per-pattern buckets. Understanding.md §4 + §7 updated. Tier-required pattern not attempted is BLOCKED (W001/W002 partial from tool failure is a warning).
120
+ - `propagation-verified`: every scan candidate has a `reaches_critical_sink` verdict, a failure→value state transformation type, a Q4 signal, a four-dimensional score (S/P/B/H), a risk level, and an exception classification (A/B/C/D). No-score / no-sink-verdict candidate is BLOCKED (W003 per-item needs_review acceptable only when truly undecidable).
121
+ - `report-produced`: severity matrix with §14 standard report entries (DEF-NNN / risk / location / trigger pattern / original failure type / state transformation / full propagation chain / business impact / remediation) for every finding. Summary statistics computed. Understanding.md §8 written. Session.json `audit_result` populated. Read-only invariant verified (no source modifications in session).
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: ew-odyssey-improve
3
+ description: 6-dimension runtime quality audit → diagnose → fix → verify cycle with baseline metrics tracking and zero-residual enforcement
4
+ argument-hint: "<target> [--dimensions <list>] [--fix-threshold <severity>] [--skip-fix] [--skip-generalize] [-y] [-c]"
5
+ contract:
6
+ contract_version: 2.1
7
+ produces:
8
+ - path: outputs/session.json
9
+ kind: session
10
+ schema: session/1.0
11
+ role: primary
12
+ alias: improve-session
13
+ required: true
14
+ - path: outputs/evidence.ndjson
15
+ kind: evidence
16
+ schema: evidence/1.0
17
+ role: evidence
18
+ alias: improve-evidence
19
+ required: false
20
+ - path: outputs/understanding.md
21
+ kind: understanding
22
+ schema: understanding/1.0
23
+ role: primary
24
+ alias: improve-understanding
25
+ required: false
26
+ goal: true
27
+ ---
28
+
29
+ # Pre-task Thinking: odyssey-improve
30
+
31
+ ## Purpose
32
+
33
+ Odyssey improve performs a systematic 6-dimension quality audit of a target module or changeset, diagnoses root causes for critical/high findings, applies exhaustive fixes by severity tier, and verifies improvements against a captured baseline. Before starting, establish the target scope, dimension coverage, and baseline metrics.
34
+
35
+ ## Input Interpretation
36
+
37
+ Target resolution determines what gets audited:
38
+
39
+ | Input | Resolution |
40
+ |-------|-----------|
41
+ | Module/dir path | Audit that module |
42
+ | `HEAD` / `staged` | Review changes in diff |
43
+ | Feature area keyword | Resolve to related files |
44
+ | `--all` | Full project scan (use with caution) |
45
+
46
+ The six dimensions (default all, overridable via `--dimensions`): performance, security, architecture, reliability, observability, maintainability. `--fix-threshold` controls the minimum severity that triggers a fix (default: all).
47
+
48
+ ## Required Context
49
+
50
+ Context injection (optional, may continue if missing):
51
+
52
+ - Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → module boundaries, layering rules
53
+ - Wiki: `agent-memory wiki references "<target keywords>"` → prior audits, known issues
54
+ - Specs: `agent-memory wiki constraints --category coding` + `agent-memory wiki constraints --category debug` → coding standards, known vulnerability patterns
55
+ - Role knowledge: `agent-memory wiki references "<topic>" --category coding` → pick relevant items → `agent-memory wiki reference <id>`
56
+ - Baseline metrics: capture current test pass rate, bundle size, dependency count, complexity hotspots before any changes — these form `session.json.baseline_metrics` for before/after comparison
57
+
58
+ When prior improve sessions of the same target exist, check their audit results and fixes first to avoid re-diagnosing already-resolved issues.
59
+
60
+ ## Boundaries and Invariants
61
+
62
+ - **Zero-residual** — every finding MUST have a concrete action (fix / issue / decision). "Report and shelve" and blanket "pre-existing" skips are forbidden.
63
+ - **Dimension independence** — each of the 6 dimensions produces findings independently; one dimension's result must not suppress or override another's.
64
+ - **No partial-tier advancement** — each severity tier (critical → high → medium → low) must be fully addressed before advancing to the next; blanket "pre-existing" skip forbidden.
65
+ - **Baseline integrity** — `baseline_metrics` captured at INTAKE are immutable throughout the session; before/after comparison in §8 uses these exact values.
66
+ - **Fix scope** — fixes target diagnosed root causes, not symptoms. Symptoms may indicate a deeper architectural issue requiring `--mode debug` escalation.
67
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
68
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
69
+ - **Exhaustive audit** — all 6 dimensions (or `--dimensions` subset) must be attempted. Zero dimensions reviewed is BLOCKED, not a warning.
70
+ - **Behavioral equivalence** — fixes MUST preserve existing behavior. All tests MUST pass after each individual change, not just at the end of a tier.
71
+ - **Scope locked after confirmation** — once the fix plan is confirmed (or auto-proceeded via `-y`), no scope expansion to additional files without re-confirmation.
72
+ - **Incremental verification** — each discrete fix step MUST be verified (tests run) before proceeding. NEVER batch multiple unrelated changes into a single verification.
73
+ - **No feature creep** — fixes MUST NOT add new functionality, change APIs, or alter public interfaces. Beneficial changes discovered → evidence phase=decision as recommendations, NOT applied.
74
+ - **Rollback safety** — if any test fails after a fix step, revert that specific change before attempting alternatives. NEVER proceed with failing tests.
75
+
76
+ ## Risk Checklist
77
+
78
+ - Is every finding anchored to `file:line` with severity, dimension, description, and measurement? Unanchored findings are not actionable.
79
+ - Were baseline metrics captured before any changes? Without a baseline, the before/after comparison in §8 is meaningless.
80
+ - Are all 6 dimensions (or the `--dimensions` subset) audited with independent agents? Missing dimensions mean incomplete coverage.
81
+ - Does root cause diagnosis trace to the true source, not the symptom? Fixing symptoms leaves the root cause live.
82
+ - After each severity tier fix, was re-verification scoped to the current tier's dimension only? Cross-dimension regression checks belong at S_VERIFY.
83
+ - Were 3 diagnosis retries exhausted before marking INCONCLUSIVE? Premature escalation misses solvable issues.
84
+ - Is zero-residual enforced — every finding has fix / issue / decision, with no blanket skips?
85
+ - Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
86
+ - Does each fix preserve behavioral equivalence? A fix that changes observable behavior (API shape, return values, side effects) is scope creep, not a fix.
87
+ - Was each fix step individually verified before proceeding? Batched changes make regression attribution impossible.
88
+ - If a test failed after a fix, was that specific change reverted before trying alternatives? Proceeding with failing tests compounds risk.
89
+
90
+ ## Gate Intent
91
+
92
+ - `all-dimensions-audited`: all 6 dimensions (or `--dimensions` subset) completed audit with structured findings (`[{title, severity, dimension, file, line, description, suggestion, measurement}]`), merged into severity matrix, and evidence phase=audit logged for each. Zero dimensions reviewed is BLOCKED (W002 partial coverage from agent failure is a warning, not a block).
93
+ - `zero-remaining-verified`: all diagnosed findings are either fixed and verified, individually classified with justification (issue created / decision recorded), or legitimately skipped via `--skip-fix` flag. Tests pass over modified areas. Metrics re-captured and compared against `baseline_metrics`. No unaddressed actionable findings remain. Before/after improvement metrics table written to understanding.md §8.
@@ -0,0 +1,104 @@
1
+ ---
2
+ name: ew-odyssey-planex
3
+ description: "Odyssey planex mode — single requirement delivery loop through acceptance criteria definition, task planning, execution, verification, and fix iteration until all criteria pass"
4
+ argument-hint: "<requirement> [--template feature|bugfix|refactor|migration|api-endpoint] [--method auto|agent|<cli>] [--skip-verify] [--skip-generalize] [--max-iterations N] [-y] [-c]"
5
+ contract:
6
+ contract_version: 2.1
7
+ produces:
8
+ - path: outputs/session.json
9
+ kind: session
10
+ schema: session/1.0
11
+ role: primary
12
+ alias: planex-session
13
+ required: true
14
+ - path: outputs/evidence.ndjson
15
+ kind: evidence
16
+ schema: evidence/1.0
17
+ role: evidence
18
+ alias: planex-evidence
19
+ required: false
20
+ - path: outputs/understanding.md
21
+ kind: understanding
22
+ schema: understanding/1.0
23
+ role: primary
24
+ alias: planex-understanding
25
+ required: false
26
+ goal: true
27
+ ---
28
+
29
+ # Pre-task Thinking: odyssey-planex
30
+
31
+ ## Purpose
32
+
33
+ Odyssey planex is a full requirement delivery cycle: requirement intake → acceptance criteria derivation → task planning → execution (agent or CLI) → verification → fix iteration → generalization → discovery → knowledge persistence. Unlike standalone `/plan` + `/execute` (which handle planning and execution separately), odyssey-planex owns the entire loop from requirement to all acceptance criteria passing, including iterative fix cycles and pattern generalization.
34
+
35
+ ## Input Interpretation
36
+
37
+ Entry modes:
38
+
39
+ | Mode | Trigger | Requirement source |
40
+ |------|---------|-------------------|
41
+ | standalone | requirement description in `<intent>` | Parse requirement directly |
42
+ | template | `--template <name>` | Apply predefined criteria pattern (feature, bugfix, refactor, migration, api-endpoint) |
43
+ | continuation | `-c` | Resume via latest session, jump to `current_state` |
44
+
45
+ Template criteria patterns:
46
+
47
+ | Template | Criteria pattern | Use case |
48
+ |----------|-----------------|----------|
49
+ | `feature` | User story acceptance + boundary tests + UI verification | New feature |
50
+ | `bugfix` | Regression tests + root cause confirmation + boundary coverage | Bug fix |
51
+ | `refactor` | Behavior preservation + performance baseline + API compatibility | Refactoring |
52
+ | `migration` | Data consistency + rollback verification + performance comparison | Data/API migration |
53
+ | `api-endpoint` | Request/response contract + error handling + permission checks | API development |
54
+
55
+ Execution method is configurable at S_EXECUTE via interactive confirmation or `--method`:
56
+
57
+ | Method | Resolution |
58
+ |--------|-----------|
59
+ | `auto` | Domain routing — frontend/backend/general mapped to configured tools |
60
+ | `agent` | All tasks executed by Agent |
61
+ | `<cli-name>` | All tasks dispatched to specific CLI tool |
62
+
63
+ ## Required Context
64
+
65
+ Context injection (optional, may continue if missing):
66
+
67
+ - Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → module boundaries, integration points
68
+ - Wiki: `agent-memory wiki references "<requirement keywords>"` → prior implementations, patterns
69
+ - Specs: `agent-memory wiki constraints --category coding` → coding standards, implementation patterns
70
+ - Review specs: `agent-memory wiki constraints --category review` → acceptance criteria templates
71
+ - Role knowledge: `agent-memory wiki references "<topic>" --category coding` → pick relevant items → `agent-memory wiki reference <id>`
72
+ - CLI tools: `the Codex or Agy executables available to the host` → available executors for task dispatch
73
+
74
+ When prior planex sessions of the same scope exist, check their acceptance criteria and plan to avoid duplicating work or re-implementing already-delivered features.
75
+
76
+ ## Boundaries and Invariants
77
+
78
+ - **State chain:** `S_INTAKE → S_PLAN → S_EXECUTE → S_VERIFY → S_FIX → [back-half]` with FIX↔VERIFY loop until all criteria pass.
79
+ - **Acceptance criteria are sacred** — once confirmed at S_INTAKE, criteria cannot be silently dropped or weakened. All must reach `passed` (or `deferred` at max iteration with user consent).
80
+ - **Max iterations** (default 3) prevents infinite FIX↔VERIFY loops. When exceeded: Normal → request_user_input (continue/lower bar/accept) | `-y` → `deferred`, proceed S_RECORD.
81
+ - **Max 3 retries per task** — first attempt normal → retry with `--resume` simplified → fallback to Agent → all 3 fail → mark `blocked`, continue remaining. NEVER exceed 3 attempts.
82
+ - **Replan preserves criteria** — when S_VERIFY routes back to S_PLAN (fundamental plan flaw), `acceptance_criteria[]` statuses are preserved; only `plan.tasks[]` are regenerated. Passed criteria retain `passed`; failed criteria reset to `pending`.
83
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
84
+ - **Phase goal tracking** — mark each goal done/failed before transition; no silent skips.
85
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
86
+ - **Fix scope:** fixes target diagnosed gaps in specific failed criteria, not re-implementation. Targeted code fix, not wholesale rewrite.
87
+ - **In scope:** Single requirement delivery loop. **Out of scope:** Multi-requirement orchestration → `/ew-orchestrate --goal roadmap` | Deep debugging → `--mode debug` | Code review → `--mode review` | UI optimization → `--mode ui`.
88
+
89
+ ## Risk Checklist
90
+
91
+ - Are acceptance criteria testable and each assigned a `verify_method` (test|grep|cli-review|manual)? Vague criteria like "works well" cannot be verified.
92
+ - Is the plan decomposition complete — every criterion mapped to at least one task? Unmapped criteria will never be satisfied.
93
+ - Was execution method confirmed (or defaulted with `-y`) before task dispatch? Dispatching without confirmed config wastes cycles on wrong executors.
94
+ - Did each task respect the 3-retry hard limit? Exceeding 3 attempts on a single task is forbidden — mark `blocked` and continue.
95
+ - At S_VERIFY, was every criterion verified by its declared method? Switching methods silently (e.g., skipping `test` and using `grep` instead) undermines verification integrity.
96
+ - On replan (S_VERIFY → S_PLAN), were passed criteria preserved? Regenerating the entire criteria set loses confirmed progress.
97
+ - Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
98
+ - Is every discovery hit individually classified with a reason? Blanket "pre-existing" skips are forbidden.
99
+
100
+ ## Gate Intent
101
+
102
+ - `criteria-defined`: acceptance criteria are derived from the requirement (≥1 criterion in `acceptance_criteria[]`), each with a testable `criterion` statement and assigned `verify_method` (test|grep|cli-review|manual). Criteria are confirmed by user or auto-derived with deferred confirmation under `-y`. Goal G1 is marked.
103
+ - `all-criteria-passed`: every `acceptance_criteria[].status == passed` with recorded evidence and `passed_at` timestamp, verified by the declared `verify_method`. Iterations are logged in `iterations[]`. If max iterations exceeded, criteria may be `deferred` only with explicit user consent (or `-y` auto-accept). Goal G4 is marked.
104
+ - `plan-executed`: all plan tasks are executed (status `completed`) or explicitly `blocked` after 3 retries with logged evidence. Per-task execution evidence is recorded. Post-execution validation (convergence, existence, substance, anti-patterns) is completed unless `--skip-verify`. Goal G3 is marked.
@@ -0,0 +1,98 @@
1
+ ---
2
+ name: ew-odyssey-review
3
+ description: "Odyssey review mode — multi-dimensional deep code review through archaeology, exploration, 4-dimension audit, exhaustive severity-tiered fix, and zero-residual confirmation, producing review"
4
+ argument-hint: "<target: file|dir|HEAD|staged|phase#|PR#> [--skip-fix] [--skip-generalize] [-y] [-c]"
5
+ contract:
6
+ contract_version: 2.1
7
+ produces:
8
+ - path: outputs/session.json
9
+ kind: session
10
+ schema: session/1.0
11
+ role: primary
12
+ alias: review-session
13
+ required: true
14
+ - path: outputs/evidence.ndjson
15
+ kind: evidence
16
+ schema: evidence/1.0
17
+ role: evidence
18
+ alias: review-evidence
19
+ required: false
20
+ - path: outputs/understanding.md
21
+ kind: understanding
22
+ schema: understanding/1.0
23
+ role: primary
24
+ alias: review-understanding
25
+ required: false
26
+ goal: true
27
+ ---
28
+
29
+ # Pre-task Thinking: odyssey-review
30
+
31
+ ## Purpose
32
+
33
+ Odyssey review is a full-lifecycle code review cycle: target intake → archaeology → code exploration → multi-dimensional review audit → exhaustive severity-tiered fix → zero-residual confirmation → generalization → discovery → knowledge persistence. Unlike standalone code review (which produces only findings), odyssey-review carries through to fix ALL findings by severity, confirm zero residual, generalize patterns project-wide, and persist learnings.
34
+
35
+ ## Input Interpretation
36
+
37
+ Entry modes:
38
+
39
+ | Mode | Trigger | Target source |
40
+ |------|---------|---------------|
41
+ | file/dir | file or directory path in `<intent>` | Review those files directly |
42
+ | diff | `HEAD` or `staged` in `<intent>` | `git diff HEAD` or `git diff --staged` |
43
+ | phase | phase number in `<intent>` | state.json → changed files for that phase |
44
+ | PR | PR number in `<intent>` | `git diff main...HEAD` |
45
+ | continuation | `-c` | Resume via latest session, jump to `current_state` |
46
+
47
+ Target resolution table:
48
+
49
+ | Input | Resolution |
50
+ |-------|-----------|
51
+ | File/dir path | Review those files |
52
+ | `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
53
+ | Phase number | state.json → changed files |
54
+ | PR number | `git diff main...HEAD` |
55
+
56
+ ## Required Context
57
+
58
+ Context injection (optional, may continue if missing):
59
+
60
+ - Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → module boundaries, ownership
61
+ - Wiki: `agent-memory wiki references "<target keywords>" --json` → prior reviews and known patterns
62
+ - Specs: `agent-memory wiki constraints --category review` → known review standards and recurring patterns
63
+ - Coding specs: `agent-memory wiki constraints --category coding` → patterns relevant to the review area
64
+ - Role knowledge: `agent-memory wiki references "<topic>" --category review` → pick relevant items → `agent-memory wiki reference <id>`
65
+
66
+ When prior review artifacts of the same scope exist, check their findings first to avoid re-reviewing already-addressed patterns.
67
+
68
+ ## Boundaries and Invariants
69
+
70
+ - **State chain:** `S_INTAKE → S_ARCHAEOLOGY → S_EXPLORE → S_REVIEW → S_FIX → S_CONFIRM → [back-half]`
71
+ - **Zero-residual applies** — fix ALL findings within fix_threshold (default: all severity levels). No partial-tier advancement.
72
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
73
+ - **Phase goal tracking** — mark each goal done/failed before transition; no silent skips.
74
+ - **4-dimension mandatory** — all dimensions (correctness, security, performance, architecture) must be reviewed. Zero dimensions reviewed is BLOCKED.
75
+ - **Exhaustive fix by severity** — descend through [critical, high, medium, low], each tier fully addressed before advancing. Blanket "pre-existing" classification forbidden; each finding must be individually assessed.
76
+ - **max_fix_rounds = 5** — hard limit on fix retry rounds. After 5 rounds with remaining > 0, escalate to user or classify as deferred.
77
+ - **Test evidence reuse across S_FIX/S_CONFIRM** — a per-tier commit invalidates only tests covering the committed changes; unchanged passing results carry forward, and S_CONFIRM reruns only invalidated targets plus the modified-area re-review. Never rerun the full matrix merely because a tier advanced.
78
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
79
+ - **Fix scope:** source code modifications during fix phase are in-scope but MUST be committed per tier. Session artifacts target `{run_dir}/outputs/` only.
80
+ - **In scope:** Multi-dimensional deep review → exhaustive fix → generalize. **Out of scope:** Root cause debug → `--mode debug` | Feature implementation → `--mode planex` | UI visual optimization → `--mode ui`.
81
+
82
+ ## Risk Checklist
83
+
84
+ - Are all 4 review dimensions (correctness, security, performance, architecture) covered? Missing a dimension leaves an entire class of findings undetected.
85
+ - Is every finding backed by file, line, and description evidence? Vague findings without location are not actionable.
86
+ - Did you descend severity tiers in order (critical → high → medium → low)? Skipping tiers leaves high-severity issues unfixed.
87
+ - Is every finding in a tier either fixed or individually classified with a reason? Blanket "pre-existing" skips are forbidden.
88
+ - Have fix rounds exceeded 5? Stop and escalate — do not continue fixing indefinitely.
89
+ - Are archaeology/explore results properly logged even on partial failure (W003/W006)? Missing evidence must be flagged, not silently omitted.
90
+ - Is every discovery hit individually classified with a reason? Blanket skips are forbidden.
91
+ - Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
92
+ - Did the zero-residual confirmation actually re-review modified areas? A pass-through without re-review does not satisfy the CONFIRM gate.
93
+
94
+ ## Gate Intent
95
+
96
+ - `discovery-complete`: archaeology and/or exploration phases have logged evidence, understanding.md §2-§3 are updated, and explore goal (G2) is marked. Archaeology partial results via W003 are acceptable; explore skip via W006 is acceptable if no CLI tools are available.
97
+ - `all-dimensions-reviewed`: all 4 dimension agents (correctness, security, performance, architecture) have completed, findings are merged into review_result with severity classification, evidence phase=review is logged, and understanding.md §4 severity matrix is written. G1 is marked. Zero dimensions reviewed is BLOCKED (W002 partial with at least 1 dimension is allowed).
98
+ - `zero-remaining`: exhaustive fix has been applied tier-by-tier, `remaining_actionable == 0` (or all remaining individually classified as deferred after 5-round escalation), tests covering the modified areas pass (reusing still-valid live-run results from S_FIX rounds when nothing they cover changed since; rerunning only invalidated targets), CLI re-review confirms no new findings, confirmation is written, understanding.md §5 is updated, and G3 is marked. `needs_rework` routes back to FIX. Skippable only when `skip_fix == true`.
@@ -0,0 +1,94 @@
1
+ ---
2
+ name: ew-odyssey-security
3
+ description: "Odyssey security mode — read-only tiered security audit (OWASP Top 10, dependency supply chain, secrets, CI/CD, STRIDE, git history) producing severity matrix report with file:line evidence."
4
+ argument-hint: "<target> [--tier quick|standard|deep] [--skip-generalize] [-y] [-c]"
5
+ contract:
6
+ contract_version: 2.1
7
+ produces:
8
+ - path: outputs/session.json
9
+ kind: security-audit-result
10
+ schema: security-audit-result/1.0
11
+ role: primary
12
+ alias: security-session
13
+ required: true
14
+ - path: outputs/evidence.ndjson
15
+ kind: evidence
16
+ schema: evidence/1.0
17
+ role: evidence
18
+ alias: security-evidence
19
+ required: true
20
+ - path: outputs/understanding.md
21
+ kind: security-report
22
+ schema: security-report/1.0
23
+ role: primary
24
+ alias: security-understanding
25
+ required: true
26
+ goal: true
27
+ ---
28
+
29
+ # Pre-task Thinking: odyssey-security
30
+
31
+ ## Purpose
32
+
33
+ Odyssey security performs a systematic read-only security audit of a target module or project. It covers OWASP Top 10, dependency supply chain, secrets detection, CI/CD pipeline review, STRIDE threat modeling, and git history archaeology — tiered by depth (quick/standard/deep). Unlike other Odyssey modes, security is strictly read-only: it produces a severity matrix report with file:line evidence and remediation suggestions, but NEVER modifies source code. Before starting, establish the target scope, audit tier, and entry points.
34
+
35
+ ## Input Interpretation
36
+
37
+ Target resolution determines what gets audited:
38
+
39
+ | Input | Resolution |
40
+ |-------|-----------|
41
+ | Module/dir path | Audit that module |
42
+ | `--scope <path>` | Limit scan to directory |
43
+ | Project root (default) | Full project scan |
44
+ | `HEAD` / `staged` | Review changes in diff for security issues |
45
+
46
+ Tier selection (default: `standard`):
47
+
48
+ | Tier | OWASP | Dependencies | Secrets | CI/CD | STRIDE | Git History |
49
+ |------|-------|-------------|---------|-------|--------|-------------|
50
+ | quick | ✓ | ✓ | — | — | — | — |
51
+ | standard | ✓ | ✓ | ✓ | ✓ | — | — |
52
+ | deep | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
53
+
54
+ ## Required Context
55
+
56
+ Context injection (optional, may continue if missing):
57
+
58
+ - Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → module boundaries, trust zones
59
+ - Wiki: `agent-memory wiki references "<target keywords>"` → prior security audits, known vulnerabilities
60
+ - Specs: `agent-memory wiki constraints --category debug` → known vulnerability patterns
61
+ - Role knowledge: `agent-memory wiki references "<topic>" --category coding` → pick relevant items → `agent-memory wiki reference <id>`
62
+
63
+ When prior security audit sessions of the same target exist, check their findings first to avoid re-reporting already-documented issues.
64
+
65
+ Use [read-only audit artifacts](../audit-artifacts.md) for the checkpoint and output metadata.
66
+
67
+ ## Boundaries and Invariants
68
+
69
+ - **Read-only** — NEVER modify source code, configuration, dependencies, or CI/CD files during audit. Security audit produces reports only. All file writes target `{run_dir}/outputs/` exclusively.
70
+ - **Findings require file:line evidence** — every finding MUST reference a specific file:line location and include the vulnerable code pattern. No vague or category-only findings.
71
+ - **Severity NEVER downgraded without justification** — if a finding matches a known OWASP category, its severity follows OWASP guidance. Downgrading requires documented rationale (e.g., compensating control exists).
72
+ - **Tier coverage is mandatory** — all scan phases required by the selected tier MUST complete. NEVER skip a tier-required phase silently; failures are logged as W00x warnings.
73
+ - **False positive marking requires evidence** — marking a finding as false positive MUST include the compensating control or code path that prevents exploitation. NEVER dismiss findings without counter-evidence.
74
+ - **Secrets are never logged** — if secrets are discovered, report their location (file:line) and type but NEVER include the actual secret value in the report output.
75
+ - **No fix loop** — this mode has NO S_FIX or S_CONFIRM states. Findings are reported with remediation suggestions; actual fixes route to `--mode improve` or `--mode debug`.
76
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
77
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
78
+
79
+ ## Risk Checklist
80
+
81
+ - Is every finding anchored to `file:line` with severity, category, description, and remediation? Unanchored findings are not actionable.
82
+ - Were all tier-required scan phases attempted? Missing phases mean incomplete coverage.
83
+ - Are OWASP category severities preserved without unjustified downgrades?
84
+ - Are false positive dismissals backed by compensating-control evidence?
85
+ - Were discovered secrets reported by location only, never by value?
86
+ - Did the audit remain strictly read-only? Any source modification is a violation.
87
+ - Is every discovery hit individually classified with a reason? Blanket skips are forbidden.
88
+ - Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
89
+
90
+ ## Gate Intent
91
+
92
+ - `recon-complete`: tech stack detected, entry points identified, auth/authz modules listed, data flow mapped. Evidence phase=recon logged. Understanding.md §2 updated. Cannot scan without entry points and data flow baseline.
93
+ - `scan-complete`: all tier-required scan phases completed (OWASP + dependencies for quick; + secrets + CI/CD for standard; + STRIDE + git history for deep). Evidence phase=scan logged per phase. Findings merged into severity matrix. Understanding.md §3-§4 updated. Tier-required phase not attempted is BLOCKED (W001/W002 partial from tool failure is a warning).
94
+ - `report-produced`: severity matrix with file:line references and remediation for every finding. Summary statistics computed. Understanding.md §5 (full report) written. Session.json `audit_result` populated.
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: ew-odyssey-ui
3
+ description: "6-dimension visual experience audit with divergent exploration — survey design context, audit visual/interaction/a11y/responsive/motion/edge dimensions, diverge for polish+delight, fix, verify,"
4
+ argument-hint: "<target> [--dimensions <list>] [--skip-fix] [--skip-generalize] [-y] [-c]"
5
+ contract:
6
+ contract_version: 2.1
7
+ produces:
8
+ - path: outputs/session.json
9
+ kind: session
10
+ schema: session/1.0
11
+ role: primary
12
+ alias: ui-session
13
+ required: true
14
+ - path: outputs/evidence.ndjson
15
+ kind: evidence
16
+ schema: evidence/1.0
17
+ role: evidence
18
+ alias: ui-evidence
19
+ required: false
20
+ - path: outputs/understanding.md
21
+ kind: understanding
22
+ schema: understanding/1.0
23
+ role: primary
24
+ alias: ui-understanding
25
+ required: false
26
+ goal: true
27
+ ---
28
+
29
+ # Pre-task Thinking: odyssey-ui
30
+
31
+ ## Purpose
32
+
33
+ Odyssey UI performs a full-lifecycle visual experience optimization cycle: survey design context → 6-dimension audit (visual hierarchy, interaction states, accessibility, responsiveness, micro-interactions, edge cases) → divergent exploration for polish and delight ideas → exhaustive fix → verify → generalize to sibling components → persist learnings. Unlike a standalone review or audit, odyssey-ui goes beyond defect fixing to explore what would make the UI delightful, then carries through to fix, verify, generalize, and persist.
34
+
35
+ ## Input Interpretation
36
+
37
+ Target resolution determines what gets audited:
38
+
39
+ | Input | Resolution |
40
+ |-------|-----------|
41
+ | Component path | Audit component |
42
+ | Page/route | Audit page |
43
+ | `staged` / `HEAD` | Diff UI changes |
44
+ | Feature area | Resolve to components/pages |
45
+
46
+ The six dimensions (default all, overridable via `--dimensions`): visual_hierarchy, interaction_states, accessibility, responsiveness, micro_interactions, edge_cases. Each dimension has a distinct focus area (see Dimensions table in workflow file).
47
+
48
+ ## Required Context
49
+
50
+ Context injection (optional, may continue if missing):
51
+
52
+ - Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → component hierarchy, design system structure
53
+ - Wiki: `agent-memory wiki references "<target keywords>"` → prior UI audits, design decisions
54
+ - Specs: `agent-memory wiki constraints --category ui` → design patterns, interaction specs, accessibility rules
55
+ - Coding specs: `agent-memory wiki constraints --category coding` → component patterns, generalization patterns
56
+ - Role knowledge: `agent-memory wiki references "<topic>" --category ui` → pick relevant items → `agent-memory wiki reference <id>`
57
+ - Design system scan: scan for design tokens, CSS variables, theme imports at survey phase — these inform the audit baseline
58
+
59
+ When prior UI sessions of the same target exist, check their audit results and diverge ideas first to avoid re-auditing already-addressed dimensions.
60
+
61
+ ## Boundaries and Invariants
62
+
63
+ - **Browser is truth** — the rendered visual output in the browser is the authoritative source of UI quality; code-level analysis alone is insufficient for visual/interaction judgment.
64
+ - **Diverge before converge** — the DIVERGE phase explicitly generates ideas beyond the audit defects. Polish (shadows, transitions, hover, feedback, skeleton loading) and delight (motion design, progressive disclosure, smart defaults, celebratory feedback) are separate from fixing audit findings.
65
+ - **Decision gate narrow scope** — ONLY these qualify as decisions requiring user input: brand/style direction requiring human creative judgment | layout restructuring that significantly changes user flow | requires new design tokens or breaking component API. Everything else is actionable without user escalation.
66
+ - **All dimensions mandatory** — all 6 dimensions (or `--dimensions` subset) must be audited with independent agents. Zero dimensions reviewed is BLOCKED, not a warning.
67
+ - **Priority-ordered fixing** — findings and ideas are fixed by priority tier (critical → high → medium → low + high-impact ideas). No partial-tier advancement.
68
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
69
+ - **Fix scope** — source code modifications during fix phase are in-scope but MUST be committed per action. Session artifacts target `{run_dir}/outputs/` only.
70
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
71
+
72
+ ## Risk Checklist
73
+
74
+ - Is every audit finding anchored to `file:line` with severity, dimension, description, and suggestion? Unanchored findings are not actionable.
75
+ - Were all 6 dimensions (or `--dimensions` subset) audited with independent agents? Missing dimensions mean incomplete coverage.
76
+ - Did the DIVERGE phase go beyond fixing defects — did it explore polish and delight opportunities separately? Diverge that only restates audit findings is insufficient.
77
+ - Are the 2 diverge agents (Polish + Delight) returning distinct categories? Overlapping outputs indicate the agents were not properly scoped.
78
+ - After consolidation, is the priority list sorted by severity × impact × effort? Unsorted lists lead to suboptimal fix ordering.
79
+ - Is every discovery hit individually classified with a reason? Blanket "pre-existing" skips are forbidden.
80
+ - Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
81
+ - Does the decision gate only escalate brand/style/layout/token decisions? Over-escalation slows the cycle; under-escalation risks unwanted visual changes.
82
+
83
+ ## Gate Intent
84
+
85
+ - `all-dimensions-audited`: all 6 dimensions (or `--dimensions` subset) completed audit with structured findings (`[{title, severity, file, line, description, suggestion, dimension}]`), merged into severity matrix, and evidence phase=audit logged for each. Zero dimensions reviewed is BLOCKED (W002 partial coverage from agent failure is a warning, not a block).
86
+ - `diverge-explored`: both Polish and Delight agents completed, returning distinct `[{idea, category, impact, effort, description, inspiration}]` entries. CLI-assisted analysis completed. All outputs consolidated with audit findings into a prioritized list (severity × impact × effort). Evidence phase=diverge logged. Understanding.md §4 written.
87
+ - `zero-remaining-verified`: all prioritized findings and ideas are either fixed and verified, individually classified with justification (issue created / decision recorded), or legitimately skipped via `--skip-fix` flag. Tests pass (lint, unit, visual regression). Confirmation written. No unaddressed actionable findings remain. Understanding.md §5 updated. `needs_rework` routes back to FIX.