maestro-flow 0.4.26 → 0.5.1

package/.agy/skills/wiki-digest/SKILL.md

@@ -1,70 +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:
-  - ask_question
-  - define_subagent
-  - grep_search
-  - invoke_subagent
-  - manage_subagents
-  - run_command
-  - send_message
-  - view_file
-  - write_to_file
----
-<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>

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

@@ -1,157 +0,0 @@
----
-name: learn-retro
-description: Retrospective of git activity and decision quality
-argument-hint: "[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--tag <tag>] [--id <id>] [--compare]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
-
-All insights persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
-</purpose>
-
-<context>
-$ARGUMENTS — lens selection and scope flags.
-
-**Lens**: `--lens git` | `--lens decision` | `--lens all` (default: all)
-
-**Git lens flags**: `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare` (vs prior retro)
-**Decision lens flags**: `--phase N`, `--tag <tag>`, `--id <id>` (single decision by wiki/INS id)
-
-**Storage write**:
-- `.workflow/knowhow/KNW-retro-{date}.md` — unified report
-- `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
-- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
-
-**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `.workflow/specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
-</context>
-
-<state_machine>
-
-<states>
-S_PARSE       — 解析 lens + flags                           PERSIST: —
-S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
-S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
-S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
-S_PERSIST     — 写 spec-entry 块                             PERSIST: .workflow/specs/learnings.md
-</states>
-
-<transitions>
-
-S_PARSE:
-  → S_GIT         WHEN: lens == git OR all               DO: ensure .workflow/knowhow/ exists (mkdir -p)
-  → S_DECISION    WHEN: lens == decision                  DO: ensure .workflow/knowhow/ exists (mkdir -p)
-
-S_GIT:
-  → S_DECISION    WHEN: lens == all                          DO: A_GIT_ANALYSIS
-  → S_REPORT      WHEN: lens == git                          DO: A_GIT_ANALYSIS
-
-S_DECISION:
-  → S_REPORT      DO: A_DECISION_ANALYSIS
-
-S_REPORT:
-  → S_PERSIST     DO: write KNW-retro-{date}.md + .json
-
-S_PERSIST:
-  → END           DO: append insights to .workflow/specs/learnings.md via `maestro spec add learning`
-  RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
-
-</transitions>
-
-<actions>
-
-### A_GIT_ANALYSIS
-
-**Parallel git commands**:
-```bash
-git log --since="{start}" --format="%H|%aN|%ae|%ai|%s" --shortstat
-git log --since="{start}" --format="COMMIT:%H|%aN" --numstat
-git log --since="{start}" --format="%at|%aN|%ai|%s" | sort -n
-git log --since="{start}" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
-git shortlog --since="{start}" -sn --no-merges
-```
-Apply --author and --area filters.
-
-**Compute metrics**:
-
-| Metric | Formula |
-|--------|---------|
-| Test ratio | test_insertions / total_insertions * 100% |
-| Churn rate | files changed >2x / total unique files |
-| Sessions | Cluster commits by >2hr gaps in timestamps |
-| LOC/session-hour | net_loc / total_session_hours |
-
-**Per-author breakdown**: commits, LOC, top 3 areas, test ratio, session count.
-
-**Trend** (if --compare or prior KNW-retro-*.json exists): compute deltas, flag >20% changes.
-
-**Distill insights**: high churn files (instability), low test ratio areas (<20%), session patterns, area drift vs roadmap.
-
-### A_DECISION_ANALYSIS
-
-**Collect** (parallel):
-```bash
-maestro wiki search "decision" --json
-maestro wiki list --type spec --json
-git log --oneline --all --grep="decision\|chose\|decided" -20
-```
-Plus: architecture-constraints.md, phase context Locked/Deferred sections, .workflow/specs/learnings.md.
-Apply --phase/--tag/--id filters.
-
-**Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
-
-**Evaluate** — spawn 3 Agents in single message:
-
-| Agent | Dimension | Grades |
-|-------|-----------|--------|
-| Technical Soundness | Implementation matches intent? Context changed? | sound / degraded / violated |
-| Cost Assessment | Complexity added? Coupling/debt? | low-cost / acceptable / expensive / debt-creating |
-| Alternative Hindsight | Right call with current knowledge? Reversible? | confirmed / questionable / should-revisit |
-
-**Classify lifecycle**:
-
-| Status | Criteria |
-|--------|---------|
-| Validated | sound + low/acceptable + confirmed |
-| Aging | sound + expensive + confirmed |
-| Questionable | degraded/violated + questionable |
-| Stale | any + should-revisit |
-| Reversed | code contradicts decision |
-
-**Recommend**: Aging → tech debt review, Questionable → create issue, Stale → refresh, Reversed → document reversal.
-
-</actions>
-
-</state_machine>
-
-<error_codes>
-| Code | Condition | Recovery |
-|------|-----------|----------|
-| E001 | Not in git repo (git lens) | Navigate to git repo |
-| E002 | No commits in window (git lens) | Increase --days |
-| E003 | No decisions found (decision lens) | Check wiki/specs or provide --id |
-| E004 | --id not found in wiki or knowhow | Verify the decision ID exists |
-| W002 | No prior retro for comparison | Skip trend; first retro = baseline |
-| W003 | One perspective agent failed | Proceed with available perspectives |
-</error_codes>
-
-<success_criteria>
-- [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
-- [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
-- [ ] Unified report + structured JSON written
-- [ ] .workflow/specs/learnings.md appended with stable INS-ids
-</success_criteria>
-
-<next_step_routing>
-- Browse insights → `/manage-learn list --tag retro`
-- Deep dive churn → `/learn-follow <path>`
-- Fix test gaps → `/quality-auto-test <area>`
-- Investigate stale decision → `/learn-investigate <question>`
-</next_step_routing>

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>