maestro-flow 0.4.26 → 0.5.1

package/.agents/skills/maestro-ralph-execute/SKILL.md

@@ -203,8 +203,7 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 
      [✓] 0.   maestro-plan 1            [global]
      [✓] 1.   maestro-execute 1         [project]
-     [✓] 2.   maestro-verify 1          [global]
-     [✓] 3. ◆ post-verify               [decision]
+     [✓] 2. ◆ post-execute               [decision]
      ...
    ============================================================
    ```

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

@@ -63,13 +63,13 @@ maestro-analyze    ─┘ context-package.json
         ↓
 maestro-roadmap → .workflow/roadmap.md (Milestone > Phase hierarchy)
         ↓
-maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
+maestro-analyze {phase} → maestro-plan → maestro-execute
 ```
 
 ### Pre-load
 
 1. **Specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
-2. **Wiki search**: `maestro wiki search "{requirement keywords}" --json` → prior knowledge
+2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge
 3. All optional — proceed without if unavailable
 </context>
 
@@ -94,6 +94,32 @@ Sub-modes:
 - **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
 - **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
 
+### Phase Gates (MANDATORY, BLOCKING — Create mode)
+
+**GATE 1: Input → Decomposition**
+- REQUIRED: Requirement parsed with goal, constraints, stakeholders.
+- REQUIRED: Upstream context loaded via --from (if specified).
+
+**GATE 2: Decomposition → Refinement**
+- REQUIRED: Milestones defined with deliverable targets.
+- REQUIRED: Phases defined within milestones with dependencies.
+- REQUIRED: Every Active requirement from project.md mapped to exactly one phase.
+- REQUIRED: No circular dependencies in phase ordering.
+
+**GATE 3: Refinement → Completion**
+- REQUIRED: User approved roadmap (or auto-approved with -y).
+- REQUIRED: `.workflow/roadmap.md` written with Milestone > Phase hierarchy.
+- REQUIRED: Artifact registered in state.json with milestone entries.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  ".workflow/roadmap.md"    // Milestone > Phase hierarchy with progress table
+]
+```
+If missing: DO NOT report completion.
+
 </execution>
 
 <completion>

package/.agents/skills/maestro-swarm-workflow/SKILL.md

@@ -28,7 +28,7 @@ Scripts: `~/.maestro/workflows/swarm/wf-*.js`
 | `wf-analyze` | maestro-analyze | explore → 6-dim scoring → **skeptic cross-verify** → **3-way advocacy (go/no-go/conditional) + referee** |
 | `wf-brainstorm` | maestro-brainstorm | multi-role analysis → **3-specialist cross-review** → **3-proposal competition** → **arbitrator** |
 | `wf-review` | quality-review | 6-dim scan → **3-vote adversarial verify (prosecutor/defense/judge)** → **3-perspective report + arbitrated verdict** |
-| `wf-verify` | maestro-verify | 3-layer + antipattern + convergence → **prosecutor vs defender debate** → **judge verdict** |
+| `wf-verify` | maestro-execute (verification gate) | 3-layer + antipattern + convergence → **prosecutor vs defender debate** → **judge verdict** |
 | `wf-grill` | maestro-grill | explore → parallel branch stress → **meta-skeptic challenge** → **3-vote verdict (optimist/pessimist/realist)** |
 | `wf-plan` | maestro-plan | parallel context → **3-strategy competing proposals** → **judge panel scoring** → **3-critic adversarial check** |
 | `wf-execute` | maestro-execute | wave-based parallel execution → **adversarial convergence spot-check** → **3-vote status determination** |
@@ -230,7 +230,7 @@ Ralph 可以在 A_BUILD_STEPS 中将某些 step 的执行方式标记为 `swarm-
   "args": "--script wf-analyze {phase}",
   "stage": "analyze",
   "command_scope": "project",
