Workflow Framework Generator

工作流框架生成器 (workflow-framework-generator)

能力边界

• 能做: 根据工作流类型+目标平台，生成完整的CataForge兼容框架（agents/skills/workflows/configs）
• 不做: 执行生成的工作流、替代领域专家做业务决策、硬编码特定工作流逻辑

输入规范

• 必填: workflow_type 工作流类型（自由文本，如"公众号写作"）+ target_ide 目标平台（枚举: claude-code | cursor | codex | opencode）
• 可选: multi_agent / tool_calls / structured_output / output_format / project_name / output_dir 约束字段（详见 Phase 1.1）
• 上游知识源: references/domain-patterns.md（领域模式库）+ references/platform-capabilities.md（平台能力矩阵）

输出规范

• 输出目录: <output_dir>/（默认 ./generated-frameworks/<project_name>/）
• 完整产出: .cataforge/{framework.json, PROJECT-STATE.md, agents/, skills/, workflows/, hooks/hooks.yaml, rules/, platforms/, schemas/} + 根目录 README.md + docs/ 空目录
• 设计决策记录: 控制台输出 §设计决策输出 段定义的四节内容
• 不写入: 用户项目源码、CI 配置、运行时数据

执行流程

本 Skill 按三个阶段执行：解析 → 规划 → 生成。每个阶段有明确的输入输出契约。

Phase 1: 输入解析与需求澄清

1.1 解析用户输入

从用户消息中提取以下字段：

workflow_type: <string>        # 工作流类型 (必填)
target_ide: <string>           # 目标平台 (必填，枚举: claude-code | cursor | codex | opencode)
constraints:
  multi_agent: <bool>          # 是否需要多智能体协作 (默认: true)
  tool_calls: <bool>           # 是否需要工具调用 (默认: true)
  structured_output: <bool>    # 是否需要结构化产出 (默认: true)
  output_format: <string>      # 产出格式 (默认: markdown)
project_name: <string>         # 项目名称 (可选，默认从 workflow_type 派生)
output_dir: <string>           # 输出目录 (可选，默认: ./generated-frameworks/<project_name>)

1.2 输入验证

• target_ide 必须是已知平台之一。若用户输入模糊（如"vscode"），映射到最接近的平台并确认
• workflow_type 为自由文本，但需确认其属于可识别的领域类别

1.3 需求澄清（条件触发）

当以下条件满足时，必须向用户提出澄清问题（每批 ≤ MAX_QUESTIONS_PER_BATCH）：

澄清问题格式：

为了生成最适合的工作流框架，我需要确认以下信息：
1. [具体问题]
2. [具体问题]
3. [具体问题]

1.4 领域调研增强（条件触发）

当用户需求涉及你不熟悉的领域知识时：

1. 读取 references/domain-patterns.md 查找是否有匹配的领域模式
2. 若无匹配，使用 web_search 检索该领域的标准工作流程和最佳实践
3. 将调研结果结构化为：关键角色、核心流程、产出物清单、质量标准
4. 将结构化结果融入后续的架构设计

Phase 2: 架构规划

2.1 加载平台能力矩阵

读取 references/platform-capabilities.md，提取目标平台的：

• 支持的工具映射（tool_map）
• 可用特性（features）
• 代理调度方式（dispatch）
• Hook 支持程度
• 降级策略需求

2.2 设计 Agent 角色体系

基于工作流需求，设计 Agent 角色列表。每个 Agent 必须包含：

agent_id: <kebab-case>
name: <display_name>
role: <一句话角色定义>
responsibilities:
  - <职责1>
  - <职责2>
capabilities_needed:    # 使用 CataForge 能力标识符
  - file_read
  - file_write
  - shell_exec
interaction_pattern: <orchestrated | autonomous | reactive>
upstream_agents: [<agent_id>]     # 上游依赖
downstream_agents: [<agent_id>]   # 下游消费

设计原则：

• 每个 Agent 有且仅有一个核心职责（单一职责原则）
• Agent 之间通过文件系统传递状态，不依赖共享内存
• 至少包含一个 orchestrator 角色（当 multi_agent=true 时）
• 总 Agent 数量控制在 3-10 个（避免过度设计）

