maestro-flow 0.4.25 → 0.5.0

package/.claude/commands/maestro-ui-codify.md

@@ -56,6 +56,26 @@ If specs not initialized, continue without — the workflow still produces valid
 Route to `~/.maestro/workflows/ui-codify.md` and follow completely.
 
 The workflow orchestrates 4 phases with deferred loading of phase-specific workflow files. Each phase reads its workflow file only when execution reaches that phase.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE Phase 1 → Phase 2**: Source path validated, file discovery completed. design-tokens.json generated.
+**GATE Phase 2 → Phase 3**: layout-templates.json generated with component patterns.
+**GATE Phase 3 → Phase 4**: preview.html + preview.css generated as interactive showcase.
+**GATE Phase 4 → Completion**: knowhow-manifest.json created. codify-to-knowhow called and completed.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "design-tokens.json",      // Phase 1
+  "layout-templates.json",   // Phase 2
+  "preview.html",            // Phase 3
+  "preview.css",             // Phase 3
+  "knowhow-manifest.json"    // Phase 4
+]
+```
+If any artifact is missing: DO NOT report completion.
 </execution>
 
 <error_codes>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-update
 description: Detect version, preview changes, apply workflow upgrades
-argument-hint: "[--dry-run] [--force]"
+argument-hint: "[--dry-run] [--force] [--setup-only]"
 allowed-tools:
   - Read
   - Write
@@ -12,9 +12,13 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Detect the current `.workflow/` schema version, show available migrations, and interactively apply them step-by-step. Uses a migration registry that supports incremental version upgrades (e.g., 1.0 → 2.0 → 3.0).
+Version router — detect current version, run schema migration to latest, then follow the version-specific smart upgrade workflow.
 
-Each migration step is previewed before execution. The user confirms each step in a loop.
+Migration scripts live in two layers:
+- **Schema** (`src/migrations/`): code-level state.json transforms, auto-chained by registry
+- **Workflow** (`~/.maestro/workflows/updates/`): version-specific upgrade guides with environment setup
+
+Schema migrations handle the mechanical version bump. Workflow docs handle the smart part — what the user needs to know, configure, or verify for that version. The router runs schema first, then loads the matching workflow doc.
 </purpose>
 
 <context>
@@ -22,131 +26,80 @@ $ARGUMENTS — optional flags.
 
 **Flags:**
 - `--dry-run` -- Preview migration plan without executing
-- `--force` -- Skip confirmation prompts (apply all pending migrations)
+- `--force` -- Skip confirmation prompts
+- `--setup-only` -- Skip schema migration, run only the setup for current version
 
-**Migration registry:** `src/migrations/`
-- Each migration is a standalone file (e.g., `v1-to-v2.ts`) exporting a `MigrationDef`
-- All migrations are registered via `src/migrations/index.ts`
-- Registry auto-chains: detects current version → walks chain → applies in order
-- To add a new migration: create `src/migrations/v{N}-to-v{N+1}.ts`, register in `index.ts`
+**Version source:** `.workflow/state.json` → `version` field
 
-**CLI runner:** `src/migrations/run.ts`
-- Executable entrypoint: `npx tsx src/migrations/run.ts [root] [--dry-run] [--force] [--json]`
-- Outputs JSON (with `--json`) or human-readable text
+**Workflow docs:** `~/.maestro/workflows/updates/`
+- `update-v{TO}-setup.md` — post-migration setup for version {TO}
 
-**State version source:** `.workflow/state.json` → `version` field
+**Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
 </context>
 
 <execution>
 
-### Step 1: Detect Current State
+### Step 1: Detect Version
 
 ```
-1. Read .workflow/state.json
-2. Extract version field (default "1.0" if missing)
-3. Display:
-
-   === Maestro Workflow Update ===
-   Project:  {project_name}
-   Version:  {version}
-   Location: {.workflow/ path}
+1. Read .workflow/state.json → extract version (default "1.0" if missing)
+2. Display:
+   === Maestro Update ===
+   Current version: v{version}
 ```
 
-### Step 2: Dry-Run Preview
-
-Run the migration CLI in dry-run + JSON mode to get the full plan:
+IF `--setup-only`:
+  → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
+  → IF exists: follow that document completely, then EXIT
+  → IF not exists: display "No setup script for v{version}" → EXIT
 
-```bash
-npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
-```
+### Step 2: Check for Updates
 
-Parse the JSON output. If status is `up-to-date`:
 ```
-Already up to date (v{version})
-```
-→ EXIT
-
-Otherwise display the migration plan:
+1. Run: npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
+2. Parse JSON output
+3. IF status = "up-to-date":
+     Display "Already up to date (v{version})"
+     → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
+     → IF exists: AskUserQuestion "Run setup for v{version}?" → load and follow
+     → EXIT
+
+4. Display target:
+   Update available: v{current} → v{target}
+   Schema migrations: {N} step(s) (handled automatically)
 ```
