maestro-flow 0.5.35 → 0.5.36

package/.agents/skills/maestro-ralph/SKILL.md

@@ -24,7 +24,7 @@ $ARGUMENTS — intent text, flags, or keywords.
 
 **Parse:**
 ```
--y flag       → auto_confirm = true
+-y flag       → auto_confirm = true   # 唯一来源：用户显式传入；ralph 不内部推断（invariant 14）
 --roadmap     → wants_roadmap = true (强制多发布 roadmap 路径；roadmap 默认 opt-in)
 .md/.txt path → input_doc (supplementary context only, NEVER substitutes lifecycle stages)
 Remaining     → intent
@@ -50,6 +50,9 @@ Remaining     → intent
 11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
 12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作。不得以 "效率" 或 "意图明确" 为由绕过。特别是 invariant 1（ralph 不执行 step）和 invariant 6（completion_confirmed 由 CLI 写入）不可隐性违反。
 13. **Delegate fallback 必须标记** — A_DELEGATE_EVALUATE 解析 verdict 失败时 fallback 为 "fix"，但 MUST 在 decisions.ndjson 记录 `"parse_failed": true, "confidence_score": 0`，后续 step 继承 LOW CONFIDENCE 标记。
+14. **auto_confirm 单一来源** — `auto_confirm` 仅由用户 `-y` 标志设定；ralph 不得内部推断。`session.auto_mode` 仅反映用户输入。
+15. **分解契约单一所有者** — `boundary_contract` / `task_decomposition` 由 session 创建者拥有（`source=="ralph"` → `decomposition_owner="ralph"`；`source=="maestro"` → `"maestro"`）。contract 已存在时，后续 S_DECOMPOSE MUST 跳过 ask_user，仅做 shape 校验 + 缺省补齐；goal-audit 只更新 `task_decomposition[*].status/completion_confirmed/completed_at`，禁止改 `goal/done_when/boundary`。
+16. **控制权优先级（范式治理）** — FSM 独占 session 生命周期 + step 排序 + retry/fix/escalate + cross-step decision 节点；Pipeline 命令只拥有自身 artifact GATE（GATE 失败 → `maestro ralph complete <idx> --status BLOCKED|NEEDS_RETRY`，自身 GATE 全过 → DONE）；Router 命令不得出现在 FSM step 内。
 </invariants>
 
 <state_machine>
@@ -139,11 +142,14 @@ S_DECISION_EVAL: (decision 节点 == `step.decision` 非空，下述 gate 名取
                      DO: A_SCOPE_EVALUATE
   → S_APPLY_VERDICT WHEN: structural (post-milestone, post-debug-escalate)
                      DO: A_STRUCTURAL_EVALUATE
+  → S_APPLY_VERDICT WHEN: reground-gate (post-reground)
+                     DO: A_REGROUND_EVALUATE
 
 S_APPLY_VERDICT:
   → S_DISPATCH      WHEN: verdict == "proceed"              DO: A_APPLY_PROCEED
-  → S_DISPATCH      WHEN: post-goal-audit + unmet sub-goals  DO: A_APPLY_GOAL_FIX
-  → S_DISPATCH      WHEN: post-goal-audit + all sub-goals met DO: A_APPLY_GOAL_DONE
+  → S_DISPATCH      WHEN: post-goal-audit + has_unmet         DO: A_APPLY_GOAL_FIX
+  → S_DISPATCH      WHEN: post-goal-audit + all_met + INTENT_ALIGNED=true  DO: A_APPLY_GOAL_DONE
+  → END             WHEN: post-goal-audit + all_met + INTENT_ALIGNED=false DO: A_REGROUND_HALT（尾部漂移熔断）
   → S_DISPATCH      WHEN: post-analyze-scope                 DO: A_APPLY_SCOPE_VERDICT
   → S_DISPATCH      WHEN: verdict == "fix"                  DO: A_APPLY_FIX
   → S_DISPATCH      WHEN: verdict == "escalate"             DO: A_APPLY_ESCALATE
@@ -151,11 +157,15 @@ S_APPLY_VERDICT:
   → END             WHEN: post-milestone + standard + no next milestone DO: mark completed
   → END             WHEN: post-milestone + adhoc                       DO: mark completed (adhoc self-contained)
   → END             WHEN: post-debug-escalate (always STOP)  DO: A_PAUSE_ESCALATE
+  → END             WHEN: post-reground + drifted + confidence_score >= 60  DO: A_REGROUND_HALT
+  → S_DISPATCH      WHEN: post-reground + aligned                           DO: A_APPLY_PROCEED
+  → S_DISPATCH      WHEN: post-reground + drifted + confidence_score < 60   DO: A_APPLY_PROCEED (标 LOW CONFIDENCE)
   GUARD: retry_count >= max_retries → force escalate
   GUARD: confidence_score < 60 AND proceed → override to fix
   GUARD: confidence_score > 95 AND fix AND retry > 0 → suggest proceed
   GUARD: auto_confirm → skip user prompt, apply adjusted verdict
   GUARD: not auto_confirm → ask_user with override options
+  GUARD: post-reground + drifted + confidence_score >= 60 → A_REGROUND_HALT（漂移熔断为安全门，auto_confirm 不跳过）
 
 S_FALLBACK:
   → S_PARSE_ROUTE   WHEN: user provides input               DO: ask_user
@@ -213,7 +223,7 @@ resolve_milestone(phase_number):
 
 | Pattern | Position |
 |---------|----------|
-| 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`（**auto_confirm=true 时跳过，直接 `brainstorm`**） |
+| 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`（**auto_confirm=true 时透传 `-y`，grill 以 Auto mode 代码代答，不跳过**） |
 | brainstorm / 头脑风暴 / 探索 / ideate / 设计思路 | `brainstorm` |
 | blueprint / 规格 / 正式文档 / spec-generate / 7-phase | `blueprint` |
 | broad/medium intent 无数字 phase (重构/全面/重写/迁移/新功能 X) | `analyze-macro` |
@@ -275,7 +285,8 @@ wants_roadmap = (--roadmap flag)
 | passed==true, no review.json | `business-test` |
 | review.json: verdict=="BLOCK" | `review-failed` |
 | review.json: verdict!="BLOCK" | `test` |
-| uat.md: all passed | `milestone-audit` |
+| uat.md: all passed + `session.milestone` 存在 | `milestone-audit` |
+| uat.md: all passed + `session.milestone=null` (standalone) | 标记 session completed（无 milestone 可审计） |
 | uat.md: has failures | `test-failed` |
 
 ### A_DETERMINE_QUALITY_MODE
@@ -320,7 +331,9 @@ options:
 
 ### A_DECOMPOSE_TASKS
 
-Runs once before chain build; additive to status.json.
+Runs once before chain build; additive to status.json. 设 `session.decomposition_owner = "ralph"`。
+
+**0. Ownership guard** (invariant 15): 若 `session.boundary_contract` 或 `session.task_decomposition` 已非空（上游 maestro 已写入，`decomposition_owner == "maestro"`）→ MUST 跳过下述提问，仅做 shape 校验 + 缺省字段补齐，直接进入步骤 6。
 
 **1. Classify intent breadth:**
 
@@ -357,11 +370,11 @@ narrow → derive defaults from intent + codebase, skip questions.
 
 ### A_BUILD_STEPS
 
-Generate steps from `session.lifecycle_position` to `milestone-complete`.
+Generate steps from `session.lifecycle_position` to `milestone-complete`（`session.milestone` 存在时）或最后一个质量门（standalone 时）。
 
 | Stage | invoke_skill(independent) | invoke_skill(unified) | Decision after | quality_mode |
 |-------|---------------------|-----------------|----------------|--------------|
-| grill | `maestro-grill "{intent}"` | *(same)* | — | all (**skip when auto_confirm**) |
+| grill | `maestro-grill "{intent}"` | *(same)* | — | all (**auto_confirm → 透传 `-y` 到 grill args，不删除 stage**) |
 | brainstorm | `maestro-brainstorm "{intent}" --from grill:{grill_id}` *(if grill ran)* / `maestro-brainstorm "{intent}"` *(otherwise)* | *(same)* | — | all |
 | blueprint | `maestro-blueprint "{intent}"` | *(same)* | — | all |
 | init | `maestro-init` | *(same)* | — | all |
@@ -389,11 +402,12 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 1. **起点**：从 `session.lifecycle_position` 开始
 2. **跳过已完成**：跳过当前 milestone+phase 下已有 completed artifact 的 stage（按 `session.phase` 过滤）；unified 按 milestone 过滤
 3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 stage
-3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
+3.5. **grill auto_confirm 透传**：`auto_confirm == true` 时为 `grill` step args 追加 `-y`（grill 自身 Auto mode 用代码代答，见 maestro-grill `<context>` Mode selection）；保留 `grill` stage 与 brainstorm 的 `--from grill:*`（grill 仍产出 grill-report/terminology/context-package）
 3.6. **frontend-verify UI 门控**：仅当当前 phase 交付前端（检出 `dashboard/` 目录，或 phase 目标/计划含 UI 关键词 `landing|page|dashboard|frontend|UI|component|界面`）时保留 `frontend-verify` stage + `post-frontend-verify` decision；纯后端 phase 删除该 stage
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
 5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
-6. **终点硬约束**：chain 以 `milestone-complete` 结尾
+5.5. **re-grounding 插入**：当 `task_decomposition` 存在 **且** 链路含 ≥3 个执行 step（不含 decision 节点）时，从第 3 个执行 step 起每隔 3 个执行 step 后插入 `{ decision: "post-reground", retry_count: 0, max_retries: 0, command_scope: null, command_path: null }`。不在最后一个执行 step 之后插入（由 goal-audit 覆盖）；不与已有 quality-gate decision 节点相邻（顺延到下一个 3-step 边界）；fix-loop 动态插入的 step（index > 原始 chain 长度）不纳入计数
+6. **终点硬约束**：`session.milestone` 存在时 chain 以 `milestone-complete` 结尾；`session.milestone=null`（standalone）时跳过 `milestone-audit` + `milestone-complete` stage，chain 以最后一个质量门 stage 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
 9. **command_path 解析**（每个执行 step，decision 节点跳过）：
@@ -496,14 +510,18 @@ Runs only when `task_decomposition` present.
      1. 读取 status.json.task_decomposition 中 status!=done 的子目标
      2. 打开 evidence 产物，对照 done_when 严格判定
      3. 输出 met / unmet，unmet 给出 gap + target_phase
+     4. 对照 intent + definition_of_done 判定累积产出是否仍服务原始意图（意图保真检查）
    CONTEXT:
-     status.json   = {session_dir}/status.json
-     evidence      = {evidence artifacts}
+     status.json        = {session_dir}/status.json
+     intent             = {session.intent}
+     definition_of_done = {boundary_contract.definition_of_done}
+     evidence           = {evidence artifacts}
      execution_criteria = {execution_criteria}
      boundary_contract  = {boundary_contract}
    EXPECTED:
      ---VERDICT---
      STATUS=all_met|has_unmet
+     INTENT_ALIGNED=true|false
      UNMET=[{id:G2,gap:'...',target_phase:execute}, ...]
      CONFIDENCE_SCORE=0-100
      ---END---
@@ -516,9 +534,64 @@ Runs only when `task_decomposition` present.
    ```
 4. On callback: 对每个 met 子目标，set `task_decomposition[i].status="done"` + `completion_confirmed=true` + `completed_at=now`
 5. Append `{session_dir}/decisions.ndjson` with `"type": "goal-gate"`, `unmet_count`, `unmet_ids`
