pi-maestro-flow 0.2.0

package/skills/maestro-roadmap/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: maestro-roadmap
+description: "Generate roadmap with milestone/phase structure from requirements or upstream context Arguments: <requirement> [-y] [-c] [-m progressive|direct|auto] [--from <source>] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Generate milestone/phase roadmap from requirements or upstream context. Three modes: create (default), revise (`--revise`), review (`--review`). For formal spec documents, use `/maestro-blueprint`.
+
+Pipeline: brainstorm/blueprint/analyze → **roadmap** → analyze {milestone} → plan {milestone} → execute.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/roadmap-common.md
+@~/.maestro/templates/roadmap.md
+</required_reading>
+
+<deferred_reading>
+- [roadmap.md](~/.maestro/workflows/roadmap.md) — read for roadmap generation workflow
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- requirement text, @file reference, or upstream context source.
+
+**Flags:**
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive questions, use recommended defaults | false |
+| `-c` / `--continue` | Resume from last checkpoint | false |
+| `-m progressive\|direct\|auto` | Decomposition strategy | auto |
+| `--from <source>` | Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json | — |
+| `--from-brainstorm SESSION-ID` | Backward compat alias for `--from brainstorm:ID` | — |
+| `--revise [instructions]` | Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress. | — |
+| `--review` | Roadmap health assessment (read-only) | — |
+
+**Input types:**
+- Direct text: `"Implement user authentication system with OAuth and 2FA"`
+- File reference: `@requirements.md`
+- Context import: `--from brainstorm:BRN-001` or `--from analyze:ANL-xxx` or `--from blueprint:BLP-xxx`
+- No args + `--revise` / `--review`: Operate on existing `.workflow/roadmap.md`
+
+### Pre-load
+
+1. **Specs**: `maestro load --type spec --category arch` — load architecture constraints for phase decomposition
+2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge
+3. All optional — proceed without if unavailable
+</context>
+
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): mode (create / revise / review) → requirement scope (MVP / complete / phased) → decomposition strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order
+**Scope guard**: only roadmap shape; do not pre-resolve task breakdown or phase decomposition (belongs to plan)
+**Writeback target**: .workflow/roadmap.md "Roadmap Decisions" section (create if absent)
+**Additional skip conditions**: --revise, --review (skip to respective mode)
+**Exit condition**: on consensus or explicit user signal → finalize Roadmap Decisions section
+</interview_protocol>
+
+<execution>
+
+1. Read `@~/.maestro/workflows/roadmap-common.md` (always — shared logic)
+2. Read `@~/.maestro/workflows/roadmap.md`, follow its process
+
+Sub-modes:
+- **Create** (default): Build roadmap from requirements or upstream context
+- **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
+- **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
+
+### Phase Gates (MANDATORY, BLOCKING — Create mode)
+
+**GATE 1: Input → Decomposition**
+- REQUIRED: Requirement parsed with goal, constraints, stakeholders.
+- REQUIRED: Upstream context loaded via --from (if specified).
+- BLOCKED if missing: cannot decompose without parsed requirement.
+
+**GATE 2: Decomposition → Refinement**
+- REQUIRED: Milestones defined with deliverable targets.
+- REQUIRED: Phases defined within milestones with dependencies.
+- REQUIRED: Every Active requirement from project.md mapped to exactly one phase.
+- REQUIRED: No circular dependencies in phase ordering (E003 if detected).
+- BLOCKED if incomplete: finish milestone/phase decomposition before refinement.
+
+**GATE 3: Refinement → Completion**
+- REQUIRED: User approved roadmap (or auto-approved with -y).
+- REQUIRED: `.workflow/roadmap.md` written with Milestone > Phase hierarchy.
+- REQUIRED: Artifact registered in state.json with milestone entries.
+- BLOCKED if missing: do not report completion without written roadmap.
+
+
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== ROADMAP READY ===
+Milestones: {count}
+Phases: {total_phases}
+Strategy: {progressive|direct|auto}
+Output: .workflow/roadmap.md
+--- COMPLETION STATUS ---
+Status: {DONE|DONE_WITH_CONCERNS}
+Concerns: {if any}
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Roadmap approved, need analysis | `/maestro-analyze 1` |
+| Simple project, ready to plan | `/maestro-plan 1` |
+| Need UI design first | `/maestro-impeccable build` |
+| View project dashboard | `/manage-status` |
+| Need formal spec documents | `/maestro-blueprint` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Requirement/idea text or @file required | Prompt user for input |
+| E002 | error | Context source not found (--from / --from-brainstorm) | Show available sessions/sources |
+| E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
+| E004 | error | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
+| E005 | error | Revision invalidates completed phase work | Warn user, ask to confirm or adjust |
+| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
+| W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
+</error_codes>
+
+<success_criteria>
+- [ ] Interactive mode: interview decision table appended to `.workflow/roadmap.md` "Roadmap Decisions" section
+- [ ] Requirement parsed with goal, constraints, stakeholders
+- [ ] Milestones defined with deliverable targets and version tags
+- [ ] Decomposition strategy selected (progressive or direct)
+- [ ] Phases defined within milestones with success criteria, dependencies, and requirement mappings
+- [ ] Every Active requirement from project.md mapped to exactly one phase
+- [ ] No circular dependencies in phase ordering
+- [ ] User approved roadmap (or auto-approved with -y)
+- [ ] `.workflow/roadmap.md` written with Milestone > Phase hierarchy, scope decisions, and progress table
+- [ ] No phase directories created (phases are labels in roadmap, not directories)
+- [ ] Artifact registered in state.json with milestone entries
+</success_criteria>

