hexabot-workflow-writer

hexabot-workflow-writer

Hexabot v3 のワークフローの作成とレビューには、このスキルを使用します。Hexabot のワークフロー YAML は厳密な仕様に従うため、最終的な YAML を作成する前に、現在のリポジトリを確認してください。

使用する場面

• ビジネス上のユースケースから Hexabot のワークフローを生成する。
• Hexabot のワークフロー YAML をレビュー、デバッグ、改善する。
• 会話型、手動、スケジュール、イベント駆動、システムの各ワークフローを含む、Hexabot のエージェント型自動化を設計する。
• ワークフローのアクション、バインディング、メモリ要件、LLM のステップ、ツールの使用方法を設計する。
• 営業、ドキュメント、製品紹介のデモを Hexabot のワークフローに変換する。

使用しない場面

• Hexabot のワークフロー実装を伴わない、一般的なチャットボットのマーケティングコピー。
• Hexabot に関連しない、一般的な AI 戦略や自動化に関するアドバイス。
• Hexabot 以外の自動化プラットフォーム。
• Hexabot のワークフロー、アクション、バインディングの開発に直接関係しない、一般的な NestJS または React の作業。

信頼できる情報源

最終的なワークフロー YAML やアクションのコントラクトを作成する前に、関連する最新のリポジトリファイルを確認してください。<hexabot-repo>/ で始まるパスは、このパッケージ化されたスキルではなく、チェックアウト済みの Hexabot リポジトリからの相対パスです。現在のワークスペースがパッケージ化されたスキルのみの場合は、このスキルに含まれるリファレンスと例を使用し、ランタイムでの検証には Hexabot リポジトリまたは稼働中の API が引き続き必要であることを明記してください。