-6. Verdict: `all_met` → A_APPLY_GOAL_DONE; `has_unmet` → A_APPLY_GOAL_FIX
+6. Verdict routing:
+   - `all_met` + `INTENT_ALIGNED=true` → A_APPLY_GOAL_DONE
+   - `all_met` + `INTENT_ALIGNED=false` → A_REGROUND_HALT（尾部漂移熔断，auto_confirm 不跳过）
+   - `has_unmet` → A_APPLY_GOAL_FIX
    GUARD: retry_count >= max_retries AND still unmet → A_APPLY_ESCALATE
 
+### A_REGROUND_EVALUATE
+
+仅当 `task_decomposition` 存在。周期触发（build rule 5.5）。
+
+1. 从 status.json 读取：`session.intent`、`session.boundary_contract`、`steps[]` 中 `status=="completed"` 的 step + `completion_evidence`、`task_decomposition` 中已 done 子目标的 `goal` + `done_when`
+2. Delegate read-only audit (run_in_background, STOP, wait):
+   ```
+   maestro delegate "PURPOSE: 意图保真检查 — 对照 intent 验证累积执行是否漂移
+   TASK:
+     1. 读取 intent + boundary_contract.definition_of_done
+     2. 读取已完成 steps 的 completion_evidence + 已 done 子目标 done_when
+     3. 判定累积产出是否仍服务 intent；是否有 step 产出超出 in_scope 或触碰 out_of_scope
+     4. 输出 aligned / drifted，drifted 给出 drift_description + corrective_action
+   CONTEXT:
+     intent             = {session.intent}
+     definition_of_done = {boundary_contract.definition_of_done}
+     in_scope           = {boundary_contract.in_scope}
+     out_of_scope       = {boundary_contract.out_of_scope}
+     completed_steps    = [{index, skill, stage, completion_evidence}, ...]
+     done_goals         = [{id, goal, done_when}, ...]
+   EXPECTED:
+     ---VERDICT---
+     STATUS=aligned|drifted
+     DRIFT_DESCRIPTION=<空或具体描述>
+     CORRECTIVE_ACTION=<空或建议>
+     CONFIDENCE_SCORE=0-100
+     ---END---
+   CONSTRAINTS:
+     - 只评估，不修改文件
+     - aligned 阈值：≥80% 已完成产出直接服务 intent
+     - 单个 step 触碰 out_of_scope → 直接判 drifted"
+   --role analyze --mode analysis
+   ```
+3. On callback: parse verdict
+4. Append `{session_dir}/decisions.ndjson`：`{ "id": "DEC-{ts}", "type": "reground-gate", "source": "ralph", "node_id": "post-reground", "verdict": "{aligned|drifted}", "confidence_score": {N}, "drift_description": "...", "corrective_action": "..." }`
+5. Verdict routing：`aligned` → A_APPLY_PROCEED；`drifted` + `confidence_score >= 60` → A_REGROUND_HALT；`drifted` + `confidence_score < 60` → A_APPLY_PROCEED（标 LOW CONFIDENCE）
+
+### A_REGROUND_HALT
+
+漂移熔断（安全门，auto_confirm 不跳过）。
+
+1. Set `session.status = "paused"`，write status.json
+2. Display:
+   ```
+   ⚠️ Re-grounding 检测失败 — 执行已偏离 intent。
+   Intent: {session.intent}
+   Drift:  {drift_description}
+   建议回归: {corrective_action}
+   选项：1) /maestro-ralph continue 忽略漂移继续  2) 手动修正后 continue  3) /maestro-ralph status 查看后决定
+   ```
+3. GUARD: auto_confirm 对本动作无效——漂移熔断不可自动跳过
+
 ### A_APPLY_PROCEED
 
 1. Mark decision completed, write status.json
