odyssey-ui

A_INTAKE

1. Parse arguments: target, flags, --dimensions subset
2. Generate slug, create SESSION_DIR
3. maestro search + Glob prior sessions + ARCHITECTURE.md + spec load ui/coding
4. Derive phase_goals[] from flags (apply skip_when)
5. Write session.json + understanding.md section 1, emit Goal Prompt

Commit: "odyssey-ui({slug}): INTAKE -- target parsed"

A_RESUME

Glob latest session -> read session.json -> jump to current_state.

A_SURVEY

spawn_agents_on_csv (Wave 1):

Write tasks.csv with Wave 1 rows:

"survey-tokens","Design Token Audit","Scan {target_files} for CSS variables, design tokens, theme values. Return [{token,usage_count,consistency,file,line}].","survey","","","1","pending","","",""
"survey-patterns","Pattern Inventory","Catalog component patterns, layout, spacing, typography in {target_files}. Return [{pattern,files,consistency}].","survey","","","1","pending","","",""

spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:2, max_runtime_seconds:300, output_csv_path:"wave-1-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })

Merge -> evidence (phase: "survey"). Update section 2. Mark G1 done. Commit: "odyssey-ui({slug}): SURVEY -- visual landscape"

A_AUDIT

spawn_agents_on_csv (Wave 2) -- 6 agents (one per dimension, or --dimensions subset):

Append Wave 2 rows to tasks.csv:

"audit-hierarchy","Visual Hierarchy","Spacing, typography scale, contrast, alignment, whitespace, visual weight","audit","visual-hierarchy","","2","pending","","",""
"audit-interaction","Interaction States","hover/focus/active/disabled/loading/error/empty/selected states","audit","interaction-states","","2","pending","","",""
"audit-a11y","Accessibility","WCAG AA contrast, focus mgmt, aria, keyboard nav, screen reader","audit","accessibility","","2","pending","","",""
"audit-responsive","Responsiveness","Breakpoints, overflow, touch targets >=44px, fluid typography","audit","responsiveness","","2","pending","","",""
"audit-motion","Micro-interactions","Transitions, animations, feedback, loading states, scroll behavior","audit","micro-interactions","","2","pending","","",""
"audit-edge","Edge Cases","Long text, empty data, error states, extreme values, i18n, RTL","audit","edge-cases","","2","pending","","",""

spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:6, max_runtime_seconds:600, output_csv_path:"wave-2-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })

Each returns [{title, severity, file, line, description, suggestion, dimension}]. Merge -> evidence (phase: "audit"). Write audit_result with dimensions, finding count, severity distribution. Update section 3 (severity matrix). Mark G2 done. Commit: "odyssey-ui({slug}): AUDIT -- 6-dimension review"

A_DIVERGE

spawn_agents_on_csv (Wave 3) -- 2 agents:

Append Wave 3 rows to tasks.csv:

"diverge-polish","Polish Agent","Missing subtle details: shadows, borders, transitions, hover feedback, empty states, skeleton loading, scroll behavior. Return [{idea,category:'polish',impact,effort,description}].","diverge","","","3","pending","","",""
"diverge-delight","Delight Agent","What makes this memorable: motion design, progressive disclosure, smart defaults, celebratory feedback, personality. Return [{idea,category:'delight',impact,effort,description}].","diverge","","","3","pending","","",""

spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:2, max_runtime_seconds:300, output_csv_path:"wave-3-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })

Optional CLI delegate for creative review:

maestro delegate "PURPOSE: Creative UI review for: {target}
TASK: Identify polish opportunities | Suggest delight moments | Evaluate visual rhythm
MODE: analysis  CONTEXT: @{target_files} | Survey: {token_summary} | Audit: {top_findings}
EXPECTED: JSON [{idea, category, impact, effort, description}]
CONSTRAINTS: User-perceptible improvements only
" --role analyze --mode analysis

Execute with run_in_background: true, then wait for callback.

Consolidate: audit findings + divergent ideas -> prioritized improvement list (impact/effort matrix). Write diverge_result. Append evidence (phase: "diverge"). Update section 4. Mark G3 done. Commit: "odyssey-ui({slug}): DIVERGE -- creative exploration"

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.

Commit: "odyssey-ui({slug}): FIX -- improvements applied"

A_VERIFY

1. Run tests (lint, unit, visual regression)
2. CLI-assisted: maestro delegate --role review -- visual correctness, interaction states, accessibility, responsive
3. needs_rework -> S_FIX. verified -> mark G4 done. Update section 5, write confirmation.

Commit: "odyssey-ui({slug}): VERIFY -- visual verification"

A_GENERALIZE

Skip if --skip-generalize. Pattern source: audit findings + diverge ideas (severity >= medium OR impact = high).

Wave 4 -- 4-agent scan (spawn_agents_on_csv):

Append Wave 4 rows to tasks.csv:

"gen-syntax","Syntax Grep","Grep CSS/style patterns matching '${signatures}' across project","generalization","syntax","","4","pending","","",""
"gen-semantic","Semantic Scan","Find components with same interaction pattern but missing states","generalization","semantic","","4","pending","","",""
"gen-structural","Structural Match","Find structurally similar components, check for same issues","generalization","structural","","4","pending","","",""
"gen-historical","Historical Grep","git log -S '${signature}' for UI pattern history","generalization","historical","","4","pending","","",""

spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:4, max_runtime_seconds:600, output_csv_path:"wave-4-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })

Cross-layer dedup + iterative deepening per base. Update section 6. Mark G5 done. Commit: "odyssey-ui({slug}): GENERALIZE -- pattern scan"

A_DISCOVER, A_RECORD

Base shared_actions. UI overrides:

• A_DISCOVER routing per base triage logic
• A_RECORD learnings per Knowledge Persistence table

Completion summary:

--- UI ODYSSEY COMPLETE ---
Target:     {target} | Dimensions: {dimensions_audited}
Findings:   {C}C {H}H {M}M {L}L | Diverge: {improvements} polish + {creative} delight
Fix:        {fixed_count} applied, verified={yes|skipped}
Patterns:   {extracted} ({by_layer})
Scan hits:  {total} ({cross_layer} cross-layer)
Issues:     {N} created
Decisions:  {N} resolved, {M} pending, {K} deferred
Learnings:  {N} entries
Self-iter:  {N} rounds
Goals:      {done}/{total} ({skipped} skipped)
---