单代理降级：当 multi_agent=false 或目标平台不支持 agent_dispatch 时：

• 将所有角色合并为单一 Agent
• 使用 Skill 模块化拆分不同职责
• 工作流编排退化为 prompt 级顺序执行

2.3 设计 Skill 模块

从 Agent 职责中提取可复用的能力单元：

skill_id: <kebab-case>
name: <display_name>
type: instructional | executable | hybrid
description: <一句话描述>
input: <输入描述>
output: <输出描述>
used_by: [<agent_id>]
depends: [<skill_id>]
suggested-tools: [<capability_id>]   # 注意短横线，非下划线 — SkillLoader 仅识别带短横线的键名

提取规则：

• 跨 Agent 复用的逻辑 → 独立 Skill
• 可独立测试的处理逻辑 → 独立 Skill
• 特定于单一 Agent 且不复用 → 保留在 Agent 指令中
• 不创建仅被一个 Agent 使用且逻辑简单的 Skill

2.4 设计 Workflow 编排

定义工作流的阶段、依赖和状态流转：

workflow_id: <kebab-case>
phases:
  - id: <phase_id>
    name: <phase_name>
    agent: <agent_id>
    skills: [<skill_id>]
    inputs: [<doc_path or previous_phase_output>]
    outputs: [<doc_path>]
    gate: <quality_gate_description>  # 可选
    next: <phase_id> | [<phase_id>]   # 支持分支

编排原则：

• 阶段间通过文件产出物传递状态
• 每个阶段有明确的输入/输出契约
• 关键阶段设置质量门禁（gate）
• 支持线性、分支、并行三种流转模式

2.5 平台适配决策

按 references/platform-capabilities.md 中目标平台的能力矩阵做出适配决策并记录理由。对每个不支持的能力，选择降级策略：

• 替代实现: 用可用工具组合实现等效功能
• 规则注入: 将逻辑嵌入 Agent 指令中
• 跳过: 标记为不可用并说明影响

Phase 3: 框架生成

3.1 生成目录结构

根据规划结果，生成以下目录结构：

<output_dir>/
├── .cataforge/
│   ├── framework.json              # 框架主配置
│   ├── PROJECT-STATE.md            # 项目状态文档
│   ├── agents/                     # Agent 定义
│   │   ├── <agent-id>/
│   │   │   └── AGENT.md
│   │   └── ...
│   ├── skills/                     # Skill 模块
│   │   ├── <skill-id>/
│   │   │   └── SKILL.md
│   │   └── ...
│   ├── workflows/                  # 工作流定义
│   │   └── <workflow-id>.yaml
│   ├── hooks/                      # Hook 规范
│   │   └── hooks.yaml
│   ├── rules/                      # 通用规则
│   │   ├── COMMON-RULES.md
│   │   └── SUB-AGENT-PROTOCOLS.md
│   ├── platforms/                   # 平台适配
│   │   └── <target_ide>/
│   │       └── profile.yaml
│   └── schemas/                    # 数据模型
│       └── agent-result.schema.json
├── docs/                           # 工作产出目录（空，由 context 在生成首份文档时调用 `cataforge context index` 创建 .doc-index.json）
└── README.md                       # 框架说明

3.2 生成 Agent 定义

读取 templates/agent.md.tmpl，为每个 Agent 生成 AGENT.md。

关键规则：

• tools 字段使用 CataForge 能力标识符（如 file_read），不使用平台原生名称
• skills 字段引用 Phase 2.3 中设计的 Skill ID
• allowed_paths 根据 Agent 职责设置写入范围限制
• maxTurns 根据任务复杂度设置（简单任务: 30, 中等: 80, 复杂: 150）
• Agent 指令部分使用中文（与 CataForge 惯例一致），技术标识符使用英文

章节骨架以 templates/agent.md.tmpl 为准；其中 Identity / Input Contract / Output Contract / Anti-Patterns 必须各为独立的 ## 二级标题（validate_framework.py 强制）。

3.3 生成 Skill 定义

读取 templates/skill.md.tmpl，为每个 Skill 生成 SKILL.md（章节骨架与 frontmatter 字段以 tmpl 为准）。

