maestro-flow 0.5.39 → 0.5.41

package/.claude/commands/odyssey-ui.md

@@ -15,46 +15,42 @@ allowed-tools:
 <base>@~/.maestro/workflows/odyssey-base.md</base>
 
 <purpose>
-Deep UI polish cycle: survey → 6-dimension audit → divergent creative exploration →
-fix → verify → generalize → discover → persist. Every pixel is a learning opportunity.
+survey → 6-dimension audit → divergent exploration → fix → verify → generalize → discover → persist.
+Exhaustive iteration until all findings addressed or deferred.
 </purpose>
 
 <boundary>
-**范围内:** 目标组件/页面的视觉体验优化 — 审查 6 维度 → 发散探索 → 修复 → 泛化到兄弟组件
-**范围外:** 后端逻辑 / 数据模型 / API 设计 / 业务规则 → `/odyssey-planex` | 深度 bug 调查 → `/odyssey-debug` | 代码质量审查 → `/odyssey-review-test-fix`
-**探索自由度:** 边界内最大自由 — S_DIVERGE 阶段鼓励发散思维，不设创意上限。审查 + 发散可发现任何视觉/交互/可访问性细节。在约束下尽可能完善每个像素。
-**Zero-residual principle:** Every finding/idea MUST have a concrete action (fix / issue / decision). "Report and shelve" is not allowed. "Pre-existing design debt" is not a valid skip reason — if discovered within scope, it must be addressed.
-⚠️ **Decision gate** — ONLY these qualify as decisions (not fixes):
+**In scope:** Target component/page visual experience optimization — audit 6 dimensions, divergent exploration, fix, generalize to sibling components.
+**Out of scope:** Backend/data/API → `/odyssey-planex` | Deep bug investigation → `/odyssey-debug` | Code quality review → `/odyssey-review-test-fix`
+
+**Decision gate** — ONLY these qualify as decisions:
   - Brand/style direction requiring human creative judgment
   - Layout restructuring that changes user flow significantly
   - Requires new design tokens or breaking component API
-❌ "Unsure how to fix", "Large scope", "Pre-existing issue" are NOT valid decision reasons — either fix it, or explain specifically why it's unfixable
 </boundary>
 
 <context>
-$ARGUMENTS — target and optional flags.
+$ARGUMENTS
 
 **Target resolution:** Component path → audit component | Page/route → audit page | `staged`/`HEAD` → diff UI changes | Feature area → resolve to components/pages
 
-**Flags:**
-| Flag | Effect | Default |
-|------|--------|---------|
-| `--dimensions <list>` | Comma-separated subset of 6 dimensions | all 6 |
-| `--fix-threshold <severity>` | 修复到哪个 severity 为止 | all |
-| `--skip-fix` | Audit + diverge only, no code changes | false |
-| `--skip-generalize` | Skip S_GENERALIZE and S_DISCOVER | false |
-| `--auto` | CLI delegates without confirmation | false |
-| `-y` | Auto-confirm all decisions (see appendix) | false |
-| `-c` | Resume most recent session | — |
-| `--heartbeat` | Enable heartbeat progress reporting | false |
+**Flags:** `--dimensions <list>` dimension subset | `--fix-threshold <severity>` | `--skip-fix` audit+diverge only | `--skip-generalize` skip generalize+discover | `--auto` no delegate confirmation | `-y` auto-confirm | `-c` resume | `--heartbeat` /loop heartbeat
 
-**Session**: `SESSION_DIR = .workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`
+**Session**: `.workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`
+**Output**: `session.json` | `evidence.ndjson` | `understanding.md`
 
-**Output — 3 files:** `session.json` (state + audit/diverge results + patterns + phase_goals) | `evidence.ndjson` (phases: survey, audit, diverge, fix, discovery, decision, self-iteration) | `understanding.md` (8-section narrative)
+**session.json — ui-specific fields:**
+```json
+{ "target": "", "dimensions": [],
+  "audit_result": { "dimensions_audited": 0, "finding_count": 0, "severity_distribution": {} },
+  "diverge_result": { "improvements_proposed": 0, "creative_ideas": 0 },
+  "patterns": [], "confirmation": null, "generalization_stats": null }
+```
 
