Storage architecture: knowhow/ is the single source of truth for tool content. Spec index entries (specs/) serve only as discovery pointers — they reference knowhow documents via ref: links but never store tool steps directly. Downstream agents discover tools via maestro search or maestro load --type knowhow --keyword <name>, with spec index providing category-based routing.

Four modes:

Extract — Pull reusable processes from conversations/code/docs
Generate — Create new tool definitions from user description
Optimize — Improve existing tool spec steps, structure, clarity
Promote — Convert existing knowhow document to tool (add tool: true + category in place)

Short processes (<10 steps) inline; long processes (>=10 steps or with code examples) use ref mode with knowhow detail doc (RCP-/DOC-).

maestro-tools-register