@@ -593,6 +666,8 @@ Runs only when `task_decomposition` present.
   "phase": null, "phase_is_new": false,
   "milestone": "",                // D-007 反查结果，禁止读 current_milestone
   "auto_mode": false,
+  "decomposition_owner": "ralph", // 分解契约所有者（invariant 15）；缺省按 source 推断
+
   "quality_mode": "standard",     // "full" | "standard" | "quick"
   "planning_mode": "independent", // "unified" | "independent"
   "scope_verdict": null,          // "large" | "medium" | "small" | "unknown" | null
@@ -743,7 +818,7 @@ decision:post-goal-audit {retry+1}
 - [ ] D-007 反查：phase 数字 → `session.milestone`，禁止读 current_milestone；写入 step.milestone_id
 - [ ] phase_is_new=true → lifecycle_position 强制 `analyze`
 - [ ] Intent overrides 识别 grill / brainstorm / blueprint / analyze-macro
-- [ ] auto_confirm=true 时 grill stage 跳过（交互式拷问不支持自动模式）
+- [ ] auto_confirm=true 时 grill step args 追加 `-y`（grill 以 Auto mode 执行，stage 不跳过，产出 grill-report/terminology/context-package）
 - [ ] A_RESOLVE_SCOPE_VERDICT 读 macro analyze conclusions.scope_verdict，写入 session.scope_verdict + analyze_macro_id
 - [ ] 链路起点 = analyze-macro 时：large+wants_roadmap→roadmap+analyze+plan(phase)；其余(含 large 默认/medium/small)→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
 - [ ] post-analyze-scope decision 节点在 macro analyze 之后插入；A_SCOPE_EVALUATE/A_APPLY_SCOPE_VERDICT 重塑链路

