maestro-flow-one 0.2.10 → 0.2.12

package/maestro-flow/commands/lifecycle/analyze.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-analyze
-description: Multi-angle analysis with CLI-assisted exploration
+description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
 argument-hint: "[phase|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
 allowed-tools:
   - Read

package/maestro-flow/commands/lifecycle/brainstorm.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-brainstorm
-description: Brainstorm with auto pipeline or single-role analysis
+description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
 argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
 allowed-tools:
   - Read

package/maestro-flow/commands/lifecycle/collab.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-collab
-description: Multi-CLI collaborative analysis -- fan-out to multiple CLI tools, cross-verify, synthesize
-argument-hint: "\"<requirement>\" [--tools gemini,qwen,claude] [--mode analysis|write] [--rule <template>] [-y]"
+description: Use when a question needs cross-verification from multiple CLI tools or diverse analytical perspectives
+argument-hint: "<requirement> [--tools gemini,qwen,claude] [--mode analysis|write] [--rule <template>] [-y]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/lifecycle/composer.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-composer
 description: Compose reusable workflow templates from natural language
-argument-hint: "\"workflow description\" [--resume] [--edit <template-path>]"
+argument-hint: "<workflow-description> [--resume] [--edit <template-path>]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/lifecycle/execute.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-execute
-description: Execute plan with parallel waves and atomic commits
+description: Use when a confirmed plan is ready for implementation
 argument-hint: "[phase] [--auto-commit] [--method agent|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
 allowed-tools:
   - Read
@@ -98,6 +98,15 @@ Next steps:
   /manage-status               -- View project dashboard
 ```
 
+**Completion status:**
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {failed_count} tasks failed (if any)
+NEXT: /maestro-verify
+--- END STATUS ---
+```
+
 If failed tasks exist, suggest /quality-debug for investigation.
 </execution>
 

package/maestro-flow/commands/lifecycle/guard.md

@@ -0,0 +1,101 @@
+---
+name: maestro-guard
+description: Manage editing boundary restrictions
+argument-hint: "<on|off|status|allow <path>|deny <path>>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+<purpose>
+Configure directory-level write boundaries enforced by the workflow-guard PreToolUse hook.
+When enabled, Write and Edit tool calls targeting files outside allowed paths are blocked.
+
+Subcommands:
+- **on** — Enable path guard (defaults to `src/` if no paths configured)
+- **off** — Disable path guard (preserves path list)
+- **status** — Show current guard configuration
+- **allow `<path>`** — Add a directory to the allowed paths list
+- **deny `<path>`** — Switch to deny mode and add path to deny list
+</purpose>
+
+<context>
+$ARGUMENTS — Parse subcommand and optional path argument.
+
+**Config location:** `.workflow/config.json` → `guard` section
+
+```json
+{
+  "guard": {
+    "enabled": false,
+    "mode": "allow",
+    "paths": []
+  }
+}
+```
+
+**Enforcement:** The `workflow-guard` hook (PreToolUse on Write/Edit) reads this config
+and blocks operations targeting files outside boundaries. Requires hooks level >= `full`.
+</context>
+
+<execution>
+
+**Step 1: Parse subcommand**
+
+Extract from $ARGUMENTS:
+- `on` / `off` / `status` / `allow <path>` / `deny <path>`
+- If no subcommand, default to `status`
+
+**Step 2: Read config**
+
+Read `.workflow/config.json`. If file missing, initialize with empty guard section.
+
+**Step 3: Execute subcommand**
+
+**`status`:**
+- Display: enabled/disabled, mode (allow/deny), paths list
+- Check if workflow-guard hook is active (read `.claude/settings.json` for hook presence)
+- If guard enabled but hook not active, warn: "⚠ PathGuard enabled but workflow-guard hook not installed. Run `maestro hooks level full` to activate."
+
+**`on`:**
+- Set `guard.enabled = true`
+- If `guard.paths` is empty, set default: `["src/", "tests/", ".workflow/"]`
+- Check hook level, warn if < full
+- Write config
+
+**`off`:**
+- Set `guard.enabled = false`
+- Preserve existing paths and mode
+- Write config
+
+**`allow <path>`:**
+- Normalize path to forward slashes, ensure trailing slash for directories
+- If `guard.mode` is `deny`, switch to `allow` and clear paths with warning
+- Add path to `guard.paths` (deduplicate)
+- Set `guard.enabled = true` if not already
+- Write config
+
+**`deny <path>`:**
+- Normalize path to forward slashes
+- Set `guard.mode = "deny"`
+- Add path to `guard.paths` (deduplicate)
+- Set `guard.enabled = true` if not already
+- Write config
+
+**Step 4: Confirm**
+
+Display updated guard configuration.
+
+</execution>
+
+<error_codes>
+- E001: `.workflow/config.json` not found and cannot be created (not a maestro project)
+- W001: PathGuard enabled but workflow-guard hook not installed
+</error_codes>
+
+<success_criteria>
+- [ ] Config read/written correctly
+- [ ] Hook level warning displayed when applicable
+- [ ] Updated configuration shown after changes
+</success_criteria>

