maestro-flow 0.3.37 → 0.3.39

package/.claude/commands/wiki-connect.md

@@ -1,62 +1,62 @@
----
-name: wiki-connect
-description: Surface hidden connections in the wiki knowledge graph and suggest or apply new links
-argument-hint: "[--scope <type>] [--min-similarity N] [--fix] [--max N]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<required_reading>
-@~/.maestro/workflows/wiki-connect.md
-</required_reading>
-
-<purpose>
-Knowledge graph link discovery and health improvement. Analyzes the wiki index to find orphaned entries, missing connections, and transitive link gaps, then suggests or auto-applies new `related` links to improve graph connectivity.
-
-Leverages maestro's unique wiki graph infrastructure (BM25 search, backlinks, health scoring) — no equivalent in gstack. Directly improves the quality of all downstream wiki consumers (search, digest, follow-along).
-</purpose>
-
-<context>
-Arguments: $ARGUMENTS
-
-Flags, storage paths, and CLI commands defined in workflow wiki-connect.md.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
-
-**Next-step routing:**
-- Generate knowledge digest → `/wiki-digest <topic>`
-- Follow-along on orphan → `/learn-follow <wiki-id>`
-- View full graph → `maestro wiki graph`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No wiki entries found (empty index) | Initialize wiki content first, or run `/maestro-init` |
-| E002 | error | `maestro wiki` CLI not available | Check maestro installation |
-| W001 | warning | No connection candidates found above threshold | Lower --min-similarity or check if graph is already well-connected |
-| W002 | warning | Some wiki update calls failed during --fix | Partial application; retry failed entries manually |
-| W003 | warning | Health score unchanged after fix | Connections may not have improved the specific health metrics |
-</error_codes>
-
-<success_criteria>
-- [ ] Wiki index loaded with entry count and type distribution
-- [ ] Baseline health score recorded
-- [ ] Orphans identified and rescue candidates generated
-- [ ] Connection candidates scored and ranked
-- [ ] Results filtered by --min-similarity and limited by --max
-- [ ] Suggestions displayed with scores and reasons
-- [ ] If --fix: entries updated with new `related` links
-- [ ] If --fix: new health score computed and delta reported
-- [ ] Report written to `wiki-connections-{date}.md`
-- [ ] Graph insights appended to `lessons.jsonl`
-- [ ] No unintended entry modifications (only `related` field changed)
-- [ ] Summary displayed with next-step routing
-</success_criteria>
+---
+name: wiki-connect
+description: Find and link hidden connections in wiki graph
+argument-hint: "[--scope <type>] [--min-similarity N] [--fix] [--max N]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<required_reading>
+@~/.maestro/workflows/wiki-connect.md
+</required_reading>
+
+<purpose>
+Knowledge graph link discovery and health improvement. Analyzes the wiki index to find orphaned entries, missing connections, and transitive link gaps, then suggests or auto-applies new `related` links to improve graph connectivity.
+
+Leverages maestro's unique wiki graph infrastructure (BM25 search, backlinks, health scoring) — no equivalent in gstack. Directly improves the quality of all downstream wiki consumers (search, digest, follow-along).
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags, storage paths, and CLI commands defined in workflow wiki-connect.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
+
+**Next-step routing:**
+- Generate knowledge digest → `/wiki-digest <topic>`
+- Follow-along on orphan → `/learn-follow <wiki-id>`
+- View full graph → `maestro wiki graph`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first, or run `/maestro-init` |
+| E002 | error | `maestro wiki` CLI not available | Check maestro installation |
+| W001 | warning | No connection candidates found above threshold | Lower --min-similarity or check if graph is already well-connected |
+| W002 | warning | Some wiki update calls failed during --fix | Partial application; retry failed entries manually |
+| W003 | warning | Health score unchanged after fix | Connections may not have improved the specific health metrics |
+</error_codes>
+
+<success_criteria>
+- [ ] Wiki index loaded with entry count and type distribution
+- [ ] Baseline health score recorded
+- [ ] Orphans identified and rescue candidates generated
+- [ ] Connection candidates scored and ranked
+- [ ] Results filtered by --min-similarity and limited by --max
+- [ ] Suggestions displayed with scores and reasons
+- [ ] If --fix: entries updated with new `related` links
+- [ ] If --fix: new health score computed and delta reported
+- [ ] Report written to `wiki-connections-{date}.md`
+- [ ] Graph insights appended to `lessons.jsonl`
+- [ ] No unintended entry modifications (only `related` field changed)
+- [ ] Summary displayed with next-step routing
+</success_criteria>

