skill-system-workflow

技能系统工作流

skill-system-workflow 是技能系统的规划层。它将目标转换为带有 Mermaid 输出的 DAG，尽可能优先使用可复用的方案，并且严格遵循只读原则，不参与执行。

工单生命周期操作由 skill-system-tkt 负责。此技能现在仅负责规划、可视化和方案发现。

概览

• 输入：目标和可选上下文
• 输出：DAG 文档和 Mermaid flowchart TD
• 规划策略：优先匹配方案，其次动态规划
• 执行：不在范围内；下游技能会使用该 DAG

核心操作

plan

分析目标，生成工作流 DAG 和 Mermaid 可视化图。

1. 读取可用的 recipes/
2. 将 goal 与 trigger_patterns 匹配
3. 如果匹配到方案，则根据目标调整方案
4. 否则，使用 prompts/plan-workflow.md 生成自定义 DAG
5. 按照下文约定从 DAG 渲染 Mermaid

流程：scripts/plan-and-visualize.md

visualize

将现有 DAG YAML 转换为 Mermaid 流程图。

• 解析 waves[*].tasks[*]
• 每个波次使用一个 Mermaid subgraph
• 添加 depends_on 边
• 应用状态样式（pending、running、done、failed）

list-recipes

读取 recipes/，列出可用的工作流方案，并返回每个方案的名称和描述。

文件布局

