maestro-flow-one 0.2.30 → 0.2.32

package/maestro-flow/commands/quality/auto-test.md

@@ -55,7 +55,7 @@ Flags, artifact context resolution, and output formats defined in workflow auto-
 1. **Test specs + tools**: Run `maestro spec load --category test` to load test conventions (framework, patterns, naming). Apply to all generated tests.
 2. **Coding specs**: Run `maestro spec load --category coding` to understand coding patterns for accurate test targeting.
 3. **Role Knowledge**:
-   - Browse: `maestro wiki list --category test`
+   - Browse: `maestro search --category test`
    - Load task-relevant entries: `maestro wiki load <id1> [id2...]`
 4. All are optional — proceed without if unavailable.
 </context>
@@ -91,13 +91,13 @@ Append to state.json.artifacts[]:
 ```
 
 **Next-step routing on completion:**
-- Converged (>=95%) → `/maestro-verify {phase}`
+- Converged (>=95%) → `/quality-review {phase}`
 - All requirements verified (spec source) → `/maestro-milestone-audit`
 - Bugs discovered → `/quality-debug --from-uat {phase}`
 - Max iter, >80% → `/quality-test {phase}` for manual UAT
 - Max iter, <80% → `/quality-debug {phase}`
 - Coverage still low → `/quality-auto-test {phase} --layer {missing}`
-- Re-run all pass → `/maestro-verify {phase}`
+- Re-run all pass → `/quality-review {phase}`
 - Single pass, all pass → `/quality-test {phase}`
 </execution>
 

package/maestro-flow/commands/quality/debug.md

@@ -45,9 +45,9 @@ Extract conclusions from related artifacts that may affect this debug session
 
 ### Pre-load (optional, proceed without)
 - Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → module boundaries
-- Wiki: `maestro wiki search "<symptom keywords>" --json` → prior investigations
+- Wiki: `maestro search "<symptom keywords>" --json` → prior investigations
 - Specs: `maestro spec load --category debug --keyword "<symptom>"` → known issues/workarounds
-- Role knowledge: `maestro wiki list --category debug` → select relevant → `maestro wiki load`
+- Role knowledge: `maestro search --category debug` → select relevant → `maestro wiki load`
 
 **Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
 </context>
@@ -81,13 +81,13 @@ Append to state.json.artifacts[]:
 | Non-obvious fix / workaround | "Record as learning?" | spec-add learning |
 | Root cause = architectural boundary violation | "Update architecture-constraints.md?" | spec-add arch |
 
-On confirm → `Skill("spec-add", "<category> <content>")`.
+On confirm → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
 
 **Next-step routing on completion:**
 - Root cause found, fix needed → `/maestro-plan {phase} --gaps`
 - Root cause found (from UAT), auto-fix → `/quality-test {phase} --auto-fix`
 - Inconclusive, need more info → `/quality-debug {issue} -c` (resume session)
-- Standalone fix already applied → `/maestro-verify {phase}`
+- Standalone fix already applied → `/maestro-execute {phase}`
 </execution>
 
 <error_codes>

package/maestro-flow/commands/quality/refactor.md

@@ -33,7 +33,7 @@ If not provided, prompt user for scope.
 1. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Apply conventions to all refactored code.
 2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality gate for refactored code.
 3. **Role Knowledge**:
-   - Browse: `maestro wiki list --category coding`
+   - Browse: `maestro search --category coding`
    - Identify task-relevant entries, then load: `maestro wiki load <id1> [id2...]`
 4. All are optional — proceed without if unavailable.
 </context>
@@ -42,7 +42,7 @@ If not provided, prompt user for scope.
 Follow '~/.maestro/workflows/refactor.md' completely.
 
 **Knowledge inquiry on completion:**
-After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes, persist via `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2>")`.
+After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes, persist via `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
 
 **Next-step routing on completion:**
 - All tests pass → `/quality-sync` (update codebase docs)

package/maestro-flow/commands/quality/retrospective.md

@@ -22,7 +22,7 @@ Post-execution multi-perspective retrospective (复盘) for completed phases. Co
 
 <deferred_reading>
 - @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
-- @~/.maestro/workflows/learn.md (tip routing via manage-learn tip)
+- @~/.maestro/workflows/learn.md (tip routing via manage-knowhow-capture tip)
 - @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
 - @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
 </deferred_reading>
@@ -39,7 +39,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 1. **Read-only until Stage 6** — Stages 1–5 must not write anything except the in-memory retrospective record.
 2. **Parallel lens dispatch** — Stage 4 spawns one Agent per active lens in a single message (multiple Agent tool calls). All agents use `subagent_type: "general-purpose"` and `run_in_background: false`.
 3. **Match canonical issues schema** — Stage 6 issue routing must produce rows that pass `jq` parsing and match the schema in `workflows/issue.md` Step 4 exactly (status `"open"`, full `issue_history` entry, all required fields).
-4. **Reuse `manage-learn tip` for note routing** — do not duplicate the learning pipeline; invoke via `Skill({ skill: "manage-learn", args: "tip ..." })`.
+4. **Reuse `manage-knowhow-capture tip` for note routing** — do not duplicate the learning pipeline; invoke via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`.
 5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
 6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
 7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{artifact_dir}/.history/` with a timestamp suffix first.
@@ -55,7 +55,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 | E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
 | W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
 | W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
-| W003 | warning | `manage-learn tip` did not return parseable INS id; fell back to direct write | route_outputs |
+| W003 | warning | `manage-knowhow-capture tip` did not return parseable INS id; fell back to direct write | route_outputs |
 | W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
 </error_codes>
 
@@ -69,9 +69,9 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
-- [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
+- [ ] Note tips (if any) created via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`
 - [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
-- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library
+- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-knowhow list` to browse the knowhow library
 </success_criteria>

package/maestro-flow/commands/quality/review.md

@@ -13,7 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" -- complementing maestro-verify ("is the goal met?") and quality-test ("does it work for users?"). Three review levels (quick/standard/deep) scale with task depth, auto-detected from file count. Level definitions, dimension lists, deep-dive rules, and issue creation thresholds defined in workflow review.md.
+Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" -- complementing maestro-execute's built-in verification ("is the goal met?") and quality-test ("does it work for users?"). Three review levels (quick/standard/deep) scale with task depth, auto-detected from file count. Level definitions, dimension lists, deep-dive rules, and issue creation thresholds defined in workflow review.md.
 </purpose>
 
 <required_reading>
@@ -50,9 +50,9 @@ Extract conclusions from related artifacts that may affect this review. Pass as
 
 ### Pre-load (optional, proceed without)
 - Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → component boundaries, layer rules
-- Wiki constraints: `maestro wiki search "architecture constraint" --json` → documented decisions
+- Wiki constraints: `maestro search "architecture constraint" --json` → documented decisions
 - Specs: `maestro spec load --category review` → review standards, checklists, knowhow tools
-- Role knowledge: `maestro wiki list --category review` → select relevant → `maestro wiki load`
+- Role knowledge: `maestro search --category review` → select relevant → `maestro wiki load`
 
 **Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>
@@ -99,7 +99,7 @@ NEXT: /quality-refactor
 
 Status mapping:
 - **DONE** — PASS verdict, no critical findings → NEXT: /quality-refactor
-- **DONE_WITH_CONCERNS** — WARN verdict, issues found but non-blocking → NEXT: /maestro-verify
+- **DONE_WITH_CONCERNS** — WARN verdict, issues found but non-blocking → NEXT: /quality-test
 - **NEEDS_RETRY** — BLOCK verdict, critical findings require fix first
 </execution>
 

package/maestro-flow/commands/quality/sync.md

@@ -33,6 +33,7 @@ Follow '~/.maestro/workflows/sync.md' completely.
 **Next-step routing on completion:**
 - Docs refreshed → `/manage-status`
 - Major structural changes detected → `/manage-codebase-rebuild` (full rebuild recommended)
+- Incremental refresh (replaces former `/manage-codebase-refresh`) → use `--since` flag
 </execution>
 
 <error_codes>

package/maestro-flow/commands/quality/test.md

@@ -41,8 +41,8 @@ Follow '~/.maestro/workflows/test.md' completely.
 **Command-specific extensions (not in workflow):**
 
 **Knowledge context loading** (before test design):
-- Wiki search: `maestro wiki search "<phase/feature keywords>" --json` → prior test strategies, recipes, decisions
-- Role knowledge: `maestro wiki list --category test` → select relevant → `maestro wiki load <id>`
+- Wiki search: `maestro search "<phase/feature keywords>" --json` → prior test strategies, recipes, decisions
+- Role knowledge: `maestro search --category test` → select relevant → `maestro wiki load <id>`
 - Specs + tools: `maestro spec load --category test` → test conventions + discoverable knowhow tools
 
 **Test tool discovery** (knowhow tools as scenario source):
@@ -77,7 +77,7 @@ Append to state.json.artifacts[]:
 
 **Next-step routing on completion:**
 - All tests pass → `/maestro-milestone-audit`
-- Issues found, --auto-fix ran and succeeded → `/maestro-verify {phase}`
+- Issues found, --auto-fix ran and succeeded → `/maestro-execute {phase}`
 - Issues found, --auto-fix ran but gaps remain → `/quality-debug --from-uat {phase}`
 - Issues found, manual fix needed → `/quality-debug --from-uat {phase}`
 - Coverage below threshold → `/quality-auto-test {phase}`
@@ -88,7 +88,7 @@ Append to state.json.artifacts[]:
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Phase or task target required (no active sessions) | Prompt user for phase number |
-| E002 | error | Phase not verified yet (no verification.json) | Suggest `/maestro-verify` first |
+| E002 | error | Phase not verified yet (no verification.json) | Suggest `/maestro-execute` first (verification is built-in) |
 | E003 | error | Smoke test failed (app won't start) | Suggest `/quality-debug` |
 | W001 | warning | One or more test scenarios failed | Auto-diagnose, suggest fix options |
 | W002 | warning | Coverage below threshold | Suggest `/quality-auto-test` |

package/maestro-flow/commands/spec/add.md

@@ -24,6 +24,7 @@ Entries use `category` attribute to declare which category they belong to.
 $ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
 
 **Options:**
+- `--description <desc>` — One-line description for search results (falls back to content[:240])
 - `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
 - `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
 
@@ -34,12 +35,13 @@ Scope-to-directory mapping, category-to-file mapping, and entry format defined i
 # English content → English keywords
 /spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
 
-# Chinese content → Chinese keywords (匹配中文 prompt)
-/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
+# With description for search results
+/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --keywords "oauth,pkce" --description "OAuth 2.0 PKCE 认证流程规范"
 
-# Mixed → bilingual keywords
-/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --ref knowhow/RCP-oauth-pkce.md --keywords "oauth,pkce,认证,授权"
+# Chinese content → Chinese keywords
+/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
 
+# Ref mode
 /spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
 ```
 </context>

package/maestro-flow/commands/spec/setup.md

@@ -12,7 +12,7 @@ allowed-tools:
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
 Core files (coding, arch, learnings) are always created. Optional spec files (quality, test, ui) are created only when relevant signals are detected.
-Additionally, generates recipe-type knowhow docs in `.workflow/knowhow/` for detected operational workflows (test / debug / build / dev / lint) — capturing "how to do X in this project" so future agents can find them via `maestro wiki search`.
+Additionally, generates recipe-type knowhow docs in `.workflow/knowhow/` for detected operational workflows (test / debug / build / dev / lint) — capturing "how to do X in this project" so future agents can find them via `maestro search`.
 Spec output lands in `.workflow/specs/`; recipe output lands in `.workflow/knowhow/`.
 </purpose>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"

package/maestro-flow/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/maestro-flow/commands/lifecycle/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>