-Pending Migrations ({N} step(s)):
-
-  1. [v{from} → v{to}] {name}
-     {description}
-
-  2. [v{from} → v{to}] {name}
-     {description}
-```
-
-If `--dry-run` flag was passed by user → display plan and EXIT.
 
-### Step 3: Interactive Confirmation Loop
+IF `--dry-run` → display info and EXIT.
 
-For each migration step (unless `--force`):
+### Step 3: Execute
 
 ```
-LOOP for step_index = 1 to N:
+1. Confirm (unless --force):
+   AskUserQuestion: "Upgrade v{current} → v{target}?"
+   Options: [执行 / 取消]
 
-  Display:
-    --- Step {step_index}/{N}: {name} ---
-    Version: v{from} → v{to}
+2. Create backup:
+   Bash: cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp}
 
-    Changes:
-      {description, indented}
+3. Run schema migration (handles all intermediate steps automatically):
+   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
+   Parse result, display changes.
 
-  IF NOT --force:
-    AskUserQuestion: "Apply this migration?"
-    Options: [yes / skip / abort]
+4. IF failed → display backup restore command → EXIT
 
-    - "yes"   → proceed to Step 4 (execute)
-    - "skip"  → WARN "Skipping may break the migration chain"
-                 continue to next step
-    - "abort" → display summary of what was applied so far → EXIT
+5. Load version-specific setup:
+   Read: ~/.maestro/workflows/updates/update-v{target}-setup.md
+   IF exists → follow completely (hooks, deps, knowledge system config)
 
-  IF --force:
-    → proceed to Step 4 (execute)
+6. Display: "v{current} → v{target}: done"
 ```
 
-### Step 4: Execute Single Migration
+### Step 4: Summary
 
 ```
-1. Create backup:
-   Bash: cp .workflow/state.json .workflow/state.json.backup-v{from}-{timestamp}
-
-2. Run migration:
-   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
-   
-   NOTE: The runner executes ALL pending migrations. For step-by-step control,
-   read state.json, call the migration function directly, or use the runner
-   which stops on first failure.
-
-3. Parse result JSON and display:
-
-   {status_icon} Step {N} completed: {name}
-   Summary: {summary}
-   Changes:
-     - {change_1}
-     - {change_2}
-     - ...
-
-4. If failed:
-   Display: "Migration failed: {summary}"
-   Display: "Backup available at: {backup_path}"
-   Display: "Restore with: cp {backup_path} .workflow/state.json"
-   → EXIT
-
-5. Continue loop to next step
-```
-
-### Step 5: Summary
-
-After all steps completed (or user aborted):
-
-```
-=== Migration Complete ===
-Applied: {applied_count} / {total_count} migration(s)
-Skipped: {skipped_count}
-Version: v{original} → v{final}
-Backup:  .workflow/state.json.backup-v{original}-{timestamp}
+=== Update Complete ===
+Version: v{current} → v{target}
+Backup:  .workflow/state.json.backup-v{current}-{timestamp}
 
 Next steps:
   /manage-status  -- Verify project state
@@ -155,22 +108,12 @@ Next steps:
 
 </execution>
 
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/state.json not found | Run /maestro-init first |
-| E002 | error | state.json parse error | Check file for corruption |
-| E003 | error | Migration function failed | Restore from backup |
-| W001 | warning | Skipped migration may break version chain | Re-run /maestro-update later |
-| W002 | warning | tsx not available | Install tsx: npm i -D tsx |
-</error_codes>
-
 <success_criteria>
 - [ ] Current version detected from state.json
-- [ ] Dry-run preview shows full migration plan without execution
-- [ ] Each step confirmed interactively (unless --force)
-- [ ] Backup created before each migration
-- [ ] Migration executed and result displayed with change list
-- [ ] Abort stops cleanly with partial summary
-- [ ] Summary shows applied/skipped counts and version change
+- [ ] Schema migrations run automatically (no manual intermediate steps)
+- [ ] Backup created before migration
+- [ ] Version-specific setup doc loaded and followed (if exists)
+- [ ] --setup-only runs only setup for current version
+- [ ] --dry-run previews without executing
+- [ ] Summary shows version change and backup path
 </success_criteria>

package/.claude/commands/maestro.md

@@ -49,12 +49,14 @@ $ARGUMENTS — user intent text, or special keywords.
 3. **Auto flag pass-through** — 仅当用户传入 `-y` 时透传 `-y` 到 skill args
 4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)。Reference maestro-ralph `A_DECOMPOSE_TASKS`
 5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单
