maestro-flow 0.3.44 → 0.3.46

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

@@ -1,144 +1,171 @@
----
-name: maestro-tools-register
-description: Register tool specs - extract, generate, or optimize reusable process definitions
-argument-hint: "[description or intent]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
----
-
-<purpose>
-Codify reusable business processes as tool specs into `.workflow/specs/tools.md`. Once registered, entries are auto-discovered by downstream agents via `spec load --role` and spec-injector — plan agents pick up design/architecture flows, test agents pick up verification methods, implement agents pick up execution steps.
-
-Three modes:
-
-1. **Extract** — Pull reusable processes from conversations/code/docs
-2. **Generate** — Create new tool definitions from user description
-3. **Optimize** — Improve existing tool spec steps, structure, clarity
-
-Short processes (<10 steps) inline; long processes (>=10 steps or with code examples) use ref mode with knowhow detail doc (RCP-/DOC-).
-</purpose>
-
-<context>
-$ARGUMENTS — User intent description, or empty (interactive guidance)
-
-```bash
-$maestro-tools-register "extract OAuth PKCE token exchange flow from src/auth/"
-$maestro-tools-register "generate Stripe webhook idempotency verification --roles implement,test"
-$maestro-tools-register "generate E2E checkout flow with payment gateway mock setup --roles test"
-$maestro-tools-register "optimize e2e-checkout tool"
-```
-
-**Tool spec storage**: `.workflow/specs/tools.md`, format:
-```xml
-<spec-entry roles="implement,test" keywords="testing,api" date="YYYY-MM-DD">
-### Tool Name
-Step content...
-</spec-entry>
-```
-
-**Ref mode** (long processes):
-```xml
-<spec-entry roles="implement" keywords="deploy,pipeline" date="YYYY-MM-DD"
-  ref="knowhow/RCP-deploy-flow.md">
-### Deploy Flow
-Standard deployment process. See referenced document.
-</spec-entry>
-```
-</context>
-
-<execution>
-
-### Step 1: Intent Detection
-
-Parse $ARGUMENTS to determine mode:
-- Contains "extract" → extract mode
-- Contains "optimize/improve" → optimize 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 --role implement --keyword <name>`
-- Analyze improvement points (step splitting, prerequisites, error handling)
-
-**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 Roles
-
-Infer applicable roles from context, or ask user:
-- implement — execution tools (build, deploy, integrate)
-- test — testing tools (test flows, verification steps)
-- review — review tools (checklists, audit standards)
-- plan — planning tools (design flows, analysis steps)
-- analyze — analysis tools (diagnostic flows, investigation steps)
-
-### 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 ...
-```
-
-**Inline mode**:
-```bash
-maestro spec add tools "<title>" "Use when <timing>.\n\n1. <step1>\n2. <step2>" --roles "<csv>" --keywords "<csv>"
-```
-
-**Ref mode**:
-1. Generate knowhow detail document (RCP- or DOC- prefix). YAML frontmatter must include `summary` with usage timing — this is what `wiki list` and wiki-role-loader show to agents:
-```yaml
----
-title: <Title>
-type: recipe
-category: recipe
-summary: "Use when <timing>. <scope description>"
-tags: [<keywords>]
-roles: [<roles>]
----
-```
-2. Register spec index entry — description must also include usage timing within 200 chars (this is what `spec load` shows):
-```bash
-maestro spec add tools "<title>" "Use when <timing>. <scope summary>" --roles "<csv>" --keywords "<csv>" \
-  --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
-```
-
-### Step 6: Verify
-
-- `maestro spec load --role <role> --keyword <keyword>` to confirm loadable
-- Display result: title, roles, 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 | roles parameter empty — tools must declare applicable roles |
-</error_codes>
-
-<success_criteria>
-- [ ] Tool definition written to tools.md (or ref to knowhow)
-- [ ] roles attribute correctly set
-- [ ] keywords auto-extracted (3-5 terms)
-- [ ] Loadable via `spec load --role <role>`
-- [ ] Long processes use ref mode with knowhow file created
-</success_criteria>
+---
+name: maestro-tools-register
+description: Register tool specs - extract, generate, or optimize reusable process definitions
+argument-hint: "[description or intent]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+---
+
+<purpose>
+Codify reusable business processes as knowhow documents with `tool: true` in YAML frontmatter. Once registered, entries are auto-discovered by downstream agents via `spec load --category` — plan agents pick up design/architecture flows, test agents pick up verification methods, coding agents pick up execution steps.
+
+Four modes:
+
+1. **Extract** — Pull reusable processes from conversations/code/docs
+2. **Generate** — Create new tool definitions from user description
+3. **Optimize** — Improve existing tool spec steps, structure, clarity
+4. **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-).
+</purpose>
+
+<context>
+$ARGUMENTS — User intent description, or empty (interactive guidance)
+
+```bash
+$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"
+```
+
+**Tool registration**: Creates knowhow documents in `knowhow/` folder with `tool: true` in YAML frontmatter. Tools are auto-discovered by `spec load` based on category + tool flag.
+
+**Knowhow format**:
+```yaml
+---
+title: Tool Name
+type: recipe
+category: coding
+summary: "Use when <timing>. <scope description>"
+tags: [testing, api]
+tool: true
+---
+Step content...
+```
+</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 ...
+```
+
+**Inline mode**:
+Create a knowhow document in `knowhow/` with `tool: true` frontmatter:
+```yaml
+---
+title: <Title>
+type: recipe
+category: <category>
+summary: "Use when <timing>. <scope description>"
+tags: [<keywords>]
+tool: true
+---
+Use when <timing>.
+
+1. <step1>
+2. <step2>
+```
+
+**Ref mode**:
+1. Generate knowhow detail document (RCP- or DOC- prefix). YAML frontmatter must include `summary` with usage timing and `tool: true`:
+```yaml
+---
+title: <Title>
+type: recipe
+category: <category>
+summary: "Use when <timing>. <scope description>"
+tags: [<keywords>]
+tool: true
+---
+```
+
+### 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 applicable category |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool registered as knowhow document with `tool: true` frontmatter
+- [ ] category attribute correctly set
+- [ ] keywords auto-extracted (3-5 terms)
+- [ ] Loadable via `spec load --category <category>`
+- [ ] Long processes use ref mode with knowhow file created
+</success_criteria>

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -361,7 +361,7 @@ Open preview:
   file://{absolute_path}/preview.html
 
 Next steps:
-  maestro wiki list --role implement    # Browse by role
+  maestro wiki list --category coding    # Browse by role
   maestro spec load --keyword {package_name}    # Load related specs
 ```
 

