maestro-flow 0.4.9 → 0.4.11

package/.agents/skills/maestro-help/phases/03-workflow-guide.md

@@ -0,0 +1,186 @@
+# Phase 3: Workflow Guide
+
+工作流推荐和新手引导。覆盖 Mode 4/5。
+
+## Objective
+
+- 根据用户任务推荐最合适的工作流
+- 为新手提供入门指引
+- 给出具体命令序列和说明
+
+## Execution
+
+### Mode 4: Workflow Guide
+
+根据用户描述的任务类型推荐工作流：
+
+#### Step 4.1: 任务分类
+
+```javascript
+// 任务类型识别
+const taskPatterns = [
+  { type: "new_project", patterns: ["新项目", "从头开始", "new project", "创建项目"] },
+  { type: "feature", patterns: ["添加功能", "新功能", "add feature", "实现"] },
+  { type: "bugfix", patterns: ["修复", "bug", "fix", "问题"] },
+  { type: "refactor", patterns: ["重构", "refactor", "优化", "改进"] },
+  { type: "analysis", patterns: ["分析", "analyze", "调查", "investigate"] },
+  { type: "review", patterns: ["审查", "review", "检查", "check"] },
+  { type: "test", patterns: ["测试", "test", "验证"] },
+  { type: "explore", patterns: ["探索", "explore", "头脑风暴", "brainstorm"] },
+  { type: "knowledge", patterns: ["知识", "knowhow", "学习", "learn"] },
+]
+```
+
+#### Step 4.2: 推荐工作流
+
+**新项目** (复杂度: 高):
+
+```markdown
+## 新项目工作流
+
+### 路径 1: 最简路径（适合快速启动）
+1. `/maestro-init` — 初始化 .workflow/ 目录
+2. `/maestro-roadmap "项目目标" -y` — 生成路线图
+3. 按里程碑执行: analyze → plan → execute → verify
+
+### 路径 2: 从头脑风暴开始（适合需要创意探索）
+1. `/maestro-brainstorm "项目描述"` — 多角色头脑风暴
+2. `/maestro-init --from-brainstorm ANL-xxx` — 基于分析初始化
+3. `/maestro-roadmap "创建路线图" -y`
+
+### 路径 3: 完整规范链（适合大型项目）
+1. `/maestro-init`
+2. `/maestro-spec-generate` — 7 阶段规范生成
+```
+
+**功能开发** (复杂度: 中):
+
+```markdown
+## 功能开发工作流
+
+### 主干管线（标准流程）
+1. `/maestro-analyze [phase]` — 分析需求和现有代码
+2. `/maestro-plan [phase]` — 生成执行计划
+3. `/maestro-execute [phase]` — 执行实现
+4. `/maestro-verify [phase]` — 验证成果
+
+### 快速渠道（简单功能）
+1. `/maestro-quick "功能描述"` — 一键完成
+
+### 全自动
+1. `/maestro -y "功能描述"` — 自动选择并执行完整流程
+```
+
+**Bug 修复** (复杂度: 低-中):
+
+```markdown
+## Bug 修复工作流
+
+### 快速修复（已知问题）
+1. `/maestro-quick "修复 Bug 描述"`
+
+### Issue 闭环（需要追踪）
+1. `/manage-issue-discover by-prompt "问题描述"` — 发现 Issue
+2. `/manage-issue create --title "Bug 标题" --severity high` — 创建 Issue
+3. `/maestro-analyze --gaps ISS-xxx` — 根因分析
+4. `/maestro-plan --gaps` — 方案规划
+5. `/maestro-execute` — 执行修复
+6. `/manage-issue close ISS-xxx --resolution "Fixed"` — 关闭 Issue
+```
+
+**代码审查**:
+
+```markdown
+## 质量管线
+
+1. `/quality-review [phase] --level standard` — 多维代码审查
+2. `/quality-auto-test [phase]` — 自动测试（智能路由）
+3. `/quality-test [phase]` — 业务测试（UAT）
+
+### 测试失败修复循环
+1. `/quality-debug --from-uat [phase]` — 诊断失败
+2. `/maestro-plan [phase] --gaps` — 生成修复计划
+3. `/maestro-execute [phase]` — 执行修复
+4. `/quality-auto-test [phase] --re-run` — 重跑失败场景
+```
+
+#### Step 4.3: 工作流全景图
+
+对需要全景视角的用户，展示 Mermaid 图：
+
+```
+主干管线: analyze → plan → execute → verify → quality (review/test) → milestone-audit → milestone-complete
+快速渠道: maestro-quick → (直接完成)
+Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
+全自动: /maestro -y → (自动路由)
+```
+
+#### Step 4.4: 关键概念说明
+
+对不熟悉 Maestro 的用户，简要说明核心概念：
+
+```markdown
+## 核心概念
+
+- **Milestone**: 项目阶段，包含多个 Phase
+- **Phase**: 单个工作单元，走 analyze → plan → execute → verify 生命周期
+- **Overlay**: 非侵入式命令补丁，扩展命令行为而不修改源文件
+- **Delegate**: 将子任务委派给外部 AI 工具（Gemini/Claude/Codex）
+- **Spec**: 项目规范，自动注入到工作流中作为约束
+- **Wiki**: 知识图谱，存储详细技术文档
+- **Ralph**: 自适应决策引擎，动态调整执行链
+```
+
+### Mode 5: Beginner Onboarding
+
+#### Step 5.1: 展示核心命令
+
+从 `catalog.json essential_commands[]` 读取核心命令列表：
+
+```markdown
+## Maestro Flow 快速入门
+
+### 10 个核心命令
+
+| # | 命令 | 用途 | 何时使用 |
+|---|------|------|---------|
+| 1 | `/maestro` | 智能协调器 | 不确定用哪个命令时，告诉它你的目标 |
+| 2 | `/maestro-init` | 初始化项目 | 首次使用，创建 .workflow/ 结构 |
+| 3 | `/maestro-roadmap` | 生成路线图 | 初始化后，规划里程碑 |
+| 4 | `/maestro-analyze` | 分析 | 开始一个 Phase 的分析 |
+| 5 | `/maestro-plan` | 规划 | 分析完成后，生成执行计划 |
+| 6 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
+| 7 | `/maestro-verify` | 验证 | 执行完成后，检查成果 |
+| 8 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
+| 9 | `/quality-review` | 代码审查 | 执行后进行质量检查 |
+| 10 | `/manage-issue` | Issue 管理 | 追踪和解决 Bug |
+```
+
+#### Step 5.2: 快速入门路径
+
+```markdown
+### 5 分钟上手
+
+1. **安装**: `maestro install --force`
+2. **初始化**: `/maestro-init`
+3. **开始工作**: `/maestro "你的任务描述"` — 自动选择最佳工作流
+
+### 10 分钟深入
+
+阅读 `guide/quick-start-guide.md` 了解完整功能。
+```
+
+#### Step 5.3: 分类浏览引导
+
+```markdown
+### 想了解更多？
+
+- **全部命令**: `/maestro-help` 查看完整目录
+- **工作流指南**: `/maestro-help workflow` 了解工作流选择
+- **Skill 浏览**: `/maestro-help skills` 查看可用 Skill
+- **CLI 命令**: `/maestro-help cli` 查看终端命令
+```
+
+## Output
+
+结构化的工作流推荐或新手引导内容，直接展示给用户。

