maestro-flow 0.5.34 → 0.5.36

package/.agy/skills/maestro-ralph-execute/SKILL.md

@@ -132,19 +132,44 @@ S_FALLBACK:
 | maestro-brainstorm | topic | `"{intent}"` |
 | maestro-roadmap | description | `"{intent}"` |
 | maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
-| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
-| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
+| maestro-plan | phase, --from, or --dir | see --from auto-injection below |
+| maestro-execute | phase or --dir | see --from auto-injection below |
 | quality-debug | gap context | Read previous step's error/gap |
 | quality-* | phase | `{phase}` |
 
-**Artifact dir resolution for --dir:**
+**--from auto-injection (phase-level artifact chaining):**
+
+Phase-level steps 在 build 阶段无法预知前序 artifact ID。A_RESOLVE_ARGS 运行时从 state.json 查找并注入显式引用，打通 analyze→plan→execute 数据管道：
+
 ```
-Read state.json → filter artifacts by milestone + phase
-plan commands: latest type=="analyze" → --dir .workflow/scratch/{path}
-execute commands: latest type=="plan" → --dir .workflow/scratch/{path}
+Read state.json.artifacts（含 milestone_history 内归档 artifacts）
+→ filter by milestone={session.milestone} + phase={session.phase} + status=="completed"
+
+plan step（含 {phase} 占位符，args 无 --from 且无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="analyze" artifact → id = ANL-xxx
+  2. 命中 → args 追加 --from analyze:{id}
+  3. 写 step.source_artifact_ref = "analyze:{id}"
+
+execute step（含 {phase} 占位符，args 无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="plan" artifact → id = PLN-xxx, path = scratch/...
+  2. 命中 → args 追加 --dir .workflow/scratch/{path}
+  3. 写 step.source_artifact_ref = "plan:{id}"
 ```
 
-Write enriched args back to status.json.
+兜底：查询无结果 → 不注入，由命令自身 discovery 逻辑处理。已有 `--from` 或 `--dir` 的 step 不覆盖。
+
+**Goal context injection:**
+
+当 step.goal_ref 非空且 session.task_decomposition 存在时：
+```
+goal = session.task_decomposition.find(g => g.id == step.goal_ref)
+if goal:
+  goal_snippet = { id: goal.id, goal: goal.goal, done_when: goal.done_when,
+                   boundary: goal.boundary, evidence: goal.evidence }
+  → 传递给 A_EXEC_STEP 用于 inline execution 前注入（见 step 2 goal context pre-injection）
+```
+
+Write enriched args + source_artifact_ref back to status.json.
 
 ### A_EXEC_DECISION
 
@@ -160,13 +185,24 @@ Write enriched args back to status.json.
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
-2. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
-3. **Complete**:
+2. **Goal context pre-injection** — 若 A_RESOLVE_ARGS 产出了 `goal_snippet`（step.goal_ref 非空），在 ralph next stdout prompt **顶部前置**以下 block，使执行命令感知当前子目标和执行约束：
+   ```
+   <goal_context>
+   Sub-goal: {goal.id} — {goal.goal}
+   Done when: {goal.done_when}
+   Boundary: {goal.boundary}
+   Evidence target: {goal.evidence}
+   Execution criteria: {session.execution_criteria joined by '; '}
+   </goal_context>
+   ```
+   无 goal_snippet 时跳过此步。goal_context block 不替换 ralph next 的 stdout 内容，仅在其前方拼接。
+3. **Inline execution** — 按 stdout（含 goal_context 前置）执行；deferred_reading 按需 Read
+4. **Complete**:
    - `run_command("maestro ralph complete N --status DONE [--evidence <path>]")`
    - `run_command("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
    - `run_command("maestro ralph retry N")`
    - `run_command("maestro ralph complete N --status BLOCKED --reason \"...\"")`
-4. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
+5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph-execute/SKILL.md") + execute inline` 自调用。
 
