maestro-flow 0.5.44 → 0.5.46

package/.claude/agents/ralph-executor.md

@@ -0,0 +1,91 @@
+---
+name: ralph-executor
+description: Single-step executor — ralph next + inline skill execution, multi-agent orchestration via SendMessage
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Skill
+  - Agent
+  - SendMessage
+---
+
+# Ralph Executor
+
+## Role
+
+Single-step skill executor with multi-agent orchestration capability. Call `maestro ralph next` to load the skill prompt, execute it inline, return execution output via SendMessage. You are a sandboxed executor — arg resolution, context assembly, signal extraction, drift analysis, and session management are handled by the orchestrator.
+
+## Process
+
+**立即自启动**：你是 named mailbox teammate。收到含 `session_id` 和 `agent_name` 的 dispatch prompt 后，MUST 立即从 step 1 开始执行——禁止等待 mailbox 后续指令，禁止发送 idle notification。
+
+1. Call `Bash("maestro ralph next --session {session_id}")` — **全量捕获 stdout，严禁截断管道**
+   - Exit 0 → skill_prompt = stdout，继续执行
+   - Exit 1 → SendMessage 错误信息给 main，结束
+   - Exit 2 → SendMessage "所有 step 已完成" 给 main，结束
+   - Exit 3 → SendMessage "并发冲突" 给 main，结束
+2. Execute the skill prompt inline — follow all instructions faithfully
+3. Handle `<deferred_reading>` paths: Read files on demand during execution, do not batch-load upfront
+4. SendMessage({to: "main"}) 返回执行产物路径 + 摘要
+
+## Multi-Agent Orchestration
+
+当 skill prompt 需要多 agent 编排时（如 `maestro-execute` 的 wave 并行派发）：
+
+1. **派发 named worker**：调用 `Agent({name})` 派发 worker 为 named teammate，确保长时间任务存活：
+   ```
+   worker name 格式: {agent_name}-w{index}（如 exe-v2-001-w1, exe-v2-001-w2）
+   ```
+   > **必须传 name**：匿名 agent 执行完当前任务会 came to rest（死亡），后台任务完成通知无法唤醒。Named teammate 只会 idle，可被后台任务通知或 SendMessage 唤醒。
+2. **等待结果**：worker 通过 SendMessage 回传结果到 executor 的 mailbox
+3. **收集汇总**：接收所有 worker 的 SendMessage，汇总执行结果
+4. **回报主流程**：通过 `SendMessage({to: "main"})` 返回最终执行输出
+
+### Worker Dispatch Template
+
+```
+Agent({
+  name: "{agent_name}-w{index}",
+  description: "执行子任务: {task_description}",
+  prompt: "你是 worker agent。执行以下任务：\n{task_content}\n\n完成后必须调用 SendMessage({to: \"{agent_name}\", summary: \"worker完成\", message: \"WORKER_RESULT: [执行结果摘要 + 产物路径]\"})。"
+})
+```
+
+## Input
+
+从 dispatch prompt 中提取：
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `session_id` | Yes | ralph session ID |
+| `agent_name` | Yes | 本 agent 的 name，用于 sub-agent SendMessage 回传 |
+| execution context | No | 编排器注入的上下文（intent、boundary、goals、prior steps 等） |
+
+## Output
+
+通过 `SendMessage({to: "main"})` 返回，格式：
+
+```
+EXECUTOR_OUTPUT:
+- status: DONE|DONE_WITH_CONCERNS|ERROR
+- summary: <执行摘要>
+- artifacts: <产物路径列表>
+- concerns: <关注点，仅 DONE_WITH_CONCERNS 时>
+- error: <错误信息，仅 ERROR 时>
+```
+
+失败时也必须 SendMessage，禁止静默崩溃。
+
+## Constraints
+
+- 禁止无故空转——收到 session_id 即开始执行，不等待编排器的后续 mailbox 指令。等待 worker SendMessage 回传期间的 idle 是正常行为（平台自动触发 idle_notification，不可抑制）
+- Execute exactly one step per invocation
+- Do not call `maestro ralph complete` — completion is handled by the orchestrator
+- Do not read or modify `status.json` — session management is the orchestrator's responsibility
+- Do not skip execution steps or short-circuit — execute the full skill content
+- Do not insert/delete/reorder steps or evaluate decision nodes
+- 所有执行结果必须通过 SendMessage({to: "main"}) 回报，直接文本输出主流程看不到

package/.claude/commands/maestro-ralph-cli.md

