maestro-flow 0.3.44 → 0.3.45

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

@@ -1,144 +1,149 @@
----
-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.
+
+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"
+$maestro-tools-register "generate E2E checkout flow with payment gateway mock setup"
+$maestro-tools-register "optimize e2e-checkout 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
+- 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)
+
+**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
+
+Infer applicable category from context, or ask user:
+- coding — execution tools (build, deploy, integrate)
+- test — testing tools (test flows, verification steps)
+- review — review tools (checklists, audit standards)
+- arch — planning tools (design flows, analysis steps)
+- debug — 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**:
+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/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-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/spec-add/SKILL.md

@@ -1,114 +1,104 @@
----
-name: spec-add
-description: Add spec entry by category with role tagging
-argument-hint: "<category> <content> [--roles <csv>]"
-allowed-tools: Read, Write, Bash, Glob, Grep
----
-
-<purpose>
-Add a spec entry using `<spec-entry>` closed-tag format. Each category maps 1:1 to a single target file.
-
-```bash
-$spec-add "coding Always use named exports for utility functions"
-$spec-add "learning Off-by-one in pagination when page=0"
-$spec-add "arch Use Zod for runtime validation over io-ts"
-$spec-add "quality All API endpoints must return structured error objects"
-```
-
-**Valid categories**: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation.
-
-**CLI alternative**: `maestro spec add <category> "<title>" "<content>" --keywords kw1,kw2 --roles implement,test --source <src>`. Used by workflow agents (analyze, plan, execute) for programmatic spec enrichment.
-</purpose>
-
-<context>
-$ARGUMENTS — `<category> <content>` where category selects the target file.
-
-**Category-to-file mapping (1:1, same as spec-load):**
-| Category | Target file |
-|----------|------------|
-| `coding` | `coding-conventions.md` |
-| `arch` | `architecture-constraints.md` |
-| `quality` | `quality-rules.md` |
-| `debug` | `debug-notes.md` |
-| `test` | `test-conventions.md` |
-| `review` | `review-standards.md` |
-| `learning` | `learnings.md` |
-| `tools` | `tools.md` |
-| `bug` | `learnings.md` |
-| `pattern` | `coding-conventions.md` |
-| `decision` | `architecture-constraints.md` |
-| `rule` | `quality-rules.md` |
-| `validation` | `quality-rules.md` |
-
-Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
-
-**--roles option**: When `--roles` is provided, the entry uses `roles` attr instead of `category` attr. This declares which agent roles should load this entry via `spec load --role`.
-</context>
-
-<execution>
-
-### Step 1: Parse Input
-
-Extract category (first token) and content (remainder) from arguments.
-- Validate category is one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation (E003 if invalid)
-- Validate content is non-empty (E001 if missing)
-
-### Step 2: Validate Specs Directory
-
-Verify `.workflow/specs/` exists (E002).
-
-### Step 3: Route to File
-
-Resolve target file from category-to-file mapping table. If the target file does not exist, create it with a basic header.
-
-### Step 4: Extract Keywords
-
-Auto-extract 3-5 relevant keywords from the content. Keywords should be:
-- Lowercase, no spaces (use hyphens for multi-word)
-- Domain-specific terms that would help future lookup
-- Avoid generic words (code, file, function, etc.)
-
-### Step 5: Write Entry
-
-Append `<spec-entry>` closed-tag block to target file:
-
-```markdown
-<!-- With --roles (new format): -->
-<spec-entry roles="{role1},{role2}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
-
-### {title extracted from content}
-
-{content}
-
-</spec-entry>
-
-<!-- Without --roles (legacy format): -->
-<spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
-
-### {title extracted from content}
-
-{content}
-
-</spec-entry>
-```
-
-### Step 6: Confirm
-
-Display: category, target file, extracted keywords, and commands for verify (`/spec-load`) and remove (`/spec-remove`).
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | Category and content are both required |
-| E002 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation |
-</error_codes>
-
-<success_criteria>
-- [ ] Category and content parsed and validated
-- [ ] Keywords auto-extracted from content (3-5 terms)
-- [ ] Entry written in `<spec-entry>` closed-tag format with keywords attribute
-- [ ] Entry appended to correct target file
-- [ ] Confirmation displayed with keywords and verify command
-</success_criteria>
+---
+name: spec-add
+description: Add spec entry by category with role tagging
+argument-hint: "<category> <content>"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<purpose>
+Add a spec entry using `<spec-entry>` closed-tag format. Each category maps 1:1 to a single target file.
+
+```bash
+$spec-add "coding Always use named exports for utility functions"
+$spec-add "learning Off-by-one in pagination when page=0"
+$spec-add "arch Use Zod for runtime validation over io-ts"
+$spec-add "quality All API endpoints must return structured error objects"
+```
+
+**Valid categories**: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation.
+
+**CLI alternative**: `maestro spec add <category> "<title>" "<content>" --keywords kw1,kw2 --source <src>`. Used by workflow agents (analyze, plan, execute) for programmatic spec enrichment.
+</purpose>
+
+<context>
+$ARGUMENTS — `<category> <content>` where category selects the target file.
+
+**Category-to-file mapping (1:1, same as spec-load):**
+| Category | Target file |
+|----------|------------|
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
+| `tools` | `tools.md` |
+| `bug` | `learnings.md` |
+| `pattern` | `coding-conventions.md` |
+| `decision` | `architecture-constraints.md` |
+| `rule` | `quality-rules.md` |
+| `validation` | `quality-rules.md` |
+
+Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
+
+Category is determined by the first positional argument.
+</context>
+
+<execution>
+
+### Step 1: Parse Input
+
+Extract category (first token) and content (remainder) from arguments.
+- Validate category is one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation (E003 if invalid)
+- Validate content is non-empty (E001 if missing)
+
+### Step 2: Validate Specs Directory
+
+Verify `.workflow/specs/` exists (E002).
+
+### Step 3: Route to File
+
+Resolve target file from category-to-file mapping table. If the target file does not exist, create it with a basic header.
+
+### Step 4: Extract Keywords
+
+Auto-extract 3-5 relevant keywords from the content. Keywords should be:
+- Lowercase, no spaces (use hyphens for multi-word)
+- Domain-specific terms that would help future lookup
+- Avoid generic words (code, file, function, etc.)
+
+### Step 5: Write Entry
+
+Append `<spec-entry>` closed-tag block to target file:
+
+```markdown
+<spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
+
+### {title extracted from content}
+
+{content}
+
+</spec-entry>
+```
+
+### Step 6: Confirm
+
+Display: category, target file, extracted keywords, and commands for verify (`/spec-load`) and remove (`/spec-remove`).
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | Category and content are both required |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation |
+</error_codes>
+
+<success_criteria>
+- [ ] Category and content parsed and validated
+- [ ] Keywords auto-extracted from content (3-5 terms)
+- [ ] Entry written in `<spec-entry>` closed-tag format with keywords attribute
+- [ ] Entry appended to correct target file
+- [ ] Confirmation displayed with keywords and verify command
+</success_criteria>