エージェントワークフロー

ワークフローの作成

ワークフローとは、「ユーザーがやりたいこと」を「最初に何をし、次に何をし、各ステップでどのツールを使い、何を生成するか」に変換する再利用可能なプロセス単位です。このスキルは、ユーザーの要件からdocs/workflow/index.md仕様に準拠したWORKFLOW.mdを作成するためのガイドです。

作成前に仕様書を読んでください：docs/workflow/index.md（3段階の段階的開示、グラフとステップの1対1対応、プロセスルール、ツール呼び出し規約）。

使用すべきタイミング

• ユーザーが「ワークフロー/プロセス/標準化されたフローを作成して」と依頼したとき
• ユーザーが自動実行されるフローに固めたいマルチステップタスクを説明したとき
• ユーザーが既存のワークフローの修正や改善を依頼したとき
• セッション中に再利用可能で複数ステップの作業を行い、「このフローを固めて」と言われたとき

作成プロセス

フェーズ1：意図を理解する

まずはヒアリング；ファイルを急いで書き始めない：

1. 解決するタスクは何か？タスククラスに名前を付ける（例：「コードレビュー」、「リリースノート」）。
2. トリガーシナリオ：ユーザーはいつ使うのか？トリガーワード（日本語＋英語）を収集する。
3. 入力と出力：どのような入力（ファイル/ディレクトリ/文字列）が必要か？何を生成するか（ファイル/レポート）？
4. 既存のステップ：ユーザーはすでに習慣的なフローを持っているか？セッション履歴からツール呼び出しシーケンス、修正点、入出力形式を抽出する。
5. 境界とルール：やってはいけないことは？成果物はどこに置くか？障害時の処理は？

不足情報はask_userで埋めてから次のフェーズに進む。

フェーズ2：フローチャートを設計する

mermaidで実行フローを描画する。グラフとステップの対応ルール（仕様5.2.1）に従う：

• すべてのノードに対応するステップセクションが必要；すべてのステップがグラフに1回だけ出現すること
• ノード名はステップ名と完全に一致し、全体で一意である（step-Nプレフィックスはノードに表示しなくてよい）
• 判定ノードはひし形{}で表し、必ずステップセクションも持ち、Branchで各分岐先を明記する
• 並列ステップ（scatter）はグラフ上では1つのノードとする
• グラフは完全であること：開始、分岐、終了を含む

ステップを書く前にグラフをユーザーに表示して確認を取る。

フェーズ3：WORKFLOW.mdを書く

<workspace>/workflows/<name>/の下にディレクトリとファイルを作成する：

1. frontmatter（レベル1メタデータ）：
   • name：ケバブケース、ディレクトリ名と一致、小文字/数字/ハイフンのみ
   • description：機能＋使用タイミング＋トリガーワード（日本語と英語）、トリガー率を決定する
   • inputs / outputs：明示的に宣言、必須項目をマーク
   • version / tags：任意
2. 概要：何をするか、いつ使うか、何を生成するかを1段落で記載
3. フローチャート：フェーズ2と整合したmermaidグラフ
4. ステップ：ステップごとに### <ID>: <名前>セクションを作成し、属性Tools / Input / Depends on / Action / Checkを記述（判定ノードにはBranchと任意のwhenを追加）
5. プロセスルール：順序制約、データ依存関係、検証ゲート、副作用制約、最終状態チェック
6. ツール呼び出し規約：ビルトインツールを優先、スクリプトはフォールバック、読み取り主体で書き込みは最小限、パス規約

段階的開示：長いテーブルはREFERENCES.mdに、決定論的ロジックはscripts/に配置し、本体は500行未満に保つ。

フェーズ4：自己チェックと検証

記述後、仕様に照らしてチェック：

• グラフとステップの1対1対応：グラフに「孤立」ノードがなく、セクションに「孤立」ステップがない
• ノード名が一意でステップ名と一致している
• すべてのステップに具体的で判定可能なCheckがある（例：「ファイルが存在し空でない」であって「成功を確認」ではない）
• ツール名は正確（read_file / execであり「ファイルを見る」ではない）
• inputs / outputsがステップ参照と整合している
• ルールに障害処理（リトライ / ロールバック / ユーザーへの問い合わせ）が含まれている
• frontmatterのdescriptionに機能とトリガーワードが含まれている

workflow_listで新しいワークフローが検出されることを確認し、workflow_get <name>で読み取り可能であることを確認する。

フェーズ5：納品

ユーザーに以下の情報を伝える：

• ワークフロー名とパス
• トリガーシナリオ（どのような言い回しがトリガーとなるか）
• フローの概要（ステップ数、判定/並列処理の有無）
• 任意：実際に動作を確認するためのテストリクエストを2～3件提案する

既存のワークフローの修正

• まずworkflow_get <name>で現在の内容を読む
• frontmatterのnameとディレクトリ名は変更しない
• 変更時も同じ仕様に従い、編集後にフェーズ4の自己チェックを実行する

注意事項

• ワークスペースのworkflows/にのみ書き込む；ビルトインの読み取り専用ワークフローは決して変更しない；同名のワークスペースワークフローがビルトインを上書きする
• 1つのワークフローは1つのタスククラスを解決する；無関係なフローを詰め込まない
• ステップ数は3～8に保つ；それを超える場合は分割するかサブフローを参照する
• 悪意のある誤解を招く命令を決して書かない；ルールは監査可能でなければならない