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,294 @@
1
+ <!-- session-mode: inherited -->
2
+
3
+ # Workflow: Odyssey UI (Codex)
4
+
5
+ 6-dimension visual experience audit — survey design context, audit dimensions, divergent exploration, fix, verify, generalize. Codex-adapted: uses `spawn_agents_on_csv`, `request_user_input`, `update_plan`.
6
+
7
+ ---
8
+
9
+ ## State Chain
10
+
11
+ ```
12
+ S_INTAKE → S_SURVEY → S_AUDIT → S_DIVERGE → S_FIX → S_VERIFY → [back-half]
13
+ ```
14
+
15
+ Back-half: `S_GENERALIZE → S_DISCOVER → S_RECORD → END` (see [shared Codex phases](odyssey-base-codex.md) §Shared Back-Half).
16
+
17
+ ---
18
+
19
+ ## Boundary
20
+
21
+ **In scope:** Target component/page visual experience optimization — audit 6 dimensions, divergent exploration, fix, generalize to sibling components.
22
+ **Out of scope:** Backend/data/API → `--mode planex` | Deep bug investigation → `--mode debug` | Code quality review → `--mode review`.
23
+
24
+ ---
25
+
26
+ ## Decision Gate
27
+
28
+ ONLY these qualify as decisions: brand/style direction requiring human creative judgment | layout restructuring that significantly changes user flow | requires new design tokens or breaking component API.
29
+
30
+ ---
31
+
32
+ ## Context
33
+
34
+ ### Target Resolution
35
+
36
+ | Input | Resolution |
37
+ |-------|-----------|
38
+ | Component path | Audit component |
39
+ | Page/route | Audit page |
40
+ | `staged` / `HEAD` | Diff UI changes |
41
+ | Feature area | Resolve to components/pages |
42
+
43
+ ### Dimensions (6)
44
+
45
+ | Dimension | Focus |
46
+ |-----------|-------|
47
+ | visual_hierarchy | Spacing, typography scale, color contrast, alignment, whitespace, visual weight |
48
+ | interaction_states | Hover, focus, active, disabled, loading, error, empty, selected states |
49
+ | accessibility | WCAG AA contrast, focus management, aria labels, keyboard nav, screen reader |
50
+ | responsiveness | Breakpoints, overflow, touch targets, fluid typography, container queries |
51
+ | micro_interactions | Transitions, animations, feedback indicators, loading states, progress |
52
+ | edge_cases | Long text truncation, empty data, error states, extreme values, i18n, RTL |
53
+
54
+ ### Session Fields
55
+
56
+ ```json
57
+ { "target": "", "dimensions": [],
58
+ "audit_result": { "dimensions_audited": 0, "finding_count": 0, "severity_distribution": {} },
59
+ "diverge_result": { "improvements_proposed": 0, "creative_ideas": 0 },
60
+ "patterns": [], "confirmation": null, "generalization_stats": null }
61
+ ```
62
+
63
+ ### evidence.ndjson Phases
64
+
65
+ `survey|audit|diverge|fix|discovery|decision|self-iteration`
66
+
67
+ ### phase_goals[]
68
+
69
+ | ID | Goal | Phase | skip_when |
70
+ |----|------|-------|-----------|
71
+ | G1 | Survey completed | S_SURVEY | — |
72
+ | G2 | Audit completed | S_AUDIT | — |
73
+ | G3 | Divergent exploration done | S_DIVERGE | — |
74
+ | G4 | Zero remaining: all findings/ideas fixed and verified | S_VERIFY | skip_fix |
75
+ | G5 | Pattern generalized | S_GENERALIZE | skip_generalize |
76
+ | G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
77
+ | G7 | Learnings persisted | S_RECORD | — |
78
+
79
+ ### understanding.md — 8 Sections
80
+
81
+ 1. Target & Design Context
82
+ 2. Survey
83
+ 3. Audit
84
+ 4. Diverge
85
+ 5. Verify
86
+ 6. Generalize
87
+ 7. Discover
88
+ 8. Learnings
89
+
90
+ ---
91
+
92
+ ## State Machine
93
+
94
+ ### Transitions
95
+
96
+ ```
97
+ S_SURVEY → S_AUDIT : complete
98
+ S_AUDIT → S_DIVERGE : complete
99
+ S_DIVERGE → S_FIX : !skip_fix AND actionable findings/ideas
100
+ S_DIVERGE → S_GENERALIZE : (skip_fix OR no actionable) AND !skip_generalize
101
+ S_DIVERGE → S_RECORD : (skip_fix OR no actionable) AND skip_generalize
102
+ S_FIX → S_VERIFY : fix implemented
103
+ S_VERIFY → S_GENERALIZE : verified, !skip_generalize
104
+ S_VERIFY → S_RECORD : verified, skip_generalize
105
+ S_VERIFY → S_FIX : needs_rework
106
+ ```
107
+
108
+ Discover routes: new component to audit → S_AUDIT; fixable sibling → S_FIX.
109
+
110
+ ### Actions
111
+
112
+ **A_SURVEY** — (1) Design system inventory: scan for design tokens, CSS variables, theme imports. (2) Current state analysis: styling patterns, layout strategy, component hierarchy. (3) CLI-assisted: `evolve delegate --role analyze --mode analysis` (`run_in_background: true`) — survey tokens, spacing, typography, hierarchy, consistency. (4) Evidence phase=survey. Update §2. Mark G1. `update_plan`(G1 → completed)
113
+
114
+ Commit: `"odyssey-ui({slug}): SURVEY — design context survey complete"`
115
+
116
+ **A_AUDIT** — 6-dimension parallel audit via CSV wave.
117
+
118
+ **Step 1 — Generate `ui-audit.csv`:**
119
+
120
+ ```csv
121
+ id,dimension,focus,target,status,findings_json,error
122
+ "1","visual_hierarchy","Spacing, typography scale, color contrast, alignment, whitespace, visual weight","{target}","","",""
123
+ "2","interaction_states","Hover, focus, active, disabled, loading, error, empty, selected states","{target}","","",""
124
+ "3","accessibility","WCAG AA contrast, focus management, aria labels, keyboard nav, screen reader","{target}","","",""
125
+ "4","responsiveness","Breakpoints, overflow, touch targets, fluid typography, container queries","{target}","","",""
126
+ "5","micro_interactions","Transitions, animations, feedback indicators, loading states, progress","{target}","","",""
127
+ "6","edge_cases","Long text truncation, empty data, error states, extreme values, i18n, RTL","{target}","","",""
128
+ ```
129
+
130
+ If `--dimensions` subset specified, include only matching rows.
131
+
132
+ **Step 2 — Execute CSV wave:**
133
+
134
+ ```javascript
135
+ MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
136
+ spawn_agents_on_csv({
137
+ csv_path: `${sessionFolder}/ui-audit.csv`,
138
+ id_column: "id",
139
+ instruction: "You are auditing UI for a specific dimension. Read 'dimension' and 'focus' columns. Scan target component/page files. Return findings as JSON: [{title, severity, file, line, description, suggestion, dimension}].",
140
+ max_concurrency: 6,
141
+ max_runtime_seconds: 3600,
142
+ output_csv_path: `${sessionFolder}/ui-audit-results.csv`,
143
+ output_schema: { id, status, findings_json, error }
144
+ })
145
+ ```
146
+
147
+ **Step 3 — Merge:** Collect `findings_json` from all 6 agents. Merge into unified findings list. Evidence phase=audit. Write `audit_result` to session state. Update §3 severity matrix. Mark G2. `update_plan`(G2 → completed)
148
+
149
+ **GATE: all-dimensions-audited** — all 6 dimensions (or `--dimensions` subset) completed with structured findings, merged into severity matrix, evidence phase=audit logged per dimension. Zero dimensions reviewed is BLOCKED (W002 partial from agent failure is a warning).
150
+
151
+ Commit: `"odyssey-ui({slug}): AUDIT — dimension audit complete"`
152
+
153
+ **A_DIVERGE** — Goes beyond defect fixing — "what would make this delightful?"
154
+
155
+ **Step 1 — Generate `diverge.csv`:**
156
+
157
+ ```csv
158
+ id,category,focus,target,status,ideas_json,error
159
+ "1","polish","Shadows, borders, transitions, hover, feedback, empty states, skeleton loading, scroll behavior","{target}","","",""
160
+ "2","delight","Motion design, progressive disclosure, smart defaults, contextual hints, celebratory feedback, personality in copy","{target}","","",""
161
+ ```
162
+
163
+ **Step 2 — Execute CSV wave:**
164
+
165
+ ```javascript
166
+ MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
167
+ spawn_agents_on_csv({
168
+ csv_path: `${sessionFolder}/diverge.csv`,
169
+ id_column: "id",
170
+ instruction: "You are exploring UI improvements. Read 'category' (polish or delight) and 'focus' for your area. Go beyond defect fixing — find opportunities. Return ideas as JSON: [{idea, category, impact, effort, description, inspiration}].",
171
+ max_concurrency: 2,
172
+ max_runtime_seconds: 3600,
173
+ output_csv_path: `${sessionFolder}/diverge-results.csv`,
174
+ output_schema: { id, status, ideas_json, error }
175
+ })
176
+ ```
177
+
178
+ **Step 3 — CLI-assisted:** `evolve delegate --role analyze --mode analysis` (`run_in_background: true`) — polish opportunities, micro-interactions, visual rhythm, delight moments.
179
+
180
+ **Step 4 — Consolidate:** Merge audit findings + divergent ideas → prioritized list (severity x impact x effort). Evidence phase=diverge. Update §4. Mark G3. `update_plan`(G3 → completed)
181
+
182
+ **GATE: 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.
183
+
184
+ Commit: `"odyssey-ui({slug}): DIVERGE — divergent exploration complete"`
185
+
186
+ **A_FIX** — Skip if `--skip-fix`. (1) Exhaustive fix: ALL findings/ideas by priority tier (critical → high → medium → low + high-impact ideas). After each tier, re-review — new findings append. (2) Each fix → evidence phase=fix. (3) Normal: `request_user_input` per-fix | `-y`: auto-proceed, record `deferred`.
187
+
188
+ Commit: `"odyssey-ui({slug}): FIX — {tier} tier addressed"`
189
+
190
+ **A_VERIFY** — (1) Run tests (lint, unit, visual regression). (2) `evolve delegate --role review --mode analysis` (`run_in_background: true`) — visual correctness, interaction states, accessibility, responsive. (3) `needs_rework` → S_FIX; `verified` → mark G4. `update_plan`(G4 → completed). Update §5, write `confirmation`.
191
+
192
+ **GATE: zero-remaining-verified** — every prioritized finding and idea is fixed and verified, individually classified (issue / decision), or skipped via `--skip-fix`; tests pass (lint, unit, visual regression); confirmation written; no unaddressed actionable findings; understanding.md §5 updated. `needs_rework` routes back to FIX.
193
+
194
+ Commit: `"odyssey-ui({slug}): VERIFY — fix verification complete"`
195
+
196
+ ---
197
+
198
+ ## Generalize Source
199
+
200
+ Audit findings + diverge ideas (severity >= medium OR impact = high).
201
+
202
+ **Discover routing:** new component → S_AUDIT; fixable sibling → S_FIX.
203
+
204
+ ---
205
+
206
+ ## Knowledge Persistence (§8)
207
+
208
+ Include verified reusable findings in the Run summary and harvest the completed Session through Agent Memory closeout.
209
+
210
+
211
+ | Category | Content | Follow-up |
212
+ |----------|---------|-----------|
213
+ | Design pattern | Component pattern + applicable scenarios + token references | `stage spec → ui` |
214
+ | Interaction spec | State definitions + transition rules + feedback patterns | `stage spec → ui` |
215
+ | Accessibility rule | WCAG requirement + implementation approach | `stage spec → ui` |
216
+ | Reusable generalization pattern | Pattern signature + application scope | `stage spec → coding` |
217
+
218
+ ---
219
+
220
+ ## Completion Summary
221
+
222
+ ```
223
+ --- UI ODYSSEY COMPLETE ---
224
+ Target: {target} | Dimensions: {dimensions_audited}
225
+ Findings: {C}C {H}H {M}M {L}L | Diverge: {improvements} polish + {creative} delight
226
+ Fix: {fixed_count} applied, verified={yes|skipped}
227
+ Patterns: {extracted} ({by_layer})
228
+ Scan hits: {total} ({cross_layer} cross-layer)
229
+ Issues: {N} created
230
+ Decisions: {N} resolved, {M} pending, {K} deferred
231
+ Learnings: {N} persisted
232
+ Self-iter: {N} rounds
233
+ Goals: {done}/{total} ({skipped} skipped)
234
+ ---
235
+ ```
236
+
237
+ ---
238
+
239
+ ## Mode `-y` Points
240
+
241
+ | Decision Point | Normal | `-y` |
242
+ |---------------|--------|------|
243
+ | A_FIX confirmation | `request_user_input` | auto-proceed `deferred` |
244
+ | A_DISCOVER routing | `request_user_input` | auto-fix w/ template, issue for rest |
245
+
246
+ ---
247
+
248
+ ## Phase Gates
249
+
250
+ - **Discovery gate** (SURVEY): evidence logged, understanding.md updated. Survey requires all scan types attempted.
251
+ - **Audit gate** (AUDIT+DIVERGE): all dimension agents completed, findings merged. Diverge agents completed, ideas consolidated. Zero dimensions reviewed is BLOCKED (W002 partial allowed).
252
+ - **FIX gate:** current priority tier fully addressed. Per-fix evidence logged. Auto-commit per tier.
253
+ - **VERIFY gate:** tests pass; confirmation written, understanding.md updated, verify goal marked. needs_rework → route back to FIX.
254
+
255
+ ---
256
+
257
+ ## Error Codes
258
+
259
+ | Code | Severity | Condition | Recovery |
260
+ |------|----------|-----------|----------|
261
+ | E001 | error | No target provided | Provide target or -c |
262
+ | E002 | error | Target path not found | Check path |
263
+ | W002 | warning | Some dimension agents failed | Partial coverage accepted |
264
+ | W004 | warning | Generalization 0 hits after full 3-layer scan | Advance to S_RECORD |
265
+ | W005 | warning | Pending decisions | Filter evidence phase=decision |
266
+
267
+ ---
268
+
269
+ ## Success Criteria
270
+
271
+ - [ ] Target resolved; session + output files created
272
+ - [ ] Survey completed with design system inventory + current state analysis
273
+ - [ ] 6-dimension audit completed with structured findings + severity matrix
274
+ - [ ] Divergent exploration: polish + delight ideas consolidated with audit findings
275
+ - [ ] understanding.md 8 sections written progressively (§1–§8)
276
+ - [ ] Fix + verify (unless --skip-fix); all findings/ideas addressed by priority
277
+ - [ ] Multi-layer generalization + discovery triage (unless --skip-generalize)
278
+ - [ ] phase_goals derived, tracked, and hardened-audited; goal_mode injected via prepare goal:true
279
+ - [ ] Session resumable via -c; completion summary emitted
280
+
281
+ ---
282
+
283
+ ## Next Step Routing
284
+
285
+ | Condition | Next |
286
+ |-----------|------|
287
+ | Discovery issues created | `Open the follow-up findings in the project issue tracker` |
288
+ | Backend/data issue found | `$ew-odyssey <target> --mode planex` |
289
+ | Deep bug investigation | `$ew-odyssey <target> --mode debug` |
290
+ | Code quality review | `$ew-odyssey <changed-files> --mode review` |
291
+ | Document pattern | Review the component and harvest reusable methods through Agent Memory. |
292
+ | Second opinion | `evolve delegate "<review prompt>" --mode analysis` |
293
+ | Design/interaction pattern to persist | `stage spec → ui` |
294
+ | Pending decisions | Filter evidence phase=decision status=pending |
@@ -0,0 +1,250 @@
1
+ ---
2
+ name: ew-odyssey-ui
3
+ prepare: odyssey-ui
4
+ session-mode: inherited
5
+ ---
6
+
7
+ # Workflow: Odyssey UI
8
+
9
+ 6-dimension visual experience audit — survey design context → audit dimensions → divergent exploration → fix → verify → generalize.
10
+
11
+ ---
12
+
13
+ ## State Chain
14
+
15
+ ```
16
+ S_INTAKE → S_SURVEY → S_AUDIT → S_DIVERGE → S_FIX → S_VERIFY → [back-half]
17
+ ```
18
+
19
+ Back-half: `S_GENERALIZE → S_DISCOVER → S_RECORD → END` (see [shared phases](odyssey-base.md) §Shared Back-Half).
20
+
21
+ ---
22
+
23
+ ## Boundary
24
+
25
+ **In scope:** Target component/page visual experience optimization — audit 6 dimensions, divergent exploration, fix, generalize to sibling components.
26
+ **Out of scope:** Backend/data/API → `--mode planex` | Deep bug investigation → `--mode debug` | Code quality review → `--mode review`.
27
+
28
+ ---
29
+
30
+ ## Decision Gate
31
+
32
+ ONLY these qualify as decisions: brand/style direction requiring human creative judgment | layout restructuring that significantly changes user flow | requires new design tokens or breaking component API.
33
+
34
+ ---
35
+
36
+ ## Context
37
+
38
+ ### Target Resolution
39
+
40
+ | Input | Resolution |
41
+ |-------|-----------|
42
+ | Component path | Audit component |
43
+ | Page/route | Audit page |
44
+ | `staged` / `HEAD` | Diff UI changes |
45
+ | Feature area | Resolve to components/pages |
46
+
47
+ ### Dimensions (6)
48
+
49
+ | Dimension | Focus |
50
+ |-----------|-------|
51
+ | visual_hierarchy | Spacing, typography scale, color contrast, alignment, whitespace, visual weight |
52
+ | interaction_states | Hover, focus, active, disabled, loading, error, empty, selected states |
53
+ | accessibility | WCAG AA contrast, focus management, aria labels, keyboard nav, screen reader |
54
+ | responsiveness | Breakpoints, overflow, touch targets, fluid typography, container queries |
55
+ | micro_interactions | Transitions, animations, feedback indicators, loading states, progress |
56
+ | edge_cases | Long text truncation, empty data, error states, extreme values, i18n, RTL |
57
+
58
+ ### Session Fields
59
+
60
+ ```json
61
+ { "target": "", "dimensions": [],
62
+ "audit_result": { "dimensions_audited": 0, "finding_count": 0, "severity_distribution": {} },
63
+ "diverge_result": { "improvements_proposed": 0, "creative_ideas": 0 },
64
+ "patterns": [], "confirmation": null, "generalization_stats": null }
65
+ ```
66
+
67
+ ### evidence.ndjson Phases
68
+
69
+ `survey|audit|diverge|fix|discovery|decision|self-iteration`
70
+
71
+ ### phase_goals[]
72
+
73
+ | ID | Goal | Phase | skip_when |
74
+ |----|------|-------|-----------|
75
+ | G1 | Survey completed | S_SURVEY | — |
76
+ | G2 | Audit completed | S_AUDIT | — |
77
+ | G3 | Divergent exploration done | S_DIVERGE | — |
78
+ | G4 | Zero remaining: all findings/ideas fixed and verified | S_VERIFY | skip_fix |
79
+ | G5 | Pattern generalized | S_GENERALIZE | skip_generalize |
80
+ | G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
81
+ | G7 | Learnings persisted | S_RECORD | — |
82
+
83
+ ### understanding.md — 8 Sections
84
+
85
+ 1. Target & Design Context
86
+ 2. Survey
87
+ 3. Audit
88
+ 4. Diverge
89
+ 5. Verify
90
+ 6. Generalize
91
+ 7. Discover
92
+ 8. Learnings
93
+
94
+ ---
95
+
96
+ ## State Machine
97
+
98
+ ### Transitions
99
+
100
+ ```
101
+ S_SURVEY → S_AUDIT : complete
102
+ S_AUDIT → S_DIVERGE : complete
103
+ S_DIVERGE → S_FIX : !skip_fix AND actionable findings/ideas
104
+ S_DIVERGE → S_GENERALIZE : (skip_fix OR no actionable) AND !skip_generalize
105
+ S_DIVERGE → S_RECORD : (skip_fix OR no actionable) AND skip_generalize
106
+ S_FIX → S_VERIFY : fix implemented
107
+ S_VERIFY → S_GENERALIZE : verified, !skip_generalize
108
+ S_VERIFY → S_RECORD : verified, skip_generalize
109
+ S_VERIFY → S_FIX : needs_rework
110
+ ```
111
+
112
+ Discover routes: new component to audit → S_AUDIT; fixable sibling → S_FIX.
113
+
114
+ ### Actions
115
+
116
+ **A_SURVEY** — (1) Design system inventory: scan for design tokens, CSS variables, theme imports. (2) Current state analysis: styling patterns, layout strategy, component hierarchy. (3) CLI-assisted: `evolve delegate --role analyze --mode analysis` (`run_in_background: true`) — survey tokens, spacing, typography, hierarchy, consistency. (4) Evidence phase=survey. Update §2. Mark G1.
117
+
118
+ Commit: `"odyssey-ui({slug}): SURVEY — design context survey complete"`
119
+
120
+ **A_AUDIT** — Spawn 6 parallel Agents (one per dimension, or `--dimensions` subset; see Dimensions table). Each returns `[{title, severity, file, line, description, suggestion, dimension}]`. Merge → evidence phase=audit. Write `audit_result`. Update §3 severity matrix. Mark G2.
121
+
122
+ **GATE: all-dimensions-audited** — all 6 dimensions (or `--dimensions` subset) completed with structured findings, merged into severity matrix, evidence phase=audit logged per dimension. Zero dimensions reviewed is BLOCKED (W002 partial from agent failure is a warning).
123
+
124
+ Commit: `"odyssey-ui({slug}): AUDIT — dimension audit complete"`
125
+
126
+ **A_DIVERGE** — Goes beyond defect fixing — "what would make this delightful?"
127
+
128
+ **Step 1 — 2 parallel Agents:**
129
+ - **Polish Agent**: shadows, borders, transitions, hover, feedback, empty states, skeleton loading, scroll behavior.
130
+ - **Delight Agent**: motion design, progressive disclosure, smart defaults, contextual hints, celebratory feedback, personality in copy.
131
+
132
+ Each returns `[{idea, category (polish|delight), impact, effort, description, inspiration}]`.
133
+
134
+ **Step 2 — CLI-assisted:** `evolve delegate --role analyze --mode analysis` (`run_in_background: true`) — polish opportunities, micro-interactions, visual rhythm, delight moments.
135
+
136
+ **Step 3 — Consolidate:** merge audit findings + divergent ideas → prioritized list (severity × impact × effort). Evidence phase=diverge. Update §4. Mark G3.
137
+
138
+ **GATE: 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.
139
+
140
+ Commit: `"odyssey-ui({slug}): DIVERGE — divergent exploration complete"`
141
+
142
+ **A_FIX** — Skip if `--skip-fix`. (1) Exhaustive fix: ALL findings/ideas by priority tier (critical → high → medium → low + high-impact ideas). After each tier, re-review — new findings append. (2) Each fix → evidence phase=fix. (3) Normal: request_user_input per-fix | `-y`: auto-proceed, record `deferred`.
143
+
144
+ Commit: `"odyssey-ui({slug}): FIX — {tier} tier addressed"`
145
+
146
+ **A_VERIFY** — (1) Run tests (lint, unit, visual regression). (2) `evolve delegate --role review --mode analysis` (`run_in_background: true`) — visual correctness, interaction states, accessibility, responsive. (3) `needs_rework` → S_FIX; `verified` → mark G4. Update §5, write `confirmation`.
147
+
148
+ **GATE: zero-remaining-verified** — every prioritized finding and idea is fixed and verified, individually classified (issue / decision), or skipped via `--skip-fix`; tests pass (lint, unit, visual regression); confirmation written; no unaddressed actionable findings; understanding.md §5 updated. `needs_rework` routes back to FIX.
149
+
150
+ Commit: `"odyssey-ui({slug}): VERIFY — fix verification complete"`
151
+
152
+ ---
153
+
154
+ ## Generalize Source
155
+
156
+ Audit findings + diverge ideas (severity >= medium OR impact = high).
157
+
158
+ **Discover routing:** new component → S_AUDIT; fixable sibling → S_FIX.
159
+
160
+ ---
161
+
162
+ ## Knowledge Persistence (§8)
163
+
164
+ Include verified reusable findings in the Run summary and harvest the completed Session through Agent Memory closeout.
165
+
166
+
167
+ | Category | Content | Follow-up |
168
+ |----------|---------|-----------|
169
+ | Design pattern | Component pattern + applicable scenarios + token references | `stage spec → ui` |
170
+ | Interaction spec | State definitions + transition rules + feedback patterns | `stage spec → ui` |
171
+ | Accessibility rule | WCAG requirement + implementation approach | `stage spec → ui` |
172
+ | Reusable generalization pattern | Pattern signature + application scope | `stage spec → coding` |
173
+
174
+ ---
175
+
176
+ ## Completion Summary
177
+
178
+ ```
179
+ --- UI ODYSSEY COMPLETE ---
180
+ Target: {target} | Dimensions: {dimensions_audited}
181
+ Findings: {C}C {H}H {M}M {L}L | Diverge: {improvements} polish + {creative} delight
182
+ Fix: {fixed_count} applied, verified={yes|skipped}
183
+ Patterns: {extracted} ({by_layer})
184
+ Scan hits: {total} ({cross_layer} cross-layer)
185
+ Issues: {N} created
186
+ Decisions: {N} resolved, {M} pending, {K} deferred
187
+ Learnings: {N} persisted
188
+ Self-iter: {N} rounds
189
+ Goals: {done}/{total} ({skipped} skipped)
190
+ ---
191
+ ```
192
+
193
+ ---
194
+
195
+ ## Mode `-y` Points
196
+
197
+ | Decision Point | Normal | `-y` |
198
+ |---------------|--------|------|
199
+ | A_FIX confirmation | request_user_input | auto-proceed `deferred` |
200
+ | A_DISCOVER routing | request_user_input | auto-fix w/ template, issue for rest |
201
+
202
+ ---
203
+
204
+ ## Phase Gates
205
+
206
+ - **Discovery gate** (SURVEY): evidence logged, understanding.md updated. Survey requires all scan types attempted.
207
+ - **Audit gate** (AUDIT+DIVERGE): all dimension agents completed, findings merged. Diverge agents completed, ideas consolidated. Zero dimensions reviewed is BLOCKED (W002 partial allowed).
208
+ - **FIX gate:** current priority tier fully addressed. Per-fix evidence logged. Auto-commit per tier.
209
+ - **VERIFY gate:** tests pass; confirmation written, understanding.md updated, verify goal marked. needs_rework → route back to FIX.
210
+
211
+ ---
212
+
213
+ ## Error Codes
214
+
215
+ | Code | Severity | Condition | Recovery |
216
+ |------|----------|-----------|----------|
217
+ | E001 | error | No target provided | Provide target or -c |
218
+ | E002 | error | Target path not found | Check path |
219
+ | W002 | warning | Some dimension agents failed | Partial coverage accepted |
220
+ | W004 | warning | Generalization 0 hits after full 3-layer scan | Advance to S_RECORD |
221
+ | W005 | warning | Pending decisions | Filter evidence phase=decision |
222
+
223
+ ---
224
+
225
+ ## Success Criteria
226
+
227
+ - [ ] Target resolved; session + output files created
228
+ - [ ] Survey completed with design system inventory + current state analysis
229
+ - [ ] 6-dimension audit completed with structured findings + severity matrix
230
+ - [ ] Divergent exploration: polish + delight ideas consolidated with audit findings
231
+ - [ ] understanding.md 8 sections written progressively (§1–§8)
232
+ - [ ] Fix + verify (unless --skip-fix); all findings/ideas addressed by priority
233
+ - [ ] Multi-layer generalization + discovery triage (unless --skip-generalize)
234
+ - [ ] phase_goals derived, tracked, and hardened-audited; goal_mode injected via prepare goal:true
235
+ - [ ] Session resumable via -c; completion summary emitted
236
+
237
+ ---
238
+
239
+ ## Next Step Routing
240
+
241
+ | Condition | Next |
242
+ |-----------|------|
243
+ | Discovery issues created | `Open the follow-up findings in the project issue tracker` |
244
+ | Backend/data issue found | `/ew-odyssey <target> --mode planex` |
245
+ | Deep bug investigation | `/ew-odyssey <target> --mode debug` |
246
+ | Code quality review | `/ew-odyssey <changed-files> --mode review` |
247
+ | Document pattern | Review the component and harvest reusable methods through Agent Memory. |
248
+ | Second opinion | `evolve delegate "<review prompt>" --mode analysis` |
249
+ | Design/interaction pattern to persist | `stage spec → ui` |
250
+ | Pending decisions | Filter evidence phase=decision status=pending |
@@ -0,0 +1,105 @@
1
+ ---
2
+ name: ew-odyssey-debug
3
+ description: "Odyssey debug mode — symptom-driven investigation through archaeology, exploration, hypothesis testing, fix, and confirmation, producing diagnosis with full evidence trail"
4
+ argument-hint: "<issue> [--template performance|memory-leak|race-condition|regression|crash] [--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: debug-session
13
+ required: true
14
+ - path: outputs/evidence.ndjson
15
+ kind: evidence
16
+ schema: evidence/1.0
17
+ role: evidence
18
+ alias: debug-evidence
19
+ required: true
20
+ - path: outputs/understanding.md
21
+ kind: diagnosis-report
22
+ schema: diagnosis-report/1.0
23
+ role: primary
24
+ alias: debug-understanding
25
+ required: true
26
+ - path: outputs/explore.json
27
+ kind: exploration
28
+ schema: exploration/1.0
29
+ role: evidence
30
+ alias: debug-explore
31
+ required: false
32
+ goal: true
33
+ ---
34
+
35
+ # Pre-task Thinking: odyssey-debug
36
+
37
+ ## Purpose
38
+
39
+ Odyssey debug is a full-lifecycle debugging cycle: symptom intake → archaeology → code exploration → hypothesis-driven diagnosis → fix → confirmation → generalization → discovery → knowledge persistence. Unlike standalone `/debug` (which produces only a diagnosis), odyssey-debug carries through to fix, confirm, generalize sibling occurrences, and persist learnings.
40
+
41
+ ## Input Interpretation
42
+
43
+ Entry modes:
44
+
45
+ | Mode | Trigger | Symptom source |
46
+ |------|---------|----------------|
47
+ | standalone | issue description in `<intent>` | Parse issue description directly |
48
+ | template | `--template <name>` | Apply predefined investigation strategy (performance, memory-leak, race-condition, regression, crash) |
49
+ | continuation | `-c` | Resume via latest session, jump to `current_state` |
50
+
51
+ Template strategies:
52
+
53
+ | Template | Strategy | Use case |
54
+ |----------|----------|----------|
55
+ | `performance` | profiling → hot path → allocation → cache | Performance degradation |
56
+ | `memory-leak` | heap snapshot → retention chain → lifecycle | Memory leaks |
57
+ | `race-condition` | timeline → concurrent access → lock analysis | Race conditions |
58
+ | `regression` | git bisect → diff analysis → boundary check | Regressions |
59
+ | `crash` | stack trace → null chain → error propagation | Crashes / exceptions |
60
+
61
+ ## Required Context
62
+
63
+ Context injection (optional, may continue if missing):
64
+
65
+ - Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → module boundaries, ownership
66
+ - Wiki: `agent-memory wiki references "<symptom keywords>" --json` → prior investigations
67
+ - Specs: `agent-memory wiki constraints --category debug --keyword "<symptom>"` → known issues/workarounds
68
+ - Coding specs: `agent-memory wiki constraints --category coding` → patterns relevant to the issue area
69
+ - Role knowledge: `agent-memory wiki references "<topic>" --category debug` → pick relevant items → `agent-memory wiki reference <id>`
70
+
71
+ When prior debug artifacts of the same scope exist, check their root cause first to avoid re-investigating an already-confirmed root cause.
72
+
73
+ ## Boundaries and Invariants
74
+
75
+ - **State chain:** `S_INTAKE → S_ARCHAEOLOGY → S_EXPLORE → S_DIAGNOSE → S_FIX → S_CONFIRM → [back-half]`
76
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
77
+ - **Phase goal tracking** — mark each goal done/failed before transition; no silent skips.
78
+ - **Root cause confirmation requires evidence** — a hypothesis without reproduction or code/log evidence stays "suspected", never promoted to confirmed.
79
+ - **3-strike escalation** — stop after 3 failed hypotheses and escalate (delegate or ask user); do not free-associate a 4th.
80
+ - **Backward trace** from where the error first appears to where correct data turned wrong; fix at the source, not at the symptom.
81
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
82
+ - **Fix scope:** source code modifications during fix phase are in-scope but MUST be committed per action. Session artifacts target `{run_dir}/outputs/` only.
83
+ - **In scope:** Single bug/issue full loop. **Out of scope:** Features → `--mode planex` | Quality review → `--mode review` | UI → `--mode ui` | Architecture → `/ew-orchestrate --goal plan`.
84
+
85
+ ## Run Artifact Metadata
86
+
87
+ Keep domain progress in `outputs/session.json`. Keep the Run identity in the Evolve Session receipt. Resume Debug from the domain checkpoint after attaching to the exact Run.
88
+
89
+ Use the artifact identities in the contract above. For `session.json` and `explore.json`, put `kind`, `schema`, `role` and `alias` in the top-level `_meta` object. Put the same fields in the first JSON record of `evidence.ndjson` under `_meta`, and append later observations as separate lines. Put those fields in the YAML frontmatter of `understanding.md`. Keep the Debug phase fields alongside the artifact metadata. `evolve run complete` validates artifact identities and availability as part of sealing.
90
+
91
+ ## Risk Checklist
92
+
93
+ - Is every confirmed root cause backed by a reproduction or code/log evidence? A hypothesis without evidence must stay "suspected", never promoted to confirmed.
94
+ - Did you change only one variable at a time during diagnosis? Simultaneous changes make attribution impossible.
95
+ - Have 3 hypotheses failed? Stop and escalate to architecture inspection — do not propose a 4th hypothesis on your own.
96
+ - Did the trace reach the true source? Fixing at the symptom rather than where correct data first turned wrong leaves the root cause live.
97
+ - Are archaeology/explore results properly logged even on partial failure (W003/W006)? Missing evidence must be flagged, not silently omitted.
98
+ - Is every discovery hit individually classified with a reason? Blanket "pre-existing" skips are forbidden.
99
+ - Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
100
+
101
+ ## Gate Intent
102
+
103
+ - `discovery-complete`: archaeology and/or exploration phases have logged evidence, understanding.md §2-§3 are updated, and discovery goal (G2) is marked. Archaeology partial results via W003 are acceptable; explore skip via W006 is acceptable if no CLI tools are available.
104
+ - `diagnosis-confirmed`: all hypotheses are tested with evidence logged (phase=diagnosis), root cause is confirmed with reproduction or code/log evidence (or INCONCLUSIVE after 3-strike escalation), and understanding.md §4-§5 are written. Zero hypotheses tested is BLOCKED.
105
+ - `fix-confirmed`: fix is implemented and tests pass, CLI review completed, `confirmation.overall` is set, understanding.md §6 is written, and verify goal (G3) is marked. `needs_rework` routes back to FIX. Skippable only when `skip_fix == true`.