• prompts/plan-workflow.md：单次动态 DAG 规划提示词
• schema/workflow-dag.yaml：工作流 DAG 结构规范
• schema/recipe.yaml：方案结构规范
• recipes/*.yaml：可复用的工作流模板
• scripts/plan-and-visualize.md：从规划到 DAG 再到 Mermaid 的人工流程
• scripts/dispatch.sh：多 Agent 调度引擎（发送 opencode run 命令）
• scripts/chain.sh：步骤完成处理程序（自动调度下一步或通知审核者）
• schema/dispatch-order.yaml：调度顺序结构规范
• recipes/multi-agent-dispatch.yaml：用于跨仓库组合调度的方案

方案格式参考

方案是描述可复用波次和任务的小型 YAML 文档。

• name：方案标识符（必须与去掉扩展名后的文件名一致）
• trigger_patterns：表示适用该方案的目标关键词／短语
• waves：按顺序排列的执行波次
• waves[*].parallel：该波次中的任务是否可以同时执行
• waves[*].tasks[*].depends_on：必须先完成的较早波次中的任务 ID

参见：schema/recipe.yaml

Mermaid 约定

图表结构

• 图表方向：flowchart TD
• 每个波次使用一个子图：subgraph waveN [Wave N: <description>]
• 每个任务是一个 ID 为 task_id 的节点
• 节点标签格式：<agent_type>\n<task name>

节点形状

• 任务节点：圆角矩形：task_id(["<agent_type>\\n<name>"])
• 可选的起始／结束锚点（如果使用）：start((Start))、end((End))

状态样式

根据每个任务的 status 使用 Mermaid 类：

pending: not started
running: in progress
done: completed successfully
failed: needs intervention

配置

运行时设置位于 config/workflow.yaml。配置是唯一事实来源。

参见：../../config/workflow.yaml

多 Agent 调度

skill-system-workflow 现在还通过 opencode run 协调跨仓库调度。 skill-system-tkt 中的 TKT-000 集成工单模式用作协调点。

dispatch

将一个 bundle 的下游工作分派给多个项目编码人员。

1. 读取上游 bundle 的 downstream_bundles 字段
2. 按依赖顺序构建包含各步骤的 dispatch-order.yaml
3. 执行 scripts/dispatch.sh 以发送 opencode run 命令
4. 编码人员完成工作后调用 scripts/chain.sh
5. chain.sh 会自动分派下一步，或通知审核人员

流程：参见配方 multi-agent-dispatch.yaml

脚本：

• scripts/dispatch.sh <dispatch-order.yaml> — 发送 opencode run 命令
• scripts/chain.sh <dispatch-order.yaml> <step-id> — 处理步骤完成事件
• 两者都支持使用 --dry-run 进行验证

架构： schema/dispatch-order.yaml

链式协议：

Reviewer → dispatch.sh → opencode run (coder A)
                             ↓ (coder A completes)
                         chain.sh → opencode run (coder B)
                                        ↓ (coder B completes)
                                    chain.sh → notify reviewer

与 TKT-000 集成

TKT-000 集成票据负责协调 bundle。分派链完成后：

1. 每位编码人员将自己的 bundle 标记为已完成
2. chain.sh 更新 dispatch-order 中的步骤状态
3. 最后一步完成时：写入 .done 文件，或通过 claude CLI 通知审核人员
4. 审核人员关闭上游 TKT-000

迁移说明

票据生命周期操作由 skill-system-tkt 负责。skill-system-workflow 负责规划（3 项操作：plan、visualize、list-recipes），现在也负责 多 Agent 分派（dispatch）。

操作说明

• 每轮任务保持精简（2-6 项），以便图表保持清晰易读。
• 优先在同一轮内并行处理；跨轮排序请使用 depends_on。
• 每项任务都应有明确的验证结果。

{
  "schema_version": "2.0",
  "id": "skill-system-workflow",
  "version": "2.0.0",
  "capabilities": ["workflow-plan", "workflow-visualize", "workflow-list-recipes", "workflow-dispatch"],
  "effects": ["fs.read", "fs.write", "db.read", "proc.exec"],
  "operations": {
    "plan": {
      "description": "Analyze a goal and produce an execution plan as a DAG with Mermaid visualization.",
      "input": {
        "goal": {"type": "string", "required": true, "description": "User's goal or task description"},
        "context": {"type": "string", "required": false, "description": "Additional context (files, constraints)"}
      },
      "output": {
        "description": "Workflow DAG YAML plus Mermaid diagram",
        "fields": {"dag": "YAML", "mermaid": "string"}
      },
      "entrypoints": {
        "agent": "Follow scripts/plan-and-visualize.md procedure"
      }
    },
    "visualize": {
      "description": "Convert an existing DAG YAML to a Mermaid flowchart.",
      "input": {
        "dag_yaml": {"type": "string", "required": true, "description": "DAG YAML content"}
      },
      "output": {
        "description": "Mermaid flowchart string",
        "fields": {"mermaid": "string"}
      },
      "entrypoints": {
        "agent": "Apply Mermaid conventions from SKILL.md to the DAG"
      }
    },
    "list-recipes": {
      "description": "List available workflow recipes.",
      "input": {},
      "output": {
        "description": "Array of recipe names and descriptions",
        "fields": {"recipes": "array"}
      },
      "entrypoints": {
        "agent": "List files in recipes/ directory"
      }
    },
    "dispatch": {
      "description": "Dispatch a bundle's downstream work to multiple project coders via opencode run with automatic chaining.",
      "input": {
        "upstream_bundle": {"type": "string", "required": true, "description": "Path to the upstream bundle directory containing downstream_bundles"},
        "workspace_root": {"type": "string", "required": true, "description": "Absolute path to the workspace root"},
        "dry_run": {"type": "boolean", "required": false, "description": "If true, show commands without executing"}
      },
      "output": {
        "description": "Dispatch order YAML with step statuses",
        "fields": {"dispatch_order": "YAML", "steps_dispatched": "number"}
      },
      "entrypoints": {
        "agent": "Follow recipe multi-agent-dispatch.yaml: build dispatch-order.yaml from bundle, then run scripts/dispatch.sh",
        "cli": "scripts/dispatch.sh <dispatch-order.yaml> [--dry-run]"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false,
    "note": "Agent-executed procedures; output is DAG YAML and Mermaid text."
  }
}