maestro-flow 0.5.2 → 0.5.31

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

@@ -1,119 +1,122 @@
----
-name: maestro-update
-description: Detect version, preview changes, apply workflow upgrades
-argument-hint: "[--dry-run] [--force] [--setup-only]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Version router — detect current version, run schema migration to latest, then follow the version-specific smart upgrade workflow.
-
-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>
-$ARGUMENTS — optional flags.
-
-**Flags:**
-- `--dry-run` -- Preview migration plan without executing
-- `--force` -- Skip confirmation prompts
-- `--setup-only` -- Skip schema migration, run only the setup for current version
-
-**Version source:** `.workflow/state.json` → `version` field
-
-**Workflow docs:** `~/.maestro/workflows/updates/`
-- `update-v{TO}-setup.md` — post-migration setup for version {TO}
-
-**Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
-</context>
-
-<execution>
-
-### Step 1: Detect Version
-
-```
-1. Read .workflow/state.json → extract version (default "1.0" if missing)
-2. Display:
-   === Maestro Update ===
-   Current version: v{version}
-```
-
-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
-
-### Step 2: Check for Updates
-
-```
-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)
-```
-
-IF `--dry-run` → display info and EXIT.
-
-### Step 3: Execute
-
-```
-1. Confirm (unless --force):
-   AskUserQuestion: "Upgrade v{current} → v{target}?"
-   Options: [执行 / 取消]
-
-2. Create backup:
-   Bash: cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp}
-
-3. Run schema migration (handles all intermediate steps automatically):
-   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
-   Parse result, display changes.
-
-4. IF failed → display backup restore command → EXIT
-
-5. Load version-specific setup:
-   Read: ~/.maestro/workflows/updates/update-v{target}-setup.md
-   IF exists → follow completely (hooks, deps, knowledge system config)
-
-6. Display: "v{current} → v{target}: done"
-```
-
-### Step 4: Summary
-
-```
-=== Update Complete ===
-Version: v{current} → v{target}
-Backup:  .workflow/state.json.backup-v{current}-{timestamp}
-
-Next steps:
-  /manage-status  -- Verify project state
-  /maestro        -- Continue workflow
-```
-
-</execution>
-
-<success_criteria>
-- [ ] Current version detected from state.json
-- [ ] 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>
+---
+name: maestro-update
+description: Detect version, preview changes, apply workflow upgrades
+argument-hint: "[--dry-run] [--force] [--setup-only]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Detect current version, run schema migration to latest, then follow the version-specific upgrade workflow.
+Schema (`src/migrations/`) handles transforms; workflow docs (`~/.maestro/workflows/updates/`) handle setup.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+**Flags:**
+- `--dry-run` -- Preview migration plan without executing
+- `--force` -- Skip confirmation prompts
+- `--setup-only` -- Skip schema migration, run only the setup for current version
+
+**Version source:** `.workflow/state.json` → `version` field
+
+**Workflow docs:** `~/.maestro/workflows/updates/`
+- `update-v{TO}-setup.md` — post-migration setup for version {TO}
+
+**Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
+</context>
+
+<execution>
+
+### Step 1: Detect Version
+
+```
+1. Read .workflow/state.json → extract version (default "1.0" if missing)
+2. Display:
+   === Maestro Update ===
+   Current version: v{version}
+```
+
+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
+
+### Step 2: Check for Updates
+
+```
+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)
+```
+
+IF `--dry-run` → display info and EXIT.
+
+### Step 3: Execute
+
+```
+1. Confirm (unless --force):
+   AskUserQuestion: "Upgrade v{current} → v{target}?"
+   Options: [执行 / 取消]
+
+2. Create backup:
+   Bash: cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp}
+
+3. Run schema migration (handles all intermediate steps automatically):
+   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
+   Parse result, display changes.
+
+4. IF failed → display backup restore command → EXIT
+
+5. Load version-specific setup:
+   Read: ~/.maestro/workflows/updates/update-v{target}-setup.md
+   IF exists → follow completely (hooks, deps, knowledge system config)
+
+6. Display: "v{current} → v{target}: done"
+```
+
+### Step 4: Summary
+
+```
+=== Update Complete ===
+Version: v{current} → v{target}
+Backup:  .workflow/state.json.backup-v{current}-{timestamp}
+
+Next steps:
+  /manage-status  -- Verify project state
+  /maestro        -- Continue workflow
+```
+
+</execution>
+
+<success_criteria>
+- [ ] Current version detected from state.json
+- [ ] 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>
+
+<completion>
+### Next-step routing
+| Condition | Suggestion |
+|-----------|-----------|
+| Update complete | `/manage-status` to verify project state |
+| Want to continue workflow | `/maestro` |
+</completion>