-6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global）；decision 节点不走 CLI，走 `Skill("maestro-ralph")` handoff
+6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global，限定 `.claude/`）；decision 节点不走 CLI，走 `Skill("maestro-ralph")` handoff
 7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
 8. **Grill is interactive-only** — `-y` auto mode MUST skip grill stage and route directly to brainstorm; grill requires Socratic Q&A with the user
 9. **D-007 milestone 反查** — 数字 phase 的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
 10. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入
 11. **schema** — `ralph_protocol_version: "1"` 标记 CLI-driven session；新增字段全部可选
+12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作，不可绕过。特别是 invariant 1（dispatch via ralph-execute）和 invariant 2（session before execution）和 invariant 10（completion_confirmed 由 CLI 写入）为硬约束。
+13. **Classification evidence** — S_CLASSIFY 的 chain 选择决策 MUST 记录到 status.json 的 `classification_rationale` 字段：匹配了哪个 pattern、排除了哪些备选、confidence level。无记录的分类不可进入 S_CREATE。
 </invariants>
 
 <state_machine>
@@ -135,13 +137,14 @@ S_FALLBACK:
 3. Select chain from chainMap，遵循拓扑约束：
    - 压力测试/拷问/验证假设/grill/stress-test → `grill`（**-y 模式跳过 grill，直接走 brainstorm**）
    - 头脑风暴/探索 → `brainstorm`
+   - 学习/阅读代码/跟读/follow → `Skill("learn-follow")`；调查/为什么/investigate → `Skill("learn-investigate")`；分解/模式/decompose → `Skill("learn-decompose")`；评审/挑战/second-opinion → `Skill("learn-second-opinion")`；回顾/retro → `Skill("quality-retrospective")`
    - 正式规格/spec-generate/7-phase → `blueprint`
    - 项目初始化 → `init`
    - 宽/中等意图 + 无数字 phase → `analyze-macro`（产 scope_verdict，由 ralph 在 `post-analyze-scope` 决定是否插入 roadmap+analyze 或直跳 plan --from analyze）
    - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → `verify {phase}` → quality pipeline
    - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → verify
    - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → verify