package/.codex/skills/maestro-verify/SKILL.md

@@ -226,7 +226,7 @@ If exit code is 1, present warnings and ask whether to proceed.
    - Wave 2: artifact/substance + wiring (need existence confirmation from wave 1)
    - Wave 3: antipattern + nyquist (need substance/wiring context from wave 2)
 
-7. **Specs loading**: `specs_content = maestro spec load --role review`
+7. **Specs loading**: `specs_content = maestro spec load --category review`
 
 8. **CSV generation**: One row per check task.
 

package/.codex/skills/manage-issue-discover/SKILL.md

@@ -225,7 +225,7 @@ Initialize `discovery-state.json`:
 4. Store dimensions in `{discoveryDir}/exploration-plan.json`
 5. Generate N dimension rows (wave 1) + 1 dedup row (wave 2)
 
-**Specs loading**: `specs_content = maestro spec load --role implement` -- pass to agents for severity calibration.
+**Specs loading**: `specs_content = maestro spec load --category coding` -- pass to agents for severity calibration.
 
 **User validation**: Display perspective/dimension breakdown (skip if AUTO_YES).
 

package/.codex/skills/manage-knowhow-capture/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>
-Capture reusable knowledge into `.workflow/knowhow/`. Six content types: `session` (full session recovery), `template` (code/config pattern), `recipe` (step-by-step guide), `reference` (external doc summary), `decision` (ADR), `tip` (quick note). Auto-detects type or asks user.
+Capture reusable knowledge into `.workflow/knowhow/`. Nine content types: `session` (full session recovery), `template` (code/config pattern), `recipe` (step-by-step guide), `reference` (external doc summary), `decision` (ADR), `tip` (quick note), `asset` (API contract, data model, etc.), `blueprint` (architecture design with code paths), `document` (general long-form). Auto-detects type or asks user.
 </purpose>
 
 <context>
@@ -22,13 +22,16 @@ $manage-knowhow-capture "reference Stripe API --source https://docs.stripe.com/a
 $manage-knowhow-capture "decision Use PostgreSQL over MongoDB --status accepted"
 ```
 
-**Types**: `compact` | `template` | `recipe` | `reference` | `decision` | `tip`
+**Types**: `compact` | `template` | `recipe` | `reference` | `decision` | `tip` | `asset` | `blueprint` | `document`
 
 **Flags**:
 - `--lang <lang>` — Language for templates (typescript, python, bash, yaml, ...)
 - `--source <url>` — Source URL for references
 - `--tag tag1,tag2` — Categorization tags
 - `--title <title>` — Explicit title
+- `--asset-type <type>` — Asset subtype (api-contract, data-model, prompt, config, ...)
+- `--code-paths <paths>` — Related source paths for asset/blueprint (comma-separated)
+- `--category <cat>` — Spec category for agent discovery (coding, arch, test, debug, review, learning)
 </context>
 
 <execution>
@@ -49,6 +52,9 @@ Parse first token as type. If absent or ambiguous, ask user via AskUserQuestion.
 | `reference`, `ref`, `参考` | reference |
 | `decision`, `dcs`, `决策` | decision |
 | `tip`, `note`, `记录` | tip |
+| `asset`, `ast`, `资产`, `契约` | asset |
+| `blueprint`, `blp`, `蓝图` | blueprint |
+| `document`, `doc`, `文档` | document |
 
 ### Step 3: Capture Content by Type
 
@@ -70,6 +76,15 @@ Prompt for or extract: context, decision, alternatives (at least 2), rationale,
 **tip** (TIP-{YYYYMMDD}-{HHMM}.md):
 Content from remaining arguments. Auto-detect context from recent conversation files. Sections: Content, Context, Tags, Timestamp.
 
+**asset** (AST-{YYYYMMDD}-{HHMM}.md):
+Prompt for or extract: asset subtype (`--asset-type`), related code paths (`--code-paths`), category (`--category`). Sections: Overview, Structure (tables/schemas), Usage, Related Code Paths. Common asset subtypes: `api-contract`, `data-model`, `prompt`, `config`, `ui-prototype`.
+
+**blueprint** (BLP-{YYYYMMDD}-{HHMM}.md):
+Prompt for or extract: system scope, code paths (`--code-paths`), category (`--category`). Sections: Overview, Components, Interactions, Code Paths, Constraints, Trade-offs.
+
+**document** (DOC-{YYYYMMDD}-{HHMM}.md):
+General long-form fallback. No specific structure enforced.
+
 ### Step 4: Write File
 
 Write to `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter:
