maestro-flow 0.5.2 → 0.5.31

package/workflows/skill-authoring.md

@@ -1,265 +1,265 @@
-# SKILL.md Authoring Standard
-
-<purpose>
-SKILL.md 的编写规范。核心原则：SKILL.md 是给 LLM agent 执行的状态机定义，不是给人读的操作手册。
-</purpose>
-
----
-
-## 1. Architecture: Hybrid State Machine
-
-采用"骨架状态机 + 肉身散文"的混合架构。顶层用显式状态转移定义控制流，ACTIONS 内部用结构化散文指导具体操作。
-
-### File Structure
-
-```
----
-frontmatter (name, description, argument-hint, allowed-tools)
----
-
-<purpose>           <!-- 1-5 行：目标 + 拓扑图 + 入口点 -->
-<context>           <!-- 用法示例、flag 说明 -->
-<invariants>        <!-- 全局底线规则，独立于状态转移 -->
-
-<state_machine>
-  <states>          <!-- 显式声明所有状态节点 -->
-  <transitions>     <!-- 每个状态的转移规则 -->
-  <actions>         <!-- 具体操作逻辑，结构化散文 -->
-</state_machine>
-
-<appendix>          <!-- 查阅型内容：schema、error codes、examples、success criteria -->
-```
-
-### Why Hybrid
-
-- **纯状态机**（6.5/10）：过度缩写导致 LLM 卡死或幻觉操作，丢失执行语境
-- **纯散文**（5/10）：LLM 需"阅读理解"提取转移条件，注意力分散，上下文寻址迷失
-- **混合**（8.5/10）：状态机路由 + 散文动作，兼顾确定性和可理解性
-
----
-
-## 2. Section Specifications
-
-### `<invariants>` — Global Guard Rails
-
-保留为独立段落，不打散到 transitions 中。这些是 LLM 的系统级底线指令，无论处于哪个状态都必须遵守。
-
-```markdown
-<invariants>
-1. CSV is Source of Truth — 所有状态持久化在 CSV/JSON，不在内存
-2. Wave Order is Sacred — 永远不执行 wave N+1 直到 wave N 完成
-3. Coordinator Never Executes — 只组装 prompt + spawn，不直接执行 skill 逻辑
-</invariants>
-```
-
-**规则**：
-- 只放跨状态的全局约束
-- 绑定到特定转移的条件放 `<transitions>` 的 GUARD 中
-- 每条 invariant 必须可验证（有明确的违反判定条件）
-
-### `<states>` — Explicit State Declaration
-
-显式声明所有状态节点，每个节点含 1 行 rationale + PERSIST 字段。
-
-```markdown
-<states>
-S_INIT          — 解析参数、路由入口           PERSIST: session.status
-S_INFER         — 推断生命周期位置             PERSIST: session.lifecycle_position
-S_BUILD_CHAIN   — 构建步骤链                   PERSIST: session.steps[]
-S_CONFIRM       — 用户确认（auto_mode 跳过）   PERSIST: —
-S_WAVE_LOOP     — 构建并执行下一波             PERSIST: session.waves[], session.current_step
-S_DECISION      — 委托评估 + 应用裁决          PERSIST: session.passed_gates[], step.retry_count
-S_FIX_LOOP      — 插入修复步骤并重索引          PERSIST: session.steps[] (expanded)
-S_COMPLETE      — 标记完成、释放目标            PERSIST: session.status = "completed"
-S_PAUSED        — 暂停等待人工介入              PERSIST: session.status = "paused"
-S_FALLBACK      — 兜底：条件不匹配时请求输入    PERSIST: session.status = "paused"
-</states>
-```
-
-**规则**：
-- 每个 state 必须有 `PERSIST` 字段，明确写哪些 session/status/csv 字段
-- `S_FALLBACK` 必须存在——当所有 WHEN 条件不满足时进入此状态，调用 `request_user_input`
-- Rationale 限 1 行，不展开
-
-### `<transitions>` — State Transition Rules
-
-每个状态列出所有出边，格式：`→ TARGET  WHEN: condition  [GUARD: constraint]  DO: action_ref`
-
-```markdown
-<transitions>
-
-S_INIT:
-  → S_INFER         WHEN: intent is non-empty
-  → S_WAVE_LOOP     WHEN: intent == "execute" | "continue"
-  → S_FALLBACK      WHEN: no intent AND no running session
-
-S_INFER:
-  → S_BUILD_CHAIN   WHEN: position resolved
-  → S_FALLBACK      WHEN: cannot infer position         DO: show raw state
-
-S_WAVE_LOOP:
-  → S_DECISION      WHEN: next_step.type == "decision"
-  → S_WAVE_LOOP     WHEN: next_step.type == "external"  DO: A_BUILD_AND_SPAWN_WAVE
-  → S_COMPLETE      WHEN: no pending steps
-  → S_PAUSED        WHEN: step failed
-                     GUARD: auto_mode → retry once then pause
-
-S_DECISION:
-  → S_WAVE_LOOP     WHEN: verdict == "proceed"          DO: add to passed_gates
-  → S_FIX_LOOP      WHEN: verdict == "fix"              DO: A_INSERT_FIX_LOOP
-  → S_PAUSED        WHEN: verdict == "escalate"
-  → S_WAVE_LOOP     WHEN: structural(post-milestone) + has next milestone
-                                                         DO: A_ADVANCE_MILESTONE
-  GUARD: retry_count >= max_retries → force escalate
-  GUARD: confidence_score < 60 + proceed → override to fix
-
-</transitions>
-```
-
-**规则**：
-- 转移条件用 `WHEN`，绑定到特定转移的约束用 `GUARD`
-- 动作引用 `DO: A_XXX`，具体逻辑在 `<actions>` 中定义
-- 每个 state 必须有到 `S_FALLBACK` 或 `S_PAUSED` 的兜底路径
-- 条件必须互斥且穷尽（覆盖所有可能）
-
-### `<actions>` — Operation Definitions
-
-每个 ACTION 独立定义，内部使用结构化散文 + 伪代码。不压缩为纯 DSL。
-
-```markdown
-<actions>
-
-### A_BUILD_AND_SPAWN_WAVE
-
-1. buildNextWave: barrier → solo CSV; non-barrier → batch until decision node
-2. buildSkillCall per step: resolve placeholders, apply enrichment table, append auto flags
-3. Write wave-{N}.csv
-4. spawn_agents_on_csv({ csv_path, instruction, max_workers, output_csv_path })
-5. Merge results into master, delete wave CSV
-6. Update session: current_step, waves[], context fields
-
-Enrichment table:
-| Skill | Args | Source |
-|-------|------|--------|
-| maestro-plan | --dir {analyze_artifact_path} | state.json artifacts |
-| maestro-execute | --dir {plan_artifact_path} | state.json artifacts |
-| quality-debug | "{gap_summary}" | decision verdict |
-
-### A_INSERT_FIX_LOOP
-
-1. Clear passed_gates (code will change)
-2. Select fix-loop template by decision type (see Appendix: Fix-Loop Templates)
-3. Insert steps after current position
-4. Reindex all steps
-5. Write status.json
-
-</actions>
-```
-
-**规则**：
-- ACTION 名称以 `A_` 前缀，与 transitions 中的 `DO:` 引用对应
-- 内部用编号步骤，不用散文段落
-- 数据映射用表格，不用散文描述
-- 每个 ACTION 必须明确输入/输出和副作用（写了什么文件）
-
----
-
-## 3. Shared Primitives
-
-### MACRO: RUN_CSV_WAVE
-
-三个 skill（ralph、plan、execute）共享的 CSV 波执行逻辑，抽为标准子程序：
-
-```markdown
-### MACRO: RUN_CSV_WAVE(wave_rows, session_folder, instruction_builder)
-
-1. Filter pending rows for target wave
-2. Build prev_context from completed predecessor findings
-3. Write wave-{N}.csv with prev_context column
-4. spawn_agents_on_csv({
-     csv_path: wave-{N}.csv,
-     instruction: instruction_builder(context),
-     output_csv_path: wave-{N}-results.csv
-   })
-5. Merge results into master CSV
-6. Delete wave-{N}.csv
-7. Return: updated master CSV rows
-```
-
-各 skill 通过不同的 `instruction_builder` 和上下文参数调用此 MACRO，不重复描述流程。
-
----
-
-## 4. `<appendix>` — Reference-Only Content
-
-以下内容移出主流程，放入 appendix 供按需查阅：
-
-| Section | Content |
-|---------|---------|
-| CSV Schema | 列定义、示例行 |
-| Worker Contract | 子 agent instruction 模板、output schema |
-| Fix-Loop Templates | 各 decision type 的修复步骤链 |
-| Discovery Board Protocol | 类型定义、去重规则 |
-| Error Codes | 错误码 + 恢复策略 |
-| Success Criteria | 验收检查项 |
-| Golden Examples | 典型执行路径的完整示例 |
-
----
-
-## 5. Implementation Plan
-
-### Order
-
-1. **Pilot**: `maestro-ralph/SKILL.md` — 本质是 adaptive state machine，收益最大
-2. **Extract**: 抽 `MACRO: RUN_CSV_WAVE` 共享子程序
-3. **Rollout**: `maestro-plan` 和 `maestro-execute` 用 Phase Cards 轻量整理（不必完整状态机化）
-
-### Phase Cards（适用于 plan/execute）
-
-对于线性 pipeline 型 skill，用 Phase Cards 代替完整状态机：
-
-```markdown
-<phases>
-
-PHASE P1_RESOLVE_INPUT:
-  DO: parse args, resolve phase dir, load context
-  NEXT: P2_BUILD_CSV
-  FAIL: abort with error
-
-PHASE P2_BUILD_CSV:
-  DO: generate tasks.csv from plan/exploration angles
-  NEXT: P3_RUN_WAVES
-  FAIL: abort
-
-PHASE P3_RUN_WAVES:
-  DO: MACRO:RUN_CSV_WAVE per wave (sequential)
-  NEXT: P4_AGGREGATE
-  FAIL: mark failed, pause
-
-PHASE P4_AGGREGATE:
-  DO: export results, update state, generate report
-  NEXT: END
-
-</phases>
-```
-
-### Safety Protocol
-
-- 第一版将原散文移入 `<appendix>`，不删除
-- 跑 3-5 次真实 skill 调用后评估效果，再压缩 appendix
-- 每条原 invariant 必须能映射到 global invariant 或 transition GUARD
-- 每条原 error code 必须在 appendix 中保留
-
----
-
-## 6. Anti-Patterns
-
-| Anti-Pattern | Correct |
-|---|---|
-| 在散文中嵌入隐式状态转移 | 所有转移在 `<transitions>` 中显式声明 |
-| ACTION 内只写 2-3 个单词 | ACTION 内用编号步骤 + 表格，保留足够细节 |
-| 用 GUARD 完全替代 invariants | 全局约束留在 `<invariants>`，只有绑定到特定转移的条件用 GUARD |
-| 在主流程中内联 CSV schema | Schema 放 `<appendix>`，主流程只引用 |
-| 每个 skill 重写 wave 执行逻辑 | 引用 `MACRO: RUN_CSV_WAVE` |
-| 状态没有兜底路径 | 每个 state 必须有到 `S_FALLBACK` 的出边 |
-| PERSIST 字段缺失 | 每个 state 声明写入哪些持久化字段 |
+# SKILL.md Authoring Standard
+
+<purpose>
+SKILL.md 的编写规范。核心原则：SKILL.md 是给 LLM agent 执行的状态机定义，不是给人读的操作手册。
+</purpose>
+
+---
+
+## 1. Architecture: Hybrid State Machine
+
+采用"骨架状态机 + 肉身散文"的混合架构。顶层用显式状态转移定义控制流，ACTIONS 内部用结构化散文指导具体操作。
+
+### File Structure
+
+```
+---
+frontmatter (name, description, argument-hint, allowed-tools)
+---
+
+<purpose>           <!-- 1-5 行：目标 + 拓扑图 + 入口点 -->
+<context>           <!-- 用法示例、flag 说明 -->
+<invariants>        <!-- 全局底线规则，独立于状态转移 -->
+
+<state_machine>
+  <states>          <!-- 显式声明所有状态节点 -->
+  <transitions>     <!-- 每个状态的转移规则 -->
+  <actions>         <!-- 具体操作逻辑，结构化散文 -->
+</state_machine>
+
+<appendix>          <!-- 查阅型内容：schema、error codes、examples、success criteria -->
+```
+
+### Why Hybrid
+
+- **纯状态机**（6.5/10）：过度缩写导致 LLM 卡死或幻觉操作，丢失执行语境
+- **纯散文**（5/10）：LLM 需"阅读理解"提取转移条件，注意力分散，上下文寻址迷失
+- **混合**（8.5/10）：状态机路由 + 散文动作，兼顾确定性和可理解性
+
+---
+
+## 2. Section Specifications
+
+### `<invariants>` — Global Guard Rails
+
+保留为独立段落，不打散到 transitions 中。这些是 LLM 的系统级底线指令，无论处于哪个状态都必须遵守。
+
+```markdown
+<invariants>
+1. CSV is Source of Truth — 所有状态持久化在 CSV/JSON，不在内存
+2. Wave Order is Sacred — 永远不执行 wave N+1 直到 wave N 完成
+3. Coordinator Never Executes — 只组装 prompt + spawn，不直接执行 skill 逻辑
+</invariants>
+```
+
+**规则**：
+- 只放跨状态的全局约束
+- 绑定到特定转移的条件放 `<transitions>` 的 GUARD 中
+- 每条 invariant 必须可验证（有明确的违反判定条件）
+
+### `<states>` — Explicit State Declaration
+
+显式声明所有状态节点，每个节点含 1 行 rationale + PERSIST 字段。
+
+```markdown
+<states>
+S_INIT          — 解析参数、路由入口           PERSIST: session.status
+S_INFER         — 推断生命周期位置             PERSIST: session.lifecycle_position
+S_BUILD_CHAIN   — 构建步骤链                   PERSIST: session.steps[]
+S_CONFIRM       — 用户确认（auto_mode 跳过）   PERSIST: —
+S_WAVE_LOOP     — 构建并执行下一波             PERSIST: session.waves[], session.current_step
+S_DECISION      — 委托评估 + 应用裁决          PERSIST: session.passed_gates[], step.retry_count
+S_FIX_LOOP      — 插入修复步骤并重索引          PERSIST: session.steps[] (expanded)
+S_COMPLETE      — 标记完成、释放目标            PERSIST: session.status = "completed"
+S_PAUSED        — 暂停等待人工介入              PERSIST: session.status = "paused"
+S_FALLBACK      — 兜底：条件不匹配时请求输入    PERSIST: session.status = "paused"
+</states>
+```
+
+**规则**：
+- 每个 state 必须有 `PERSIST` 字段，明确写哪些 session/status/csv 字段
+- `S_FALLBACK` 必须存在——当所有 WHEN 条件不满足时进入此状态，调用 `request_user_input`
+- Rationale 限 1 行，不展开
+
+### `<transitions>` — State Transition Rules
+
+每个状态列出所有出边，格式：`→ TARGET  WHEN: condition  [GUARD: constraint]  DO: action_ref`
+
+```markdown
+<transitions>
+
+S_INIT:
+  → S_INFER         WHEN: intent is non-empty
+  → S_WAVE_LOOP     WHEN: intent == "execute" | "continue"
+  → S_FALLBACK      WHEN: no intent AND no running session
+
+S_INFER:
+  → S_BUILD_CHAIN   WHEN: position resolved
+  → S_FALLBACK      WHEN: cannot infer position         DO: show raw state
+
+S_WAVE_LOOP:
+  → S_DECISION      WHEN: next_step.type == "decision"
+  → S_WAVE_LOOP     WHEN: next_step.type == "external"  DO: A_BUILD_AND_SPAWN_WAVE
+  → S_COMPLETE      WHEN: no pending steps
+  → S_PAUSED        WHEN: step failed
+                     GUARD: auto_mode → retry once then pause
+
+S_DECISION:
+  → S_WAVE_LOOP     WHEN: verdict == "proceed"          DO: add to passed_gates
+  → S_FIX_LOOP      WHEN: verdict == "fix"              DO: A_INSERT_FIX_LOOP
+  → S_PAUSED        WHEN: verdict == "escalate"
+  → S_WAVE_LOOP     WHEN: structural(post-milestone) + has next milestone
+                                                         DO: A_ADVANCE_MILESTONE
+  GUARD: retry_count >= max_retries → force escalate
+  GUARD: confidence_score < 60 + proceed → override to fix
+
+</transitions>
+```
+
+**规则**：
+- 转移条件用 `WHEN`，绑定到特定转移的约束用 `GUARD`
+- 动作引用 `DO: A_XXX`，具体逻辑在 `<actions>` 中定义
+- 每个 state 必须有到 `S_FALLBACK` 或 `S_PAUSED` 的兜底路径
+- 条件必须互斥且穷尽（覆盖所有可能）
+
+### `<actions>` — Operation Definitions
+
+每个 ACTION 独立定义，内部使用结构化散文 + 伪代码。不压缩为纯 DSL。
+
+```markdown
+<actions>
+
+### A_BUILD_AND_SPAWN_WAVE
+
+1. buildNextWave: barrier → solo CSV; non-barrier → batch until decision node
+2. buildSkillCall per step: resolve placeholders, apply enrichment table, append auto flags
+3. Write wave-{N}.csv
+4. spawn_agents_on_csv({ csv_path, instruction, max_workers, output_csv_path })
+5. Merge results into master, delete wave CSV
+6. Update session: current_step, waves[], context fields
+
+Enrichment table:
+| Skill | Args | Source |
+|-------|------|--------|
+| maestro-plan | --dir {analyze_artifact_path} | state.json artifacts |
+| maestro-execute | --dir {plan_artifact_path} | state.json artifacts |
+| quality-debug | "{gap_summary}" | decision verdict |
+
+### A_INSERT_FIX_LOOP
+
+1. Clear passed_gates (code will change)
+2. Select fix-loop template by decision type (see Appendix: Fix-Loop Templates)
+3. Insert steps after current position
+4. Reindex all steps
+5. Write status.json
+
+</actions>
+```
+
+**规则**：
+- ACTION 名称以 `A_` 前缀，与 transitions 中的 `DO:` 引用对应
+- 内部用编号步骤，不用散文段落
+- 数据映射用表格，不用散文描述
+- 每个 ACTION 必须明确输入/输出和副作用（写了什么文件）
+
+---
+
+## 3. Shared Primitives
+
+### MACRO: RUN_CSV_WAVE
+
+三个 skill（ralph、plan、execute）共享的 CSV 波执行逻辑，抽为标准子程序：
+
+```markdown
+### MACRO: RUN_CSV_WAVE(wave_rows, session_folder, instruction_builder)
+
+1. Filter pending rows for target wave
+2. Build prev_context from completed predecessor findings
+3. Write wave-{N}.csv with prev_context column
+4. spawn_agents_on_csv({
+     csv_path: wave-{N}.csv,
+     instruction: instruction_builder(context),
+     output_csv_path: wave-{N}-results.csv
+   })
+5. Merge results into master CSV
+6. Delete wave-{N}.csv
+7. Return: updated master CSV rows
+```
+
+各 skill 通过不同的 `instruction_builder` 和上下文参数调用此 MACRO，不重复描述流程。
+
+---
+
+## 4. `<appendix>` — Reference-Only Content
+
+以下内容移出主流程，放入 appendix 供按需查阅：
+
+| Section | Content |
+|---------|---------|
+| CSV Schema | 列定义、示例行 |
+| Worker Contract | 子 agent instruction 模板、output schema |
+| Fix-Loop Templates | 各 decision type 的修复步骤链 |
+| Discovery Board Protocol | 类型定义、去重规则 |
+| Error Codes | 错误码 + 恢复策略 |
+| Success Criteria | 验收检查项 |
+| Golden Examples | 典型执行路径的完整示例 |
+
+---
+
+## 5. Implementation Plan
+
+### Order
+
+1. **Pilot**: `maestro-ralph/SKILL.md` — 本质是 adaptive state machine，收益最大
+2. **Extract**: 抽 `MACRO: RUN_CSV_WAVE` 共享子程序
+3. **Rollout**: `maestro-plan` 和 `maestro-execute` 用 Phase Cards 轻量整理（不必完整状态机化）
+
+### Phase Cards（适用于 plan/execute）
+
+对于线性 pipeline 型 skill，用 Phase Cards 代替完整状态机：
+
+```markdown
+<phases>
+
+PHASE P1_RESOLVE_INPUT:
+  DO: parse args, resolve phase dir, load context
+  NEXT: P2_BUILD_CSV
+  FAIL: abort with error
+
+PHASE P2_BUILD_CSV:
+  DO: generate tasks.csv from plan/exploration angles
+  NEXT: P3_RUN_WAVES
+  FAIL: abort
+
+PHASE P3_RUN_WAVES:
+  DO: MACRO:RUN_CSV_WAVE per wave (sequential)
+  NEXT: P4_AGGREGATE
+  FAIL: mark failed, pause
+
+PHASE P4_AGGREGATE:
+  DO: export results, update state, generate report
+  NEXT: END
+
+</phases>
+```
+
+### Safety Protocol
+
+- 第一版将原散文移入 `<appendix>`，不删除
+- 跑 3-5 次真实 skill 调用后评估效果，再压缩 appendix
+- 每条原 invariant 必须能映射到 global invariant 或 transition GUARD
+- 每条原 error code 必须在 appendix 中保留
+
+---
+
+## 6. Anti-Patterns
+
+| Anti-Pattern | Correct |
+|---|---|
+| 在散文中嵌入隐式状态转移 | 所有转移在 `<transitions>` 中显式声明 |
+| ACTION 内只写 2-3 个单词 | ACTION 内用编号步骤 + 表格，保留足够细节 |
+| 用 GUARD 完全替代 invariants | 全局约束留在 `<invariants>`，只有绑定到特定转移的条件用 GUARD |
+| 在主流程中内联 CSV schema | Schema 放 `<appendix>`，主流程只引用 |
+| 每个 skill 重写 wave 执行逻辑 | 引用 `MACRO: RUN_CSV_WAVE` |
+| 状态没有兜底路径 | 每个 state 必须有到 `S_FALLBACK` 的出边 |
+| PERSIST 字段缺失 | 每个 state 声明写入哪些持久化字段 |