@@ -242,5 +278,10 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 - [ ] Context signals 由执行 step 显式写回 status.json.context（非 ralph-execute 内嵌扫描）
 - [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
 - [ ] 自调用持续到全部 completion_confirmed 或 paused
+- [ ] --from auto-injection：phase-level plan step 运行时从 state.json 查找同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `source_artifact_ref`
+- [ ] --from auto-injection：phase-level execute step 运行时查找同 phase+milestone 最新 completed plan artifact → 注入 `--dir`，写 `source_artifact_ref`
+- [ ] Goal context injection：step.goal_ref 非空时从 task_decomposition 提取 goal_snippet，A_EXEC_STEP 在 ralph next stdout 顶部前置 `<goal_context>` block
+- [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria
+- [ ] 已有 `--from` 或 `--dir` 的 step 不被 auto-injection 覆盖
 
 </appendix>

package/.agy/skills/maestro-tools-register/SKILL.md

@@ -70,12 +70,8 @@ Parse $ARGUMENTS to determine mode:
 - Update frontmatter via: `maestro wiki update <id> --frontmatter '{"tool": true, "category": "<cat>", "summary": "<summary>"}'`
 - Do NOT recreate the document — modify in place
 
-**For all modes** — identify the usage timing: when should an agent or user invoke this tool? This becomes the first line of the entry description (see Step 5).
-
 ### Step 3: Determine Category
 
-**Core principle**: `category` = **who consumes this tool** (which agent type discovers and uses it), not what the content is about.
-
 | Category | Consumer Agent | Decision Question | Signal Words |
 |---|---|---|---|
 | `coding` | code-developer, workflow-executor | 开发者实现时需要这个流程吗？ | build, deploy, integrate, configure, setup, migrate, api-contract |
@@ -89,8 +85,6 @@ Parse $ARGUMENTS to determine mode:
 - API verification steps (how to test) → `category: test` (RCP-*, tool: true)
 - Ask user when ambiguous: "This tool content serves both developers and testers. Split into separate documents?"
 
-**Ambiguous cases**: Choose the **primary consumer** — the agent that would fail without this knowledge.
-
 ### Step 4: Decide Inline vs Ref
 
 - Steps <10 and no code blocks → **inline mode**

package/.agy/skills/maestro-ui-codify/SKILL.md

@@ -44,8 +44,6 @@ Load project UI conventions before extracting design system:
 maestro spec load --category ui
 ```
 
-If specs not initialized, continue without — the workflow still produces valid output.
-
 ## 2. Execute Workflow
 
 Route to `~/.maestro/workflows/ui-codify.md` and follow completely.

package/.agy/skills/manage-kg-extractors/SKILL.md

@@ -17,8 +17,6 @@ allowed-tools:
 
 <purpose>
 Analyze current repository's code patterns to auto-generate `.workflow/kg/extractors.yaml` — a declarative config that teaches MaestroGraph's codegraph extractor to recognize project-specific symbols beyond standard function/class/method declarations.
-
-Detects: builder/factory API registrations, domain constant patterns, custom decorator conventions, framework-specific patterns, module-level constants.
 </purpose>
 
 <context>

package/.agy/skills/quality-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: quality-test
 description: Use when implementation needs user acceptance testing with interactive verification and gap closure
-argument-hint: [phase] [--smoke] [--auto-fix]
+argument-hint: [phase] [--smoke] [--auto-fix] [--frontend-verify]
 allowed-tools:
   - ask_question
   - define_subagent
@@ -29,6 +29,29 @@ Flags, artifact context resolution, and output directory format defined in workf
 </context>
 
 <execution>
+**Mode select:** `--frontend-verify` → 走下方 **Frontend Verify Mode**（确定性浏览器 smoke，**不是**对话式 UAT）；否则 Follow '~/.maestro/workflows/test.md' completely.
+
+### Frontend Verify Mode (`--frontend-verify`)
+
+1. **Resolve targets**: 读 phase 的 `plan.json` / `.task/TASK-*.json`，提取所有 `[UI-observable]` convergence.criteria（plan 阶段产出）；缺失则枚举后端写端点（POST/PUT/PATCH/DELETE）作为待验证清单。
+2. **Start app**: `next start`（或从 dashboard/package.json 解析的既有启动脚本）；启动失败 → E003。
+3. **Drive browser**: 用 chrome-devtools MCP（`mcp__claude_dms3-chrome-devtools__*`：navigate / click / fill / take_snapshot / list_network_requests）逐条执行每个 `[UI-observable]` 流程，断言：UI 入口存在且可触发 → 对应写请求返回 2xx → DOM 出现预期结果。
+4. **Write evidence**: 产出 `e2e-results.json`（结构见下），逐条记 pass/fail + 证据（网络状态码、快照引用）。**确定性断言，禁止"无人应答=全过"**。
+5. **Verdict**: 任一 `[UI-observable]` fail 或写端点无 UI 入口 → STATUS=NEEDS_RETRY（ralph 经 post-frontend-verify 触发 Fix-Loop）；全过 → DONE。
+
+```json
+// e2e-results.json
+{ "phase": "{phase}", "app_url": "http://localhost:3000",
+  "checks": [ { "criterion": "[UI-observable] ...", "ui_entry": "<selector/route>",
+    "request": "POST /api/notes", "status": 201, "dom_assert": "list shows new item",
+    "passed": true } ],
+  "summary": { "total": 0, "passed": 0, "failed": 0 }, "verdict": "pass|fail" }
+```
+
+Ralph-invoked 完成：`maestro ralph complete <idx> --status {STATUS} --evidence e2e-results.json`。
+
+---
+
 Follow '~/.maestro/workflows/test.md' completely.
 
 ### Phase Gates (MANDATORY, BLOCKING)
@@ -146,4 +169,5 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 - [ ] Gaps updated with root_cause, fix_direction, affected_files
 - [ ] Gap-fix loop triggered if --auto-fix (max 2 iterations)
 - [ ] Next step routed (phase-transition if pass, verify if auto-fix success, debug --from-uat if issues, test-gen if low coverage)
+- [ ] `--frontend-verify`: 每条 [UI-observable] criterion 经真实浏览器断言，产出 e2e-results.json；任一 fail → NEEDS_RETRY（不放行）
 </success_criteria>

package/.agy/skills/spec-load/SKILL.md

@@ -74,4 +74,3 @@ Follow '~/.maestro/workflows/specs-load.md' completely.
 - [ ] Legacy entries filtered by text grep fallback
 - [ ] Results displayed with file:category references
 </success_criteria>
-</output>

package/.agy/skills/spec-setup/SKILL.md

@@ -45,4 +45,3 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 - [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
 - [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
 </success_criteria>
-</output>

package/.agy/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -48,15 +48,21 @@ Research and codebase exploration for context gathering.
 | package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore |
 | No project files | Skip (codebase_context = null) |
 
-When project detected:
-```
-run_command({ command: `maestro delegate "PURPOSE: Explore codebase for context
-TASK: • Identify tech stack • Map architecture patterns • Document conventions • List integration points
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --tool gemini --mode analysis`, run_in_background: false })
+When project detected — prefer `maestro explore` multi-prompt:
+```bash
+maestro explore \
+  "FIND: tech stack and framework detection
+SCOPE: package.json, Cargo.toml, pyproject.toml, go.mod, src/
+EXPECTED: tech_stack list with versions" \
+  "FIND: architecture patterns and conventions
+SCOPE: src/
+EXCLUDE: tests, node_modules
+EXPECTED: patterns list with file:line evidence" \
+  --max-turns 3 --json
 ```
 
+**Fallback**: `maestro delegate "PURPOSE: Explore codebase for context ..." --tool gemini --mode analysis`
+
 ### Tech Profile Scan
 
 After codebase exploration, scan results for context-aware trigger signals (based on detected codebase characteristics):

package/.agy/skills/team-quality-assurance/roles/scout/role.md

@@ -36,18 +36,22 @@ Scan codebase from multiple perspectives (bug, security, test-coverage, code-qua
 
 **Low complexity**: Use `` for quick pattern-based scan.
 
-**Medium/High complexity**: CLI fan-out -- one `maestro delegate --mode analysis` per perspective:
-
-For each active perspective, build prompt:
-```
-PURPOSE: Scan code from <perspective> perspective to discover potential issues
-TASK: Analyze code patterns for <perspective> problems, identify anti-patterns, check for common issues
-MODE: analysis
-CONTEXT: @<scan-scope>
-EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
-CONSTRAINTS: Focus on actionable findings only
+**Medium/High complexity**: Multi-prompt `maestro explore` (preferred for read-only scan):
+
+Build one prompt per active perspective:
+```bash
+maestro explore \
+  "FIND: <perspective1> issues and anti-patterns
+SCOPE: <scan-scope>
+ATTENTION: common <perspective1> problems
+EXPECTED: severity + file:line + description" \
+  "FIND: <perspective2> issues and anti-patterns
+SCOPE: <scan-scope>
+EXPECTED: severity + file:line + description" \
+  --max-turns 3 --json
 ```
-Execute via: `maestro delegate "<prompt>" --role analyze --mode analysis`
+
+**Fallback** (when deeper analysis needed per perspective): `maestro delegate "<prompt>" --role analyze --mode analysis`
 
 After all perspectives complete:
 - Parse CLI outputs into structured findings

package/.agy/skills/team-tech-debt/roles/scanner/role.md

@@ -55,7 +55,7 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch
 - Classify findings into dimensions
 
 **Medium/High Complexity** (Fan-out):
-- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `maestro delegate --role explore --mode analysis`
+- Fan-out A: `maestro explore` multi-prompt parallel (structure, patterns, dependencies angles) — preferred over delegate for exploration
 - Fan-out B: CLI dimension analysis (parallel per dimension -- code, architecture, testing, dependency, documentation) via `--role analyze`
 - Fan-out C (High only): Multi-perspective analysis (security, performance, code-quality, architecture) via `--role analyze`
 - Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings

package/.agy/skills/team-ultra-analyze/roles/explorer/role.md

@@ -39,24 +39,31 @@ Explore codebase structure through cli-explore-agent, collecting structured cont
 
 ## Phase 3: Codebase Exploration
 
-Use CLI tool for codebase exploration:
-
-```javascript
-run_command({
-  command: `maestro delegate "PURPOSE: Explore codebase for <topic> from <perspective> perspective; success = structured findings with relevant files and patterns
-TASK: • Run module depth analysis • Search for topic-related patterns • Identify key files and their relationships • Extract architectural insights
-MODE: analysis
-CONTEXT: @**/* | Memory: Session <session-folder>, perspective <perspective>
-EXPECTED: JSON output with: relevant_files (path, relevance, summary), patterns, key_findings, module_map, questions_for_analysis, _metadata (perspective, search_queries, timestamp)
-CONSTRAINTS: Focus on <perspective> angle - <strategy.focus> | Write to <session>/explorations/exploration-<num>.json
-" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
-  run_in_background: false
-})
+**Primary: `maestro explore`** (structured multi-prompt):
+
+```bash
+maestro explore \
+  "FIND: <topic> patterns and implementations
+SCOPE: src/
+ATTENTION: <perspective>-specific concerns
+EXPECTED: file:line evidence with relevance" \
+  "FIND: module boundaries and relationships for <topic>
+SCOPE: src/
+EXCLUDE: tests, generated code
+EXPECTED: dependency pairs and architectural insights" \
+  --max-turns 3 --json
 ```
 
-**ACE fallback** (when CLI produces no output):
-```javascript
-({ project_root_path: ".", query: "<topic> <perspective>" })
+Parse JSON results → extract relevant_files, patterns, key_findings.
+
+**Fallback: `maestro delegate`** (when explore results insufficient):
+
+```bash
+maestro delegate "PURPOSE: Explore codebase for <topic> from <perspective> perspective
+TASK: Search for topic-related patterns | Identify key files and relationships | Extract architectural insights
+EXPECTED: JSON with relevant_files, patterns, key_findings
+CONSTRAINTS: Focus on <perspective> angle
+" --tool gemini --mode analysis --rule analysis-analyze-code-patterns
 ```
 
 ## Phase 4: Result Validation

package/.claude/agents/cli-explore-agent.md

@@ -11,96 +11,103 @@ allowed-tools:
 # CLI Explore Agent
 
 ## Role
-You are a specialized CLI exploration agent that autonomously analyzes codebases and generates structured outputs. You perform read-only code exploration using dual-source analysis (Bash structural scan + CLI semantic analysis), validate outputs against schemas, and produce structured JSON results.
+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 via Bash tools
-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
+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` → Bash only (fast)
-- `deep-scan` → Bash + CLI dual-source (thorough)
-- `dependency-map` → Graph construction (comprehensive)
+- `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 prompt for: analysis scope, output requirements, schema path
-Phase 2: Analysis Execution
-    ↓ Bash structural scan + CLI semantic analysis (based on mode)
-Phase 3: Schema Validation (MANDATORY if schema specified)
-    ↓ Read schema → Extract EXACT field names → Validate structure
-Phase 4: Output Generation
-    ↓ Agent report + File output (strictly schema-compliant)
+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
 
-### Autonomous Initialization (execute before any analysis)
-
 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 begins
+   - Read schema file and memorize requirements BEFORE any analysis
 
 3. **Project Context Loading** (from spec system):
    - Load exploration specs: `maestro spec load --category arch`
-   - Extract: tech_stack, architecture, key_components, overview
-   - If no specs returned, proceed with fresh analysis
 
-4. **Task Keyword Search** (initial file discovery):
-   - Extract keywords from prompt, detect primary language, run targeted Grep
-   - Store results as `keyword_files` for Phase 2 scoping
+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
 
-**Extract from prompt**:
-- Analysis target and scope
-- Analysis mode (quick-scan / deep-scan / dependency-map)
-- Output file path and schema file path (if specified)
+## Phase 2: Analysis Execution
 
-**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
+### Primary: `maestro explore` (preferred)
 
-## Phase 2: Analysis Execution
+**Quick-scan** — single targeted prompt:
 
-### Bash Structural Scan
+```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
-# Pattern discovery (adapt based on language)
-rg "^export (class|interface|function) " --type ts -n
-rg "^(class|def) \w+" --type py -n
-rg "^import .* from " -n | head -30
+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
 ```
 
-### CLI Semantic Analysis (deep-scan, dependency-map)
+### Secondary: Bash structural scan (supplement only)
 
 ```bash
-maestro delegate "
-PURPOSE: {from prompt}
-TASK: {from prompt}
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: {from prompt}
-" --role explore --mode analysis --cd {dir}
+rg "^export (class|interface|function) " --type ts -n | head -30
+rg "^import .* from " -n | head -30
 ```
 
-**Fallback Chain**: config-driven via `cli-tools.json` role mappings → Bash-only
+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. Bash results: Precise file:line locations → `discovery_source: "bash-scan"`
-2. CLI results: Semantic understanding, design intent → `discovery_source: "cli-analysis"`
-3. Dependency tracing: Import/export graph → `discovery_source: "dependency-trace"`
-4. Merge with source attribution and generate for each file:
+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)
@@ -112,39 +119,35 @@ EXPECTED: {from prompt}
 **Step 1: Read Schema FIRST** before generating any output
 
 **Step 2: Extract Schema Requirements**
-1. Root structure - Is it 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
+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
-  - GOOD: "Contains AuthService.login() which is the entry point for JWT token generation"
-  - BAD: "Related to auth"
 - `role` (required, enum): modify_target / dependency / pattern_reference / test_target / type_definition / integration_point / config / context_only
-- `discovery_source` (recommended): bash-scan / cli-analysis / dependency-trace / manual
+- `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 (array vs object)
+- [ ] Root structure matches schema
 - [ ] ALL required fields present at each level
-- [ ] Field names EXACTLY match schema (character-by-character)
-- [ ] Enum values EXACTLY match schema (case-sensitive)
+- [ ] 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
@@ -170,16 +173,16 @@ Brief summary: task completion status, key findings, generated file paths
 ## Rules
 
 ### ALWAYS
-- Read schema file FIRST before generating any output (if schema specified)
+- 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
-- Every file MUST have rationale (specific, not generic) and role
 - Track discovery source for all findings
-- Populate key_code and topic_relation for high-relevance files (>= 0.7)
 - 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
+- Guess field names — ALWAYS copy from schema
 - Omit required fields

package/.claude/agents/workflow-analyzer.md

@@ -40,6 +40,7 @@ You perform structured multi-dimensional analysis of technical topics, proposals
 - Comparison alternatives (if applicable)
 - **Codebase docs** (if `.workflow/codebase/` exists) — `ARCHITECTURE.md` and `CONCERNS.md` as evidence sources for feasibility/risk/dependency dimensions
 - **Wiki prior knowledge** (if `maestro wiki` available) — `maestro wiki search "<subject keywords>"` for prior decisions and analyses on related topics
+- **Codebase search** — prefer `maestro explore "FIND: <analysis target> SCOPE: src/ EXPECTED: file:line evidence"` over raw Grep for gathering multi-file evidence across dimensions
 
 ## Output
 `analysis.md`:

package/.claude/agents/workflow-collab-planner.md

@@ -117,6 +117,7 @@ You are a collaborative planner that works within a pre-allocated task ID range.
 - Task files must use `convergence.criteria` (array of testable strings), not `done_when`
 - files must use `[{path, action, target, change}]` format, not `["path"]`
 - Each task must have convergence.criteria with min 2 testable conditions
+- Vertical slice for UI features: deliver backend + frontend + integration as one end-to-end capability per wave (no backend-only/frontend-only split); each UI delivery wave needs ≥1 task with a `[UI-observable]` convergence criterion (verifiable user-facing flow)
 - Each task must have `read_first[]` — files the executor MUST read before implementation
 - `action` must contain concrete values (function signatures, config keys, import paths), not just a verb
 - Task definitions follow the same schema as workflow-planner output

package/.claude/agents/workflow-debugger.md

@@ -50,6 +50,7 @@ Each line in evidence.ndjson:
 - **Project specs** — `maestro spec load --category debug`: known issues, root causes, workarounds. Check before forming hypotheses to avoid re-investigating known problems.
 - **Codebase docs** (if `.workflow/codebase/` exists) — Read `ARCHITECTURE.md` for module boundaries to scope impact analysis and form better hypotheses
 - **Wiki prior knowledge** (if `maestro wiki` available) — `maestro wiki search "<symptom keywords>"` for prior investigations on similar issues; skip already-documented root causes
+- **Codebase search** — prefer `maestro explore "FIND: <symptom> SCOPE: src/ ATTENTION: <error context>"` over raw Grep for multi-file evidence gathering
 
 ## Output
 - Debug session directory with:

package/.claude/agents/workflow-executor.md

@@ -67,6 +67,7 @@ You implement a single task from the execution plan. Each task is executed atomi
 - Codebase access for implementation
 - **Codebase docs** (if `.workflow/codebase/` exists) — Read `ARCHITECTURE.md` for module boundaries and component relationships before implementing cross-module changes
 - **Wiki prior knowledge** (if `maestro wiki` available) — `maestro wiki search "<task keywords>"` for related decisions/constraints that may affect implementation approach
+- **Codebase search** — prefer `maestro explore "FIND: <pattern> SCOPE: src/ EXCLUDE: tests"` over raw Grep when searching for implementation patterns or integration points
 
 ## Output
 - Code changes (the actual implementation)

package/.claude/agents/workflow-planner.md

@@ -160,11 +160,13 @@ These rules prevent over-splitting that wastes tokens on unnecessary agent spawn
    - **Low** (single file, single concern, zero cross-module): **1 task**
    - **Medium** (multiple files OR integration point): **1-4 tasks**
    - **High** (cross-module, architectural, new subsystem): **4-10 tasks**
+8. **Vertical slice for UI features (MANDATORY)** — 含用户界面的功能必须作为端到端纵向切片交付一个用户可观测能力（后端 endpoint + 前端 wiring + 集成同属一个交付波次），**禁止**拆成 backend-only / frontend-only 任务或按层切波。每个交付波次须闭合一个可用能力，而非一层。
 
 ## Constraints
 - Each task must be substantial (15-60 min of work); group related changes, avoid file-per-task
 - Each task must have convergence.criteria (min 2 testable conditions)
 - convergence.criteria must be specific and testable (not "works correctly")
+- For UI features, each delivery wave MUST have ≥1 task with a `[UI-observable]` convergence criterion — a verifiable user-facing flow (e.g. `[UI-observable] User can create a Note in the UI and see it in the list`). Backend-only criteria do NOT satisfy this; the runtime check is enforced by ralph's frontend-verify gate.
 - Each task must have `read_first[]` — files the executor MUST read before implementation (the file being modified + source-of-truth files)
 - `action` must contain concrete values (function signatures, config keys, import paths), not just a verb like "Implement"
 - files must use array format `[{path, action, target, change}]`