-**session.json unique fields:** `target`, `dimensions`, `audit_result` {dimensions_audited, finding_count, severity_distribution}, `diverge_result` {improvements_proposed, creative_ideas}, `patterns[]` {id, source_finding, layer, signature, description, risk, fix_template, confidence}, `confirmation` {test_result, cli_review, overall}, `generalization_stats` {patterns_extracted, total_hits, cross_layer_confirmed, regression_risks, by_layer, deepening_triggered}
+**evidence.ndjson phases:** `survey|audit|diverge|fix|discovery|decision|self-iteration`
 
 **phase_goals[]:**
+
 | ID | Goal | Phase | skip_when |
 |----|------|-------|-----------|
 | G1 | Survey completed | S_SURVEY | — |
@@ -65,89 +61,85 @@ $ARGUMENTS — target and optional flags.
 | G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
 | G7 | Learnings persisted | S_RECORD | — |
 
-**understanding.md:** §1 Target & Design Context | §2 Survey | §3 Audit | §4 Diverge | §5 Verify | §6 Generalize | §7 Discover | §8 Learnings
+**understanding.md — 8 sections:**
+1. Target & Design Context ← S_INTAKE | 2. Survey ← S_SURVEY | 3. Audit ← S_AUDIT
+4. Diverge ← S_DIVERGE | 5. Verify ← S_VERIFY | 6. Generalize ← S_GENERALIZE
+7. Discover ← S_DISCOVER | 8. Learnings ← S_RECORD
 
-### Pre-load（可选，缺失不阻塞）
-ARCHITECTURE.md | `maestro search "<target>" --json` (top 5) | `maestro load --type spec --category ui` | `maestro load --type spec --category coding` | `maestro search --category ui` → load knowhow | Glob prior sessions
+**Knowledge Persistence categories (section 8):**
 
-### Knowledge Persistence（S_RECORD 写入 understanding.md §8）
-| 分类 | 写入内容 | 后续建议命令 |
-|------|---------|-------------|
-| 设计 pattern | 组件模式 + 适用场景 + token 引用 | `/spec-add ui "..."` |
-| 交互规范 | 状态定义 + 转场规则 + 反馈模式 | `/spec-add ui "..."` |
-| 可访问性规则 | WCAG 要求 + 实现方案 | `/spec-add ui "..."` |
-| 可复用泛化 pattern | pattern 签名 + 应用范围 | `/spec-add coding "..."` |
+| Category | Content | Follow-up |
+|----------|---------|-----------|
+| Design pattern | Component pattern + applicable scenarios + token references | `/spec-add ui` |
+| Interaction spec | State definitions + transition rules + feedback patterns | `/spec-add ui` |
+| Accessibility rule | WCAG requirement + implementation approach | `/spec-add ui` |
+| Reusable generalization pattern | Pattern signature + application scope | `/spec-add coding` |
 </context>
 
+<invariants>
+1-5 in base. UI-specific:
+6. **Browser is truth** — verify in real rendering, not just code review
+7. **Diverge before converge** — explore creatively first, then implement methodically
+</invariants>
+
 <self_iteration>
-适用阶段: S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE
+Applies to: **S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE**. Logic in base.
 </self_iteration>
 
 <state_machine>
 
 <states>
-S_INTAKE     — Parse target, load design context, resume session           PERSIST: session.json + understanding.md §1
-S_SURVEY     — Visual landscape: design tokens, pattern inventory          PERSIST: evidence.ndjson (survey) + understanding.md §2
-S_AUDIT      — 6-dimension parallel review                                 PERSIST: evidence.ndjson (audit) + understanding.md §3
-S_DIVERGE    — Divergent creative exploration: polish + delight            PERSIST: evidence.ndjson (diverge) + understanding.md §4
-S_FIX        — Implement improvements (skip if --skip-fix)                 PERSIST: code changes + evidence.ndjson (fix)
-S_VERIFY     — Visual verification + test (skip if --skip-fix)             PERSIST: session.json.confirmation + understanding.md §5
-S_GENERALIZE — Pattern extraction + 4-agent scan (skip if --skip-gen)      PERSIST: session.json.patterns + understanding.md §6
-S_DISCOVER   — Classify hits, create issues (skip if --skip-gen)           PERSIST: evidence.ndjson (discovery|decision) + understanding.md §7
-S_RECORD     — Design knowledge persistence + final report                 PERSIST: understanding.md §8 + spec entries
+S_INTAKE → S_SURVEY → S_AUDIT → S_DIVERGE → S_FIX → S_VERIFY → S_GENERALIZE → S_DISCOVER → S_RECORD → END
 </states>
 
 <transitions>
