maestro-tools-register

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

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

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>