3.4 生成 Workflow 定义

读取 templates/workflow.yaml.tmpl，生成工作流编排文件（phase 字段结构以 tmpl 内注释为准）。

3.5 生成框架配置

framework.json — 读取 templates/framework.json.tmpl，填充：

• version: "1.0.0"
• runtime.platform: target_ide 的 platform_id
• constants: 根据工作流特性设置
• features: 根据 Skill 依赖启用

hooks.yaml — 读取 templates/hooks.yaml.tmpl，生成适用的 Hook 规范。仅生成目标平台支持的 Hook，不支持的标记降级策略。

profile.yaml — 读取 templates/platform-profiles/<target_ide>.yaml.tmpl，生成目标平台的能力映射。

COMMON-RULES.md — 读取 templates/common-rules.md.tmpl 生成工作流通用规则。

SUB-AGENT-PROTOCOLS.md — 读取 templates/sub-agent-protocols.md.tmpl 生成子代理协议。

PROJECT-STATE.md — 读取 templates/project-state.md.tmpl 生成项目状态文档。

3.6 生成 README.md

生成项目级 README，包含：

• 框架概述与设计目标
• 目录结构说明
• 快速开始指南（针对目标平台）
• Agent 与 Skill 清单
• 工作流阶段说明
• 平台限制与降级说明
• 扩展指南

Phase 4: 输出验证

生成完成后，执行以下验证：

4.1 自动化检查

运行 scripts/validate_framework.py（覆盖：frontmatter 合法性、必填章节、framework.json / profile.yaml / hooks.yaml 结构、交叉引用、孤立 Skill、Agent 依赖 DAG）。

4.2 LLM 独有检查（脚本无法判定）

• 无未实现占位符（禁止出现待办标记或空壳逻辑）
• 无冗余 Agent（每个 Agent 的职责不与其他 Agent 显著重叠，无大面积职责交叉）
• 降级策略覆盖所有不支持的能力
• Workflow 有且仅有一个入口阶段和至少一个终止阶段

设计决策输出

生成完成后，按 templates/design-decisions.md.tmpl 输出四节设计决策说明（Agent 角色划分 / Skill 提取策略 / 工作流编排模式 / 平台适配）。

多平台同时生成

当用户请求为多个平台生成框架时：

1. 先生成平台无关的核心结构（agents/, skills/, workflows/）
2. 为每个目标平台生成独立的 platforms/<platform_id>/profile.yaml
3. 共享 framework.json 但 runtime.platform 设为首选平台
4. 在 README.md 中说明多平台切换方式

扩展机制

生成的框架遵循开闭原则：新增 Agent / Skill / Workflow / 平台 / Hook 均在 §3.1 目录树对应子目录下新建文件（agents/ / skills/ / workflows/ / platforms/ / hooks/hooks.yaml），不需修改已有文件。

Anti-Patterns

• 禁止: 生成的 SKILL.md / AGENT.md 含硬约束违规（版本里程碑 / PR 编号 / 特定语言关键字）— 下游项目会继承腐化，应在 Phase 3 模板填充后跑 check_no_design_residue / check_no_language_coupling 守卫
• 禁止: 生成的 Anti-Patterns 段少于 ANTI_PATTERN_MIN_COUNT_SKILL / ANTI_PATTERN_MIN_COUNT_AGENT — framework-review Layer 1 的 Anti-Patterns 数量下限检查会 FAIL，下游 framework-review 阻塞
• 禁止: 生成的 agent allowed_paths 与 Anti-Patterns 行为约束矛盾 — 机制层放行 vs 行为层禁止的矛盾会让 reviewer 兜底失效
• 避免: 生成框架时跳过 Phase 4 验证 — 自动化检查 + LLM 独有检查是防止半成品产出的关键

注意事项

• 生成的框架使用 CataForge 能力标识符，部署时由 deployer 自动翻译为平台原生名称
• Agent 指令内容使用中文（与 CataForge 项目惯例一致），技术标识符和配置键使用英文
• 生成的文件不包含任何未实现占位符，每个文件都是完整可用的，不依赖后续手动补全