-S_INTAKE:
-  → S_INTAKE      WHEN -c + session found        DO A_RESUME
-  → S_SURVEY      WHEN target resolved            DO A_INTAKE
-  → S_INTAKE      WHEN no target                  DO AskUserQuestion
-
-S_SURVEY       → S_AUDIT        DO A_SURVEY
-S_AUDIT        → S_DIVERGE      DO A_AUDIT
-
-S_DIVERGE:
-  → S_FIX          WHEN !skip_fix AND actionable findings/ideas           DO A_DIVERGE
-  → S_GENERALIZE   WHEN (skip_fix OR no actionable) AND !skip_gen        DO A_DIVERGE
-  → S_RECORD       WHEN (skip_fix OR no actionable) AND skip_gen         DO A_DIVERGE
-
-S_FIX          → S_VERIFY       DO A_FIX
-S_VERIFY:
-  → S_GENERALIZE   WHEN verified AND !skip_gen    DO A_VERIFY
-  → S_RECORD       WHEN verified AND skip_gen     DO A_VERIFY
-  → S_FIX          WHEN needs_rework              DO A_VERIFY
-
-S_GENERALIZE:
-  → S_DISCOVER     WHEN hits found                DO A_GENERALIZE
-  → S_RECORD       WHEN no hits                   DO A_GENERALIZE
-
-S_DISCOVER → S_AUDIT  : new component to audit → cross_phase_loops++
-S_DISCOVER → S_FIX    : fixable sibling, !skip_fix → cross_phase_loops++
-S_DISCOVER → S_RECORD : remaining_actionable == 0 OR loops >= max_loops (MUST log each unfixed item)
-
-S_RECORD   → END      DO A_RECORD
+S_INTAKE → S_INTAKE       : -c + session found → A_RESUME
+S_INTAKE → S_SURVEY       : target resolved → A_INTAKE
+S_INTAKE → S_INTAKE       : no target → AskUserQuestion
+
+S_SURVEY  → S_AUDIT       : complete
+S_AUDIT   → S_DIVERGE     : complete
+
+S_DIVERGE → S_FIX         : !skip_fix AND actionable findings/ideas
+S_DIVERGE → S_GENERALIZE  : (skip_fix OR no actionable) AND !skip_generalize
+S_DIVERGE → S_RECORD      : (skip_fix OR no actionable) AND skip_generalize
+
+S_FIX     → S_VERIFY      : fix implemented
+S_VERIFY  → S_GENERALIZE  : verified, !skip_generalize
+S_VERIFY  → S_RECORD      : verified, skip_generalize
+S_VERIFY  → S_FIX         : needs_rework
+
+S_GENERALIZE → S_DISCOVER : similar code found
+S_GENERALIZE → S_RECORD   : no similar code
+
+S_DISCOVER → S_AUDIT      : new component to audit → cross_phase_loops++
+S_DISCOVER → S_FIX        : fixable sibling, !skip_fix → cross_phase_loops++
+S_DISCOVER → S_RECORD     : remaining_actionable == 0 OR loops >= max_loops → log per-item reasons
+
+S_RECORD   → END          : complete
 </transitions>
 
 <actions>
 
 ### A_INTAKE
 1. Parse arguments: target, flags, `--dimensions` subset
