maestro-flow 0.5.3 → 0.5.31

package/.claude/commands/maestro-tools-execute.md

@@ -1,117 +1,122 @@
----
-name: maestro-tools-execute
-description: Load and execute tool specs by category or name
-argument-hint: "[<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. Two invocation modes:
-
-1. **Direct** — Specify tool name, load full steps, execute sequentially
-2. **Category-based** — List available tools for a category, user selects, then execute
-
-Execution follows the tool definition steps in order, reporting progress per step and asking user on blockers.
-</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 spec load --category coding --keyword <name>
-```
-Match knowhow documents with `tool: true` whose title or keywords contain the name.
-
-**By category**:
-```bash
-maestro spec load --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 wiki load <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>
+---
+name: maestro-tools-execute
+description: Load and execute tool specs by category or name
+argument-hint: "[<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>
+
+<execution>
+
+### Step 1: Load Tool
+
+**By name**:
+```bash
+maestro spec load --category coding --keyword <name>
+```
+Match knowhow documents with `tool: true` whose title or keywords contain the name.
+
+**By category**:
+```bash
+maestro spec load --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 wiki load <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>

package/.claude/commands/maestro-tools-register.md

@@ -1,157 +1,162 @@
----
-name: maestro-tools-register
-description: Register tool specs - extract, generate, or optimize
-argument-hint: "[<description>] [--extract <path>] [--optimize <name>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
-  - Agent
----
-<purpose>
-Codify reusable business processes as knowhow documents with `tool: true` in `.workflow/knowhow/`. Once registered, tools are auto-discovered by `spec load --category` and spec-injector — plan agents pick up design/architecture flows, test agents pick up verification methods, implement agents pick up execution steps.
-
-When to register: during planning to standardize a business process (e.g. payment reconciliation, OAuth integration steps); after execution to capture a validated procedure (e.g. database migration rollback); before testing to register verification methods for test agents (e.g. E2E checkout flow, API idempotency verification); during retrospective/harvest to extract reusable process knowledge from artifacts.
-
-Four modes: Extract (from code/docs), Generate (from description), Optimize (improve existing), Promote (existing knowhow → tool in place).
-Short processes (<10 steps) inline; long processes (>=10 steps) use ref mode with knowhow detail doc.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/tools-spec.md
-</required_reading>
-
-<context>
-$ARGUMENTS — Intent description
-
-**Examples**:
-```
-/maestro-tools-register extract OAuth PKCE token exchange flow from src/auth/
-/maestro-tools-register generate Stripe webhook idempotency verification
-/maestro-tools-register generate E2E checkout flow with payment gateway mock setup
-/maestro-tools-register optimize e2e-checkout tool
-/maestro-tools-register promote RCP-db-migration-rollback as test tool
-/maestro-tools-register promote knowhow-auth-api to coding tool
-```
-</context>
-
-<execution>
-
-### Step 1: Intent Detection
-
-Parse $ARGUMENTS to determine mode:
-- Contains "extract" → extract mode
-- Contains "optimize/improve" → optimize mode
-- Contains "promote" or references existing knowhow doc (path/ID) → promote mode
-- Other → generate mode
-- Empty → ask user with AskUserQuestion
-
-### Step 2: Gather Information
-
-**Extract mode**:
-- Identify source (current conversation, specified files, codebase scan)
-- Extract step sequence, prerequisites, expected outputs
-
-**Generate mode**:
-- Confirm tool name, applicable roles, target scenario
-- If unclear, ask user with AskUserQuestion
-
-**Optimize mode**:
-- Load existing tool: `maestro spec load --category coding --keyword <name>`
-- Analyze improvement points (step splitting, prerequisites, error handling)
-
-**Promote mode** (existing knowhow → tool):
-- Locate document: `maestro search "<name>" --type knowhow` or by path in `.workflow/knowhow/`
-- Read document, verify it contains actionable steps (numbered list or ## Steps section)
-- If no actionable steps, suggest extract mode instead
-- Determine category (Step 3) and summary ("Use when ...")
-- 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 |
-| `test` | tdd-developer, test-fix-agent | 测试者验证行为时需要这个流程吗？ | verify, validate, assert, e2e, regression, coverage, idempotency |
-| `review` | workflow-reviewer | 审查者需要这个作为 checklist 吗？ | audit, checklist, compliance, quality-gate, standard |
-| `arch` | workflow-planner | 规划者设计方案时需要这个吗？ | design, architecture, decompose, trade-off, migration-strategy |
-| `debug` | debug-explore-agent | 调试者排查问题时需要这个吗？ | diagnose, trace, investigate, root-cause, reproduce |
-
-**Multi-consumer split**: If content serves multiple consumers (e.g., API doc for both dev and test), split into separate documents:
-- API contract (what endpoints look like) → `category: coding` (AST-*, tool: false)
-- 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**
-- Steps >=10 or contains code examples/config → **ref mode**
-
-### Step 5: Write
-
-**Description format**: First line after `### Title` must state **when to use** this tool (the usage timing from Step 2). This is critical for ref entries — `spec load` only shows the first 200 chars after the heading as the summary.
-
-```
-### {Title}
-
-Use when {timing/trigger condition}.
-
-1. Step one ...
-```
-
-**Create knowhow tool document** in `.workflow/knowhow/` with `tool: true` in YAML frontmatter:
-```yaml
----
-title: <Title>
-type: recipe
-category: <category>
-keywords: [<keywords>]
-tool: true
-summary: "Use when <timing>. <scope description>"
----
-
-## Steps
-1. Step one ...
-```
-
-**Optionally register spec ref entry** for index discoverability:
-```bash
-maestro spec add <category> "<title>" "Use when <timing>. <scope summary>" --keywords "<csv>" \
-  --description "<one-line summary>" --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
-```
-
-### Step 6: Verify
-
-- `maestro spec load --category <category> --keyword <keyword>` to confirm loadable
-- Display result: title, category, keywords, storage location
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | `.workflow/specs/` does not exist — run `maestro spec init` |
-| E002 | warning | Duplicate tool name detected — confirm overwrite/optimize |
-| E003 | fatal | category parameter empty — tools must declare a category |
-</error_codes>
-
-<success_criteria>
-- [ ] Tool registered as knowhow document with `tool: true` frontmatter
-- [ ] category correctly set
-- [ ] keywords auto-extracted (3-5 terms)
-- [ ] Description starts with "Use when ..." (usage timing)
-- [ ] Loadable via `spec load --category <category>`
-- [ ] Long processes use ref mode with knowhow file created
-- [ ] Ref knowhow YAML includes `summary` with usage timing
-</success_criteria>
+---
+name: maestro-tools-register
+description: Register tool specs - extract, generate, or optimize
+argument-hint: "[<description>] [--extract <path>] [--optimize <name>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Agent
+---
+<purpose>
+Codify reusable business processes as knowhow documents with `tool: true` in `.workflow/knowhow/`.
+Four modes: Extract, Generate, Optimize, Promote. Short processes inline; long use ref mode.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/tools-spec.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Intent description
+
+**Examples**:
+```
+/maestro-tools-register extract OAuth PKCE token exchange flow from src/auth/
+/maestro-tools-register generate Stripe webhook idempotency verification
+/maestro-tools-register generate E2E checkout flow with payment gateway mock setup
+/maestro-tools-register optimize e2e-checkout tool
+/maestro-tools-register promote RCP-db-migration-rollback as test tool
+/maestro-tools-register promote knowhow-auth-api to coding tool
+```
+</context>
+
+<execution>
+
+### Step 1: Intent Detection
+
+Parse $ARGUMENTS to determine mode:
+- Contains "extract" → extract mode
+- Contains "optimize/improve" → optimize mode
+- Contains "promote" or references existing knowhow doc (path/ID) → promote mode
+- Other → generate mode
+- Empty → ask user with AskUserQuestion
+
+### Step 2: Gather Information
+
+**Extract mode**:
+- Identify source (current conversation, specified files, codebase scan)
+- Extract step sequence, prerequisites, expected outputs
+
+**Generate mode**:
+- Confirm tool name, applicable roles, target scenario
+- If unclear, ask user with AskUserQuestion
+
+**Optimize mode**:
+- Load existing tool: `maestro spec load --category coding --keyword <name>`
+- Analyze improvement points (step splitting, prerequisites, error handling)
+
+**Promote mode** (existing knowhow → tool):
+- Locate document: `maestro search "<name>" --type knowhow` or by path in `.workflow/knowhow/`
+- Read document, verify it contains actionable steps (numbered list or ## Steps section)
+- If no actionable steps, suggest extract mode instead
+- Determine category (Step 3) and summary ("Use when ...")
+- 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 |
+| `test` | tdd-developer, test-fix-agent | 测试者验证行为时需要这个流程吗？ | verify, validate, assert, e2e, regression, coverage, idempotency |
+| `review` | workflow-reviewer | 审查者需要这个作为 checklist 吗？ | audit, checklist, compliance, quality-gate, standard |
+| `arch` | workflow-planner | 规划者设计方案时需要这个吗？ | design, architecture, decompose, trade-off, migration-strategy |
+| `debug` | debug-explore-agent | 调试者排查问题时需要这个吗？ | diagnose, trace, investigate, root-cause, reproduce |
+
+**Multi-consumer split**: If content serves multiple consumers (e.g., API doc for both dev and test), split into separate documents:
+- API contract (what endpoints look like) → `category: coding` (AST-*, tool: false)
+- 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**
+- Steps >=10 or contains code examples/config → **ref mode**
+
+### Step 5: Write
+
+**Description format**: First line after `### Title` must state **when to use** this tool (the usage timing from Step 2). This is critical for ref entries — `spec load` only shows the first 200 chars after the heading as the summary.
+
+```
+### {Title}
+
+Use when {timing/trigger condition}.
+
+1. Step one ...
+```
+
+**Create knowhow tool document** in `.workflow/knowhow/` with `tool: true` in YAML frontmatter:
+```yaml
+---
+title: <Title>
+type: recipe
+category: <category>
+keywords: [<keywords>]
+tool: true
+summary: "Use when <timing>. <scope description>"
+---
+
+## Steps
+1. Step one ...
+```
+
+**Optionally register spec ref entry** for index discoverability:
+```bash
+maestro spec add <category> "<title>" "Use when <timing>. <scope summary>" --keywords "<csv>" \
+  --description "<one-line summary>" --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
+```
+
+### Step 6: Verify
+
+- `maestro spec load --category <category> --keyword <keyword>` to confirm loadable
+- Display result: title, category, keywords, storage location
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/specs/` does not exist — run `maestro spec init` |
+| E002 | warning | Duplicate tool name detected — confirm overwrite/optimize |
+| E003 | fatal | category parameter empty — tools must declare a category |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool registered as knowhow document with `tool: true` frontmatter
+- [ ] category correctly set
+- [ ] keywords auto-extracted (3-5 terms)
+- [ ] Description starts with "Use when ..." (usage timing)
+- [ ] Loadable via `spec load --category <category>`
+- [ ] Long processes use ref mode with knowhow file created
+- [ ] Ref knowhow YAML includes `summary` with usage timing
+</success_criteria>
+
+<completion>
+### Next-step routing
+| Condition | Suggestion |
+|-----------|-----------|
+| Tool registered, want to test | `/maestro-tools-execute <name>` |
+| Want to register another | `/maestro-tools-register` |
+| Tool for test agents | `/spec-load --category test` to verify discovery |
+</completion>