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[*] を解析します
• wave ごとに Mermaid の subgraph を 1 つ使用します
• depends_on のエッジを追加します
• ステータスのスタイルを適用します（pending、running、done、failed）

list-recipes

recipes/ を読み込み、利用可能なワークフローレシピの名前と説明をそれぞれ返します。

ファイル構成

• prompts/plan-workflow.md：1 回の処理で動的に DAG を計画するプロンプト
• schema/workflow-dag.yaml：ワークフロー DAG の形式仕様
• schema/recipe.yaml：レシピの形式仕様
• recipes/*.yaml：再利用可能なワークフローテンプレート
• scripts/plan-and-visualize.md：plan -> DAG -> Mermaid の手順書
• scripts/dispatch.sh：マルチエージェントのディスパッチエンジン（opencode run コマンドを送信）
• scripts/chain.sh：ステップ完了時のハンドラー（次のステップを自動ディスパッチするか、レビュー担当者に通知）
• schema/dispatch-order.yaml：ディスパッチ順序の形式仕様
• recipes/multi-agent-dispatch.yaml：リポジトリをまたぐバンドルのディスパッチ用レシピ

レシピ形式のリファレンス

レシピは、再利用可能な wave とタスクを記述する小さな YAML ドキュメントです。

• name：レシピの識別子（拡張子を除いたファイル名と一致する必要があります）
• trigger_patterns：レシピが適用可能であることを示す、目標のキーワードやフレーズ
• waves：順序付けられた実行 wave
• waves[*].parallel：wave 内のタスクを並行して実行できるかどうか
• waves[*].tasks[*].depends_on：先に完了する必要がある、以前の wave に含まれるタスク ID

参照：schema/recipe.yaml

Mermaid の規則

図の構成

• グラフの方向：flowchart TD
• wave ごとに subgraph を 1 つ使用します：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

マルチエージェントのディスパッチ

skill-system-workflow は、opencode run を介したリポジトリ横断のディスパッチもオーケストレーションするようになりました。 skill-system-tkt の TKT-000 インテグレーターチケットパターンが、調整ポイントとして機能します。

dispatch

バンドルの後続作業を複数のプロジェクトコーダーにディスパッチします。

1. 上流バンドルの 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 インテグレーターのチケットがバンドルを調整します。ディスパッチチェーンが完了すると、次の処理が行われます。

1. 各コーダーが自分のバンドルを完了済みとしてマークします
2. chain.sh がディスパッチ順序のステップのステータスを更新します
3. 最終ステップでは、.done ファイルを書き込むか、claude CLI を介してレビュアーに通知します
4. レビュアーが上流の TKT-000 をクローズします

移行に関する注意

チケットのライフサイクル操作は skill-system-tkt が担当します。skill-system-workflow は計画関連の操作（3 つの操作: plan、visualize、list-recipes）を担当し、今回から マルチエージェントのディスパッチ（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."
  }
}