package/.claude/commands/wiki-digest.md

@@ -1,69 +1,69 @@
----
-name: wiki-digest
-description: Generate knowledge digest from wiki entries with theme clustering, gap analysis, and coverage heatmap
-argument-hint: "[<topic>|--recent N] [--type <type>] [--format brief|full]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Knowledge synthesis command that generates actionable digests from the wiki knowledge graph. Clusters entries by semantic theme, identifies knowledge gaps, and produces a coverage heatmap. Unique to maestro — leverages the wiki graph (BM25 search, backlinks, health) to surface trends and missing knowledge.
-
-Unlike `maestro wiki list` which shows raw entries, this command synthesizes and interprets the knowledge base, producing a curated summary with gap analysis and recommended next actions.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/wiki-digest.md
-</required_reading>
-
-<deferred_reading>
-- @~/.maestro/workflows/issue.md (issues.jsonl canonical schema for `--create-issues` routing)
-</deferred_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-Flags, scope resolution, storage paths, and CLI commands defined in workflow wiki-digest.md.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
-
-**Next-step routing:**
-- Deep dive on a theme → `/learn-follow <wiki-id>`
-- Fix graph gaps → `/wiki-connect --fix`
-- Decompose code for missing patterns → `/learn-decompose <path>`
-- Create missing entries → `maestro wiki create --type <type> --slug <slug>`
-- Triage gap issues → `/manage-issue list --source wiki-digest`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No wiki entries found (empty index) | Initialize wiki content first |
-| E002 | error | Topic search returned 0 results | Broaden topic or check wiki content |
-| W001 | warning | Too few entries (<5) for meaningful theme clustering | Digest produced but themes may be trivial |
-| W002 | warning | lessons.jsonl not found — skipping cross-reference | Proceed without lesson context |
-| W003 | warning | Some entry bodies failed to load — partial summaries | Note incomplete entries in digest |
-</error_codes>
-
-<success_criteria>
-- [ ] Scope parsed and entries loaded
-- [ ] Baseline health score recorded
-- [ ] Entries clustered into 3-5 semantic themes
-- [ ] Per-theme analysis: summary, key entries, gaps, health
-- [ ] Cross-reference with lessons.jsonl completed
-- [ ] Coverage heatmap generated (type × theme matrix)
-- [ ] Knowledge gaps identified with suggested actions
-- [ ] If `--create-issues`: gap issues created in `issues.jsonl` (deduped)
-- [ ] Digest written to `digest-{slug}-{date}.md`
-- [ ] Meta-insights appended to `lessons.jsonl`
-- [ ] `learning-index.json` updated
-- [ ] No files modified outside `.workflow/learning/` and `.workflow/issues/` (issues only when `--create-issues`)
-- [ ] Summary displayed with key findings and next-step routing
-</success_criteria>
+---
+name: wiki-digest
+description: Generate wiki digest with theme clustering and gap analysis
+argument-hint: "[<topic>|--recent N] [--type <type>] [--format brief|full]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Knowledge synthesis command that generates actionable digests from the wiki knowledge graph. Clusters entries by semantic theme, identifies knowledge gaps, and produces a coverage heatmap. Unique to maestro — leverages the wiki graph (BM25 search, backlinks, health) to surface trends and missing knowledge.
+
+Unlike `maestro wiki list` which shows raw entries, this command synthesizes and interprets the knowledge base, producing a curated summary with gap analysis and recommended next actions.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-digest.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl canonical schema for `--create-issues` routing)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags, scope resolution, storage paths, and CLI commands defined in workflow wiki-digest.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
+
+**Next-step routing:**
+- Deep dive on a theme → `/learn-follow <wiki-id>`
+- Fix graph gaps → `/wiki-connect --fix`
+- Decompose code for missing patterns → `/learn-decompose <path>`
+- Create missing entries → `maestro wiki create --type <type> --slug <slug>`
+- Triage gap issues → `/manage-issue list --source wiki-digest`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first |
+| E002 | error | Topic search returned 0 results | Broaden topic or check wiki content |
+| W001 | warning | Too few entries (<5) for meaningful theme clustering | Digest produced but themes may be trivial |
+| W002 | warning | lessons.jsonl not found — skipping cross-reference | Proceed without lesson context |
+| W003 | warning | Some entry bodies failed to load — partial summaries | Note incomplete entries in digest |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope parsed and entries loaded
+- [ ] Baseline health score recorded
+- [ ] Entries clustered into 3-5 semantic themes
+- [ ] Per-theme analysis: summary, key entries, gaps, health
+- [ ] Cross-reference with lessons.jsonl completed
+- [ ] Coverage heatmap generated (type × theme matrix)
+- [ ] Knowledge gaps identified with suggested actions
+- [ ] If `--create-issues`: gap issues created in `issues.jsonl` (deduped)
+- [ ] Digest written to `digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to `lessons.jsonl`
+- [ ] `learning-index.json` updated
+- [ ] No files modified outside `.workflow/learning/` and `.workflow/issues/` (issues only when `--create-issues`)
+- [ ] Summary displayed with key findings and next-step routing
+</success_criteria>

package/.codex/skills/learn-decompose/SKILL.md

@@ -1,113 +1,113 @@
----
-name: learn-decompose
-description: 4-dimension parallel pattern extraction via CSV wave pipeline. Structural, behavioral, data, and error dimension agents scan in parallel (Wave 1), cross-reference agent deduplicates and catalogs (Wave 2). Outputs pattern catalog to lessons.jsonl.
-argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
-scan a module, then a cross-reference agent deduplicates against existing patterns and
-produces a catalog. Discovered patterns persist to `lessons.jsonl` and optionally to
-specs (via `spec-add`) and wiki.
-
-```
-Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
-```
-</purpose>
-
-<context>
-$ARGUMENTS — target path/module and optional flags.
-
-**Target resolution:**
-- File path → analyze that file
-- Directory path → all source files in it
-- Module name → Glob `src/**/{module}*`
-
-**Flags:**
-- `-y, --yes`: Skip confirmations
-- `-c, --concurrency N`: Max concurrent agents (default: 4)
-- `--continue`: Resume existing session
-- `--patterns <list>`: Comma-separated pattern names to focus on
-- `--save-spec`: Invoke `spec-add` for each new pattern
-- `--save-wiki`: Create wiki note entries per dimension group
-
-**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/learning/decompose-{slug}-{date}.md`
-</context>
-
-<invariants>
-1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
-2. **Evidence required**: Every finding must have file:line anchors
-3. **Dedup before persist**: Cross-reference against existing specs + lessons
-4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
-5. **No files modified outside** `.workflow/learning/` (and optionally specs/wiki)
-</invariants>
-
-<execution>
-
-### Phase 1: Session Init + Target Resolution
-
-Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
-Extract remaining text as target path/module.
-
-Resolve target to file list. Load existing patterns from `coding-conventions.md` + `lessons.jsonl` for dedup set.
-
-### Phase 2: Wave 1 — Parallel Dimension Scans
-
-Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
-
-| id | dimension | focus |
-|----|-----------|-------|
-| 1 | structural | Class hierarchy, composition, DI, factories, exports |
-| 2 | behavioral | Events, middleware, observer, command, state machines |
-| 3 | data | Repository, DTO, caching, serialization, validation |
-| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
-| 5 | cross-ref | Dedup + catalog from wave 1 findings |
-
-Each dimension agent returns:
-```json
-[{
-  "name": "pattern name",
-  "dimension": "structural|behavioral|data|error",
-  "confidence": "high|medium|low",
-  "anchors": ["file:line"],
-  "description": "what it does",
-  "rationale": "why this approach",
-  "tradeoffs": "what was given up"
-}]
-```
-
-### Phase 3: Wave 2 — Cross-Reference + Catalog
-
-Single agent receives all wave 1 findings via `prev_context`. Tasks:
-- Match against dedup set → mark as `documented`, `known`, or `new`
-- Merge duplicates across dimensions (same pattern found by multiple agents)
-- Flag contradictions with documented conventions
-- Build pattern catalog grouped by dimension
-
-### Phase 4: Persist
-
-1. Write `decompose-{slug}-{date}.md` with full catalog
-2. Append each **new** pattern to `lessons.jsonl` (source: "decompose", category: "pattern")
-3. If `--save-spec`: invoke `spec-add` per new pattern
-4. If `--save-wiki`: create wiki note per dimension group
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target path not found | Check path or use module name |
-| E002 | error | No source files in target | Check target has .ts/.js files |
-| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
-| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
-</error_codes>
-
-<success_criteria>
-- [ ] Target resolved to concrete file list
-- [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
-- [ ] Each finding has: name, dimension, confidence, anchors, description
-- [ ] Cross-reference performed (documented / known / new)
-- [ ] Pattern catalog written to `decompose-{slug}-{date}.md`
-- [ ] New patterns appended to `lessons.jsonl` with stable INS-ids
-- [ ] If --save-spec / --save-wiki: entries created
-</success_criteria>
+---
+name: learn-decompose
+description: Extract design patterns from code into specs and wiki
+argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
+scan a module, then a cross-reference agent deduplicates against existing patterns and
+produces a catalog. Discovered patterns persist to `lessons.jsonl` and optionally to
+specs (via `spec-add`) and wiki.
+
+```
+Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
+```
+</purpose>
+
+<context>
+$ARGUMENTS — target path/module and optional flags.
+
+**Target resolution:**
+- File path → analyze that file
+- Directory path → all source files in it
+- Module name → Glob `src/**/{module}*`
+
+**Flags:**
+- `-y, --yes`: Skip confirmations
+- `-c, --concurrency N`: Max concurrent agents (default: 4)
+- `--continue`: Resume existing session
+- `--patterns <list>`: Comma-separated pattern names to focus on
+- `--save-spec`: Invoke `spec-add` for each new pattern
+- `--save-wiki`: Create wiki note entries per dimension group
+
+**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/learning/decompose-{slug}-{date}.md`
+</context>
+
+<invariants>
+1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
+2. **Evidence required**: Every finding must have file:line anchors
+3. **Dedup before persist**: Cross-reference against existing specs + lessons
+4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
+5. **No files modified outside** `.workflow/learning/` (and optionally specs/wiki)
+</invariants>
+
+<execution>
+
+### Phase 1: Session Init + Target Resolution
+
+Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
+Extract remaining text as target path/module.
+
+Resolve target to file list. Load existing patterns from `coding-conventions.md` + `lessons.jsonl` for dedup set.
+
+### Phase 2: Wave 1 — Parallel Dimension Scans
+
+Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
+
+| id | dimension | focus |
+|----|-----------|-------|
+| 1 | structural | Class hierarchy, composition, DI, factories, exports |
+| 2 | behavioral | Events, middleware, observer, command, state machines |
+| 3 | data | Repository, DTO, caching, serialization, validation |
+| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
+| 5 | cross-ref | Dedup + catalog from wave 1 findings |
+
+Each dimension agent returns:
+```json
+[{
+  "name": "pattern name",
+  "dimension": "structural|behavioral|data|error",
+  "confidence": "high|medium|low",
+  "anchors": ["file:line"],
+  "description": "what it does",
+  "rationale": "why this approach",
+  "tradeoffs": "what was given up"
+}]
+```
+
+### Phase 3: Wave 2 — Cross-Reference + Catalog
+
+Single agent receives all wave 1 findings via `prev_context`. Tasks:
+- Match against dedup set → mark as `documented`, `known`, or `new`
+- Merge duplicates across dimensions (same pattern found by multiple agents)
+- Flag contradictions with documented conventions
+- Build pattern catalog grouped by dimension
+
+### Phase 4: Persist
+
+1. Write `decompose-{slug}-{date}.md` with full catalog
+2. Append each **new** pattern to `lessons.jsonl` (source: "decompose", category: "pattern")
+3. If `--save-spec`: invoke `spec-add` per new pattern
+4. If `--save-wiki`: create wiki note per dimension group
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target path not found | Check path or use module name |
+| E002 | error | No source files in target | Check target has .ts/.js files |
+| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
+| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete file list
+- [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
+- [ ] Each finding has: name, dimension, confidence, anchors, description
+- [ ] Cross-reference performed (documented / known / new)
+- [ ] Pattern catalog written to `decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `lessons.jsonl` with stable INS-ids
+- [ ] If --save-spec / --save-wiki: entries created
+</success_criteria>

package/.codex/skills/learn-follow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: learn-follow
-description: Guided follow-along reading of code or wiki entries. Section-by-section walk-through with 4 forcing questions, pattern extraction, and understanding map generation. Persists insights to lessons.jsonl.
+description: Guided reading of code or wiki to extract patterns
 argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---