package/skills/maestro-swarm-workflow/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: maestro-swarm-workflow
+description: "Parallel workflow accelerator — route intent to fixed Workflow scripts for multi-agent concurrent execution Arguments: <intent> [--script <name>] [--dims <d1,d2>] [--roles <r1,r2>] [--count N] [--tier quick|standard] [--resume <runId>]"
+allowed-tools: Read Write Edit Bash Glob Grep Workflow AskUserQuestion
+---
+
+<purpose>
+Parallel accelerator: route intent to pre-built Workflow scripts (`wf-*.js`) for multi-agent
+concurrent execution with adversarial decision patterns. Complements ralph's sequential chain.
+</purpose>
+
+<context>
+$ARGUMENTS — intent text with optional flags.
+
+**Parse:**
+```
+--script <name>  → 强制指定脚本（wf-analyze, wf-brainstorm, wf-review, wf-verify）
+--dims <d1,d2>   → 限定分析维度（analyze: architecture,complexity,patterns,risk,testability,performance）
+--roles <r1,r2>  → 限定角色（brainstorm: system-architect,product-manager,test-strategist,ux-expert,security-analyst,data-architect）
+--count N        → 角色数量（brainstorm 默认 3）
+--tier <level>   → review 层级（quick=2 维度, standard=4 维度）
+--resume <runId> → 从之前的 workflow 运行恢复（增量重跑）
+Remaining        → intent
+```
+
+**Script inventory** (`~/.maestro/workflows/swarm/`):
+
+| Script | args 接口 |
+|--------|-----------|
+| `wf-analyze` | `{ target, scope, context, phase?, dimensions? }` |
+| `wf-brainstorm` | `{ topic, context, count?, roles? }` |
+| `wf-review` | `{ target, scope, specs?, tier?, dimensions? }` |
+| `wf-verify` | `{ goals, plan_dir?, scope?, task_files?, must_haves?, skip_antipattern? }` |
+| `wf-grill` | `{ topic, context?, depth?: "shallow"\|"standard"\|"deep" }` |
+| `wf-plan` | `{ context_dir?, from?, phase?, scope?, specs?, gaps?, quick? }` |
+| `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
+| `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/` (results, ralph-compatible artifacts). When inside a ralph session, writes target the corresponding step's scratch directory. NEVER modify source code, workflow scripts (`~/.maestro/workflows/swarm/`), or `.claude/commands/` files.
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE        — 解析参数和意图                    PERSIST: —
+S_ROUTE        — 路由到目标脚本                    PERSIST: —
+S_CONTEXT      — 组装 context payload             PERSIST: —
+S_DISPATCH     — 调用 Workflow 工具                PERSIST: —
+S_INGEST       — 处理返回结果                      PERSIST: —
+S_FALLBACK     — 无法路由                         PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_ROUTE     WHEN: intent parsed                DO: A_PARSE_ARGS
+  → S_FALLBACK  WHEN: no intent
+
+S_ROUTE:
+  → S_CONTEXT   WHEN: script resolved              DO: A_ROUTE_SCRIPT
+  → S_FALLBACK  WHEN: ambiguous intent              DO: AskUserQuestion
+
+S_CONTEXT:
+  → S_DISPATCH  DO: A_ASSEMBLE_CONTEXT
+
+S_DISPATCH:
+  → S_INGEST    WHEN: workflow completed            DO: A_DISPATCH_WORKFLOW
+  → S_FALLBACK  WHEN: workflow failed
+
+S_INGEST:
+  → END         DO: A_INGEST_RESULTS
+
+S_FALLBACK:
+  → S_PARSE     WHEN: user provides input
+  → END         WHEN: user cancels
+
+</transitions>
+
+<actions>
+
+### A_PARSE_ARGS
+
+1. 提取 flags（--script, --dims, --roles, --count, --tier, --resume）
+2. 剩余文本作为 intent
+3. 若有 --resume，记录 resumeRunId
+
+### A_ROUTE_SCRIPT
+
+Intent-to-script routing（按关键词匹配，--script 优先级最高）。
+
+**Priority ordering** — 按下表自上而下匹配，先命中先用。高优先级的具体关键词优先于低优先级的宽泛关键词（如 "grill" > "analyze"，"verify" > "check"）：
+
+| Priority | Keywords | Script |
+|----------|----------|--------|
+| 1 | 里程碑审计 / milestone-audit / 集成检查 / integration | `wf-milestone-audit` |
+| 2 | 拷问 / grill / 压力测试 / stress-test / 挑战 / challenge | `wf-grill` |
+| 3 | 验证 / verify / 反模式 / antipattern | `wf-verify` |
+| 4 | 审查 / review / 代码审查 / code review / 质量 / quality | `wf-review` |
+| 5 | 执行 / execute / 实现 / implement / 开发 / develop | `wf-execute` |
+| 6 | 规划 / plan / 任务分解 / decompose / 分波 / wave | `wf-plan` |
+| 7 | 头脑风暴 / brainstorm / 方案 / 评估 / evaluate / 多角度 | `wf-brainstorm` |
+| 8 | 分析 / analyze / 探索 / explore / 架构 / architecture / 复杂度 / 风险 | `wf-analyze` |
+
+**Disambiguation**: 多命中（同一优先级内多个关键词匹配不同脚本）→ AskUserQuestion 让用户选择。跨优先级命中取高优先级。
+
+### A_ASSEMBLE_CONTEXT
+
+根据目标脚本组装 args payload：
+
+**wf-analyze:**
+1. Read `.workflow/state.json` 获取当前 phase/milestone 信息
+2. `target` = intent 中的目标描述
+3. `scope` = 从 intent 推断文件范围，或读 roadmap 获取 phase scope
+4. `context` = 拼接相关上下文（上游 artifact 摘要、specs）
+5. `dimensions` = --dims 解析结果（可选）
+
+**wf-brainstorm:**
+1. `topic` = intent 文本
+2. `context` = 读取相关代码文件摘要 + 已有 specs
+3. `count` = --count 或默认 3
+4. `roles` = --roles 解析结果（可选）
+
+**wf-review:**
+1. `target` = 读 git diff 描述变更范围
+2. `scope` = 变更文件列表
+3. `tier` = --tier 或 "standard"
+4. `dimensions` = --dims 解析结果（可选）
+
+**wf-verify:**
+1. `goals` = 读最近的 plan artifact 提取目标列表
+2. `plan_dir` = 定位最近的 plan scratch 目录
+3. `scope` = plan 涉及的文件范围
+4. `skip_tests` / `skip_antipattern` = 从 flags 提取
+
+### A_DISPATCH_WORKFLOW
+
+1. 确定 scriptPath = `~/.maestro/workflows/swarm/{script}.js`（展开为绝对路径）
+2. 构建 Workflow 调用：
+   ```
+   Workflow({
+     scriptPath: absoluteScriptPath,
+     args: assembledArgs,
+     resumeFromRunId: resumeRunId  // 若有
+   })
+   ```
+3. 等待 Workflow 返回结果
+4. 记录 runId 用于潜在的后续 resume
+
+### A_INGEST_RESULTS
+
+Workflow 返回 JSON 后：
+
+1. **摘要输出**：按脚本类型格式化关键指标（含对抗决策结果）
+   - analyze: overall_score, scope_verdict, adversarial_outcome (go/no-go/conditional advocacy + referee), scores_challenged count
+   - brainstorm: role count, conflict/synergy count, 3-proposal competition result, arbitration notes
+   - review: verdict (APPROVE/REQUEST_CHANGES/BLOCK), 3-vote tally, confirmed vs false-positive count, adversarial_verdict
+   - verify: overall_status, prosecutor vs defender confidence, adversarial_outcome, gap count
+   - grill: overall_verdict, meta-skeptic quality rating, 3-vote verdict tally, overblown findings count
+   - plan: selected_strategy (breadth/depth/risk), judge panel scores, 3-critic adversarial check verdict
+   - execute: 3-vote status (DONE/DONE_WITH_CONCERNS/NEEDS_RETRY), convergence trust %, discrepancy count
+   - milestone-audit: 3-vote verdict, dimensions_overturned count, next_step
+
+2. **Artifact 写入**（可选）：
+   - 若当前在 ralph session 中（检测 `.workflow/.maestro/ralph-*/status.json` 状态为 running）：
+     将结果写入对应 step 的 scratch 目录，格式兼容命令产出
+   - 否则写入 `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/results.json`
+
+3. **Ralph 兼容产出**：
+   - analyze → `analysis.md` + `context.md`（decisions）+ `conclusions.json` + `adversarial-debate.json`
+   - brainstorm → `guidance-specification.md` + `proposals-competition.json`
+   - review → `review.json`（含 adversarial_verdict + 3-vote tally）
+   - verify → `verification.json`（含 adversarial_outcome: prosecutor/defender debate）
+   - grill → `grill-results.json`（含 meta-challenge + 3-vote verdict）
+   - plan → `plan.json`（含 competition scores + critic feedback）
+   - execute → `execution-report.json`（含 convergence_checks + 3-vote status）
+   - milestone-audit → `audit-report.json`（含 dimension challenges + 3-vote verdict）
+
+4. **RunId 提示**：显示 `Resume: /maestro-swarm-workflow --resume {runId}` 用于增量重跑
+
+</actions>
+
+</state_machine>
+
+<invariants>
+1. **只做并行加速，不做状态决策** — 不修改 ralph status.json，不推进 step
+2. **args 预编译** — 所有 FS 读取在 A_ASSEMBLE_CONTEXT 完成，脚本内 agent 通过工具自行读取补充
+3. **产出格式兼容** — 写入的 artifact 格式必须与对应命令（analyze/brainstorm/review/verify）的产出一致
+4. **resume 透传** — resumeFromRunId 直接透传给 Workflow 工具，利用内置缓存机制
+5. **脚本只读** — 路由命令不修改 `~/.maestro/workflows/swarm/wf-*.js` 脚本文件
+6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
+</invariants>
+
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Route**
+- REQUIRED: Intent text or `--script` flag parsed successfully.
+- BLOCKED if: no intent and no `--script` (E001).
+
+**GATE 2: Route → Context Assembly**
+- REQUIRED: Target script resolved unambiguously (single match or user-selected from candidates).
+- BLOCKED if: ambiguous routing without user resolution (E002).
+
+**GATE 3: Context → Dispatch**
+- REQUIRED: Args payload assembled with all required fields for target script.
+- REQUIRED: Script file exists at `~/.maestro/workflows/swarm/{script}.js`.
+- BLOCKED if: script file not found (E003) or required args missing.
+
+**GATE 4: Dispatch → Ingest**
+- REQUIRED: Workflow execution completed (success or partial results available).
+- BLOCKED if: Workflow execution failed entirely (E004) — offer `--resume`.
+
+</execution>
+
+<appendix>
+
+### 与 Ralph 集成
+
+Ralph 可以在 A_BUILD_STEPS 中将某些 step 的执行方式标记为 `swarm-workflow`：
+
+```json
+{
+  "index": 2,
+  "skill": "maestro-swarm-workflow",
+  "args": "--script wf-analyze {phase}",
+  "stage": "analyze",
+  "command_scope": "project",
+  "command_path": "<resolved by maestro ralph skills --platform claude>"
+}
+```
+
+ralph-execute 正常通过 `maestro ralph next` 加载并执行，swarm-workflow 内部再调 Workflow 工具。
+
+**何时选 swarm vs 顺序命令：**
+
+| 条件 | 推荐 | 原因 |
+|------|------|------|
+| 需要多维度并行 + 对抗交叉验证 | swarm | 多 agent 并发产出 + adversarial gate |
+| 需要对话式交互（interview_protocol）| 顺序命令 | swarm agent 无法交互 |
+| 需要写入 state.json / 推进 ralph step | 顺序命令 | swarm 承诺不触碰 ralph 状态 |
+| 时间预算充裕、准确性优先 | swarm | 多角度提高覆盖率 |
+| 上下文受限、快速单视角足够 | 顺序命令 | 轻量 |
+
+### 输出示例
+
+```
+┌─ wf-analyze ──────────────────────────────────────┐
+│  Explore  [████████████████████] 6/6 dimensions    │
+│  Synthesize  [████████████████] done               │
+├────────────────────────────────────────────────────┤
+│  Score: 7.2/10  Scope: medium  Verdict: go         │
+│  Findings: 23 total (2 critical, 5 high)           │
+│  Cross-cutting: 3 themes                           │
+│  Decisions: 4 locked, 2 free, 1 deferred           │
+├────────────────────────────────────────────────────┤
+│  Output: .workflow/scratch/20260530-swarm-analyze/  │
+│  Resume: /maestro-swarm-workflow --resume wf_abc123 │
+└────────────────────────────────────────────────────┘
+```
+
+### Error Codes
+
+| Code | Description | Recovery |
+|------|-------------|----------|
+| E001 | No intent and no --script | Prompt for intent |
+| E002 | Ambiguous routing | AskUserQuestion |
+| E003 | Script file not found | Check .claude/workflows/ |
+| E004 | Workflow execution failed | Show error, suggest --resume |
+| E005 | Result ingestion failed | Write raw JSON to scratch |
+
+</appendix>

package/skills/maestro-tools-execute/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: maestro-tools-execute
+description: "Load and execute tool specs by category or name Arguments: [<tool-name> | --category <category>] [--list]"
+allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion Agent
+---
+
+<purpose>
+Load registered tool documents and execute them step-by-step.
+Direct (by name) or category-based (list + select) invocation.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/tools-spec.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Tool name, keyword, or --category filter
+
+**Examples**:
+```
+/maestro-tools-execute integration-test
+/maestro-tools-execute --category coding
+/maestro-tools-execute --category review --keyword api
+/maestro-tools-execute
+```
+
+Empty arguments enters interactive mode: list all tools for user selection.
+</context>
+
+<invariants>
+1. **Confirmation before execution** — MUST AskUserQuestion before executing tool steps; NEVER auto-execute without user consent
+2. **Sequential step execution** — steps MUST be executed in defined order; NEVER skip or reorder steps unless user explicitly requests skip
+3. **Blocker escalation** — step failure MUST be reported to user with retry/skip/abort options; NEVER silently skip failed steps
+4. **Read-only tool definition** — tool execution MUST NOT modify the tool's knowhow document or spec entry; only the target codebase is modified per tool steps
+5. **Progress feedback** — each completed step MUST report `[Step N/M] done — <step_name>`; NEVER execute silently
+6. **Output boundary** — file writes are governed by the individual tool's step definitions. This command itself writes NO files beyond what the loaded tool prescribes
+</invariants>
+
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load**
+- REQUIRED: Tool name, keyword, or --category parsed from arguments (or empty for interactive mode).
+- BLOCKED if: invalid category value.
+
+**GATE 2: Load → Confirm**
+- REQUIRED: Exactly one tool resolved (direct match or user selection from candidates).
+- REQUIRED: Tool document loaded and steps extracted (ref entries expanded via `maestro load --type knowhow`).
+- BLOCKED if: E001 (no match found), E002 unresolved (multiple matches without user selection).
+
+**GATE 3: Confirm → Execute**
+- REQUIRED: User confirmed execution mode via AskUserQuestion (execute as-is / adjust / view only).
+- BLOCKED if: user selects "View only" — display steps and END without execution.
+
+**GATE 4: Execute → Report**
+- REQUIRED: All steps attempted (completed, skipped with user approval, or aborted by user).
+- REQUIRED: Results collected for each step (success/skip/fail).
+- BLOCKED if: user chose abort mid-execution — report partial results and END.
+
+### Step 1: Load Tool
+
+**By name**:
+```bash
+maestro search "<name>" --type knowhow
+```
+Match knowhow documents with `tool: true` whose title or keywords contain the name. Load the matched entry with `maestro load --type knowhow --id <id>`.
+
+**By category**:
+```bash
+maestro load --type spec --category <category>
+```
+Extract tool entries from the "Available Tools" section in output.
+
+**Empty args**:
+Load all categories, collect tool entries, present to user with AskUserQuestion for selection.
+
+### Step 2: Display Tool
+
+Show tool information:
+- Name, category, keywords
+- Steps overview (for ref entries, expand knowhow detail first)
+
+Expand ref entries:
+```bash
+maestro load --type knowhow --id <knowhow-id>
+```
+
+### Step 3: Confirm Execution
+
+AskUserQuestion (single-select, header: "执行方式"):
+- **Execute as-is** (Recommended) — run all steps with current parameters
+- **Adjust parameters** — modify scope or parameters before executing
+- **View only** — display steps without executing
+
+### Step 4: Step-by-Step Execution
+
+Follow the tool definition steps in order:
+1. Read current step description
+2. Execute step action (file ops, commands, code changes, etc.)
+3. Verify step completion
+4. Report progress: `[Step N/M] done — <step_name>`
+5. Proceed to next step
+
+**Blocker handling**:
+- Step fails → report error, ask user: retry / skip / abort
+- Needs user input → AskUserQuestion for parameters
+- Prerequisites unmet → show missing items, ask how to proceed
+
+### Step 5: Report Results
+
+After completion, output:
+- Completed steps list
+- Skipped/failed steps (if any)
+- Artifacts produced (generated files, test results, etc.)
+- Suggested next actions
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | No matching tool found — check name/keyword |
+| E002 | warning | Multiple tools match — list options for user selection |
+| E003 | warning | Step execution failed — ask user how to proceed |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool correctly loaded (ref expanded if applicable)
+- [ ] User confirmed before execution starts
+- [ ] Each step has progress feedback
+- [ ] Blockers handled interactively
+- [ ] Results reported clearly
+</success_criteria>
+
+<completion>
+### Next-step routing
+| Condition | Suggestion |
+|-----------|-----------|
+| Tool completed successfully | `/manage-status` or continue workflow |
+| Want to register a new tool | `/maestro-tools-register` |
+| Need to adjust tool definition | `/maestro-tools-register --optimize <name>` |
+</completion>