maestro-flow-one 0.2.30 → 0.2.31

package/maestro-flow/commands/manage/codebase-refresh.md

@@ -1,60 +0,0 @@
----
-name: manage-codebase-refresh
-description: Refresh codebase docs from recent changes
-argument-hint: "[--since <date>] [--deep]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Incrementally refresh .workflow/codebase/ documentation based on changes since the last rebuild or refresh. Detects which files have changed (via git diff), identifies which codebase docs are affected, selectively re-runs mapper agents on those areas only, and updates timestamps. Much faster than a full rebuild for ongoing maintenance.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/codebase-refresh.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags.
-
-**Flags:**
-- `--since <date>` -- Override change detection window (ISO date or relative like "3d")
-- `--deep` -- Force deeper re-scan even for files with minor changes
-
-**State files:**
-- `.workflow/` -- must be initialized
-- `.workflow/codebase/` -- must contain existing docs (from prior rebuild)
-- `.workflow/codebase/doc-index.json` -- documentation index with timestamps
-- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph (optional, for KG impact analysis)
-- `.workflow/state.json` -- contains `codebase_last_rebuilt` timestamp
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/codebase-refresh.md' completely.
-</execution>
-
-<error_codes>
-| Code | Meaning                                                  |
-|------|----------------------------------------------------------|
-| E001 | .workflow/ not initialized                               |
-| E002 | No codebase/ docs exist, use codebase-rebuild instead    |
-| W001 | No changes detected since last refresh                   |
-</error_codes>
-
-<success_criteria>
-- [ ] Changed files detected via git diff since last refresh
-- [ ] Affected documentation entries identified from doc-index.json
-- [ ] KG impact analysis run (if knowledge-graph.json exists): `maestro kg diff-wiki --json`
-- [ ] Affected wiki entries flagged with warnings (if any)
-- [ ] Only affected docs refreshed (selective mapper re-run)
-- [ ] doc-index.json timestamps updated per affected entry
-- [ ] state.json updated with codebase_last_refreshed timestamp
-- [ ] Next step routing: `/manage-status` or `/spec-load` to use updated docs
-</success_criteria>

package/maestro-flow/commands/manage/learn.md

@@ -1,65 +0,0 @@
----
-name: manage-learn
-description: Capture and search learning insights and tips
-argument-hint: "[<text> | tip <text> | list | search | show <id>] [--category <cat>] [--tag t1,t2] [--phase N]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
-- **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
-- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
-
-Both types are stored in `.workflow/specs/learnings.md` as `<spec-entry>` blocks with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/learn.md
-</required_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Modes (auto-detected from first token):**
-- `"<insight text>"` (or any non-keyword text) → insight capture mode
-- `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
-- `list` → list recent entries (default 20)
-- `search <query>` → `maestro spec load --category learning` or text search across `.workflow/specs/learnings.md`
-- `show <INS-id>` → full detail with phase context
-- empty → AskUserQuestion to prompt for text
-
-Flags, storage paths, and shared store rationale defined in workflow learn.md.
-</context>
-
-<execution>
-Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
-| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
-| E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in `.workflow/specs/learnings.md` | show |
-| W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `<spec-entry>` block appended to `.workflow/specs/learnings.md` with all required fields
-- [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
-- [ ] Capture: category inference produces a sensible default when `--category` absent
-- [ ] List: filters apply, output sorted newest-first, default limit 20
-- [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
-- [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/specs/learnings.md` and `.workflow/knowhow/`
-- [ ] Confirmation banner displayed with INS-id and next-step hints
-- [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
-</success_criteria>

package/maestro-flow/commands/wiki/connect.md

@@ -1,62 +0,0 @@
----
-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 `specs/learnings.md` as `<spec-entry>` blocks
-- [ ] No unintended entry modifications (only `related` field changed)
-- [ ] Summary displayed with next-step routing
-</success_criteria>

package/maestro-flow/commands/wiki/digest.md

@@ -1,68 +0,0 @@
----
-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 | specs/learnings.md not found — skipping cross-reference | Proceed without knowhow 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 specs/learnings.md 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 `KNW-digest-{slug}-{date}.md`
-- [ ] Meta-insights appended to `specs/learnings.md` as `<spec-entry>` blocks
-- [ ] No files modified outside `.workflow/knowhow/` and `.workflow/issues/` (issues only when `--create-issues`)
-- [ ] Summary displayed with key findings and next-step routing
-</success_criteria>