ForgeFlow

面向个人开发者的 AI 协作软件工程能力框架。把优秀工程师的工作方法协议化，以 Claude Code / Codex 插件形式分发，让 Agent 在固定流程约束下工作，而不是自由发挥。

设计思路

AI 的问题不是能力不足，而是缺乏约束——不知道何时停下来问、何时写测试、何时从全局看问题。ForgeFlow 的每个 Skill 是一个约束单元，把工程师的判断时机固化成可触发的流程。

详见 meta/PHILOSOPHY.md 和 meta/METHODOLOGY.md。

Skills

decision

Skill	说明
decision/decision-forge	推进复杂设计与工程决策收敛，把模糊想法变成可执行、可追溯的工程决策
decision/domain-modeling	构建并锐化项目领域模型，维护 CONTEXT.md 术语表并克制地记录 ADR
decision/to-questionnaire	把决策中的外部知识缺口整理成面向单一知情人的异步问卷

engineering

Skill	说明
engineering/coding-with-tdd	红绿重构循环实现功能或修复 bug，通过公共接口验证行为
engineering/architecture	识别并改进代码库架构复杂度，基于 Deep Module 和分层一致性提出改进候选
engineering/code-review	对固定 diff 分别做 Standards 与 Spec 双轴审查，并复核每条 finding
engineering/implement	从 PRD 或 agent-ready tasks 按依赖推进实现、验证和双轴审查
engineering/zoom-out	上升一层抽象，给出当前代码区域的系统地图：相关模块、调用者、依赖方向
engineering/git-commit	从当前变更中提炼最小一致性提交，生成高质量 git commit
engineering/research	委派后台 agent 针对一手来源调研问题，结论沉淀为带引用的 markdown
engineering/prototype	构建一次性原型回答设计问题：逻辑用终端状态机，UI 用多变体切换
engineering/wizard	为仅剩人工操作的凭据、第三方配置或一次性切换流程生成安全交互式 Bash 向导

governance

Skill	说明
governance/issue-breakdown	用垂直切片把 PRD 或计划拆成可独立验证的工程任务
governance/diagnose-lite	轻量诊断：最小复现、假设、验证、修复、再验证
governance/repo-health	检查仓库健康度：ownership、依赖、安全、架构漂移、测试质量
governance/triage	通过分诊角色状态机推进 issue 和外部 PR：分类、验证、撰写 agent brief
governance/wayfinder	把超出单 session 的大块工作规划成调查型 tickets 地图，逐个解决直到路线清晰

operations

Skill	说明
operations/release	管理发布生命周期：发布前验收、版本说明、rollback plan、发布后检查
operations/operate	管理运行维护生命周期：observability、runbook、incident intake、维护节奏

product

Skill	说明
product/discovery	在进入 PRD 前验证问题、用户、替代方案和 MVP 成功指标
product/to-prd	将想法或对话上下文整理成轻量 PRD
product/feedback-to-roadmap	将发布后反馈、数据和复盘结论整理成下一轮 roadmap

misc

Skill	说明
misc/setup-forgeflow	在新仓库中初始化 ForgeFlow agent runtime 上下文（首次使用前运行）
misc/writing-for-agents	在非 ForgeFlow 源仓库中设计、审查和精简 Agent 会消费的文档
misc/personal-skill-builder	在 ForgeFlow 源仓库中创建、编辑、审查、精简、注册并验证双平台 Agent Skills
misc/terse-communication	中英双语极简沟通模式，压缩冗余，保留技术准确性
misc/handoff	把当前对话压缩成交接文档，供下一个 agent 会话接手
misc/resolving-merge-conflicts	基于一手来源解决进行中的 git merge/rebase 冲突
misc/ask-forgeflow	询问当前情境该用哪个 Skill 或执行路径，ForgeFlow 全部 Skills 之上的路由器

工程生命周期

阶段	推荐 Skill
问题验证	product/discovery
需求整理	product/to-prd
决策收敛	decision/decision-forge
领域建模	decision/domain-modeling
外部知识收集	decision/to-questionnaire
技术调研	engineering/research
原型验证	engineering/prototype
人工步骤向导	engineering/wizard
任务拆解	governance/issue-breakdown
Issue 分诊	governance/triage
大型工作探路	governance/wayfinder
实现编排	engineering/implement
TDD 垂直切片	engineering/coding-with-tdd
架构改进	engineering/architecture
问题诊断	governance/diagnose-lite
发布	operations/release
运维	operations/operate
反馈迭代	product/feedback-to-roadmap
仓库治理	governance/repo-health

安装

Claude Code（推荐：marketplace 持久安装）

本仓库根目录即插件本体，无需构建。在 Claude Code 对话中执行：

/plugin marketplace add Leo0426/forge-flow
/plugin install forgeflow@forgeflow

安装后跨会话持久生效。

Claude Code（本地开发：临时加载）

修改 skill 后本地验证用，只在当前会话生效：

python3 tools/build_plugins.py
python3 tools/check_skills.py
claude --plugin-dir ./build/plugins/claude-code/forgeflow

Codex（推荐：GitHub 在线安装）

无需克隆仓库或运行构建脚本，直接将 GitHub 仓库添加为 Codex marketplace：