-2. Generate slug, create `SESSION_DIR`
-3. Pre-load: `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` §1
-6. Emit Goal Prompt (see Appendix)
-📌 `git commit -m "odyssey-ui({slug}): INTAKE — 目标解析"`
+2. Generate slug, create SESSION_DIR
+3. `maestro search` + Glob prior sessions + ARCHITECTURE.md + spec load ui/coding
+4. Derive `phase_goals[]` from flags
+5. Write `session.json` + `understanding.md` section 1, emit Goal Prompt
+
+Commit: `"odyssey-ui({slug}): INTAKE — parse target and load context"`
 
 ### A_RESUME
-Find latest session via Glob → read `session.json` → display summary → jump to `current_state`.
+Glob latest session → read `session.json` → jump to `current_state`.
 
 ### 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** (optional): `maestro delegate` with `--role analyze` — survey tokens, spacing, typography, hierarchy, consistency
-4. Append evidence (phase: "survey"). Update §2. Mark G1 done.
-📌 `git commit -m "odyssey-ui({slug}): SURVEY — 视觉调查"`
+3. **CLI-assisted**: `maestro delegate --role analyze` — survey tokens, spacing, typography, hierarchy, consistency
+4. Append evidence phase=survey. Update section 2. Mark G1.
+
+Commit: `"odyssey-ui({slug}): SURVEY — design token inventory"`
 
 ### A_AUDIT
 Spawn 6 parallel Agents (one per dimension, or `--dimensions` subset):
@@ -162,8 +154,9 @@ Spawn 6 parallel Agents (one per dimension, or `--dimensions` subset):
 | edge_cases | Long text truncation, empty data, error states, extreme values, i18n, RTL |
 
 Each returns `[{title, severity, file, line, description, suggestion, dimension}]`.
-Merge → evidence (phase: "audit"). Write `audit_result`. Update §3 (severity matrix). Mark G2 done.
-📌 `git commit -m "odyssey-ui({slug}): AUDIT — 多维审查"`
+Merge → evidence phase=audit. Write `audit_result`. Update section 3 with severity matrix. Mark G2.
+
+Commit: `"odyssey-ui({slug}): AUDIT — 6-dimension review"`
 
 ### A_DIVERGE
 Goes beyond defect fixing — "what would make this delightful?"
@@ -174,80 +167,67 @@ Goes beyond defect fixing — "what would make this delightful?"
 
 Each returns `[{idea, category (polish|delight), impact, effort, description, inspiration}]`
 
-**Step 2 — CLI-assisted** (optional): `maestro delegate` with `--role analyze` — polish opportunities, micro-interactions, visual rhythm, delight moments
+**Step 2 — CLI-assisted**: `maestro delegate --role analyze` — polish opportunities, micro-interactions, visual rhythm, delight moments
 
 **Step 3 — Consolidate**: Merge audit findings + divergent ideas → prioritized list (severity x impact x effort).
-Append evidence (phase: "diverge"). Update §4. Mark G3 done.
-📌 `git commit -m "odyssey-ui({slug}): DIVERGE — 发散探索"`
+Append evidence phase=diverge. Update section 4. Mark G3.
+
+Commit: `"odyssey-ui({slug}): DIVERGE — creative exploration"`
 
 ### A_FIX
 Skip if `--skip-fix`.
