maestro-flow 0.1.3 → 0.2.0

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

@@ -0,0 +1,168 @@
+---
+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
+---
+<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:**
+- `--scope <type>` — Limit analysis to a wiki type (spec, phase, memory, note, lesson, issue). Default: all types.
+- `--min-similarity N` — Minimum similarity score threshold 0.0-1.0 (default: 0.3)
+- `--fix` — Auto-apply the top suggestions by updating wiki entries with new `related` links
+- `--max N` — Maximum number of suggestions to generate (default: 20)
+
+**Storage written:**
+- `.workflow/learning/wiki-connections-{YYYY-MM-DD}.md` — Connection analysis report
+- If `--fix`: wiki entries updated via `maestro wiki update` with new `related` links
+- `.workflow/learning/lessons.jsonl` — Graph structure insights (source: "wiki-connect")
+
+**Storage read (via maestro wiki CLI, offline mode):**
+- `maestro wiki list --json` — All wiki entries
+- `maestro wiki graph` — Full graph structure (forward + backlinks)
+- `maestro wiki health` — Current health score
+- `maestro wiki orphans` — Orphaned entries
+- `maestro wiki hubs` — Hub entries (most referenced)
+</context>
+
+<execution>
+
+### Stage 1: Load Wiki State
+Run these `maestro wiki` commands in parallel:
+
+```bash
+maestro wiki list --json
+maestro wiki health
+maestro wiki orphans
+maestro wiki hubs --top 10
+```
+
+Parse results:
+- Entry count, type distribution
+- Baseline health score (from `wiki health`)
+- Orphan list (entries with 0 in-degree and 0 out-degree)
+- Hub list (most-referenced entries)
+
+Apply `--scope` filter if provided.
+
+### Stage 2: Identify Connection Candidates
+For each entry, compute potential connections:
+
+**2a. Orphan Rescue:**
+For each orphan entry, search for related entries using:
+- `maestro wiki search "<orphan title>"` — BM25 match by title
+- Tag overlap: entries sharing 2+ tags with the orphan
+- Same phase: entries with matching `phaseRef`
+
+**2b. Missing Bidirectional Links:**
+For entries that have forward links but no corresponding backlink (A links to B, but B doesn't link to A), suggest adding the reverse link.
+
+**2c. Transitive Closure:**
+If A → B and B → C, but A has no link to C, and A and C share tags or are in the same phase, suggest A → C.
+
+**2d. Type Bridge:**
+Entries of different types that reference the same concept (e.g., a `spec-auth` and a `lesson-auth-gotcha`) but aren't linked.
+
+### Stage 3: Score Candidates
+For each candidate connection (source → target), compute similarity:
+
+```
+score = 0.4 × tag_overlap_ratio
+      + 0.3 × title_bm25_similarity
+      + 0.2 × same_phase_bonus
+      + 0.1 × type_bridge_bonus
+```
+
+- `tag_overlap_ratio`: shared_tags / max(source_tags, target_tags)
+- `title_bm25_similarity`: normalized BM25 score from wiki search
+- `same_phase_bonus`: 1.0 if same phaseRef, else 0.0
+- `type_bridge_bonus`: 1.0 if different types, else 0.0
+
+Filter by `--min-similarity`, rank descending, limit to `--max`.
+
+### Stage 4: Present Suggestions
+Display ranked connection suggestions:
+
+```
+== Wiki Connection Suggestions ==
+Baseline health: 72/100 | Orphans: 8 | Broken links: 3
+
+#  Score  Source              → Target              Reason
+1  0.85   memory-auth-flow    → spec-auth           tag overlap (auth, security) + same phase
+2  0.71   note-cache-pattern  → spec-performance    title BM25 match + type bridge
+3  0.65   lesson-retry-fix    → spec-error-handling  tag overlap (error, retry)
+...
+
+Projected health after fix: 81/100 (+9)
+```
+
+If NOT `--fix`: display and exit.
+If `--fix`: proceed to Stage 5.
+
+### Stage 5: Apply Connections (--fix only)
+For each accepted suggestion:
+1. Get current entry: `maestro wiki get <source-id> --json`
+2. Extract existing `related` list from frontmatter
+3. Append target-id to `related` if not already present
+4. Update: `maestro wiki update <source-id> --frontmatter "related: [existing..., new-target]"`
+5. Log success/failure
+
+After all updates:
+- Re-run `maestro wiki health` to get new health score
+- Report delta
+
+### Stage 6: Persist & Report
+1. Write `.workflow/learning/wiki-connections-{date}.md` with:
+   - Baseline and final health scores
+   - All suggestions (applied and unapplied)
+   - Orphan rescue results
+   - Graph structure observations (hub concentration, type distribution)
+2. Append graph insights to `lessons.jsonl`:
+   - `source: "wiki-connect"`, `category: "technique"`
+   - e.g., "Auth-related entries are poorly connected", "Phase 3 has 5 orphaned notes"
+3. Display summary
+
+**Next-step routing:**
+- Generate knowledge digest → `Skill({ skill: "wiki-digest", args: "<topic>" })`
+- Follow-along on orphan → `Skill({ skill: "learn-follow", args: "<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 `Skill({ skill: "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

@@ -0,0 +1,180 @@
+---
+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>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Scope resolution (auto-detected):**
+- `<topic>` — Search wiki for entries matching the topic via `maestro wiki search`
+- `--recent N` — Entries updated in the last N days
+- `--type <type>` — Filter by wiki type (spec, phase, memory, note, lesson, issue)
+- No arguments — digest of the entire wiki
+
+**Flags:**
+- `--format brief` — Compact summary, one paragraph per theme (default)
+- `--format full` — Detailed digest with per-entry summaries and full gap analysis
+
+**Storage written:**
+- `.workflow/learning/digest-{slug}-{YYYY-MM-DD}.md` — Digest document
+- `.workflow/learning/lessons.jsonl` — Meta-insights about knowledge structure (source: "wiki-digest")
+
+**Storage read (via maestro wiki CLI, offline mode):**
+- `maestro wiki list --json` — All entries (or filtered)
+- `maestro wiki search <topic>` — Topic-scoped entries
+- `maestro wiki get <id>` — Entry bodies for summarization
+- `maestro wiki backlinks <id>` / `maestro wiki forward <id>` — Relationship context
+- `maestro wiki health` — Overall graph health
+- `.workflow/learning/lessons.jsonl` — Cross-reference for unlinked insights
+</context>
+
+<execution>
+
+### Stage 1: Scope & Load
+- Parse arguments to determine scope:
+  - Topic: `maestro wiki search "<topic>" --json` → matching entries
+  - Recent N: `maestro wiki list --json` → filter by `updated` within N days
+  - Type: `maestro wiki list --type <type> --json`
+  - All: `maestro wiki list --json`
+- Load entry metadata (id, title, tags, status, type, related, summary)
+- For `--format full`: also load entry bodies via `maestro wiki get <id>` for top entries
+- Run `maestro wiki health` for baseline metrics
+
+### Stage 2: Theme Clustering
+Group entries into 3-5 semantic themes using:
+
+1. **Tag co-occurrence**: entries sharing 2+ tags belong to the same theme
+2. **Title similarity**: BM25-based grouping (entries whose titles match each other's keywords)
+3. **Relationship proximity**: entries connected by `related` links cluster together
+4. **Type grouping**: if entries are all same type, sub-cluster by content
+
+For each theme:
+- Name: most common tag or dominant keyword
+- Entry count
+- Type distribution within theme
+- Status distribution (draft/active/completed/archived)
+
+### Stage 3: Per-Theme Analysis
+For each theme, produce:
+
+**Summary paragraph**: synthesize the key knowledge in this theme area (what do these entries collectively say?)
+
+**Key entries**: top 3-5 most important entries (by hub score / backlink count)
+
+**Gap detection**:
+- Broken links: `[[references]]` that don't resolve within the theme
+- Orphans: entries in this theme with no connections
+- Questions: entries with `?` in title or "TODO" / "TBD" markers in body
+- Missing perspectives: if theme has specs but no lessons, or issues but no decisions
+
+**Health**: per-theme health score (adapted from wiki health formula)
+
+### Stage 4: Cross-Reference with Lessons
+- Search `lessons.jsonl` for insights related to each theme
+- Identify unlinked insights: lessons that match a theme but are not referenced by any wiki entry in that theme
+- Flag these as "knowledge not yet connected to the graph"
+
+### Stage 5: Coverage Heatmap
+Build a matrix showing knowledge density by type × theme:
+
+```
+              Theme 1    Theme 2    Theme 3    Theme 4    Theme 5
+spec          ███░░      ░░░░░      █████      ██░░░      ░░░░░
+phase         ████░      ███░░      ░░░░░      █████      ██░░░
+memory        ░░░░░      ████░      ██░░░      ░░░░░      ███░░
+lesson        █░░░░      ██░░░      ████░      █░░░░      ░░░░░
+issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
+
+Legend: █ = entries exist, ░ = sparse/missing
+```
+
+Identify: which theme × type cells are empty? These are knowledge gaps.
+
+### Stage 6: Write Digest
+Produce `.workflow/learning/digest-{slug}-{date}.md`:
+
+```markdown
+# Knowledge Digest: {scope description}
+**Generated:** {date} | **Entries:** {count} | **Health:** {score}/100
+
+## Themes
+
+### 1. {Theme Name} ({N} entries)
+{summary paragraph}
+
+**Key entries:** {linked entry IDs}
+**Gaps:** {list of missing knowledge}
+**Health:** {score}/100
+
+### 2. {Theme Name} ...
+
+## Coverage Heatmap
+{matrix}
+
+## Knowledge Gaps
+| Gap | Theme | Type Missing | Suggested Action |
+|-----|-------|-------------|-----------------|
+| No lessons for auth patterns | Security | lesson | Run /learn-decompose on src/auth/ |
+
+## Unlinked Insights
+{lessons.jsonl entries not connected to wiki graph}
+
+## Recommended Actions
+1. {action}: {reason}
+2. ...
+```
+
+### Stage 7: Persist
+1. Write digest file
+2. Append meta-insights to `lessons.jsonl`:
+   - `source: "wiki-digest"`, `category: "technique"`
+   - e.g., "Auth knowledge is concentrated in specs but lacks lessons", "Phase 2 has no decision entries"
+3. Update `learning-index.json`
+4. Display summary with key findings
+
+**Next-step routing:**
+- Deep dive on a theme → `Skill({ skill: "learn-follow", args: "<wiki-id>" })`
+- Fix graph gaps → `Skill({ skill: "wiki-connect", args: "--fix" })`
+- Decompose code for missing patterns → `Skill({ skill: "learn-decompose", args: "<path>" })`
+- Create missing entries → `maestro wiki create --type <type> --slug <slug>`
+</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
+- [ ] Digest written to `digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to `lessons.jsonl`
+- [ ] `learning-index.json` updated
+- [ ] No files modified outside `.workflow/learning/`
+- [ ] Summary displayed with key findings and next-step routing
+</success_criteria>