-  "command_path": "<resolved by maestro ralph skills>"
+  "command_path": "<resolved by maestro ralph skills --platform agent>"
 }
 ```
 

package/.agents/skills/maestro-tools-register/SKILL.md

@@ -67,7 +67,7 @@ Parse $ARGUMENTS to determine mode:
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
 **Promote mode** (existing knowhow → tool):
-- Locate document: `maestro wiki list --keyword <name>` or by path in `.workflow/knowhow/`
+- Locate document: `maestro search "<name>" --type knowhow` or by path in `.workflow/knowhow/`
 - Read document, verify it contains actionable steps (numbered list or ## Steps section)
 - If no actionable steps, suggest extract mode instead
 - Determine category (Step 3) and summary ("Use when ...")
@@ -130,7 +130,7 @@ summary: "Use when <timing>. <scope description>"
 **Optionally register spec ref entry** for index discoverability:
 ```bash
 maestro spec add <category> "<title>" "Use when <timing>. <scope summary>" --keywords "<csv>" \
-  --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
+  --description "<one-line summary>" --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
 ```
 
 ### Step 6: Verify

package/.agents/skills/maestro-ui-codify/SKILL.md

@@ -58,6 +58,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/.agents/skills/maestro-update/SKILL.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_file
   - write_file
@@ -14,9 +14,13 @@ allowed-tools:
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
 <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>
@@ -24,131 +28,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: ask_user "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):
+   ask_user: "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:
-    ask_user: "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
@@ -157,22 +110,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/.agents/skills/manage-codebase-rebuild/SKILL.md

@@ -55,9 +55,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>
 
@@ -82,6 +82,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/.agents/skills/manage-harvest/SKILL.md

@@ -55,7 +55,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/.agents/skills/manage-knowhow/SKILL.md

@@ -15,9 +15,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/.agents/skills/manage-knowhow-capture/SKILL.md

@@ -15,7 +15,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>
@@ -25,7 +25,7 @@ Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro knowhow sear
 <context>
 $ARGUMENTS — type token + description + optional flags.
 
-**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
+**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--description <desc>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
 
 **Type routing** (first token match):
 
@@ -40,15 +40,18 @@ $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 | — | — | ask_user (9 options) |
+| No args | — | — | ask_user (10 options) |
 
-**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter (title, type, category, created, tags, source, lang, status)
+**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{slug}.md` with YAML frontmatter (title, description, type, category, created, tags, source, lang, status)
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/knowhow.md' completely.
 
+**Description rule**: Every entry MUST have a `description` field in frontmatter — a one-line summary (under 120 chars) for search results. WikiIndexer uses priority chain: `description > content[:240]`. Use `--description` flag value if provided; otherwise auto-generate from content.
+
 **Tags language rule**: Tags must match content language. Chinese content → Chinese tags (如 `认证,令牌,刷新`). English content → English tags. Mixed → bilingual.
 
 **Type-specific content rules**:

package/.agents/skills/manage-wiki/SKILL.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_file
   - write_file
@@ -14,9 +14,7 @@ allowed-tools:
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
 <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>
@@ -33,16 +31,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>
@@ -56,9 +64,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/.agents/skills/quality-auto-test/SKILL.md

@@ -57,7 +57,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>
@@ -93,13 +93,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/.agents/skills/quality-debug/SKILL.md

@@ -47,9 +47,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>
@@ -83,13 +83,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 → `invoke_skill("spec-add", "<category> <content>")`.
+On confirm → `invoke_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/.agents/skills/quality-refactor/SKILL.md

@@ -35,7 +35,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>
@@ -44,7 +44,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 `invoke_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 `invoke_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/.agents/skills/quality-retrospective/SKILL.md

@@ -24,7 +24,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>
@@ -41,7 +41,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 `invoke_skill({ skill: "manage-learn", args: "tip ..." })`.
+4. **Reuse `manage-knowhow-capture tip` for note routing** — do not duplicate the learning pipeline; invoke via `invoke_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.
@@ -57,7 +57,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>
 
@@ -71,9 +71,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 `invoke_skill({ skill: "manage-learn", args: "tip ..." })`
+- [ ] Note tips (if any) created via `invoke_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>