maestro-flow 0.3.46 → 0.3.48

package/workflows/skill-authoring.md

@@ -0,0 +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 声明写入哪些持久化字段 |

package/workflows/specs-add.md

@@ -9,7 +9,7 @@ $ARGUMENTS: "[--scope <scope>] [--uid <uid>] <category> <content>"
 
 --scope  -- target scope: project (default) | global | team | personal
 --uid    -- user id for personal scope (auto-detected from git if omitted)
-category -- one of: coding, arch, quality, debug, test, review, learning
+category -- one of: coding, arch, quality, debug, test, review, learning, ui
 content  -- free-text description of the entry
 ```
 
@@ -33,6 +33,7 @@ content  -- free-text description of the entry
 | `test` | `test-conventions.md` |
 | `review` | `review-standards.md` |
 | `learning` | `learnings.md` |
+| `ui` | `ui-conventions.md` |
 
 ## Prerequisites
 
@@ -54,7 +55,7 @@ Parse $ARGUMENTS:
   4. content = remaining text
 Validate:
   - scope ∈ {project, global, team, personal}
-  - category ∈ {coding, arch, quality, debug, test, review, learning}
+  - category ∈ {coding, arch, quality, debug, test, review, learning, ui}
   - content non-empty
   - personal scope requires uid (resolve from `maestro collab whoami` if --uid not given)
 On failure: show usage `/spec-add [--scope <scope>] <category> <content>`, exit

package/workflows/specs-load.md

@@ -9,7 +9,7 @@ $ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--category <category>] [keyword]"
 
 --scope     -- load scope: project (default) | global | team | personal
 --uid       -- user id for personal scope (auto-detected from git if omitted)
---category  -- filter by category: coding | arch | test | review | debug | quality | learning
+--category  -- filter by category: coding | arch | test | review | debug | quality | learning | ui
                Loads category's primary doc in full + cross-file entries with matching category attr
 keyword     -- optional, grep within loaded specs for matching sections
 ```
@@ -29,6 +29,7 @@ Each category loads exactly one file per layer. Same mapping as spec-add.
 | `debug-notes.md` | debug |
 | `quality-rules.md` | quality |
 | `learnings.md` | learning |
+| `ui-conventions.md` | ui |
 
 ## Layer Order by Scope
 

package/workflows/specs-setup.md

@@ -180,7 +180,27 @@ Auto-generated from project analysis. Update manually as patterns evolve.
 {empty section for spec-add entries}
 ```
 
-#### 5c: debug-notes.md and review-standards.md
+#### 5c: ui-conventions.md (when frontend framework detected)
+
+Scan for frontend frameworks (React, Vue, Angular, Svelte, etc.) and UI libraries.
+
+Output: `.workflow/specs/ui-conventions.md`
+
+```markdown
+---
+title: "UI Conventions"
+category: ui
+---
+# UI Conventions
+
+Auto-generated from project analysis. Update manually as patterns evolve.
+
+## Entries
+
+{empty section for spec-add entries}
+```
+
+#### 5d: debug-notes.md and review-standards.md
 
 These are NOT created during setup. They are created on demand when `spec-add debug` or `spec-add review` is first used.