workflow-blueprint

agentic-workflows.blueprint

目標

あらゆるコードベース向けに、「エージェント型ワークフロー」のドキュメント構造を段階的な情報開示と実行可能な契約（ワークフロー）を備えた形で足場として作成する、再利用可能なブループリントワークフローを提供します。

対象範囲

• 対象：エージェント指向のドキュメントシステム（オーケストレーター＋ワークフロースキル＋リファレンス＋ランブック）を必要とするすべてのリポジトリ。
• 対象外：プロダクト機能の実装。このブループリントは足場とドキュメントのみを扱います。

トリガー

• 「エージェント型ワークフローの構造を作成」
• 「スキルフォルダーとワークフローを設定」
• 「ドキュメントをエージェントに適したものにする」
• 「AGENTS.md をリンク付きスキルにリファクタリング」

入力

• projectSlug：リポジトリの短い識別子（例：my-backend）
• baseBranch：デフォルトの統合ブランチ（例：develop、main）
• techStack：技術スタックの短い一覧（例：NestJS + MikroORM + Graphile Worker）
• existingRootDoc：ルートの指示ファイルのパス（AGENTS.md、CLAUDE.md など）
• workflowsWanted：足場として作成するワークフロー ID の一覧（例：modules、specs、document、network-engineering、infra-operations、iac、os-platform、plan-to-blueprint）
• constraints：プロジェクトの厳格なルール（例：「絵文字を使わない」、「外部との境界のみモックする」）
• skillName（任意）：プロジェクトのエントリースキルをスラッシュで呼び出す際の名前。デフォルトは projectSlug（小文字、ハイフンのみ）

出力

最小限でナビゲーションしやすい構造を作成します。

skills/<projectSlug>/
  SKILL.md
  template.json                     ← Declarative manifest (commands, entry)
  reference/
    routing-matrix.md
    role-contracts.md
    hook-blueprint.md (optional)
  workflows/
    <workflowName>/
      SKILL.md
      template.json (optional)      ← Per-workflow manifest when useful
docs/runbooks/
  agent-role-system.md
  agent-role-hooks.md (optional)
  plan-to-blueprint.md (when workflow included)

また、新しいエントリーポイントへのリンクを追加するために、ルートドキュメント（AGENTS.md または同等のファイル）を更新します。

このブループリントフォルダーには、完全なライフサイクルにわたる連鎖実行、Matt Pocock / AI Hero の手法の埋め込み、計画からスキルへの変換、ビジュアルドキュメントの生成、MCP 統合パターン、インフラ運用への対応を実演するための、バンドル済みワークフロー（embed-aihero-radioactive、mattpocock/wayfinder、mattpocock/grilling、mattpocock/domain-modeling、mattpocock/research、mattpocock/prototype、mattpocock/to-spec、radioactive、brainstorming、plan-writing、ui-ux-pro-max、remotion-video-motion、thermo-nuclear-code-quality-review、thermo-fix、changelog-generator、document、review、changelog、linear、mcp-linear-planner、mcp-linear-sync、network-engineering、infra-operations、iac、os-platform、implementing-devsecops-security-scanning、scanning-containers-with-trivy-in-cicd、scanning-docker-images-with-trivy、scanning-kubernetes-manifests-with-kubesec、implementing-network-policies-for-kubernetes、implementing-rbac-hardening-for-kubernetes、implementing-pod-security-admission-controller、securing-aws-iam-permissions、securing-container-registry-images、securing-kubernetes-on-cloud、triaging-vulnerabilities-with-ssvc-framework、performing-kubernetes-cis-benchmark-with-kube-bench、analyzing-kubernetes-audit-logs、securing-github-actions-workflows、performing-container-image-hardening、remediating-s3-bucket-misconfiguration、performing-container-security-scanning-with-trivy、performing-vulnerability-scanning-with-nessus、implementing-syslog-centralization-with-rsyslog、c4-architecture、plan-to-blueprint）が含まれています。

また、これらのワークフローに対するオペレーター向けの実行プレイブックを示すため、runbooks/ にランブックの例を含めることもできます。

不変条件（ガードレール）

• 段階的な開示：ルートドキュメントは短く保ち、詳細はリンク先に記載します。
• 実行可能な契約：すべてのワークフローを、エージェントが従える契約として記述します。
  • Goal、Scope、Triggers、Inputs、Invariants、Procedure、Outputs、Review gate、References。
• 重複の禁止：複数のファイルに長いルールをコピー＆ペーストしないでください。信頼できる情報源にリンクします。
• 一貫性：ワークフロー ID とファイルパスは、すべての参照箇所で完全に一致させます。
• 最小限の範囲：実際にリクエストされたワークフローのみを追加します。
• 信頼できる情報源：SKILL.md を正式な情報源とし、template.json はコマンドインターフェースを公開するエージェント／ツール向けの補完的な宣言レイヤーとします。
• コマンドのルーティング：ルーター専用とし、ユーザーは /<skillName> <cmd> を呼び出します。エントリースキルが cmd を workflows/<cmd>/SKILL.md に対応付け、その契約のみを読み込みます。
• マニフェストの同期：template.json 内のすべてのコマンドを既存のワークフローフォルダーに対応させ、routing-matrix.md と一致させます。

手順

1) プロジェクトのエントリースキルを作成する

グローバルなエントリーポイントとして skills/<projectSlug>/SKILL.md を作成します。

• このスキルの用途を簡潔に説明します。
• 次の内容を説明する「orchestrator」セクションを設けます。
  • タスクの分類方法
  • ワークフローを1つ選択する方法
  • 終了方法（該当する場合は検証ゲート）