package/.agents/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/.agents/skills/maestro-ui-codify/SKILL.md

@@ -45,8 +45,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/.agents/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/.agents/skills/quality-test/SKILL.md

@@ -33,8 +33,6 @@ Flags, artifact context resolution, and output directory format defined in workf
 
 ### Frontend Verify Mode (`--frontend-verify`)
 
-补 ralph 链路缺失的运行时可用性门：确定性验证每个用户可观测能力真正经 UI 可触发，避免"后端绿灯=完成"。
-
 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 出现预期结果。

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

@@ -77,4 +77,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/.agents/skills/spec-setup/SKILL.md

@@ -48,4 +48,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/.agents/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -52,15 +52,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:
-```
-shell({ 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/.agents/skills/team-quality-assurance/roles/scout/role.md

@@ -41,18 +41,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/.agents/skills/team-tech-debt/roles/scanner/role.md

@@ -58,7 +58,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/.agents/skills/team-ultra-analyze/roles/explorer/role.md

@@ -43,24 +43,31 @@ Explore codebase structure through cli-explore-agent, collecting structured cont
 
 ## Phase 3: Codebase Exploration
 
-Use CLI tool for codebase exploration:
-
-```javascript
-shell({
-  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/.agy/agents/cli-explore-agent.md

@@ -10,96 +10,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)
@@ -111,39 +118,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
@@ -169,16 +172,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