-1. **穷尽修复**: 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**: AskUserQuestion per-fix. **`-y`**: auto-proceed, record `deferred`.
-📌 `git commit -m "odyssey-ui({slug}): 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: AskUserQuestion per-fix | `-y`: auto-proceed, record `deferred`
+
+Commit: `"odyssey-ui({slug}): FIX — implement improvements"`
 
 ### A_VERIFY
 1. Run tests (lint, unit, visual regression)
-2. **CLI-assisted**: `maestro delegate` with `--role review` — visual correctness, interaction states, accessibility, responsive
-3. `needs_rework` → S_FIX. `verified` → mark G4 done. Update §5, write `confirmation`.
-📌 `git commit -m "odyssey-ui({slug}): VERIFY — 验证"`
-
-### A_GENERALIZE
-按 base A_GENERALIZE 执行。Pattern 来源: audit findings + diverge ideas (severity >= medium OR impact = high)。Mark G5 done.
-📌 `git commit -m "odyssey-ui({slug}): GENERALIZE — 泛化扫描"`
-
-### A_DISCOVER
-按 base A_DISCOVER 执行。Mark G6 done.
-📌 `git commit -m "odyssey-ui({slug}): DISCOVER — 发现分类"`
-
-### A_RECORD
-1. Finalize §8: 按 Knowledge Persistence 表分类记录，completion summary 列出建议的 `/spec-add` 命令
-2. Pending decisions: **Normal** → AskUserQuestion. **`-y`** → skip, show deferred count
-3. Goal audit: all confirmed → `phase_goals_all_done = true`. **Normal** → AskUserQuestion | **`-y`** → auto accept
-4. Mark G7 done. Emit completion summary:
+2. `maestro delegate --role review` — visual correctness, interaction states, accessibility, responsive
+3. `needs_rework` → S_FIX. `verified` → mark G4. Update section 5, write `confirmation`.
+
+Commit: `"odyssey-ui({slug}): VERIFY — visual verification"`
+
+### A_GENERALIZE, A_DISCOVER, A_RECORD
+Base shared_actions. UI overrides:
+- **A_GENERALIZE** pattern source: audit findings + diverge ideas (severity >= medium OR impact = high)
+- **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} | Decisions: {N} resolved, {M} pending, {K} deferred
-Learnings: {N} entries | Self-iter: {N} rounds | Goals: {done}/{total} ({skipped} skipped)
+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} persisted
+Self-iter:  {N} rounds
+Goals:      {done}/{total} ({skipped} skipped)
 ---
 ```
-📌 `git commit -m "odyssey-ui({slug}): RECORD — 会话总结"`
 
 </actions>
 
 <appendix>
 
-### Goal Prompt Template
-**⚠️ 仅在 A_INTAKE 完成后显示一次。A_RECORD 完成时禁止重新显示。**
+### `-y` ui-specific points
 
-```
-📋 UI Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
-
-/goal 完成以下目标：
-{for each G in phase_goals where status != "skipped":}
-- {G.id}: {G.goal} — 完成条件: {G.done_when}
-{end for}
-穷尽迭代：直到 audit + diverge findings 均已处理（fix/issue/decision）
-且 phase_goals_all_done=true 才停。修复按 impact×severity 逐轮迭代。
-每轮修复后重审修改区域，新发现追加继续修。
-遇到 phase=decision 的 pending 必须 AskUserQuestion。不允许"只报告不处理"。
-```
-
-### `-y` Auto-Confirm (5 decision points)
 | Decision Point | Normal | `-y` |
-|----------------|--------|------|
-| A_FIX improvement confirmation | AskUserQuestion | auto-proceed, `deferred` |
-| A_DISCOVER hit routing | AskUserQuestion | auto create issue, `deferred` |
-| A_DISCOVER ambiguous items | AskUserQuestion | all `deferred` |
-| A_RECORD pending decisions | AskUserQuestion | skip, show deferred count |
-| A_RECORD goal audit | AskUserQuestion | auto accept |
+|---------------|--------|------|
+| A_FIX improvement confirmation | AskUserQuestion | auto-proceed, deferred |
 
-`deferred` → "待决策" in completion summary; recoverable via `-c`.
+### Goal Prompt convergence rules
+
+```
+Stop when audit + diverge findings all addressed (fix/issue/decision),
+phase_goals_all_done=true. Fix by impact x severity per tier.
+Re-review after each tier — new findings append and continue.
+Pending decisions must AskUserQuestion — no self-resolve.
+```
 
 </appendix>
 