codex plugin marketplace add Leo0426/forge-flow
codex plugin add forgeflow@forgeflow

安装后启动一个新的 Codex 任务，使插件中的 skills 生效。可用以下命令确认安装状态：

codex plugin list

如果需要固定到特定版本，可以在首次添加 marketplace 时指定 Git tag：

codex plugin marketplace add Leo0426/forge-flow --ref vX.Y.Z
codex plugin add forgeflow@forgeflow

Codex（本地开发）

修改 skill 后使用独立的 forgeflow-local marketplace 验证，避免覆盖在线安装源：

python3 tools/build_plugins.py
python3 tools/check_skills.py
codex plugin marketplace add ./build/plugins/codex
codex plugin add forgeflow@forgeflow-local

安装后在新任务中输入 $ mention Skill，或运行 /skills 后从 picker 选择。下面列出显式调用名；这是 Codex 的官方 Skill 调用方式，和 Claude Code 的 /forgeflow:<name> 语法不同（见 OpenAI Skills 文档）：

$forgeflow:setup-forgeflow      → 初始化仓库运行时上下文（首次使用先运行这个）
$forgeflow:decision-forge       → 决策收敛
$forgeflow:domain-modeling      → 领域建模
$forgeflow:to-questionnaire     → 生成异步决策问卷
$forgeflow:coding-with-tdd      → TDD 红绿重构
$forgeflow:implement            → 按任务依赖实现、验证和审查
$forgeflow:architecture         → 架构改进
$forgeflow:code-review          → diff 审查
$forgeflow:zoom-out             → 系统地图
$forgeflow:git-commit           → 语义化 commit
$forgeflow:research             → 一手来源调研
$forgeflow:prototype            → 一次性原型
$forgeflow:wizard               → 仅剩人工步骤的安全交互向导
$forgeflow:issue-breakdown      → 任务拆解
$forgeflow:diagnose-lite        → 问题诊断
$forgeflow:repo-health          → 仓库健康检查
$forgeflow:triage               → issue/PR 分诊
$forgeflow:wayfinder            → 大型工作探路
$forgeflow:release              → 发布管理
$forgeflow:operate              → 运维管理
$forgeflow:discovery            → 问题验证
$forgeflow:to-prd               → 轻量 PRD
$forgeflow:feedback-to-roadmap  → 反馈转 roadmap
$forgeflow:terse-communication  → 极简沟通模式
$forgeflow:writing-for-agents   → 编写 Agent 消费的文档
$forgeflow:personal-skill-builder → 创建新 skill
$forgeflow:handoff              → 会话交接文档
$forgeflow:resolving-merge-conflicts → 解决 merge/rebase 冲突
$forgeflow:ask-forgeflow        → skill 路由器

更新

Claude Code（marketplace 安装）

/plugin marketplace update forgeflow
/plugin update forgeflow@forgeflow

marketplace 安装跟随本仓库 GitHub 默认分支；每个发布版本都有对应的 vX.Y.Z tag 和 CHANGELOG.md 条目，更新前可先查看变更。

Codex（在线安装）

codex plugin marketplace upgrade forgeflow
codex plugin add forgeflow@forgeflow

更新后启动一个新的 Codex 任务。使用 --ref vX.Y.Z 固定版本的 marketplace 不会自动切换到新 tag；如需升级固定版本，应移除后使用新的 --ref 重新添加。

本地开发

重新运行 python3 tools/build_plugins.py 刷新构建产物。Claude Code 的 --plugin-dir 每次启动读取最新构建；Codex 重新执行 codex plugin add forgeflow@forgeflow-local，然后启动一个新任务。

发布（维护者）

python3 tools/release.py patch --dry-run   # 预检 + 预览将写入 CHANGELOG 的提交
python3 tools/release.py patch             # 校验 → bump 版本 → CHANGELOG → 构建 → commit + tag
python3 tools/release.py minor --push      # 发布并推送 commit 与 tag 到 origin

发布脚本的 preflight 会校验工作区干净、每个 Skill 在 plugin.json / 顶层 README / bucket README / 显式调用名列表中的注册一致性、Claude/Codex 调用策略、Codex Plugin 同源性和许可文件（对应添加 Skill 检查清单）；版本号在 plugin.json 与 marketplace.json 中同步更新。开发中的脏工作区先运行 python3 tools/build_plugins.py，再运行 python3 tools/check_skills.py。

项目结构

skills/         可复用 skill，按 bucket 分类
  decision/
  engineering/
  governance/
  operations/
  product/
  misc/
.agents/plugins/marketplace.json  Codex 在线 marketplace 清单
plugins/forgeflow/                Codex 可安装发行包（由构建脚本生成）
meta/           设计文档
  PHILOSOPHY.md   核心思路
  METHODOLOGY.md  架构设计方法论
CONTEXT.md      领域术语表
CHANGELOG.md    版本变更记录
tools/          插件打包与发布脚本

鸣谢

mattpocock/skills — 把工程师工作方式显式化为可触发 Skill 的最佳范例。

本项目中实质性改编的第三方内容及对应许可见 THIRD_PARTY_NOTICES.md。

许可证

MIT