-4. 执行 step：`Bash("maestro ralph skills --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
+4. 执行 step：`Bash("maestro ralph skills --platform claude --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
 
 ### A_CLARIFY
 
@@ -228,7 +231,7 @@ S_FALLBACK:
 - [ ] Chain selected and confirmed (or auto-confirmed)
 - [ ] Session dir created with status.json before execution; decomposition fields additive-only
 - [ ] 执行 step 含 `command_scope` + `command_path` + `completion_confirmed`；decision step 由 `step.decision` 标识
-- [ ] `command_scope`/`command_path` 由 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global）
+- [ ] `command_scope`/`command_path` 由 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global）
 - [ ] Session schema 含 `ralph_protocol_version: "1"` + `active_step_index: null` + step.load 占位
 - [ ] 用户传入 `-y` 时透传到 skill args
 - [ ] All chains dispatched via maestro-ralph-execute

package/.claude/commands/manage-codebase-rebuild.md

@@ -53,9 +53,9 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 
 **Next-step routing on completion:**
 - View updated project state → `/manage-status`
-- Incremental updates later → `/manage-codebase-refresh`
+- Incremental updates later → `/quality-sync`
 - Verify KG stats → `maestro kg stats`
-- Verify wiki integration → `maestro wiki list --keyword kg`
+- Verify wiki integration → `maestro search "kg" --type knowhow`
 - Future change impact → `maestro kg diff-wiki`
 </execution>
 
@@ -80,6 +80,6 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 - [ ] KG pipeline executed (`maestro kg index`)
 - [ ] knowledge-graph.json generated in .workflow/codebase/
 - [ ] KG nodes indexed as virtual wiki entries (automatic via WikiIndexer on next wiki access)
-- [ ] Next step routing: `/manage-status` or `/manage-codebase-refresh` for incremental updates later
+- [ ] Next step routing: `/manage-status` or `/quality-sync` for incremental updates later
 - [ ] KG impact check available: `maestro kg diff-wiki` for future change impact analysis
 </success_criteria>

package/.claude/commands/manage-harvest.md

@@ -53,7 +53,7 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 
 **Next-step routing on completion:**
 - Review wiki entries → `maestro wiki list --type note`
-- Connect wiki graph → `/wiki-connect --fix`
+- Connect wiki graph → `/manage-wiki connect --fix`
 - Triage issues → `/manage-issue list --source harvest`
 - View specs → `/spec-load --role implement`
 - Full retrospective → `/quality-retrospective`

package/.claude/commands/manage-knowhow-capture.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 <purpose>
 Capture reusable knowledge into `.workflow/knowhow/` with type-specific structured fields.
-Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro knowhow search`.
+Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --type knowhow`.
 </purpose>
 
 <required_reading>
@@ -38,8 +38,9 @@ $ARGUMENTS — type token + description + optional flags.
 | `asset`/`ast`/`资产`/`契约` | asset | AST- | assetType, codePaths, category |
 | `blueprint`/`blp`/`蓝图` | blueprint | BLP- | codePaths, category |
 | `document`/`doc`/`文档` | document | DOC- | (general fallback) |
+| `insight`/`ins`/`洞察`/`经验` | insight | INS- | content, tags, phase (replaces former manage-learn) |
 | Short text + `--tag` | tip | TIP- | — |
-| No args | — | — | AskUserQuestion (9 options) |
+| No args | — | — | AskUserQuestion (10 options) |
 
 **Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter (title, type, category, created, tags, source, lang, status)
 </context>

package/.claude/commands/manage-knowhow.md

@@ -13,9 +13,11 @@ allowed-tools:
 ---
 <purpose>
 Unified memory management across two stores:
-1. **Workflow knowhow** (`.workflow/knowhow/`) — Session compacts and tips with JSON index, created by `manage-knowhow-capture`
+1. **Workflow knowhow** (`.workflow/knowhow/`) — Session compacts, tips, insights, and all reusable knowledge, created by `manage-knowhow-capture`
 2. **System memory** (`~/.claude/projects/{project}/memory/`) — Claude Code auto-memory (MEMORY.md + topic files), persists across conversations
 
+Also scans `.workflow/specs/learnings.md` for legacy insight entries (backward compat with former `manage-learn`).
+
 Provides list/search/view/edit/delete/prune operations. Default store is `all` (show both).
 </purpose>
 

package/.claude/commands/manage-wiki.md

@@ -1,7 +1,7 @@
 ---
 name: manage-wiki
 description: Manage wiki graph — health, cleanup, search, stats
-argument-hint: "<subcommand: health|search|cleanup|stats> [query] [--fix] [--dry-run]"
+argument-hint: "<subcommand: health|search|cleanup|stats|connect|digest> [query] [--fix] [--dry-run]"
 allowed-tools:
   - Read
   - Write
@@ -12,9 +12,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, and graph statistics — the day-to-day operations that keep the knowledge graph healthy.
-
-Complements `/wiki-connect` (link discovery) and `/wiki-digest` (synthesis) with operational tooling.
+Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, graph statistics, link discovery, and knowledge synthesis — the single entry point for all wiki graph operations.
 </purpose>
 
 <required_reading>
@@ -31,16 +29,26 @@ $ARGUMENTS — subcommand and optional flags.
 | `search <query>` | Interactive BM25 search with follow-up actions |
 | `cleanup` | Find and resolve orphans, broken links, stale entries |
 | `stats` | Graph statistics — type distribution, tag frequency, growth trends |
+| `connect` | Find and link hidden connections — orphan rescue, missing links, transitive gaps |
+| `digest [topic]` | Generate knowledge digest with theme clustering and gap analysis |
 | No args | Same as `health` |
 
 **Flags:**
 - `--type <type>` — Filter by wiki type: spec, knowhow, note, issue
-- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
+- `--fix` — Auto-fix issues found during cleanup/connect (remove broken links, apply connections)
 - `--json` — Output in JSON format
+- `--min-similarity N` — (connect) Minimum similarity threshold for link candidates
+- `--max N` — (connect) Maximum number of suggestions
+- `--format brief|full` — (digest) Output format
+- `--recent N` — (digest) Scope to N most recent entries
+- `--create-issues` — (digest) Create issues for identified knowledge gaps
 </context>
 
 <execution>
-Follow '~/.maestro/workflows/wiki-manage.md' completely.
+**Subcommand routing:**
+- `health|search|cleanup|stats` → Follow `~/.maestro/workflows/wiki-manage.md` completely.
+- `connect` → Follow `~/.maestro/workflows/wiki-connect.md` completely (Stages 1-6).
+- `digest` → Follow `~/.maestro/workflows/wiki-digest.md` completely (Stages 1-8).
 </execution>
 
 <error_codes>
@@ -54,9 +62,10 @@ Follow '~/.maestro/workflows/wiki-manage.md' completely.
 </error_codes>
 
 <success_criteria>
-- [ ] Subcommand parsed (health/search/cleanup/stats)
+- [ ] Subcommand parsed (health/search/cleanup/stats/connect/digest)
 - [ ] Wiki data loaded via `maestro wiki` CLI
 - [ ] Results displayed in formatted output
-- [ ] If cleanup --fix: issues resolved and delta reported
+- [ ] If cleanup/connect --fix: issues resolved and delta reported
+- [ ] If digest: themes clustered, gaps identified, coverage heatmap generated
 - [ ] Next-step suggestions provided
 </success_criteria>

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