package/maestro-flow/commands/lifecycle/impeccable.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-impeccable
-description: Production-grade UI design — 24 commands + chain orchestration with quality gates + design search
-argument-hint: "<command|chain|intent> [target] [flags]"
+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
   - Write

package/maestro-flow/commands/lifecycle/learn.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-learn
 description: Route learning intent to learn-* commands
-argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
+argument-hint: "<intent> [-y] [--dry-run] [--chain <name>]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/lifecycle/overlay.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-overlay
 description: Create or edit command overlays from natural language
-argument-hint: "<intent>"
+argument-hint: "<intent> — 描述要添加的规则或步骤，如 'always verify after execute'"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/lifecycle/plan.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-plan
-description: Plan phase execution with exploration and verification
-argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--dir <path>] [--revise [instructions]] [--check <plan-dir>]"
+description: Use when creating, revising, or verifying an execution plan for a phase or task
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--revise [instructions]] [--check <plan-dir>]"
 allowed-tools:
   - Read
   - Write
@@ -122,6 +122,19 @@ Next steps:
   /maestro-plan {phase}         -- Re-plan with modifications
 ```
 
+**Completion status:**
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|NEEDS_CONTEXT
+CONCERNS: {description if applicable}
+NEXT: /maestro-execute
+--- END STATUS ---
+```
+
+Status mapping:
+- **DONE** — Plan created/revised and confirmed → NEXT: /maestro-execute
+- **NEEDS_CONTEXT** — Ambiguous requirements, insufficient context to produce plan
+
 ### Mode: Revise / Check
 
 Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.

package/maestro-flow/commands/lifecycle/quick.md

@@ -9,7 +9,7 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
-  - Task
+  - Agent
   - AskUserQuestion
 ---
 <purpose>

package/maestro-flow/commands/lifecycle/tools-execute.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-tools-execute
 description: Load and execute tool specs by category or name
-argument-hint: "[tool-name | --category <category>]"
+argument-hint: "[<tool-name> | --category <category>] [--list]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/lifecycle/tools-register.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-tools-register
 description: Register tool specs - extract, generate, or optimize
-argument-hint: "[description]"
+argument-hint: "[<description>] [--extract <path>] [--optimize <name>]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/lifecycle/verify.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-verify
-description: Verify goals with must-have checks and test coverage validation
+description: Use after execution to verify goals are actually achieved with evidence-based structural checks
 argument-hint: "[phase] [--skip-tests] [--skip-antipattern] [--dir <path>]"
 allowed-tools:
   - Read
@@ -70,6 +70,20 @@ On confirm → `Skill("spec-add", "<category> <content>")`.
 
 **Gap-fix closure loop:**
 Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
