maestro-flow 0.4.10 → 0.4.12

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

@@ -0,0 +1,273 @@
+---
+name: maestro-ralph-execute
+description: Execute next pending step in ralph session
+argument-hint: "[-y] [session-id]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - invoke_skill
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Single-step executor for ralph (adaptive) and maestro (static) sessions.
+Each invocation: locate session → find next step → resolve args → execute → update → self-invoke next.
+
+Mutual invocation with `/maestro-ralph` forms a self-perpetuating work loop.
+Session: `.workflow/.maestro/*/status.json`
+</purpose>
+
+<context>
+$ARGUMENTS — optional `-y` flag + optional session ID.
+
+**Parse:**
+```
+-y / --yes → auto = true
+Remaining  → session_id (if matches maestro-* or ralph-*)
+```
+Also read `session.auto_mode` from status.json — if true, treat as `-y`.
+
+**Node types:**
+
+| Type | Execution | Flow after |
+|------|-----------|------------|
+| decision (ralph-only) | `invoke_skill("maestro-ralph")` | Execution ends here |
+| internal (default) | `read_file({file_path: step.command_path})` + 内联解释执行 | Self-invoke next |
+| external (opt-in) | `maestro delegate --to claude --mode write` (STOP → callback) | Self-invoke next |
+
+HARD RULES:
+- internal step MUST 通过 `read_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；禁止 `invoke_skill({skill})` 调用
+- `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json；ralph-execute 不再自行解析（缺失 → 报错 E002）
+- external 仅在 `step.type == "external"` 显式声明时使用，并 always append `-y` 到 prompt args
+- 每个 step 必须产出 `--- COMPLETION STATUS ---` 块，否则视为 NEEDS_RETRY
+</context>
+
+<invariants>
+1. **Internal = Read + inline** — 通过 Read 读取 `step.command_path`，按其指令在当前 session 内执行
+2. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
+3. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
+4. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
+5. **status.json 每步骤后写盘** — resume-safe
+</invariants>
+
+<state_machine>
+
+<states>
+S_LOCATE        — 定位 session + 找下一个 pending step   PERSIST: —
+S_RESOLVE_ARGS  — 解析占位符 + 丰富参数                  PERSIST: step.args (enriched)
+S_EXECUTE       — 执行当前 step                          PERSIST: step.status = "running", session.current_step
+S_POST_EXEC     — 标记完成 + 传播上下文                   PERSIST: step.completion_*, step.status, session.context
+S_HANDLE_FAIL   — 处理失败                               PERSIST: step.status, session.status
+S_COMPLETE      — 所有 step 完成                         PERSIST: session.status = "completed"
+S_FALLBACK      — 无 session 可执行                      PERSIST: —
+</states>
+
+<transitions>
+
+S_LOCATE:
+  → S_RESOLVE_ARGS  WHEN: pending step found                DO: A_LOCATE_SESSION
+  → S_COMPLETE      WHEN: no pending steps
+  → S_FALLBACK      WHEN: no running session
+
+S_RESOLVE_ARGS:
+  → S_EXECUTE       DO: A_RESOLVE_ARGS
+
+S_EXECUTE:
+  → END             WHEN: step.type == "decision"           DO: A_EXEC_DECISION
+  → S_POST_EXEC     WHEN: step.type == "internal" + success DO: A_EXEC_INTERNAL
+  → S_HANDLE_FAIL   WHEN: step.type == "internal" + failure DO: A_EXEC_INTERNAL
+  → END             WHEN: step.type == "external"           DO: A_EXEC_EXTERNAL
+                     (STOP after background delegate; on callback → S_POST_EXEC or S_HANDLE_FAIL)
+
+S_POST_EXEC:
+  → S_LOCATE        DO: A_MARK_COMPLETE + invoke_skill("maestro-ralph-execute")
+
+S_HANDLE_FAIL:
+  → S_LOCATE        WHEN: auto + not retried               DO: A_RETRY
+  → END             WHEN: auto + retried                    DO: A_PAUSE_SESSION
+  → S_LOCATE        WHEN: interactive + user selects retry  DO: A_RETRY
+  → S_LOCATE        WHEN: interactive + user selects skip   DO: A_SKIP_STEP
+  → END             WHEN: interactive + user selects abort  DO: A_PAUSE_SESSION
+
+S_COMPLETE:
+  → END             DO: A_COMPLETE_SESSION
+
+S_FALLBACK:
+  → END             DO: display "无运行中的会话。使用 /maestro 或 /maestro-ralph 创建。"
+
+</transitions>
+
+<actions>
+
+### A_LOCATE_SESSION
+
+1. If session_id provided → load `.workflow/.maestro/{session_id}/status.json`
+2. Else: scan `.workflow/.maestro/*/status.json`, filter `status == "running"`, sort DESC, take first
+3. Extract: session_id, source, steps[], current_step, phase, milestone, intent, auto_mode, context, cli_tool
+4. Find first step with `status == "pending"` → next step
+
+### A_RESOLVE_ARGS
+
+**Placeholder substitution:**
+
+| Placeholder | Source |
+|-------------|--------|
+| `{phase}` | session.phase |
+| `{milestone}` | session.milestone |
+| `{intent}` | session.intent |
+| `{description}` | session.intent (alias) |
+| `{scratch_dir}` | session.context.scratch_dir or latest artifact path |
+| `{plan_dir}` | session.context.plan_dir |
+| `{analysis_dir}` | session.context.analysis_dir |
+| `{issue_id}` | session.context.issue_id |
+| `{milestone_num}` | session.context.milestone_num |
+
+**Per-skill enrichment** (when args empty or minimal):
+
+| Skill | Required context | Source |
+|-------|-----------------|--------|
+| 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}` |
+| quality-debug | gap context | Read previous step's error/gap |
+| quality-* | phase | `{phase}` |
+
+**Artifact dir resolution for --dir:**
+```
+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}
+```
+
+Write enriched args back to status.json.
+
+### A_EXEC_DECISION
+
+1. Mark step running, write status.json
+2. Display: `[{index}/{total}] ◆ {decision} Retry: {retry}/{max}`
+3. `invoke_skill({ skill: "maestro-ralph" })` — ralph 评估 + handoff
+4. 执行在此结束
+
+### A_EXEC_INTERNAL
+
+1. Validate `step.command_path != null`；否则 raise E002，pause session
+2. Mark step running, write status.json
+3. Display: `[{index}/{total}] {step.skill} [internal · {step.command_scope}]`
+4. `read_file({ file_path: step.command_path })` — 把命令 .md 全文加载进当前会话
+5. 解析 frontmatter `argument-hint` 与 `<purpose>/<state_machine>/<actions>` 等指令块
+6. 计算 `effective_args`：`step.args` + auto flag（`auto ? (flag_map[step.skill] || "") : ""`）
+7. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 invoke_skill() 或 delegate
+8. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
+9. Return success / failure
+
+**Auto flag map**: 所有 lifecycle skill → `-y`; `quality-test` → `-y --auto-fix`; 未列出 → 无 flag
+
+### A_EXEC_EXTERNAL
+
+仅当 `step.type == "external"` 时使用（默认链路不产生）。
+
+1. Mark step running, write status.json
+2. Display: `[{index}/{total}] ⚡ {step.skill} [external]`
+3. 始终在 prompt 内追加 `-y`（delegate session 非交互）：`flag = flag_map[step.skill] || "-y"`
+4. Execute:
+   ```
+   shell({
+     command: `maestro delegate "/${step.skill} ${effective_args}" --to claude --mode write`,
+     run_in_background: true, timeout: 600000
+   })
+   STOP — wait for callback.
+   ```
+5. On callback: 把回调输出视为 step 的执行结果 → S_POST_EXEC / S_HANDLE_FAIL
+
+### A_MARK_COMPLETE
+
+1. 从 step 输出中提取 `--- COMPLETION STATUS ---` 块（required）
+2. 解析并写入：
+   - `STATUS: DONE` → `step.status = "completed"`, `step.completion_confirmed = true`, `step.completion_status = "DONE"`
+   - `STATUS: DONE_WITH_CONCERNS` → `step.status = "completed"`, `step.completion_confirmed = true`, `step.completion_status = "DONE_WITH_CONCERNS"`, `step.concerns = <CONCERNS>`
+   - `STATUS: NEEDS_RETRY` → `step.status = "pending"`, `step.retried = true`, `step.completion_confirmed = false`, → S_HANDLE_FAIL
+   - `STATUS: BLOCKED` / `NEEDS_CONTEXT` → `session.status = "paused"`, `step.completion_status` 记录原因, `step.completion_confirmed = false`
+   - 缺失 `--- COMPLETION STATUS ---` 块 → 视为 NEEDS_RETRY（不允许 heuristic fallback）
+3. 写入 `step.completion_evidence`（artifact 路径 / 关键输出节选）
+4. 扫描输出抓取 context 信号：`PHASE: N` → session.phase；`scratch_dir: path` → context.scratch_dir；`BLP-xxx` → context.blueprint_session_id
+5. `step.completed_at = now`，写 status.json
+6. **Sub-goal evidence 校验**（task_decomposition 存在时）：若 `step.goal_ref` 对应子目标的 `lifecycle` 覆盖当前 stage 且 evidence artifact 已生成 → 暂不直接置 done，仍交由 post-goal-audit 决策；仅在 step 显式确认时更新 `task_decomposition[*].completion_confirmed = false` 占位（保持 pending）
+7. Display: `[{index}/{total}] ✓ {step.skill} completed (confirmed)`
+
+### A_RETRY
+
+1. `step.retried = true`, `step.status = "pending"`, `step.error = null`, `step.completion_confirmed = false`
+2. Write status.json
+
+### A_SKIP_STEP
+
+1. `step.status = "skipped"`, `step.completion_confirmed = false`
+2. Write status.json
+
+### A_PAUSE_SESSION
+
+1. `session.status = "paused"`, write status.json
+2. Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
+
+### A_COMPLETE_SESSION
+
+1. 校验：所有 step `completion_confirmed == true`（除 skipped）；task_decomposition 存在时校验 `task_decomposition_all_done == true`
+2. 任一校验失败 → 不标 completed，回 S_LOCATE 或 pause
+3. `session.status = "completed"`, write status.json
+4. Display completion report:
+   ```
+   ============================================================
+     SESSION COMPLETE
+   ============================================================
+     Session:  {session_id} [{source}]
+     Steps:    {completed}/{total}   confirmed: {confirmed}/{completed}
+
+     [✓] 0.   maestro-plan 1            [internal · global]
+     [✓] 1.   maestro-execute 1         [internal · project]
+     [✓] 2.   maestro-verify 1          [internal · global]
+     [✓] 3. ◆ post-verify               [decision]
+     ...
+   ============================================================
+   ```
+   Icons: `✓` confirmed, `—` skipped, `✗` failed, `◆` decision, `⚡` external
+
+</actions>
+
+</state_machine>
+
+<appendix>
+
+### Error Codes
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No running session found | Suggest /maestro or /maestro-ralph |
+| E002 | error | step.command_path missing for internal step | Pause, ask ralph to rebuild step |
+| E003 | error | status.json corrupt | Show path, manual check |
+| E004 | error | Delegate failed + user abort | Mark paused, suggest resume |
+| E005 | error | COMPLETION STATUS block missing | Trigger NEEDS_RETRY |
+| W001 | warning | Step completed with concerns | Log and continue |
+
+### Success Criteria
+
+- [ ] Session discovery covers maestro-* and ralph-*
+- [ ] `-y` parsed from args 或 session.auto_mode
+- [ ] Placeholders resolved；per-skill enrichment 正确
+- [ ] Decision 节点 invoke_skill("maestro-ralph") handoff
+- [ ] Internal 节点通过 read_file({step.command_path}) 内联执行，禁止 invoke_skill()
+- [ ] External 仅在显式声明时走 delegate，prompt 必带 `-y`
+- [ ] 每个 step 强制 `--- COMPLETION STATUS ---`；缺失 → NEEDS_RETRY
+- [ ] step.completion_confirmed = true 仅在 STATUS: DONE/DONE_WITH_CONCERNS 时设置
+- [ ] step.completion_evidence 记录 artifact path / 输出节选
+- [ ] Context signals 传播 status.json
+- [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
+- [ ] 自调用持续到全部 completion_confirmed 或 paused
+- [ ] A_COMPLETE_SESSION 校验全部 step confirmed + sub-goal all_done
+
+</appendix>

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

@@ -0,0 +1,131 @@
+---
+name: maestro-roadmap
+description: Generate roadmap with milestone/phase structure from requirements or upstream context
+argument-hint: "<requirement> [-y] [-c] [-m progressive|direct|auto] [--from <source>] [--revise [instructions]] [--review]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Generate a milestone/phase roadmap from requirements or upstream context. Produces `.workflow/roadmap.md` with Milestone > Phase hierarchy ready for maestro-analyze and maestro-plan.
+
+Operation modes:
+- **Create** (default): Build roadmap from requirements or upstream context
+- **Revise** (`--revise`): Modify existing roadmap while preserving completed phase progress
+- **Review** (`--review`): Health assessment of current roadmap (read-only)
+
+For formal specification documents (Product Brief, PRD, Architecture, Epics), use `/maestro-blueprint` instead.
+</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:**
+- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
+- `-c` / `--continue`: Resume from last checkpoint
+- `-m progressive|direct|auto`: Decomposition strategy (default: 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`
+
+**Pipeline position:**
+```
+maestro-brainstorm ─┐
+maestro-blueprint  ─┤ (optional upstream, parallel)
+maestro-analyze    ─┘ context-package.json
+        ↓
+maestro-roadmap → .workflow/roadmap.md (Milestone > Phase hierarchy)
+        ↓
+maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
+```
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for phase decomposition — ensures roadmap respects documented decisions and boundaries.
+2. Optional — proceed without if unavailable.
+</context>
+
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c/--continue`, or input is already specific (clear requirement + mode).
+
+- One decision per turn via ask_user with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
+- Never ask what code can verify — resolve via `state.json`, existing `roadmap.md`, `project.md`, or `maestro spec load`.
+- Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
+- Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
+
+Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
+
+Exit: on consensus or `Proceed now`, append the table below to a `Roadmap Decisions` section at the top of `.workflow/roadmap.md`:
+`| # | Decision | Choice | Source (user / code / default) |`
+</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
+
+### Next-step routing on completion
+
+| 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 |
+</execution>
+
+<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/.agents/skills/maestro-tools-execute/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: maestro-tools-execute
+description: Load and execute tool specs by category or name
+argument-hint: "[<tool-name> | --category <category>] [--list]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - ask_user
+  - delegate_subagent
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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 ask_user 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
+
+Ask user:
+- Execute steps as-is?
+- Adjust parameters/scope?
+- View only, do not execute?
+
+### 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 → ask_user 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>

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

@@ -0,0 +1,159 @@
+---
+name: maestro-tools-register
+description: Register tool specs - extract, generate, or optimize
+argument-hint: "[<description>] [--extract <path>] [--optimize <name>]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - ask_user
+  - delegate_subagent
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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 ask_user
+
+### 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 ask_user
+
+**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 wiki list --keyword <name>` 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>" \
+  --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>