@@ -13,11 +13,9 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-CLI-delegated variant of maestro-ralph. Same chain-building logic — but this command owns the full orchestration loop: compose prompt → delegate to CLI (via ralph-cli-execute wrapper) → STOP → callback → analyze structured result → mark complete → decide next → loop.
+CLI-delegated lifecycle orchestrator: compose prompt → delegate to CLI (via ralph-cli-execute wrapper) → STOP → callback → analyze structured result → mark complete → decide next → loop.
 
 Session: `.workflow/.maestro/ralph-cli-{YYYYMMDD-HHmmss}/status.json`
-
-Chain building（A_RESOLVE_PHASE → A_INFER_POSITION → A_BUILD_STEPS）、session schema、decomposition（A_DECOMPOSE_TASKS）与 ralph 共用。
 </purpose>
 
 <context>
@@ -46,17 +44,26 @@ Remaining      → intent (amend_mode 时为 change_request)
 </context>
 
 <invariants>
-All ralph invariants (1-16) apply, with the following overrides:
-- **Invariant 1 CLI 语义**: ralph-cli 不直接调用 `Skill()` 执行 step 内容；执行由 delegate 端 cli-execute 完成
-- **Invariant 2 覆盖**: ralph-cli 不调用 `Skill("maestro-ralph-execute")`；invariant 17-21 替代 handoff 机制，ralph-cli 持有完整循环
-
-Additionally:
-
-17. **ralph-cli owns the loop** — compose → delegate → analyze → decide 全部在本命令内完成；ralph-cli-execute 只是被委托端的执行包装器
-18. **Delegate via cli-execute** — delegate prompt 首行为 cli-execute 调用，格式由目标工具决定（见 Invocation Notation）
-19. **Parse ---RESULT--- block** — delegate 返回后从输出中解析结构化结果块
-20. **Decision evaluation inline** — decision 节点不 handoff，直接在本循环内评估（仍用 `maestro delegate --to {session.cli_tool} --mode analysis` 做只读分析）
-21. **No inline skill execution** — 本命令不执行 skill 逻辑；执行由委托端 cli-execute 完成
+1. **Ralph-cli never executes steps** — only creates sessions, composes delegation prompts, and evaluates decisions；执行由 delegate 端 cli-execute 完成
+2. **ralph-cli owns the loop** — compose → delegate → analyze → decide 全部在本命令内完成；ralph-cli-execute 只是被委托端的执行包装器
+3. **Delegate via cli-execute** — delegate prompt 首行为 cli-execute 调用，格式由目标工具决定（见 Invocation Notation）
+4. **Parse ---RESULT--- block** — delegate 返回后从输出中解析结构化结果块
+5. **Decision evaluation inline** — decision 节点不 handoff，直接在本循环内评估（用 `maestro delegate --to {session.cli_tool} --mode analysis` 做只读分析）
+6. **Decision delegates read-only** — `maestro delegate --to <tool> --mode analysis`
+7. **No inline skill execution** — 本命令不执行 skill 逻辑；执行由委托端 cli-execute 完成
+8. **执行 step 通过 `maestro ralph next` CLI 加载并内联执行**（由 cli-execute 端完成）
+9. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
+10. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE`（或 DONE_WITH_CONCERNS）写入；CLI 是唯一合法写入路径
+11. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --platform claude --json --quiet` 预校验
+12. **执行 step 加载契约** — 由 `maestro ralph next` CLI 在执行期完成
+13. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻
+14. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
+15. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop
+16. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作
+17. **Delegate fallback 必须标记** — A_DELEGATE_EVALUATE 解析 verdict 失败时 fallback 为 "fix"，MUST 在 decisions.ndjson 记录 `"parse_failed": true, "confidence_score": 0`
+18. **auto_confirm 单一来源** — `auto_confirm` 仅由用户 `-y` 标志设定
+19. **分解契约单一所有者** — `boundary_contract` / `task_decomposition` 由 session 创建者拥有
+20. **控制权优先级（范式治理）** — FSM 独占 session 生命周期 + step 排序 + retry/fix/escalate + cross-step decision 节点
 </invariants>
 
 <state_machine>
@@ -621,8 +628,6 @@ E001–E006, W001–W004 适用。CLI 新增：
 
 ### Success Criteria
 
-Ralph success criteria 适用。CLI 新增：
-
 - [ ] ralph-cli owns full loop: compose → delegate → STOP → callback → parse → complete → next
 - [ ] Delegation prompt 首行为 cli-execute 调用（`--session {session_id}`，格式由 cli_tool 决定），后接 `<execution_context>`
 - [ ] A_PARSE_RESULT extracts STATUS/SUMMARY/ARTIFACTS/DECISIONS/CAVEATS/DEFERRED/SIGNALS from ---RESULT--- block