maestro-flow 0.3.38 → 0.3.40

package/.codex/skills/spec-add/SKILL.md

@@ -1,101 +1,101 @@
----
-name: spec-add
-description: Add a spec entry to the appropriate specs file by category
-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, 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` |
-| `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.
-</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>
+---
+name: spec-add
+description: Add spec entry by category
+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, 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` |
+| `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.
+</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>

package/.codex/skills/spec-load/SKILL.md

@@ -1,77 +1,77 @@
----
-name: spec-load
-description: Load relevant specs for current context, optionally filtered by category or keyword
-argument-hint: "[--category <type>] [--keyword <word>]"
-allowed-tools: Read, Bash, Glob, Grep
----
-
-<purpose>
-Load relevant specs filtered by category (file-level) and/or keyword (entry-level via `<spec-entry>` tags).
-</purpose>
-
-<context>
-$ARGUMENTS — optional category filter and keyword.
-
-```bash
-$spec-load
-$spec-load "--category coding"
-$spec-load "--keyword auth"
-$spec-load "--category coding --keyword naming"
-```
-
-**Category-to-file mapping (1:1, same as spec-add):**
-
-| Category | File loaded |
-|----------|------------|
-| `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` |
-| `bug` | `learnings.md` |
-| `pattern` | `coding-conventions.md` |
-| `decision` | `architecture-constraints.md` |
-| `rule` | `quality-rules.md` |
-| `validation` | `quality-rules.md` |
-| `all` (default) | All spec files |
-
-Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in their closest core category's file but retain their specific category in the `<spec-entry>` tag.
-
-**Keyword filtering**: When `--keyword` is provided, only entries with matching keyword in their `<spec-entry keywords="...">` attribute are returned. Legacy entries (heading format) are filtered by text grep.
-</context>
-
-<execution>
-
-### Step 1: Validate Specs Directory
-
-Verify `.workflow/specs/` exists (E001).
-
-### Step 2: Parse Arguments
-
-Extract optional `--category` and `--keyword` flags.
-
-### Step 3: Load via CLI
-
-Run `maestro spec load [--category <cat>] [--keyword <word>]`. If CLI unavailable, read files directly and apply keyword filter.
-
-### Step 4: Display Results
-
-Show matched entries grouped by filename and category, with `<spec-entry>` tags stripped.
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
-| W001 | warning | No matching specs for keyword -- showing all in category |
-</error_codes>
-
-<success_criteria>
-- [ ] `.workflow/specs/` directory validated
-- [ ] Category and keyword parsed from arguments
-- [ ] Files loaded per category mapping
-- [ ] Keyword filtering applied at entry level (via `<spec-entry>` keywords)
-- [ ] Results displayed with file references and stripped tags
-</success_criteria>
+---
+name: spec-load
+description: Load specs and lessons for current context
+argument-hint: "[--category <type>] [--keyword <word>]"
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+<purpose>
+Load relevant specs filtered by category (file-level) and/or keyword (entry-level via `<spec-entry>` tags).
+</purpose>
+
+<context>
+$ARGUMENTS — optional category filter and keyword.
+
+```bash
+$spec-load
+$spec-load "--category coding"
+$spec-load "--keyword auth"
+$spec-load "--category coding --keyword naming"
+```
+
+**Category-to-file mapping (1:1, same as spec-add):**
+
+| Category | File loaded |
+|----------|------------|
+| `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` |
+| `bug` | `learnings.md` |
+| `pattern` | `coding-conventions.md` |
+| `decision` | `architecture-constraints.md` |
+| `rule` | `quality-rules.md` |
+| `validation` | `quality-rules.md` |
+| `all` (default) | All spec files |
+
+Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in their closest core category's file but retain their specific category in the `<spec-entry>` tag.
+
+**Keyword filtering**: When `--keyword` is provided, only entries with matching keyword in their `<spec-entry keywords="...">` attribute are returned. Legacy entries (heading format) are filtered by text grep.
+</context>
+
+<execution>
+
+### Step 1: Validate Specs Directory
+
+Verify `.workflow/specs/` exists (E001).
+
+### Step 2: Parse Arguments
+
+Extract optional `--category` and `--keyword` flags.
+
+### Step 3: Load via CLI
+
+Run `maestro spec load [--category <cat>] [--keyword <word>]`. If CLI unavailable, read files directly and apply keyword filter.
+
+### Step 4: Display Results
+
+Show matched entries grouped by filename and category, with `<spec-entry>` tags stripped.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
+| W001 | warning | No matching specs for keyword -- showing all in category |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/specs/` directory validated
+- [ ] Category and keyword parsed from arguments
+- [ ] Files loaded per category mapping
+- [ ] Keyword filtering applied at entry level (via `<spec-entry>` keywords)
+- [ ] Results displayed with file references and stripped tags
+</success_criteria>

package/.codex/skills/spec-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-map
-description: Analyze codebase with 4 parallel mapper agents via CSV wave pipeline. Produces .workflow/codebase/ documents for tech-stack, architecture, features, and cross-cutting concerns.
+description: Map codebase tech-stack, architecture, features, and concerns
 argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"[focus area]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---

package/.codex/skills/spec-remove/SKILL.md

@@ -1,69 +1,69 @@
----
-name: spec-remove
-description: Remove a spec entry from a specs file by entry ID using maestro wiki remove-entry
-argument-hint: "<entry-id>"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Remove a `<spec-entry>` block from a specs container file. Symmetric with `spec-add`.
-Uses `maestro wiki remove-entry` for atomic removal with automatic index update.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-remove.md
-</required_reading>
-
-<context>
-$ARGUMENTS — entry ID to remove (e.g., `spec-learnings-003`)
-
-**Entry ID format**: `spec-{file-stem}-{NNN}` — sub-node ID from WikiIndexer atomic indexing.
-
-**Discovery**:
-- `maestro wiki list --type spec --json` — list all spec entries
-- `/spec-load --keyword <term>` — find by keyword
-- `maestro wiki search "<query>"` — BM25 search
-</context>
-
-<execution>
-
-### Step 1: Parse Input
-
-Extract entry ID from arguments.
-- Validate non-empty (E001 if missing)
-- Validate `.workflow/specs/` exists (E002 if not)
-
-### Step 2: Lookup Entry
-
-Run `maestro wiki get <entry-id> --json`. Validate: entry exists (E003), is spec sub-node with `type="spec"` and `parent` set (E004). Extract title, category, keywords, container path.
-
-### Step 3: Confirm
-
-Display entry details. Ask user to confirm unless `-y` flag present.
-
-### Step 4: Remove
-
-Run `maestro wiki remove-entry <entry-id>`. WikiIndexer auto-updates `wiki-index.json`.
-
-### Step 5: Verify & Report
-
-Confirm removal via `maestro wiki get <entry-id>` (should return not-found). Display removed ID, source file, and commands for verify/re-add.
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` |
-| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first |
-| E003 | fatal | Entry ID not found in wiki index |
-| E004 | fatal | Entry is not a spec sub-node (wrong type or no parent) |
-</error_codes>
-
-<success_criteria>
-- [ ] Entry ID parsed and validated
-- [ ] Entry found in wiki index (type=spec, has parent)
-- [ ] User confirmed removal
-- [ ] Entry removed via `maestro wiki remove-entry`
-- [ ] Wiki index auto-updated
-- [ ] Confirmation displayed
-</success_criteria>
+---
+name: spec-remove
+description: Remove spec entry by ID
+argument-hint: "<entry-id>"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Remove a `<spec-entry>` block from a specs container file. Symmetric with `spec-add`.
+Uses `maestro wiki remove-entry` for atomic removal with automatic index update.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-remove.md
+</required_reading>
+
+<context>
+$ARGUMENTS — entry ID to remove (e.g., `spec-learnings-003`)
+
+**Entry ID format**: `spec-{file-stem}-{NNN}` — sub-node ID from WikiIndexer atomic indexing.
+
+**Discovery**:
+- `maestro wiki list --type spec --json` — list all spec entries
+- `/spec-load --keyword <term>` — find by keyword
+- `maestro wiki search "<query>"` — BM25 search
+</context>
+
+<execution>
+
+### Step 1: Parse Input
+
+Extract entry ID from arguments.
+- Validate non-empty (E001 if missing)
+- Validate `.workflow/specs/` exists (E002 if not)
+
+### Step 2: Lookup Entry
+
+Run `maestro wiki get <entry-id> --json`. Validate: entry exists (E003), is spec sub-node with `type="spec"` and `parent` set (E004). Extract title, category, keywords, container path.
+
+### Step 3: Confirm
+
+Display entry details. Ask user to confirm unless `-y` flag present.
+
+### Step 4: Remove
+
+Run `maestro wiki remove-entry <entry-id>`. WikiIndexer auto-updates `wiki-index.json`.
+
+### Step 5: Verify & Report
+
+Confirm removal via `maestro wiki get <entry-id>` (should return not-found). Display removed ID, source file, and commands for verify/re-add.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first |
+| E003 | fatal | Entry ID not found in wiki index |
+| E004 | fatal | Entry is not a spec sub-node (wrong type or no parent) |
+</error_codes>
+
+<success_criteria>
+- [ ] Entry ID parsed and validated
+- [ ] Entry found in wiki index (type=spec, has parent)
+- [ ] User confirmed removal
+- [ ] Entry removed via `maestro wiki remove-entry`
+- [ ] Wiki index auto-updated
+- [ ] Confirmation displayed
+</success_criteria>

package/.codex/skills/spec-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-setup
-description: Initialize project specs by scanning codebase for conventions and tech stack
+description: Initialize specs from project structure
 argument-hint: ""
 allowed-tools: Read, Write, Bash, Glob, Grep
 ---

package/.codex/skills/team-coordinate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: team-coordinate
-description: Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on "Team Coordinate ".
+description: Universal team coordination with dynamic role generation
 allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__maestro-tools__team_msg(*)
 ---
 
@@ -27,6 +27,7 @@ Universal team coordination skill: analyze task -> generate role-specs -> dispat
     maestro delegate --mode analysis  - analysis and exploration
     maestro delegate --mode write     - code generation and modification
 ```
+
 </purpose>
 
 <context>