package/.claude/commands/maestro.md

@@ -14,16 +14,8 @@ allowed-tools:
   - TodoWrite
 ---
 <purpose>
-Orchestrate all maestro commands based on user intent and project state.
-Classify intent → select chain → create session → dispatch to `maestro-ralph-execute`.
-
-Entry points:
-- **`/maestro "intent"`** — Intent-based: classify → chain → execute
-- **`/maestro -c`** — Resume previous session
-- **`/maestro --dry-run "intent"`** — Show chain, no execution
-- **`/maestro --super "intent"`** — Production-ready mode (read maestro-super.md)
-
-**Session**: `.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源。session_id 格式 `maestro-{YYYYMMDD-HHmmss}`（本 command 创建，静态链）或 `ralph-{YYYYMMDD-HHmmss}`（`/maestro-ralph` 创建，自适应链）。两类都由 `/maestro-ralph-execute` 推进；schema 与 ralph 共用（含 `ralph_protocol_version: "1"` + `active_step_index`）。
+Orchestrate all maestro commands: classify intent → select chain → create session → dispatch to `maestro-ralph-execute`.
+Session: `.workflow/.maestro/{session_id}/status.json`.
 </purpose>
 
 <deferred_reading>
@@ -50,7 +42,7 @@ $ARGUMENTS — user intent text, or special keywords.
 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 --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` 决定
+7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / ...；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` 写入
@@ -141,9 +133,9 @@ S_FALLBACK:
    - 正式规格/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
+   - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → quality pipeline
+   - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → quality pipeline
+   - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → quality pipeline
 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
@@ -159,7 +151,7 @@ S_FALLBACK:
 2. broad/medium → `AskUserQuestion` ≤3 轮：Scope / Constraints / Definition of Done
 3. 派生 `execution_criteria` + `task_decomposition`（每个 sub-goal 含 `done_when` + `evidence` + `lifecycle` + `completion_confirmed: false`）
 4. **status.json 唯一真源**：写入 `boundary_contract` / `execution_criteria` / `task_decomposition`；不生成 markdown 清单
-5. 在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前追加 `decision:post-goal-audit`。ralph-execute 在该节点按需动态生长 `steps[]`
+5. 在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前追加 `decision:post-goal-audit`。ralph-execute 在该节点按需动态生长 `steps[]`
 6. **输出 `/goal` 绑定提示词（不阻塞，用户可在执行过程中随时输入）：**
    ```
    📋 任务分解完成。可随时复制下面一行设定目标（执行过程中输入即可）：
@@ -221,7 +213,7 @@ S_FALLBACK:
 ### Success Criteria
 
 - [ ] Intent classified with task_type, complexity, clarity_score