+
+**Completion status:**
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+NEXT: /quality-review
+--- END STATUS ---
+```
+
+Status mapping:
+- **DONE** — All checks pass, no gaps → NEXT: /quality-review
+- **DONE_WITH_CONCERNS** — Gaps found (must-have failures or anti-pattern blockers) → NEXT: /maestro-execute (after /maestro-plan --gaps)
+- **NEEDS_RETRY** — Verification could not complete (missing artifacts, corrupt data)
 </execution>
 
 <error_codes>

package/maestro-flow/commands/manage/issue-discover.md

@@ -1,7 +1,7 @@
 ---
 name: manage-issue-discover
 description: Discover issues via multi-perspective analysis
-argument-hint: "[multi-perspective | by-prompt \"what to look for\"] [-y|--yes] [--scope=src/**] [--depth=standard|deep]"
+argument-hint: "[multi-perspective | by-prompt <prompt>] [-y] [--scope <glob>] [--depth standard|deep]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/manage/issue.md

@@ -1,7 +1,7 @@
 ---
 name: manage-issue
 description: Create, query, update, close, and link issues
-argument-hint: "<create|list|status|update|close|link> [options]"
+argument-hint: "<subcommand: create|list|status|update|close|link> [--title text] [--severity S] [--status S] [--resolution text]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/manage/knowhow-capture.md

@@ -1,7 +1,7 @@
 ---
 name: manage-knowhow-capture
 description: Capture reusable knowledge as templates, recipes, or tips
-argument-hint: "[type] [description] [--lang <lang>] [--source <url>] [--tag tag1,tag2]"
+argument-hint: "[<type>] [<description>] [--lang <lang>] [--source <url>] [--tag t1,t2]"
 allowed-tools:
   - Read
   - Write
@@ -47,6 +47,8 @@ $ARGUMENTS — type token + description + optional flags.
 <execution>
 Follow '~/.maestro/workflows/knowhow.md' completely.
 
+**Tags language rule**: Tags must match content language. Chinese content → Chinese tags (如 `认证,令牌,刷新`). English content → English tags. Mixed → bilingual.
+
 **Type-specific content rules**:
 
 | Type | Content extraction |

package/maestro-flow/commands/manage/knowhow.md

@@ -1,7 +1,7 @@
 ---
 name: manage-knowhow
 description: Manage knowhow entries (workflow and system)
-argument-hint: "[list|search|view|edit|delete|prune] [query|id|file] [--store workflow|system|all] [--tag tag] [--type compact|tip]"
+argument-hint: "<subcommand: list|search|view|edit|delete|prune> [query|id] [--store workflow|system|all] [--tag <tag>] [--type compact|tip]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/manage/learn.md

@@ -1,7 +1,7 @@
 ---
 name: manage-learn
 description: Capture and search learning insights and tips
-argument-hint: "[<text>|tip <text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
+argument-hint: "[<text> | tip <text> | list | search | show <id>] [--category <cat>] [--tag t1,t2] [--phase N]"
 allowed-tools:
   - Read
   - Write

package/maestro-flow/commands/manage/status.md

@@ -1,6 +1,7 @@
 ---
 name: manage-status
 description: Show project dashboard with progress and next steps
+argument-hint: ""
 allowed-tools:
   - Read
   - Bash

package/maestro-flow/commands/manage/wiki.md

@@ -1,7 +1,7 @@
 ---
 name: manage-wiki
 description: Manage wiki graph — health, cleanup, search, stats
-argument-hint: "[health|search|cleanup|stats] [options]"
+argument-hint: "<subcommand: health|search|cleanup|stats> [query] [--fix] [--dry-run]"
 allowed-tools:
   - Read
   - Write

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

@@ -1,9 +1,8 @@
 ---
 name: quality-auto-test
-description: Auto-generate and run tests from specs or coverage gaps
-argument-hint: "<phase> [-y] [-c N] [--max-iter <N>] [--layer <L0-L3>] [--strategy <name>] [--dry-run] [--re-run]"
+description: Use when test coverage needs automated expansion or existing tests need iterative convergence
+argument-hint: "<phase> [-y] [-c N] [--max-iter N] [--layer L0|L1|L2|L3] [--dry-run] [--re-run]"
 allowed-tools:
-  - spawn_agents_on_csv
   - Read
   - Write
   - Edit

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

@@ -1,6 +1,6 @@
 ---
 name: quality-debug
-description: Debug with parallel hypotheses and root cause analysis
+description: Use when bugs, test failures, or unexpected behavior need systematic root cause investigation
 argument-hint: "[issue description] [--from-uat <phase>] [--parallel]"
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: quality-refactor
-description: Reduce tech debt with reflection-driven iteration
+description: Use when accumulated tech debt needs systematic identification and safe reduction
 argument-hint: "[<scope>]"
 allowed-tools:
   - Read
@@ -9,7 +9,7 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
-  - Task
+  - Agent
   - AskUserQuestion
 ---
 <purpose>

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

@@ -1,6 +1,6 @@
 ---
 name: quality-retrospective
-description: Phase retrospective with insight routing to specs and knowhow
+description: Use after completing a phase to extract lessons, patterns, and improvement opportunities
 argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: quality-review
-description: Tiered code review with severity classification
+description: Use after execution to evaluate code quality across correctness, security, performance, and architecture
 argument-hint: "<phase> [--level quick|standard|deep] [--dimensions security,architecture,...] [--skip-specs]"
 allowed-tools:
   - Read
@@ -87,6 +87,20 @@ Report format and next-step routing by verdict defined in workflow review.md Rep
 - PASS → `/quality-test {phase}`
 - WARN → `/quality-test {phase}` (proceed with caveats)
 - BLOCK → `/maestro-plan {phase} --gaps` (fix critical findings first)
+
+**Completion status:**
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+NEXT: /quality-refactor
+--- END STATUS ---
+```
+
+Status mapping:
+- **DONE** — PASS verdict, no critical findings → NEXT: /quality-refactor
+- **DONE_WITH_CONCERNS** — WARN verdict, issues found but non-blocking → NEXT: /maestro-verify
+- **NEEDS_RETRY** — BLOCK verdict, critical findings require fix first
 </execution>
 
 <error_codes>

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