@@ -82,7 +97,7 @@ category: {type}
 created: {ISO timestamp}
 tags: [{tags}]
 ```
-Plus type-specific: `lang` (template), `source` (reference), `status` (decision).
+Plus type-specific: `lang` (template), `source` (reference), `status` (decision), `assetType` + `codePaths` (asset), `codePaths` (blueprint). `category` written when `--category` provided.
 
 ### Step 5: Confirm
 

package/.codex/skills/quality-auto-test/SKILL.md

@@ -208,8 +208,8 @@ mkdir -p {sessionFolder}
 Resolve phase dir from `state.json` artifact registry (`type='execute'`, matching phase). Error E002 if not found.
 
 ```
-specs_test = maestro spec load --role test
-specs_arch = maestro spec load --role plan
+specs_test = maestro spec load --category test
+specs_arch = maestro spec load --category arch
 ```
 
 #### Step 1: Read State & Route

package/.codex/skills/quality-debug/SKILL.md

@@ -184,7 +184,8 @@ mkdir -p {sessionFolder}
 2b. **Load codebase + wiki context** (optional, informs hypothesis generation):
    - If `.workflow/codebase/ARCHITECTURE.md` exists: read module boundaries to scope impact analysis
    - Run `maestro wiki search "<symptom keywords>" --json 2>/dev/null`; if results: check for prior investigations on similar issues
-   - Both are optional — proceed without if unavailable
+   - Run `maestro spec load --category debug --keyword "<symptom keywords>"`; if tools found: extract known issues, workarounds, and root-cause notes to inform hypotheses
+   - All are optional — proceed without if unavailable
 
 3. **Symptom collection**:
 

package/.codex/skills/quality-refactor/SKILL.md

@@ -60,7 +60,7 @@ Create `.workflow/scratch/refactor-{slug}-{date}/` with `.task/` and `.summaries
 
 ### Step 3: Scope Analysis
 
-Load project specs if available (`maestro spec load --role implement`).
+Load project specs if available (`maestro spec load --category coding`).
 
 Analyze scope for tech debt categories:
 

package/.codex/skills/quality-review/SKILL.md

@@ -184,7 +184,7 @@ Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
 
 If `--dimensions` flag provided, override with explicit list.
 
-6. **Specs loading**: Read `.workflow/specs/` for project conventions (unless `--skip-specs`)
+6. **Specs loading**: Run `maestro spec load --category review` to load review standards, checklists, AND discoverable knowhow tools (unless `--skip-specs`)
 7. **CSV generation**: One row per dimension + one aggregation row
 
 **Wave computation**: Simple 2-wave -- all dimension tasks = wave 1, aggregation = wave 2.

package/.codex/skills/quality-test/SKILL.md

@@ -163,7 +163,17 @@ Record in `uat.md` under `## Smoke Tests`. If any fails: **E003** — abort, sug
 
 Read from target directory: `verification.json`, `validation.json`, `index.json`, `plan.json`, `.summaries/TASK-*.md`. Build testable list from user-observable outcomes.
 
-### Step 4.5: Load Quality Context (Cross-Artifact Integration)
+### Step 4.5: Load Test Tools (Knowhow Discovery)
+
+Load registered test tools to supplement verification-based scenarios:
+
+```bash
+maestro spec load --category test --keyword <feature>
+```
+
+If tools are found, extract their steps as additional test scenarios marked `source: "tool"`. Tool steps map to UAT scenarios: each numbered step becomes a test with its assertion as `expected` behavior. This enables tools registered via `/maestro-tools-register` to drive UAT verification.
+
+### Step 4.6: Load Quality Context (Cross-Artifact Integration)
 
 Query `state.json.artifacts[]` for all artifacts matching current phase and milestone: