workflow-blueprint

agentic-workflows.blueprint

目标

提供一个可复用的蓝图工作流，为任何代码库搭建“Agent 工作流”文档结构，并支持渐进式信息披露和可执行契约（工作流）。

范围

• 适用范围：任何希望建立面向 Agent 的文档系统（编排器 + 工作流技能 + 参考资料 + 操作手册）的代码库。
• 不适用范围：实现产品功能；本蓝图仅用于搭建结构和编写文档。

触发条件

• “创建 Agent 工作流结构”
• “设置技能文件夹 + 工作流”
• “让文档更方便 Agent 使用”
• “将 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 或同等文件），添加指向新入口的链接。

此蓝图文件夹包含打包的工作流（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），用于演示端到端的串联执行、嵌入 Matt Pocock / AI Hero 方法论、将计划转换为技能、生成可视化文档、MCP 集成模式以及基础设施运维覆盖范围。

其中还可以在 runbooks/ 下包含操作手册示例，展示面向运维人员的工作流执行手册。

不变量（护栏）

• 渐进式披露：根文档保持简短；详细内容放在链接指向的文档中。
• 可执行契约：每个工作流都写成 Agent 可遵循的契约：
  • Goal、Scope、Triggers、Inputs、Invariants、Procedure、Outputs、Review gate、References。
• 不重复：不要在多个文件中复制粘贴冗长规则；链接到唯一事实来源。
• 一致性：所有引用中的工作流 ID 和文件路径必须完全一致。
• 最小范围：仅添加实际请求的工作流。
• 唯一事实来源：SKILL.md 是权威来源；template.json 是补充性的声明层，供提供命令接口的 Agent/工具使用。
• 命令路由：仅使用路由器；用户调用 /<skillName> <cmd>；入口技能将 cmd 解析为 workflows/<cmd>/SKILL.md，并仅加载该契约。
• 清单同步：template.json 中的每条命令都必须映射到现有的工作流文件夹，并与 routing-matrix.md 一致。

流程

1) 创建项目入口技能

创建 skills/<projectSlug>/SKILL.md 作为全局入口：

• 简要说明该技能的用途。
• 设置一个“协调器”部分，说明：
  • 如何对任务进行分类
  • 如何选择一个工作流
  • 如何结束任务（如适用，执行验证关卡）
• 设置一个 命令路由 部分（仅使用路由器）：
  • 调用格式：/<skillName> <cmd>（例如：/my-backend document）
  • 将 workflowsWanted 中的每个 cmd 映射到 workflows/<cmd>/SKILL.md
  • 如果 Agent 无法解析子命令，则从用户消息中读取 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[] 条目。
• 使 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：收到请求时，调整 skills/<projectSlug>/workflows/radioactive/SKILL.md，使其运行嵌入 Matt Pocock 技能的 14 阶段生命周期，并搭建 skills/<projectSlug>/workflows/mattpocock/，其中包含 wayfinder、grilling、domain-modeling、research、prototype 和 to-spec。确保第 1 阶段始终先执行主项目技能（skills/<projectSlug>/SKILL.md），以进行请求分类和约束提取，然后再执行 /wayfinder。

可选地，对于每个工作流，当外部工具需要独立的命令描述符时，可添加 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 一致。
• 命令路由将每个列出的子命令准确地解析到一个工作流契约。

备注

• 此蓝图有意不绑定特定技术栈。对于特定技术栈的规则（日志记录、ORM 模式、测试规则、网络策略、IaC 标准和 OS 基线），请将其保留在项目技能中，并从工作流链接到这些规则。
• 带前置元数据的可安装技能契约：参见 SKILL.md（name: workflow-blueprint）。