-- [ ] Chain catalog 覆盖 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / quality pipeline
+- [ ] Chain catalog 覆盖 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / quality pipeline
 - [ ] `-y` 模式不触发 grill（交互式压力测试不支持自动模式，跳过直接走 brainstorm）
 - [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查
 - [ ] macro analyze 后跟 `decision:post-analyze-scope`（由 ralph 评估 scope_verdict 决定下游链路）

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

@@ -1,85 +1,87 @@
----
-name: manage-codebase-rebuild
-description: Rebuild all codebase documentation from scratch
-argument-hint: "[--focus <area>] [--force] [--skip-commit]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Perform a full rebuild of the .workflow/codebase/ documentation system from scratch. Scans the entire project source to identify components, features, requirements, and ADRs, then spawns parallel workflow-codebase-mapper agents to generate all documentation artifacts. This is a destructive operation that overwrites existing codebase docs.
-
-Can run before or after `/maestro-init` -- works on any codebase with source files. Also serves the previous `spec-map` use case via `--focus <area>` for scoped dimension analysis.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/codebase-rebuild.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags.
-
-**Flags:**
-- `--focus <area>` -- Scope mapper agents to a single domain (e.g., `auth`, `api`, `database`). When omitted, all 4 mappers run on the full codebase.
-- `--force` -- Skip confirmation prompt and proceed directly
-- `--skip-commit` -- Do not auto-commit after rebuild
-
-**Mapper agent assignments (when `--focus` omitted):**
-| Agent | Focus | Output file |
-|-------|-------|-------------|
-| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
-| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
-| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
-| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
-
-**State files:**
-- `.workflow/` -- must be initialized (project.md, state.json exist)
-- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
-- `.workflow/codebase/doc-index.json` -- generated documentation index
-- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
-
-**When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
-
-**Next-step routing on completion:**
-- View updated project state → `/manage-status`
-- Incremental updates later → `/quality-sync`
-- Verify KG stats → `maestro kg stats`
-- Verify wiki integration → `maestro search "kg" --type knowhow`
-- Future change impact → `maestro kg diff-wiki`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
-| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
-| W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
-| W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
-| W004 | warning | Wiki index rebuild failed after KG generation | Non-fatal, retries on next wiki access |
-</error_codes>
-
-<success_criteria>
-- [ ] User confirmed rebuild (or --force used)
-- [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
-- [ ] All 4 mapper agents spawned (failures logged as W001)
-- [ ] doc-index.json generated and valid
-- [ ] All documentation files regenerated
-- [ ] state.json updated with rebuild timestamp
-- [ ] project.md Tech Stack section updated if changes detected
-- [ ] 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 `/quality-sync` for incremental updates later
-- [ ] KG impact check available: `maestro kg diff-wiki` for future change impact analysis
-</success_criteria>
+---
+name: manage-codebase-rebuild
+description: Rebuild all codebase documentation from scratch
+argument-hint: "[--focus <area>] [--force] [--skip-commit]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Full rebuild of `.workflow/codebase/` docs: 4 parallel mapper agents → tech-stack, architecture, features, concerns. Destructive — overwrites existing docs.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/codebase-rebuild.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--focus <area>` -- Scope mapper agents to a single domain (e.g., `auth`, `api`, `database`). When omitted, all 4 mappers run on the full codebase.
+- `--force` -- Skip confirmation prompt and proceed directly
+- `--skip-commit` -- Do not auto-commit after rebuild
+
+**Mapper agent assignments (when `--focus` omitted):**
+| Agent | Focus | Output file |
+|-------|-------|-------------|
+| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
+| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
+| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
+| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
+
+**State files:**
+- `.workflow/` -- must be initialized (project.md, state.json exist)
+- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
+- `.workflow/codebase/doc-index.json` -- generated documentation index
+- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
+
+**When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
+
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| View updated state | `/manage-status` |
+| Incremental updates later | `/quality-sync` |
+| Verify KG stats | `maestro kg stats` |
+| Future change impact | `maestro kg diff-wiki` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
+| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
+| W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
+| W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
+| W004 | warning | Wiki index rebuild failed after KG generation | Non-fatal, retries on next wiki access |
+</error_codes>
+
+<success_criteria>
+- [ ] User confirmed rebuild (or --force used)
+- [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
+- [ ] All 4 mapper agents spawned (failures logged as W001)
+- [ ] doc-index.json generated and valid
+- [ ] All documentation files regenerated
+- [ ] state.json updated with rebuild timestamp
+- [ ] project.md Tech Stack section updated if changes detected
+- [ ] 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 routed
+</success_criteria>