maestro-tools-execute

<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>

<execution>

### Step 1: Load Tool

**By name**:
```bash
maestro load --type spec --category coding --keyword <name>
```
Match knowhow documents with `tool: true` whose title or keywords contain the name.

**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>