• DSL とリポジトリの例：<hexabot-repo>/packages/agentic/DSL.md、<hexabot-repo>/packages/agentic/src/dsl.types.ts、および<hexabot-repo>/packages/agentic/examples/ 配下の workflow.yml ファイル。
• ランタイムでの検証と実行：<hexabot-repo>/packages/agentic/src/workflow.ts、<hexabot-repo>/packages/agentic/src/workflow-compiler.ts、<hexabot-repo>/packages/agentic/src/__tests__/ 配下のテスト。
• API のワークフロー統合：<hexabot-repo>/packages/api/src/workflow/**、特に DTO、エンティティ、入力スキーマ、トリガーラッパー、および<hexabot-repo>/packages/api/src/workflow/lib/workflow-definition.ts。
• アクションとバインディング：<hexabot-repo>/packages/api/src/actions/**、<hexabot-repo>/packages/api/src/extensions/actions/**、<hexabot-repo>/packages/api/src/bindings/**。
• 共通ワークフロー型：<hexabot-repo>/packages/types/src/workflow/**。

組み込みの API アクションがすべて網羅されているとは限りません。エンドユーザーは npm からアクションパッケージをインストールしたり、Hexabot CLI でブートストラップしたプロジェクト内にプロジェクト固有のカスタムアクションを作成したりできます。サポートされていない YAML フィールドをでっち上げないでください。リポジトリに必要なスキーマやアクションがない場合は、それがインストール済みまたはカスタムのものと想定されているかを明記し、ランタイムでの検証が必要な YAML として提示してください。

Hexabot MCP サーバー

AI コーディングエージェントで Hexabot MCP サーバーを利用できる場合は、ワークフロー YAML やアクションのコントラクトを確定する前に、ライブの Hexabot コンテキストを得るため、そちらを優先してください。バンドルされた例だけに頼らず、利用可能な MCP ツールを使用して、ランタイムのアクション、ワークフローのスキーマ、バインディング、メモリ定義、設定済みの MCP サーバー、認証情報やプレースホルダー、既存のワークフローを確認してください。

現在のエージェントで Hexabot MCP サーバーを利用できない場合は、可能な限りリポジトリファイルとバンドルされたリファレンスを使用して作業を続けます。ただし、ランタイムの実態に即したワークフロー作成のため、ユーザーに次の手順でサーバーを設定するよう案内してください。

1. Hexabot アプリの環境で MCP_ENABLED=false に設定します。
2. アカウントページから MCP トークンを生成します：http://localhost:3000/profile。
3. 生成したトークンとローカルの Hexabot サーバー URL を使用して、OpenCode、Codex、Claude Code など、MCP に対応するツールに Hexabot MCP サーバーを追加します。

MCP トークンをワークフロー YAML やスキルの出力に貼り付けるよう、ユーザーに決して求めないでください。MCP にアクセスできない場合は、検証上の制約として扱い、ランタイム ID をでっち上げる理由にしないでください。

ワークフロー YAML のルール

• ワークフロー定義 YAML は、ルートフィールドとして inputs、context、defaults、defs、flow、outputs をサポートします。
• conversational と scheduled のワークフローでは、ルートの inputs セクションを省略してください。これらのワークフロータイプの固定トリガー入力スキーマは API が管理し、エージェント型ランナーは YAML で宣言された inputs.schema を厳密なパーサーとして扱います。不完全なスキーマでは、message_type、message、mid、triggered_at などの実行時フィールドが拒否される可能性があります。
• 名前、説明、WorkflowType（conversational、manual、scheduled）、スケジュールの cron、公開状態、レイアウト、バージョンメッセージなどのワークフローメタデータは、YAML 定義の外にある API のワークフローレコードに保存されます。
• defs はルートレジストリです。タスク定義では kind: task を使用し、action を宣言します。タスク以外の定義ではバインディングの種類を使用し、settings を宣言する必要があります。
• サポートされているフローのプリミティブは do、parallel、conditional、loop です。ループブロックでは type: for_each または type: while が必要です。
• = で始まる文字列はすべて JSONata 式として評価されます。リテラル文字列を = で始めてはいけません。最終的な outputs の値は式文字列でなければなりません。
• JSONata の YAML スカラーはすべて二重引用符で囲むか、長い式にはブロックスカラーを使用してください。これは condition、while、アクションの inputs／settings、およびすべての outputs の値に適用されます。result: =$a ? "yes" : "no" のようなプレーンスカラーは、三項演算子のコロンによって入れ子の YAML マッピングとして解析されることがあります。result: "=$a ? 'yes' : 'no'" を使用するか、次のようにしてください。

  result: >-
    =$a
      ? 'yes'
      : 'no'
  

• 式では $input、$context、$output.<task>、$iteration、$accumulator を使用できます。
• タスク出力のマッピングはサポートされていません。アクションの生の結果は $output.<task> に保存されます。
• バインディング参照は、既存の定義を参照し、kind が一致している必要があります。現在の組み込みバインディングの種類には、単一の参照としての model と、配列としての tools、memory、mcp があります。

作成手順

1. YAML の外でワークフローの種類とトリガーを特定します。会話型の受信メッセージ、手動での API／UI 実行、またはスケジュールされた cron 実行のいずれかです。
2. Hexabot MCP サーバーを AI コーディングエージェントから利用できるか確認します。利用できる場合は、実行時のライブ情報の取得に使用します。実行時の検証で結果が大きく改善する場合は、セットアップを案内します。
3. アクションを選択する前に、利用可能なアクションスキーマとワークフロータイプとの互換性を確認します。
4. 手動ワークフローでは、ワークフローが必要とする値に対して最小限の inputs.schema を定義します。会話型およびスケジュール型ワークフローでは、ルートの inputs を省略し、トリガーフィールドを $input から直接読み取ります。
5. 必要なアクションと外部連携を列挙し、それぞれを既存のアクション名に対応付けるか、カスタムアクションの設計が必要であることを記します。
6. アクションが必要とする場合にのみバインディングを追加します。特に、AI モデル、ツール、MCP、メモリのバインディングが該当します。
7. メモリは明示的に扱います。利用可能な場合は既存のメモリ定義 ID／スラッグを使用するか、必要なメモリ定義を別途記載します。
8. まず小規模なフローを作成し、ユースケースで必要になった場合にのみ分岐、並列処理、ループ、再試行、人への引き継ぎを追加します。
9. 実行時の検証の前に、YAML を解析できることを確認します。特に、三項演算子、正規表現、オブジェクトリテラル、配列リテラル、および :、?、{}、[]、#、引用符を含む式について、すべての式スカラーが引用符で囲まれているか、ブロック形式になっているかを再確認します。
10. definitionYml を使用するワークフローの作成／更新ツールまたは API を呼び出す前に、送信する YAML 文字列そのものに対して、同じ解析と式の引用符チェックを実施します。
11. 最終的な YAML を提示する前に、式、タスク参照、バインディングの多重度、最終出力を検証します。

レビュープロセス

1. スキーマをレビューする前に、YAML として解析します。= で始まるプレーンな JSONata スカラーはエラーにします。三項演算子のコロンや正規表現／オブジェクトの構文によって YAML の解析が壊れないよう、式は引用符で囲むか、ブロック形式で記述する必要があります。
2. 設定されている場合は、実行時のアクション、バインディング、メモリ、ワークフローを確認するために Hexabot MCP サーバーを使用します。設定されていない場合は、実行時検証ができないことを明記し、必要に応じてセットアップを案内します。
3. YAML の構造を WorkflowDefinitionSchema に照らして解析し、会話型またはスケジュール型ワークフローのルートにある inputs を指摘します。
4. すべての flow タスク参照が defs に存在するか確認します。
5. アクション名を、実行時のアクションレジストリ、Hexabot MCP サーバー、またはソースファイルと照合します。
6. 各バインディングの種類、多重度、def 参照、ネストされたバインディング、サポート対象バインディングの許可リストを確認します。
7. ワークフローの種類との適合性を確認します。ソースコードでサポートが確認できない限り、手動またはスケジュール型ワークフローで会話型アクションを使用しないでください。
8. LLM プロンプトについて、プロンプトインジェクションのリスク、シークレットの漏えい、曖昧な出力、構造化出力スキーマの欠落を確認します。
9. defaults.settings、タスク設定、再試行、フォールバック分岐、人間へのエスカレーションを通じたエラー処理を確認します。
10. 可能な場合は、具体的な YAML パスとリポジトリの参照を添えて、重大度順に指摘事項を報告します。

出力形式

• 新しいワークフローの生成：前提条件の簡潔なセクション、YAML の外部で設定するワークフローメタデータ、フェンス付きの yaml ブロックに記載した最終 YAML、検証メモを提示します。
• ワークフローのレビュー：重大度順の指摘事項から始め、未解決の質問、推奨するパッチのスニペット、検証手順を続けます。
• アクションの設計：アクション名、ワークフローの種類、入力スキーマ、出力スキーマ、設定スキーマ、サポート対象バインディング、冪等性に関するメモ、エラー、可観測性、テストの期待事項を提示します。
• デモのユースケース設計：対象ユーザー、デモの説明、ワークフローの種類、トリガー、アクション、バインディング／メモリ、正常系、失敗時の流れ、UI で示す内容を提示します。

参考資料

• ユースケースをワークフロー YAML に変換する場合は、references/workflow-authoring-guide.md を読みます。
• カスタムアクションを設計またはレビューする場合は、references/action-design-guide.md を読みます。
• 既存のワークフローをレビューする場合は、references/workflow-review-checklist.md を読みます。
• 洗練された回答形式が必要な場合は、references/output-templates.md を読みます。
• ワークフローの基本例として、examples/customer-support-triage.workflow.yaml を参照してください。
• メモリ、MCP、カスタムアクションを含む高度なエージェントループの例として、examples/contact-calendar-agent.workflow.yaml を参照してください。