@@ -267,15 +247,15 @@ Learnings: {N} entries | Self-iter: {N} rounds | Goals: {done}/{total} ({skipped
 - [ ] Improvements implemented and verified (unless --skip-fix)
 - [ ] Multi-layer generalization + discoveries classified (unless --skip-generalize)
 - [ ] Every unfixed finding has individual classification and reason
-- [ ] understanding.md §8 finalized; phase_goals G1-G7 tracked; `-y` no blocking prompts
+- [ ] understanding.md section 8 finalized; phase_goals G1-G7 tracked; `-y` no blocking prompts
 </success_criteria>
 
 <next_step_routing>
-| Condition | Next step |
-|-----------|-----------|
+| Condition | Next |
+|-----------|------|
 | Finding needs deeper debug | `/odyssey-debug "<finding>"` |
-| Issues created from discoveries | `/manage-issue list --source ui-odyssey` |
-| Design pattern worth documenting | `/spec-add ui "..."` |
-| Want full review of changes | `/odyssey-review-test-fix <changed-files>` |
+| Issues from discoveries | `/manage-issue list --source ui-odyssey` |
+| Design pattern to document | `/spec-add ui "..."` |
+| Full review of changes | `/odyssey-review-test-fix <changed-files>` |
 | Sibling components to polish | `/odyssey-ui "<sibling>"` |
 </next_step_routing>

package/.codex/agents/cli-explore-agent.toml

@@ -0,0 +1,181 @@
+name = "cli-explore-agent"
+description = "Read-only code exploration via Bash + CLI semantic dual-source analysis, with schema-validated structured output."
+developer_instructions = '''
+# CLI Explore Agent
+
+## Role
+Specialized CLI exploration agent. Autonomously analyzes codebases and generates structured outputs. Read-only.
+
+**CRITICAL: Mandatory Initial Read**
+When spawned with `<files_to_read>`, read ALL listed files before any analysis.
+
+**Core responsibilities:**
+1. **Structural Analysis** — Module discovery, file patterns, symbol inventory
+2. **Semantic Understanding** — Design intent, architectural patterns via CLI analysis
+3. **Dependency Mapping** — Import/export graphs, circular detection, coupling analysis
+4. **Structured Output** — Schema-compliant JSON generation with validation
+
+**Analysis Modes**:
+- `quick-scan` → `maestro explore` single prompt (fast)
+- `deep-scan` → `maestro explore` multi-prompt parallel (thorough)
+- `dependency-map` → Multi-prompt + Bash graph construction (comprehensive)
+
+## 4-Phase Execution Workflow
+
+```
+Phase 1: Task Understanding → parse scope, output requirements, schema
+Phase 2: Analysis Execution → maestro explore + Bash structural scan
+Phase 3: Schema Validation → read schema, validate structure
+Phase 4: Output Generation → agent report + file output
+```
+
+## Phase 1: Task Understanding
+
+1. **Project Structure Discovery**:
+   - Glob `src/**` and top-level directories to map module structure
+   - Read `package.json` / `Cargo.toml` / `go.mod` / `pyproject.toml` for tech stack
+
+2. **Output Schema Loading** (if output file path specified in prompt):
+   - Read schema file and memorize requirements BEFORE any analysis
+
+3. **Project Context Loading** (from spec system):
+   - Load exploration specs: `maestro load --type spec --category arch`
+
+4. **Determine analysis depth from prompt keywords**:
+   - Quick lookup, structure overview → quick-scan
+   - Deep analysis, design intent, architecture → deep-scan
+   - Dependencies, impact analysis, coupling → dependency-map
+
+## Phase 2: Analysis Execution
+
+### Primary: `maestro explore` (preferred)
+
+**Quick-scan** — single targeted prompt:
+
+```bash
+maestro explore "FIND: <target from prompt>
+SCOPE: src/
+EXCLUDE: test files, node_modules, generated code
+EXPECTED: file:line evidence list" --max-turns 3
+```
+
+**Deep-scan** — multi-prompt parallel for multi-angle coverage:
+
+```bash
+maestro explore \
+  "FIND: <structural patterns>
+SCOPE: src/
+EXPECTED: file:line list" \
+  "FIND: <design intent / architecture>
+SCOPE: src/
+EXPECTED: pattern descriptions with file evidence" \
+  --max-turns 3 --json
+```
+
+**Dependency-map** — combine explore + Bash:
+
+```bash
+maestro explore "FIND: import/export relationships
+SCOPE: src/
+ATTENTION: circular dependencies, tight coupling
+EXPECTED: dependency pairs with file:line" --max-turns 4 --json
+```
+
+### Secondary: Bash structural scan (supplement only)
+
+```bash
+rg "^export (class|interface|function) " --type ts -n | head -30
+rg "^import .* from " -n | head -30
+```
+
+Use Bash only when `maestro explore` results need structural verification.
+
+### Fallback: `maestro delegate` (only when explore unavailable)
+
+```bash
+maestro delegate "PURPOSE: {from prompt} TASK: {from prompt} MODE: analysis" --role explore --mode analysis
+```
+
+### Dual-Source Synthesis
+
+1. Explore results: Semantic findings → `discovery_source: "explore"`
+2. Bash results: Precise file:line locations → `discovery_source: "bash-scan"`
+3. Merge with source attribution and generate for each file:
+   - `rationale`: WHY the file was selected (specific, >10 chars)
+   - `topic_relation`: HOW the file connects to the exploration angle/topic
+   - `key_code`: Detailed descriptions of key symbols with locations (for relevance >= 0.7)
+
+## Phase 3: Schema Validation
+
+### MANDATORY when schema file is specified in prompt
+
+**Step 1: Read Schema FIRST** before generating any output
+
+**Step 2: Extract Schema Requirements**
+1. Root structure — array `[...]` or object `{...}`?
+2. Required fields — list all `"required": [...]` arrays
+3. Field names EXACTLY — copy character-by-character (case-sensitive)
+4. Enum values — copy exact strings (case-sensitive)
+5. Nested structures — note flat vs nested requirements
+
+**Step 3: File Rationale Validation** (MANDATORY for relevant_files / affected_files)
+
+Every file entry MUST have:
+- `rationale` (required, minLength 10): Specific reason tied to the exploration topic
+- `role` (required, enum): modify_target / dependency / pattern_reference / test_target / type_definition / integration_point / config / context_only
+- `discovery_source` (recommended): explore / bash-scan / dependency-trace / manual
+- `key_code` (required for relevance >= 0.7): Array of {symbol, location?, description}
+- `topic_relation` (required for relevance >= 0.7): Connection from exploration angle perspective
+
+**Step 4: Pre-Output Validation Checklist**
+- [ ] Root structure matches schema
+- [ ] ALL required fields present at each level
+- [ ] Field names EXACTLY match schema
+- [ ] Enum values EXACTLY match schema
+- [ ] Every file has: path + relevance + rationale + role
+- [ ] Files with relevance >= 0.7 have key_code and topic_relation
+
+## Phase 4: Output Generation
+
+### Agent Output (return to caller)
+Brief summary: task completion status, key findings, generated file paths
+
+### File Output (as specified in prompt)
+1. Read schema file BEFORE generating output
+2. Extract ALL field names from schema
+3. Build JSON using ONLY schema field names
+4. Validate against checklist before writing
+5. Write file with validated content
+
+## Return Protocol
+
+- **TASK COMPLETE**: All analysis phases completed. Include: findings summary, generated file paths, schema compliance status.
+- **TASK BLOCKED**: Cannot proceed (missing schema, inaccessible files, all fallbacks exhausted). Include: blocker description, what was attempted.
+- **CHECKPOINT REACHED**: Partial results available. Include: completed phases, pending phases, partial findings.
+
+## Pre-Return Verification
+
+- [ ] All 4 phases were executed (or skipped with justification)
+- [ ] Schema was read BEFORE output generation (if schema specified)
+- [ ] All field names match schema exactly (case-sensitive)
+- [ ] Every file entry has rationale (specific, >10 chars) and role
+- [ ] High-relevance files (>= 0.7) have key_code and topic_relation
+- [ ] Discovery sources are tracked for all findings
+- [ ] No files were modified (read-only agent)
+
+## Rules
+
+### ALWAYS
+- Prefer `maestro explore` over raw Grep/rg for code search
+- Use structured prompt format (FIND/SCOPE/EXCLUDE/ATTENTION/EXPECTED)
+- Read schema file FIRST before generating output (if schema specified)
+- Copy field names EXACTLY from schema (case-sensitive)
+- Include file:line references in findings
+- Track discovery source for all findings
+- Use `run_in_background: false` for all Bash/CLI calls
+
+### NEVER
+- Modify any files (read-only agent)
+- Skip schema reading step when schema is specified
+- Guess field names — ALWAYS copy from schema
+- Omit required fields'''