package/.agents/skills/maestro-impeccable/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: maestro-impeccable
+description: Use when designing, auditing, polishing, or improving frontend UI — websites, dashboards, landing pages, components
+argument-hint: "<command|intent> [target] [flags] — 可选 chain: build|redesign|improve|enhance|launch|harden|foundation|live"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+  - track_tasks
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+<purpose>
+UI design command. Parse input → prerequisites → read workflow file → execute → track.
+
+- **Direct**: single command via workflow file
+- **Chain**: orchestrate command sequence with quality gates
+- **Search**: query design knowledge base via CLI
+</purpose>
+
+## Input
+
+$ARGUMENTS first word determines mode:
+
+| First Word | Mode |
+|------------|------|
+| Known command (see routing table) | Direct |
+| Chain name: build, redesign, improve, enhance, launch, harden, foundation, live | Chain |
+| continue / next / -c | Resume |
+| search | Search: `maestro impeccable search "$REST"` |
+| Free text (concrete task) | Direct craft — has specific target + specs/reference |
+| Free text (project intent) | Intent → classify → chain |
+| (empty) | Menu: show commands by category |
+
+## Command Routing
+
+All workflows at `~/.maestro/workflows/impeccable/{command}.md`:
+
+| Command | Category | Description |
+|---------|----------|-------------|
+| craft | Build | Shape then build end-to-end — full page/component implementation |
+| shape | Build | Plan UX/UI before code — information architecture, wireframe, visual direction |
+| teach | Build | Set up PRODUCT.md — users, brand, tone, anti-references, principles |
+| document | Build | Generate DESIGN.md from existing code — extract tokens, typography, colors |
+| extract | Build | Pull tokens/components into reusable design system |
+| explore | Build | Multi-style comparison — generate variants, render prototypes, visual compare, select/mix |
+| critique | Evaluate | UX heuristic review with Nielsen scoring (/40) + P0/P1 findings |
+| audit | Evaluate | Technical quality checks — a11y, performance, responsive, code quality (/20) |
+| polish | Refine | Final quality pass — micro-adjustments, pixel perfection |
+| bolder | Refine | Amplify bland/safe designs — stronger personality, more contrast |
+| quieter | Refine | Tone down aggressive/overwhelming designs — reduce visual noise |
+| distill | Refine | Strip to essence — remove clutter, reduce cognitive load |
+| harden | Refine | Production-ready — error states, i18n, edge cases, overflow, empty states |
+| onboard | Refine | First-run flows, empty states, activation paths, progressive disclosure |
+| animate | Enhance | Add purposeful motion — transitions, micro-interactions, scroll effects |
+| colorize | Enhance | Add strategic color — OKLCH palette, contrast, color strategy |
+| typeset | Enhance | Improve typography — scale, hierarchy, font pairing, line length |
+| layout | Enhance | Fix spacing, rhythm, visual hierarchy, alignment, grid |
+| delight | Enhance | Add personality — memorable details, joy, surprise moments |
+| overdrive | Enhance | Push past conventional limits — ambitious visual effects |
+| clarify | Fix | Improve UX copy — labels, error messages, microcopy, CTAs |
+| adapt | Fix | Adapt for devices/screens — responsive, touch targets, breakpoints |
+| optimize | Fix | Fix UI performance — loading, rendering, bundle, paint/layout jank |
+| live | Iterate | Browser-based variant iteration — real-time design in DevTools |
+
+Reference files (loaded by workflow as needed, not standalone commands):
+brand.md, product.md, design.md, codex.md, heuristics-scoring.md, cognitive-load.md,
+color-and-contrast.md, interaction-design.md, motion-design.md, personas.md,
+responsive-design.md, spatial-design.md, typography.md, ux-writing.md
+
+## Chains
+
+| Chain | Steps | Scenario |
+|-------|-------|----------|
+| build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | New from scratch |
+| redesign | document → explore → shape → craft → critique → [refine] → audit → polish | Redesign existing code |
+| improve | critique → [refine] → polish → audit | Iterative improvement |
+| enhance | {cmd...} → critique → [refine] → polish | Targeted enhancement (multi-command) |
+| launch | harden → adapt → optimize → audit → polish | Full production readiness |
+| harden | harden → audit → polish | Edge case hardening |
+| foundation | teach? → explore → document → extract | Design system setup |
+| live | live | Real-time iteration |
+
+- `?` = conditional: teach if PRODUCT.md missing; explore if DESIGN.md missing and --skip-design not set
+- `[refine]` = quality gate loop: gate fails → auto-select fix commands from findings → re-gate
+- `{cmd...}` = enhance supports multiple commands, comma-separated: `enhance colorize,typeset landing-page`
+
+Chain flags: --threshold <N> (default 26/40), --max-loops <N> (default 3), --skip-design, --styles <N>, -y
+
+## Free Text Routing
+
+Three-layer priority matching. Stop on first match — do not continue to lower layers.
+
+### Layer 1: Single command intent → Direct
+
+Semantically match user description against the Command Routing table's Description column. Match the closest **single** command.
+
+**Skip condition**: If the prompt also contains a Layer 2 chain keyword AND does not focus on a single design dimension, skip this layer.
+Example: `enhance colors and typography` — "enhance" is a chain keyword + multiple design dimensions → skip to Layer 2.
+
+| Intent signal | Command |
+|---------------|---------|
+| review, check UX, score, heuristic, evaluate usability | critique |
+| audit, a11y, accessibility, technical check, performance audit, code quality | audit |
+| add animation, motion, transitions, micro-interactions | animate |
+| color, palette, OKLCH, contrast, color scheme | colorize |
+| font, typography, type scale, line height, font pairing | typeset |
+| layout, spacing, grid, alignment, visual hierarchy | layout |
+| too loud, tone down, visual noise, make it simpler, too busy | quieter |
+| too bland, bolder, more personality, stronger, more contrast | bolder |
+| too complex, simplify, strip, remove clutter, cognitive load | distill |
+| polish, fine-tune, pixel perfect, final pass, refine details | polish |
+| copy, labels, error messages, UX writing, microcopy, CTAs | clarify |
+| responsive, mobile, adapt, breakpoints, touch targets | adapt |
+| performance, loading, bundle, jank, speed, rendering | optimize |
+| edge cases, error states, i18n, overflow, empty state hardening | harden |
+| onboarding, first-run, empty state, activation, progressive disclosure | onboard |
+| fun, surprise, personality, memorable, joy, delight | delight |
+| extraordinary, push limits, ambitious effects, cutting-edge | overdrive |
+| plan UX, wireframe, information architecture, visual direction | shape |
+| multi-style, variants, compare styles, style comparison | explore |
+| brand definition, PRODUCT.md, product context | teach |
+| extract design, DESIGN.md, document design system | document |
+| pull tokens, extract components, design system extraction | extract |
+| real-time, browser iteration, live editing | live |
+
+### Layer 2: Project intent → Chain
+
+Layer 1 did not match. Check for chain-level keywords — even if the prompt also contains a specific target/path, chain matching takes priority.
+
+| Pattern | Chain |
+|---------|-------|
+| new, create, build, from scratch, start fresh | build |
+| redo, redesign, rethink, restyle, overhaul, revamp | redesign |
+| improve, iterate, better, refine overall | improve |
+| enhance, visual upgrade, level up | enhance |
+| launch, deploy, ship, production-ready, go live | launch |
+| harden, production-harden, edge cases | harden |
+| design system, tokens, design foundation, design infrastructure | foundation |
+| real-time, live, browser | live |
+
+Ambiguous + no `-y` → ask_user.
+
+### Layer 3: Concrete build task → Direct craft
+
+Layer 1+2 both did not match, but intent is to build/create a specific thing:
+- Contains a specific file path or target (`d:\path`, `src/pages/`, `index.html`)
+- Contains detailed visual specs (layout, style, color scheme)
+- Contains reference material (`based on...`, `like...`, `similar to...`)
+
+→ Route to **craft** (Direct)
+
+## Prerequisites
+
+Before reading any command workflow:
+
+1. **Context**: `maestro spec load --category ui` → if empty → `maestro impeccable load-context`
+2. **PRODUCT.md**: missing/placeholder (<200 chars / `[TODO]`) → execute teach first, then resume original task
+3. **Register**: identify brand/product → Read `~/.maestro/workflows/impeccable/{brand|product}.md`
+
+## Direct Execution
+
+1. Prerequisites ✓
+2. **Display execution info**:
+   ```
+   ── Command: {command} ────────────────────
+   Category: {category} | Target: {target}
+   ─────────────────────────────────────────
+   ```
+3. Read `~/.maestro/workflows/impeccable/{command}.md`
+4. **track_tasks tracking**: create todo items for each major phase in the workflow file
+   - Format: `[{command}] {phase description}`
+   - Mark each phase completed immediately upon finishing
+5. Follow workflow file instructions
+6. Post: suggest logical next command (teach→shape, shape→craft, craft→critique, etc.)
+
+## Chain Execution
+
+1. Prerequisites ✓
+2. **Display chain preview**: parse chain definition, output full step preview:
+   ```
+   ── Chain: build ──────────────────────────
+    1. teach        (conditional: PRODUCT.md missing)
+    2. explore      (conditional: DESIGN.md missing)
+    3. shape
+    4. craft
+    5. critique     ◆ quality gate (threshold: 26/40)
+    6. [refine]     ↺ auto-fix loop (max: 3)
+    7. audit        ◆ quality gate (threshold: 14/20)
+    8. polish
+   ─────────────────────────────────────────
+   Target: {target}
+   ```
+   - `◆` marks quality gate steps with threshold
+   - `↺` marks refine loop with max iteration count
+   - Conditional steps show trigger condition
+   - Skipped conditional steps marked `(skipped)`
+3. Create session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
+   ```json
+   { "chain_type": "...", "target": "...", "steps": [...], "current_step": 0,
+     "gate_history": [], "loop_count": 0, "status": "running" }
+   ```
+4. **track_tasks init**: create todo items for all chain steps
+   - One item per step, format: `[chain] step N: {command} — {description}`
+   - If conditional step is skipped, immediately mark completed
+   - Quality gate steps include threshold: `[chain] step 5: critique ◆ gate ≥26/40`
+5. For each step:
+   - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
+   - **Step start**: track_tasks marks current step in_progress
+   - **Step done**: track_tasks marks completed + update status.json (`current_step`, step `status`)
+   - **Step failed**: track_tasks marks completed (with note) + record reason
+6. **Quality gate** (critique/audit steps):
+   - Parse score: critique `**Total** | | **N/40**`, audit `**Total** | | **N/20**`
+   - Count `[P0]` / `[P1]` tags
+   - Pass: score ≥ threshold AND P0 == 0 → advance
+   - Fail: collect suggested commands from findings → execute → re-gate
+   - Max loops exceeded → force advance with warning
+   - track_tasks: record gate result in current step notes (score, P0/P1 count, pass/fail)
+7. Final report: scores + trend + commands executed
+
+## Resume
+
+Scan `.workflow/.maestro/ui-craft-*/status.json` for `status == "running"` → most recent → resume from `current_step`.
+
+## Quality Gate — Finding → Command Fallback
+
+When findings lack explicit suggested command:
+
+| Finding Category | Command |
+|-----------------|---------|
+| Layout, spacing, hierarchy, alignment | layout |
+| Color, contrast, palette | colorize |
+| Typography, font, readability | typeset |
+| Animation, motion, transitions | animate |
+| Copy, labels, UX writing | clarify |
+| Responsive, mobile, breakpoints | adapt |
+| Performance, loading, speed | optimize |
+| Complexity, overload, clutter | distill |
+| Bland, safe, generic | bolder |
+| Aggressive, overwhelming | quieter |
+| Onboarding, empty state | onboard |
+| Edge cases, i18n, error handling | harden |
+| Personality, memorability | delight |
+
+Never auto-select: teach, shape, craft, live, document, extract, overdrive, critique, audit.