• Command routing セクションを設けます（ルーター専用）。
  • 呼び出しパターン：/<skillName> <cmd>（例：/my-backend document）
  • workflowsWanted 内の各 cmd を workflows/<cmd>/SKILL.md に対応付けます。
  • エージェントがサブコマンドを解析しない場合は、ユーザーメッセージから cmd を読み取り、対応するワークフロー契約を読み込みます。
  • 明示的にリクエストされない限り、フラットなエイリアススキルを作成しないでください。
• 内部ワークフローのヘルパーを一覧にします。
  • workflows/<name>/SKILL.md へのリンク
• プロジェクトの制約と必須ルールを箇条書きで簡潔に記載します。

宣言型マニフェストとして skills/<projectSlug>/template.json を作成します。

{
  "name": "<skillName>",
  "version": "1.0.0",
  "entry": "SKILL.md",
  "routing": "router-only",
  "commands": [
    {
      "name": "<workflowName>",
      "description": "Short trigger description",
      "skill": "workflows/<workflowName>/SKILL.md"
    }
  ]
}

• workflowsWanted の各項目につき、commands[] エントリーを1つ含めます。
• name を skillName に合わせます（フォルダー名は projectSlug のままでもかまいません）。

2) リファレンスを作成する（段階的な開示）

skills/<projectSlug>/reference/ に次のファイルを作成します。

• routing-matrix.md：タスクカテゴリーとワークフローの対応付け。意図のトリガーと併せてスラッシュ形式の /<skillName> <cmd> も記載します。
• role-contracts.md：役割、境界、引き継ぎ。
• 任意の hook-blueprint.md：オプトインの自動化チェックリスト。

各ファイルは単独で完結させ、リンクできるようにします。

3) 各ワークフローを実行可能な契約としてひな形作成する

workflowsWanted 内の各ワークフローについて、次のファイルを作成します。

skills/<projectSlug>/workflows/<workflowName>/SKILL.md。以下を含めます。

• id："<projectSlug>.workflow.<workflowName>"（最初のヘッダー行として記載）

• Goal：1文

• Scope：対象範囲と対象外

• Triggers：ファイルのトリガーと意図のトリガー

• Inputs：baseBranch、diff の範囲、必須設定

• Invariants：プロジェクトの必須ルールとワークフロー固有のルール

• Procedure：決定的な手順（証拠に基づき、文書化する際は git diff を使用）

• Outputs：作成する必要のあるファイル／メモ／チェックポイント

• Review gate：合格／不合格の基準を含むチェックリスト

• References：skills/<projectSlug>/SKILL.md と詳細資料へのリンク

• 特別なひな形作成ケース — embed-aihero-radioactive：リクエストされた場合は、Matt Pocock のスキルを組み込んだ14フェーズのライフサイクルを実行するように skills/<projectSlug>/workflows/radioactive/SKILL.md を適応させ、skills/<projectSlug>/workflows/mattpocock/ に wayfinder、grilling、domain-modeling、research、prototype、to-spec を含めてひな形を作成します。Phase 1 では、リクエストの分類と制約の抽出を行うため、/wayfinder の実行前に必ずプライマリプロジェクトスキル（skills/<projectSlug>/SKILL.md）を最初に実行するようにします。

任意で、外部ツールに独立したコマンド記述子が必要な場合は、各ワークフローに workflows/<workflowName>/template.json を追加します。内容は最小限に保ちます（name、entry、parent）。

4) ルートドキュメントにすべてを組み込む

existingRootDoc を更新し、以下を含めます。

• 「最初に読む」：skills/<projectSlug>/SKILL.md へのリンク
• 「スキル」または同様のセクションに、以下を一覧表示します。
  • プロジェクトスキルへのリンク
  • 内部ワークフロースキルへのリンク
  • ランブックへのリンク

ルートドキュメントにワークフローの内容を重複して記載しないでください。

5) 任意：従来のスキル配置場所を非推奨にする（ラッパー）

ほかのディレクトリに既存のスキルがある場合：

• ファイルは残します
• 先頭に次のバナーを追加します。
  • 「移動しました：正式なワークフローは skills/<projectSlug>/workflows/... にあります」
• 残りは詳細なリファレンスとして残します

6) 整合性の検証（必須）

ひな形の完成を宣言する前に：

• すべてのリンクパスが存在すること（.md）を確認します。
• ワークフロー ID に一貫性があることを確認します。
  • projectSlug.workflow.* が配置先のファイルと一致していること。
• ルートドキュメントが正式な配置場所のみを参照していることを確認します。
• template.json の commands[].name の値が workflows/ に存在し、「コマンドルーティング」と routing-matrix.md に記載されていることを確認します。
• ルーターのみの動作がプロジェクトのエントリー SKILL.md に記載されていること（ドキュメント化されていないフラットエイリアスがないこと）を確認します。

レビューゲート（必ず合格すること）

• ルートドキュメントは最小限で、リンクのみを記載していること。
• 各ワークフローに、完全な契約セクション（Goal..References）があること。
• 制約が明示的で、検証可能であること（曖昧な「ベストプラクティス」は不可）。
• ルート、プロジェクトスキル、ワークフローの間に重複がないこと。
• すべてのリンクが解決できること（.md）。
• template.json が有効な JSON であり、workflowsWanted と整合していること。
• コマンドルーティングで、一覧にあるすべてのサブコマンドが、ちょうど 1 つのワークフロー契約に解決されること。

注記

• この設計図は、意図的に特定のスタックに依存しない構成です。スタック固有のルール（ロギング、ORM パターン、テストルール、ネットワークポリシー、IaC 標準、OS ベースライン）はプロジェクトスキルに記載し、ワークフローからリンクしてください。
• フロントマター付きのインストール可能なスキル契約については、SKILL.md（name: workflow-blueprint）を参照してください。