maestro-flow 0.4.26 → 0.5.0

package/.claude/commands/maestro-learn.md

@@ -1,140 +0,0 @@
----
-name: maestro-learn
-description: Route learning intent to learn-* commands
-argument-hint: "<intent> [-y] [--dry-run] [--chain <name>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
-
-Executes commands sequentially via Skill() with session tracking.
-</purpose>
-
-<context>
-$ARGUMENTS — user learning intent text, or flags.
-
-**Flags:**
-- `-y` / `--yes` — Auto mode: skip confirmation
-- `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain (bypass intent detection)
-
-**Available learn commands:**
-| Command | Purpose |
-|---------|---------|
-| `learn-follow` | Guided reading with forcing questions, pattern extraction |
-| `learn-investigate` | Hypothesis-driven question investigation |
-| `learn-decompose` | 4-dimension parallel pattern extraction |
-| `learn-second-opinion` | Multi-perspective review/challenge/consult |
-| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
-
-**Available chains:**
-| Chain | Steps | Use when |
-|-------|-------|----------|
-| `follow` | learn-follow | Read/understand code or docs |
-| `investigate` | learn-investigate | Answer a "how/why" question |
-| `decompose` | learn-decompose | Catalog patterns in a module |
-| `second-opinion` | learn-second-opinion | Get review/challenge on code |
-| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
-| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
-| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
-
-**Storage:**
-- `.workflow/knowhow/.maestro-learn/{session_id}/status.json` — Session tracking
-- All learn command outputs go to `.workflow/knowhow/`
-</context>
-
-<execution>
-
-### Step 1: Parse & Route
-
-Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
-
-**If `--chain` specified:** validate against known chains, jump to Step 2.
-
-**Intent routing table** (match first token or keywords):
-
-| Keywords | Route |
-|----------|-------|
-| File path (contains `/` or `\`) | `follow` |
-| Wiki ID (`type-slug` pattern) | `follow` |
-| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
-| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
-| pattern, decompose, catalog, 分解, 模式 | `decompose` |
-| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
-| retro, git, commit, decision, 回顾 | `retro` |
-| thorough, deep, 全面, 深入 | `deep-understand` |
-
-**If no match:** present menu via AskUserQuestion:
-```
-What would you like to do?
-1. Read through code/docs → follow
-2. Investigate a question → investigate
-3. Find patterns in code → decompose
-4. Get a second opinion → second-opinion
-5. Retrospective → retro
-```
-
-Max 1 clarification round. If still unclear: error.
-
-### Step 2: Resolve Target & Build Args
-
-- File path → pass directly
-- Wiki ID → pass directly
-- Topic string → pass as quoted argument
-- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
-
-**Chain → command mapping:**
-```
-follow          → Skill("learn-follow", "{target} {flags}")
-investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
-decompose       → Skill("learn-decompose", "{target} {flags}")
-second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
-retro           → Skill("learn-retro", "{flags}")
-deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
-pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
-```
-
-### Step 3: Confirm & Execute
-
-**If `--dry-run`:** display chain plan and exit.
-
-**If not `-y`:** show plan, ask for confirmation.
-
-**Execute:**
-1. Create session dir: `.workflow/knowhow/.maestro-learn/learn-{timestamp}/`
-2. Write `status.json` with chain steps
-3. Execute each step via `Skill()`:
-   - On success: mark completed, continue
-   - On failure (interactive): ask retry/skip/abort
-   - On failure (auto): skip and continue
-4. Display session summary with artifact list and next-step suggestion
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent provided | Provide a learning goal or use --chain |
-| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
-| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
-| E005 | error | Invalid --chain name | Show valid chains |
-| W001 | warning | Intent ambiguous between commands | Present options |
-| W002 | warning | Chain step completed with warnings | Log and continue |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent routed to correct chain (or --chain validated)
-- [ ] Target resolved and arguments assembled
-- [ ] Session directory created with status.json
-- [ ] All chain steps executed via Skill()
-- [ ] Error handling: retry/skip/abort per step
-- [ ] Session summary displayed with next-step routing
-- [ ] No files modified outside `.workflow/knowhow/`
-</success_criteria>

package/.claude/commands/maestro-verify.md

@@ -1,144 +0,0 @@
----
-name: maestro-verify
-description: Use after execution to verify goals are actually achieved with evidence-based structural checks
-argument-hint: "[phase] [--skip-tests] [--skip-antipattern] [--dir <path>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Verify execution results through three complementary methods:
-1. **Goal-Backward verification** — 3-layer check (Truths → Artifacts → Wiring) that validates goals are actually achieved
-2. **Anti-pattern scan** — detect stubs, placeholders, TODO/FIXME, empty returns in modified files
-3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
-
-Supports dual-level verification:
-- **Single plan**: `verify --dir scratch/{YYYYMMDD}-plan-xxx` — verifies one plan, writes `verification.json` into plan dir
-- **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
-
-Registers VRF artifact in state.json on completion.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/verify.md
-</required_reading>
-
-<deferred_reading>
-- [verification.json](~/.maestro/templates/verification.json) — read when generating output
-- [validation.json](~/.maestro/templates/validation.json) — read when generating test output
-</deferred_reading>
-
-<context>
-$ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
-
-### Flags
-
-| Flag | Effect | Default |
-|------|--------|---------|
-| `--skip-tests` | Skip Nyquist test coverage validation (V2), only run Goal-Backward verification | false |
-| `--skip-antipattern` | Skip anti-pattern scan step | false |
-| `--dir <path>` | Verify a single plan directory instead of milestone-wide | — (milestone mode) |
-
-**Scope routing:**
-| Input | Scope | Resolution |
-|-------|-------|------------|
-| `--dir scratch/{dir}` | single plan | Verify one plan, write verification.json into plan dir |
-| numeric arg | phase | Verify all execute artifacts for that phase |
-| no args | milestone | Aggregate all execute artifacts for current milestone |
-
-Output paths and VRF artifact registration schema are defined in workflow `verify.md`.
-
-### Pre-load context (before verification)
-
-1. **Codebase docs**: If `.workflow/codebase/` exists, read `ARCHITECTURE.md` for expected module wiring and `FEATURES.md` for component mapping. Use in Layer 3 (Connection) checks.
-2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality baseline for anti-pattern scan and constraint checks.
-3. **Wiki constraints**: Run `maestro wiki search "architecture constraint" --json 2>/dev/null`. If results found, include documented invariants as additional truth checks in Layer 1.
-4. **Role Knowledge**:
-   - Browse: `maestro wiki list --category review`
-   - Load task-relevant entries: `maestro wiki load <id1> [id2...]`
-5. All are optional — proceed without if unavailable.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/verify.md' completely.
-
-### Post-verify Knowledge Inquiry
-
-| Condition | Ask | Route |
-|-----------|-----|-------|
-| Anti-pattern blockers found (TODO/FIXME/stubs) | "Update quality-rules.md?" | spec-add quality |
-| Architecture constraint violations | "Update architecture-constraints.md?" | spec-add arch |
-| Recurring test coverage gap (same module across tasks) | "Add to test-conventions.md?" | spec-add test |
-
-On confirm → `Skill("spec-add", "<category> <content>")`.
-
-</execution>
-
-<completion>
-### Standalone report
-
-```
-=== VERIFY COMPLETE ===
-STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
-CONCERNS: {description if applicable}
-NEXT: /quality-review
-=== END VERIFY ===
-```
-
-Status mapping:
-- **DONE** — All checks pass, no gaps → NEXT: /quality-review
-- **DONE_WITH_CONCERNS** — Gaps found (must-have failures or anti-pattern blockers) → NEXT: /maestro-execute (after /maestro-plan --gaps)
-- **NEEDS_RETRY** — Verification could not complete (missing artifacts, corrupt data)
-
-### Ralph-invoked completion
-
-End the step by calling the CLI (no text block output):
-```
-maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
-```
-
-Status verdicts:
-- **DONE** — Normal completion
-- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
-- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
-- **BLOCKED** — External hard blocker; pass `--reason`
-
-### Next-step routing
-
-| Condition | Suggestion |
-|-----------|-----------|
-| All checks pass, no gaps | `/quality-review` |
-| Gaps found (must-have failures or anti-pattern blockers) | `/maestro-plan --gaps` |
-| Low test coverage (Nyquist gaps) | `/quality-auto-test` |
-
-**Gap-fix closure loop:**
-Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
-</completion>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No executed plans found for verification | Run maestro-execute first |
-| E002 | error | Plan directory not found | Check --dir path |
-| E003 | error | No execution results found (missing summaries) | Run maestro-execute first |
-| W001 | warning | Test coverage below configured threshold | Review coverage gaps |
-| W002 | warning | Anti-pattern blockers found in modified files | Fix blockers before proceeding |
-</error_codes>
-
-<success_criteria>
-- [ ] Must-haves established (from convergence.criteria in tasks)
-- [ ] All truths verified with status and evidence (Layer 1)
-- [ ] All artifacts checked at L1 (exists), L2 (substantive), L3 (wired) (Layer 2)
-- [ ] All key links verified with evidence (Layer 3)
-- [ ] Anti-patterns scanned and categorized (unless skipped)
-- [ ] Nyquist test coverage assessed (unless skipped)
-- [ ] Fix plans generated for identified gaps
-- [ ] verification.json written to plan dir (single plan) or milestone verify dir
-- [ ] VRF artifact registered in state.json
-</success_criteria>

package/.claude/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/.claude/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/.claude/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/.claude/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>