package/.agents/skills/maestro-init/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: maestro-init
+description: Initialize project with auto state detection
+argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-roadmap (light mode, default) or maestro-roadmap --mode full (spec package) as the next step.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/init.md
+@~/.maestro/templates/project.md
+@~/.maestro/templates/state.json
+@~/.maestro/templates/config.json
+</required_reading>
+
+<context>
+**Flags:**
+- `-y` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
+- `--from-brainstorm SESSION-ID` -- Import from a brainstorm session. Reads guidance-specification.md to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning.
+
+**Load project state if exists:**
+Check for `.workflow/state.json` -- loads context if project already initialized.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/init.md' completely.
+
+**Report format on completion:**
+
+```
+=== WORKFLOW INITIALIZED ===
+Project: {project_name}
+State:   .workflow/state.json (active)
+
+Created:
+  .workflow/project.md
+  .workflow/state.json
+  .workflow/config.json
+  .workflow/specs/
+
+Next steps (choose one path to create roadmap):
+  /maestro-roadmap <requirement>                               -- Direct interactive roadmap (light, default)
+  /maestro-roadmap --mode full <idea>                          -- Full spec package + roadmap (heavy)
+
+Other commands:
+  /manage-status                                               -- View project dashboard
+  /maestro-brainstorm <topic>                                  -- Explore ideas first
+  /maestro-quick <task>                                        -- Quick ad-hoc task
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No arguments provided when -y requires @ reference | Check arguments format, re-run with correct input |
+| E002 | error | .workflow/ already exists for greenfield init | Check .workflow/ directory state, resolve conflicts |
+| E003 | error | Brainstorm session not found (--from-brainstorm) | Check arguments format, re-run with correct input |
+| W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results |
+</error_codes>
+
+<success_criteria>
+- [ ] Deep questioning completed (threads followed, not rushed) — or extracted from document/brainstorm
+- [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
+- [ ] `.workflow/state.json` created with artifacts[] array, initialized to idle state
+- [ ] `.workflow/config.json` created with user-selected granularity, workflow agents, gate preferences
+- [ ] `.workflow/specs/` initialized with convention files
+- [ ] Research completed (if enabled) — 4 parallel agents spawned
+- [ ] User knows next step is `/maestro-roadmap` (light) or `/maestro-roadmap --mode full` (spec package)
+</success_criteria>

package/.agents/skills/maestro-learn/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: maestro-learn
+description: Route learning intent to learn-* commands
+argument-hint: "<intent> [-y] [--dry-run] [--chain <name>]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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 invoke_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 ask_user:
+```
+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          → invoke_skill("learn-follow", "{target} {flags}")
+investigate     → invoke_skill("learn-investigate", "\"{target}\" {flags}")
+decompose       → invoke_skill("learn-decompose", "{target} {flags}")
+second-opinion  → invoke_skill("learn-second-opinion", "{target} {flags}")
+retro           → invoke_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 `invoke_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 invoke_skill()
+- [ ] Error handling: retry/skip/abort per step
+- [ ] Session summary displayed with next-step routing
+- [ ] No files modified outside `.workflow/knowhow/`
+</success_criteria>