maestro-flow 0.3.44 → 0.3.46

package/.claude/skills/maestro-help/phases/02-search-present.md

@@ -0,0 +1,181 @@
+# Phase 2: Search & Present
+
+查询 catalog.json 并格式化呈现结果。覆盖 Mode 1/2/3/6/7。
+
+## Objective
+
+- 根据 Phase 1 输出的 mode 和 query 搜索 catalog
+- 读取 source 文件获取详情（Mode 2）
+- 检测项目状态提供智能推荐（Mode 3）
+- 格式化呈现搜索结果
+
+## Execution
+
+### Mode 1: Command Search
+
+```
+1. Read catalog.json
+2. Search commands[] + cli_commands[]:
+   - Filter by: name contains query (case-insensitive)
+   - OR: description contains query
+   - OR: category matches query
+3. Sort by relevance (exact name match > starts with > contains)
+4. Present top 5 results:
+```
+
+**输出格式**:
+
+```markdown
+找到 {N} 个匹配命令：
+
+**/{command-name}** — {description}
+  分类: {category} | 详细: {source file exists? → "查看详情 →" : "catalog only"}
+
+**/{command-name-2}** — {description}
+  ...
+```
+
+### Mode 2: Command Documentation
+
+```
+1. Locate command in catalog.json commands[] by name
+2. Read the source file (e.g., "../../commands/maestro-analyze.md")
+3. Extract key sections:
+   - <purpose> content
+   - argument-hint
+   - usage examples from <context>
+4. If a guide file references this command, read relevant section
+5. Present structured documentation:
+```
+
+**输出格式**:
+
+```markdown
+## /{command-name}
+
+**用途**: {description}
+
+**参数**: {argument-hint}
+
+**用法**:
+{extracted examples or usage patterns}
+
+**分类**: {category}
+
+**相关 Guide**: {guide file name if applicable}
+```
+
+**Guide 映射**:
+
+| 命令 | Guide 文档 |
+|------|-----------|
+| maestro-analyze/plan/execute/verify | `guide/command-usage-guide.md` (主干管线) |
+| maestro-init/roadmap | `guide/quick-start-guide.md` |
+| maestro-ralph | `guide/maestro-ralph-guide.md` |
+| maestro (协调器) | `guide/maestro-coordinator-guide.md` |
+| manage-* | `guide/command-usage-guide.md` (管理) |
+| quality-* | `guide/command-usage-guide.md` (质量) |
+| delegate | `guide/delegate-async-guide.md` |
+| overlay/amend | `guide/overlay-guide.md` |
+
+### Mode 3: Smart Recommendations
+
+```
+1. Detect project state from Phase 1
+2. Match state to workflow template from catalog.workflows
+3. Present recommendations with WHY:
+```
+
+**状态 → 推荐映射**:
+
+| 当前状态 | 推荐命令 | 原因 |
+|---------|---------|------|
+| 无 .workflow/ | `/maestro-init` | 项目未初始化，需要先创建工作区 |
+| init 完成，无 roadmap | `/maestro-roadmap` | 需要路线图指导后续 Phase |
+| roadmap 完成，phase=pending | `/maestro-analyze` | 准备开始分析阶段 |
+| analyze 完成 | `/maestro-plan` | 分析完成，进入规划 |
+| plan 完成 | `/maestro-execute` | 规划完成，开始执行 |
+| execute 完成 | `/maestro-verify` | 执行完成，验证成果 |
+| verify 有 gaps | `/maestro-analyze --gaps` | 发现差距，重新分析 |
+| verify 通过 | `/quality-review` | 进入质量管线 |
+| quality 全通过 | `/maestro-milestone-audit` | 准备里程碑审计 |
+| 所有 Phase 完成 | `/maestro-milestone-complete` | 里程碑可以关闭 |
+
+### Mode 6: Skill & Agent Browsing
+
+**Skills**:
+```
+1. Read catalog.json skills[]
+2. If category specified: filter by category
+3. Group by category: meta / team / knowledge
+4. Present:
+```
+
+```markdown
+## Skills ({total} 个)
+
+### Meta (2)
+- **workflow-skill-designer** — 设计 orchestrator+phases 工作流 skill
+- **skill-iter-tune** — 迭代 execute-evaluate-improve 调优
+
+### Team (6)
+- **team-coordinate** — 通用团队协调，动态生成 role-specs
+- **team-executor** — 团队执行，恢复会话
+- **team-lifecycle-v4** — 8 角色完整生命周期
+- **team-quality-assurance** — QA 质量保障流水线
+- **team-review** — 多维度代码审查
+- **team-tech-debt** — 技术债务识别和清理
+- **team-testing** — 测试规划和执行
+
+### Knowledge (1)
+- **codify-to-knowhow** — Manifest 驱动的知识资产生成
+```
+
+**Agents**:
+```
+1. Read catalog.json agents[]
+2. Group by category: workflow / team / planning / cli / ui
+3. Present with category headers
+```
+
+### Mode 7: CLI Command Reference
+
+```
+1. Read catalog.json cli_commands[]
+2. Group by category: setup / dashboard / execution / knowledge / config / team / visualization
+3. Present table with command, alias, description:
+```
+
+```markdown
+## CLI 终端命令 (21 个)
+
+### 安装与更新 (setup)
+| 命令 | 别名 | 用途 |
+|------|------|------|
+| `maestro install` | — | 安装 Maestro 资源 |
+| `maestro uninstall` | — | 卸载已安装资源 |
+| `maestro update` | — | 检查/安装最新版本 |
+| `maestro launcher` | — | Claude Code 启动器 |
+
+### 任务执行 (execution)
+| 命令 | 别名 | 用途 |
+|------|------|------|
+| `maestro delegate` | — | 委派任务给 AI 智能体 |
+| `maestro coordinate` | `coord` | 图工作流协调器 |
+| `maestro cli` | — | 运行 CLI 智能体工具 |
+| `maestro run` | — | 执行指定工作流 |
+| `maestro serve` | — | 启动工作流服务器 |
+...
+```
+
+## Error Handling
+
+| 场景 | 处理 |
+|------|------|
+| 搜索无结果 | 模糊匹配最近命令，建议使用 `/maestro-help` 查看全部 |
+| Source 文件不存在 | 仅提供 catalog 描述，标注 "详细信息不可用" |
+| Catalog 读取失败 | 回退到 Glob 扫描 .claude/commands/*.md |
+
+## Output
+
+格式化的搜索/文档/推荐结果，直接展示给用户。

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

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

package/.codex/agents/team-supervisor.toml

@@ -0,0 +1,40 @@
+name = "team_supervisor"
+description = "Resident pipeline supervisor. Spawned once, woken via followup_task for checkpoint verification. Read-only."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are a resident pipeline supervisor (message-driven lifecycle).
+
+## Lifecycle
+Init -> idle -> [wake -> execute checkpoint -> idle]* -> shutdown
+
+Unlike team_worker (task-driven), you are message-driven:
+- Spawned once at session start
+- Woken by coordinator via followup_task with checkpoint requests
+- Stay alive across checkpoints, maintaining context continuity
+
+## Boot Protocol
+1. Parse role assignment from message (role_spec, session, session_id, requirement)
+2. Read role_spec to load checkpoint definitions
+3. Load baseline context (all role states, session state)
+4. Report ready via report_agent_job_result
+5. Wait for checkpoint requests via followup_task
+
+## Per Checkpoint
+1. Parse checkpoint request from followup_task message (task_id, scope)
+2. Read artifacts specified in checkpoint scope
+3. Load incremental context (new data since last wake)
+4. Optionally read worker progress milestones from team_msg for risk assessment
+5. Verify cross-artifact consistency per role.md definitions
+6. Issue verdict: pass (>= 0.8), warn (0.5-0.79), block (< 0.5)
+7. Write report to discoveries/{checkpoint_id}.json
+8. Report findings via report_agent_job_result
+
+## Constraints
+- Read-only: never modify source artifacts
+- Never issue pass when critical inconsistencies exist
+- Never block for minor style issues
+- Only communicate with coordinator
+"""

package/.codex/agents/team-worker.toml

@@ -0,0 +1,63 @@
+name = "team_worker"
+description = "Generic team worker agent. Role-specific behavior loaded from role.md at spawn time via message parameter."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+You are a team worker agent. You execute a specific role within a team pipeline.
+
+## Boot Protocol
+1. Parse role assignment from message (role, role_spec path, session, session_id, requirement)
+2. Read role_spec file to load Phase 2-4 domain instructions
+3. Read session state from session path
+4. Execute built-in Phase 1 (task discovery from tasks.json)
+5. Execute role-specific Phase 2-4 defined in role.md
+6. Report progress milestones via team_msg at phase boundaries
+7. Write deliverables to session artifacts directory
+8. Write findings to discoveries/{task_id}.json
+9. Report completion via team_msg type="task_complete" + report_agent_job_result
+
+## Task State
+- tasks.json is source of truth (NOT CSV)
+- Filter tasks by your role prefix + status=pending + no blocked deps
+- Update task status in tasks.json (pending -> in_progress -> completed)
+
+## Inner Loop
+If inner_loop=true, process ALL same-prefix tasks sequentially:
+  Phase 1 -> Phase 2-4 -> Phase 5-L (loop) -> repeat
+  Until no more same-prefix pending tasks -> Phase 5-F (final report)
+
+## Progress Milestones
+Report progress via mcp__maestro-tools__team_msg at natural phase boundaries:
+- type="progress" with progress_pct, phase, status
+- type="blocker" immediately on errors (don't wait for next milestone)
+- type="task_complete" after report_agent_job_result
+See agent-instruction.md "Progress Milestone Protocol" for format.
+
+## Output Schema
+{
+  "id": "<task_id>",
+  "status": "completed | failed",
+  "role": "<role_name>",
+  "findings": "<max 500 chars>",
+  "artifact": "<artifact_path>",
+  "files_modified": [],
+  "error": ""
+}
+
+## Constraints
+- Only process tasks matching your role prefix
+- Never modify tasks outside your scope
+- Report to coordinator via team_msg + report_agent_job_result
+- Use CLI tools (maestro delegate) or direct tools for exploration
+
+## Maestro Delegate Execution (MANDATORY)
+When calling `maestro delegate` via exec_command:
+1. Set yield_time_ms: 30000 (initial 30s wait)
+2. If session_id returned (command still running) → poll with write_stdin(session_id, chars="", yield_time_ms=15000→60000) in a loop
+3. NEVER skip polling, NEVER abandon — delegate output is required
+4. Increase poll interval: 15s → 30s → 60s (cap)
+5. Parse result only after command completes
+Protocol: @~/.maestro/workflows/delegate-protocol.codex.md
+"""

package/.codex/skills/codify-to-knowhow/SKILL.md

@@ -56,7 +56,7 @@ $codify-to-knowhow ".workflow/reference_style/my-style-v1"
 - `<package-path>` (positional, required): Directory containing `knowhow-manifest.json`
 
 **Upstream**: `maestro-ui-codify`, `learn-decompose`, or any skill that generates a manifest
-**Downstream**: `maestro wiki list --role implement`, `maestro spec load --keyword <slug>`
+**Downstream**: `maestro wiki list --category coding`, `maestro spec load --keyword <slug>`
 </context>
 
 <manifest_schema>
@@ -396,7 +396,7 @@ Ref Links: spec -> knowhow bridge established
 Wiki Index: refreshed
 
 Next steps:
-  maestro wiki list --role implement    # Browse by role
+  maestro wiki list --category coding    # Browse by role
   maestro spec load --keyword {slug}    # Load related specs
   maestro wiki load <id>                # Load full entry
 ```

package/.codex/skills/maestro-analyze/SKILL.md

@@ -208,7 +208,7 @@ Create both directories.
    - Read `.workflow/state.json` → `current_milestone`, `artifacts[]`, `accumulated_context`
    - Find prior analyze artifacts from `state.json.artifacts[]` (type=analyze, same milestone) → load their `context.md`
    - Find brainstorm artifacts from `state.json.artifacts[]` (type=brainstorm, same milestone) → load `guidance-specification.md`
-   - Load project specs: `maestro spec load --role plan`
+   - Load project specs: `maestro spec load --category arch`
 
 3. **Quick mode routing**: If QUICK_MODE, generate only wave 3 (synthesis/decide) task in CSV. Skip exploration and scoring.
 

package/.codex/skills/maestro-brainstorm/SKILL.md

@@ -192,7 +192,7 @@ mkdir -p {sessionFolder}/.brainstorming
 **Decomposition Rules**:
 
 1. **Mode detection**: Number = phase mode (resolve via state.json artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`), text = scratch mode
-2. **Project specs loading**: Read `.workflow/specs/` for architecture-aware analysis context
+2. **Project specs loading**: Run `maestro spec load --category arch` for architecture-aware analysis context and discoverable knowhow tools
 3. **Role selection**:
 
 | Condition | Action |

package/.codex/skills/maestro-collab/SKILL.md

@@ -208,7 +208,7 @@ Mark each eligible tool as `recommended: true/false` based on auto-selection.
 
 **3. Context loading**:
 - Read `.workflow/project.md` if exists
-- Load project specs: `maestro spec load --role implement` (if available)
+- Load project specs: `maestro spec load --category coding` (if available)
 - Grep for relevant codebase files based on requirement keywords
 
 **4. Build delegate prompt** (shared across all tools):

package/.codex/skills/maestro-execute/SKILL.md

@@ -207,7 +207,7 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 4. **Build tasks.csv**: For each pending task per wave, read `.task/TASK-{NNN}.json` and extract: title, description, scope (from files), convergence.criteria, hints, execution_directives. Set `deps` from task dependency, `context_from` = deps, `wave` from plan.json.
 
-5. **Load project specs**: Read `.workflow/specs/` for coding conventions and architecture constraints (passed to all agents)
+5. **Load project specs + tools**: Run `maestro spec load --category coding` to load coding conventions, architecture constraints, AND discoverable knowhow tools (passed to all agents)
 
 6. **Load codebase + wiki context** (optional, passed to all agents):
    - If `.workflow/codebase/ARCHITECTURE.md` exists: read and include as `codebase_context` in agent instructions