@@ -1,6 +1,6 @@
 ---
 name: quality-test
-description: Conversational UAT with auto-diagnosis and gap closure
+description: Use when implementation needs user acceptance testing with interactive verification and gap closure
 argument-hint: "[phase] [--smoke] [--auto-fix]"
 allowed-tools:
   - Read
@@ -40,6 +40,11 @@ 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>`
+- Specs + tools: `maestro spec load --category test` → test conventions + discoverable knowhow tools
+
 **Test tool discovery** (knowhow tools as scenario source):
 - Load registered test tools: `maestro spec load --category test --keyword <feature>`
 - If tools found, extract their steps as additional test scenarios marked `source: "tool"`

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

@@ -31,11 +31,14 @@ Scope-to-directory mapping, category-to-file mapping, and entry format defined i
 
 **Examples:**
 ```bash
-# Standard spec entry
+# English content → English keywords
 /spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
 
-# Spec with ref to detailed knowhow
-/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --ref knowhow/RCP-oauth-pkce.md --keywords "oauth,pkce"
+# Chinese content → Chinese keywords (匹配中文 prompt)
+/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
+
+# Mixed → bilingual keywords
+/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --ref knowhow/RCP-oauth-pkce.md --keywords "oauth,pkce,认证,授权"
 
 /spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
 ```

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

@@ -19,9 +19,6 @@ All output lands in `.workflow/specs/`.
 @~/.maestro/workflows/specs-setup.md
 </required_reading>
 
-<deferred_reading>
-</deferred_reading>
-
 <context>
 $ARGUMENTS (no arguments expected)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "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"