project-flow-cy
把任何项目(代码 / 调研 / 内容 / 方案)按清晰的项目边界来管理:上下文落进文件,Agent 之间靠 flow/、docs/ 异步接力,跨模型评审做质量门。 本 skill 负责搭建与维护这套协作结构,以及在 Agent 间收工交接(进展日志)。
- 完整方法论详规在
references/(工作流程.md / 多子项目结构.md / 文档维护SOP.md / DESIGN维护SOP.md / hook机制.md / 初始化SOP.md)。
- 注入项目的模板实体在
assets/templates/。
先判断用户要哪个操作
- 要"初始化 / 接入 / 搭结构 / 建骨架" → 操作 A
- 要"收工 / 交接 / 写交接卡 / handoff / 交接给下一个" → 操作 B(在进展日志追加一条)
- 拿不准就先问一句,别猜。
操作 A:初始化 / 接入项目
把当前项目接入协作流程,产出标准结构。完整步骤与验证清单在 references/初始化SOP.md——执行前先读它。 要点(对应 R5 非破坏):
- 先判项目边界:扫描当前目录的代码入口、workspace 配置和嵌套
.git;判断是单体项目、单仓多子项目,还是多个独立仓库。发现多个有独立职责的子项目时,先读 references/多子项目结构.md。不要仅凭文件夹数量判断。
- 判断状态:目录是否已有
AGENTS.md / 内容。新项目全量铺;已有项目非破坏合并(缺啥补啥,绝不覆盖已有内容)。
- 先列清单等确认:把项目边界判断和"将创建 / 修改的文件"列给用户,确认后再动手。
- 铺根级骨架:每个项目边界只建一套
flow/(charter.md plan.md 进展.md decisions.md 踩坑记录.md tasks/)+ docs/。已有代码布局原样保留;只有全新单体代码项目且用户需要时才补 src/ 或 scripts/,不要替 monorepo 猜造业务目录。
- 生成分层入口:用
assets/templates/AGENTS.md 生成根级 AGENTS.md,再让根级 CLAUDE.md 指向它。单仓多子项目中,每个有独立职责的子项目用 assets/templates/MODULE_AGENTS.md 生成局部 AGENTS.md 并建立同目录 CLAUDE.md 软链(Windows 改复制);局部入口只写本模块职责、命令、约束和根级指针,不复制总体计划。可选 DESIGN.md 仅用于设计 / 创意工作。
- 装 hook:只在每个项目边界的根目录复制
assets/templates/.hooks/、.claude/、.codex/;chmod +x .hooks/stop-doccheck.sh;检测 Codex 版本与 features.hooks。Claude Code 只以 prompt_id、可解析版本不低于 0.145.0 的 Codex 只以 turn_id 界定用户回合,每回合自动续跑一次;更旧、未知版本或缺本工具专属稳定 ID 时安全放行。若 hooks 被关只提醒用户开 ~/.codex/config.toml 或用 --enable hooks,不擅自改全局 config;提醒 Codex 项目需 trust 且 /hooks 批准。历史事故与版本门见 references/hook机制.md。
- 详规随项目:把
references/ 下 6 份详规复制到根级 flow/规范/(自包含)。
- 跑接入自检:在 Skill 源码目录先运行
bash tests/test-stop-hook.sh,再逐项核对 references/初始化SOP.md 末尾清单(软链是否解析正确、hook 是否输出合法 JSON、根级和模块级边界是否正确)。Codex 客户端升级或 continuation 机制变动后,显式运行 PROJECT_FLOW_RUN_CODEX_TUI_E2E=1 bash tests/test-codex-stop-hook-e2e.sh;该测试会调用在线模型,不能混入普通快速回归。
- 收尾:引导用户开始填根级
flow/charter.md;多子项目时一并确认子项目地图和跨模块契约目录。
幂等:可重复跑,不产生重复或破坏(也是更新老项目详规副本的方式)。
操作 B:收工交接(在进展日志追加一条)
把当前会话这一棒的进展,追加到 flow/进展.md 最上面,供下一个 Agent / 会话接力。一个 append 文件,不是一张张攒卡;顶部那条 = 当前交接棒。
- 在
flow/进展.md 顶部加一条(模板在文件里),填:
- 做了什么 / 为什么 / 怎么理解 / 产出(路径)/ 问题→解决 / 下一步(接手方第一个动作)。
- 并把这条同时贴在回复里——用户当场看到 + 能直接复制给别的 Agent。
- 决策追加
flow/decisions.md;问题 / 踩坑追加 flow/踩坑记录.md。
- 铁律:只带「指针 + 增量」——「产出」给真实路径,例如
docs/specs/xxx.md、frontend/src/...、backend/src/...;不重抄内容。
一直要守的铁律(来自方法论)
- 审稿模型 ≠ 产出模型;产出落文件;先 plan 后 act;一会话一焦点;从根本解决不打补丁。
- 一个项目边界一个控制面:单仓多子项目只保留一套根级
flow/、docs/ 和 hook,不在子项目机械复制。
- 目录归属(R1):协调 / 推进项目的 → 根级
flow/;跨模块知识、方案和交付说明 → 根级 docs/;代码 → 对应子项目目录。
- 局部例外:已有子项目 README、紧贴代码维护的生成文档或开发说明可以就近保留,但根级
docs/README.md 要给索引;不要为了集中而搬动现有文件。
- 需要展开规则时按需读
references/ 下对应详规,别把全文塞进当前上下文。
1---2name: project-flow-cy3description: 用一套基于文件的多 Agent 协作流程来初始化和管理项目,并在 Claude Code 与 Codex 之间用 flow/进展.md 进展日志接力。初始化时先判断单体项目、单仓多子项目(monorepo)或多独立仓库;单仓多子项目只建一套根级 flow/(控制层)+ docs/(集中内容层),各子项目只补局部 AGENTS.md/CLAUDE.md 入口,不重复控制层。两个操作——(1) 把项目接入流程:生成入口、装收工自检 hook、复制方法论详规;(2) 收工交接:在 flow/进展.md 顶部追加进展。当用户说"用这套流程/协作流程初始化项目""接入协作流程""给项目搭 flow/docs 文档结构""初始化项目文档体系""建项目协作骨架""monorepo 怎么管理""前后端多个子项目怎么组织""写交接卡""写个 handoff""生成交接卡""交接给下一个 agent/会话"时,必须使用本 skill。即使没明确点名,只要是要给项目搭这套 docs/flow 协作骨架、处理多子项目的协作分层、或在 agent/会话之间做结构化交接,也应主动使用。仅用于"项目协作流程的搭建与交接",不处理具体业务内容。4---56# project-flow-cy78把任何项目(代码 / 调研 / 内容 / 方案)按清晰的**项目边界**来管理:**上下文落进文件,Agent 之间靠 `flow/`、`docs/` 异步接力,跨模型评审做质量门。** 本 skill 负责**搭建与维护这套协作结构**,以及在 Agent 间**收工交接(进展日志)**。910- 完整方法论详规在 `references/`(`工作流程.md` / `多子项目结构.md` / `文档维护SOP.md` / `DESIGN维护SOP.md` / `hook机制.md` / `初始化SOP.md`)。11- 注入项目的模板实体在 `assets/templates/`。1213## 先判断用户要哪个操作14- 要"初始化 / 接入 / 搭结构 / 建骨架" → **操作 A**15- 要"收工 / 交接 / 写交接卡 / handoff / 交接给下一个" → **操作 B**(在进展日志追加一条)16- 拿不准就先问一句,别猜。1718---1920## 操作 A:初始化 / 接入项目2122把当前项目接入协作流程,产出标准结构。**完整步骤与验证清单在 `references/初始化SOP.md`——执行前先读它。** 要点(对应 R5 非破坏):23241. **先判项目边界**:扫描当前目录的代码入口、workspace 配置和嵌套 `.git`;判断是单体项目、单仓多子项目,还是多个独立仓库。发现多个有独立职责的子项目时,先读 `references/多子项目结构.md`。不要仅凭文件夹数量判断。252. **判断状态**:目录是否已有 `AGENTS.md` / 内容。新项目全量铺;**已有项目非破坏合并(缺啥补啥,绝不覆盖已有内容)**。263. **先列清单等确认**:把项目边界判断和"将创建 / 修改的文件"列给用户,确认后再动手。274. **铺根级骨架**:每个项目边界只建一套 `flow/`(`charter.md` `plan.md` `进展.md` `decisions.md` `踩坑记录.md` `tasks/`)+ `docs/`。已有代码布局原样保留;只有全新单体代码项目且用户需要时才补 `src/` 或 `scripts/`,不要替 monorepo 猜造业务目录。285. **生成分层入口**:用 `assets/templates/AGENTS.md` 生成根级 `AGENTS.md`,再让根级 `CLAUDE.md` 指向它。单仓多子项目中,每个有独立职责的子项目用 `assets/templates/MODULE_AGENTS.md` 生成局部 `AGENTS.md` 并建立同目录 `CLAUDE.md` 软链(Windows 改复制);局部入口只写本模块职责、命令、约束和根级指针,不复制总体计划。可选 `DESIGN.md` 仅用于设计 / 创意工作。296. **装 hook**:只在每个项目边界的根目录复制 `assets/templates/.hooks/`、`.claude/`、`.codex/`;`chmod +x .hooks/stop-doccheck.sh`;检测 Codex 版本与 `features.hooks`。Claude Code 只以 `prompt_id`、可解析版本不低于 `0.145.0` 的 Codex 只以 `turn_id` 界定用户回合,每回合自动续跑一次;更旧、未知版本或缺本工具专属稳定 ID 时安全放行。若 hooks 被关只提醒用户开 `~/.codex/config.toml` 或用 `--enable hooks`,**不擅自改全局 config**;提醒 Codex 项目需 trust 且 `/hooks` 批准。历史事故与版本门见 `references/hook机制.md`。307. **详规随项目**:把 `references/` 下 6 份详规复制到根级 `flow/规范/`(自包含)。318. **跑接入自检**:在 Skill 源码目录先运行 `bash tests/test-stop-hook.sh`,再逐项核对 `references/初始化SOP.md` 末尾清单(软链是否解析正确、hook 是否输出合法 JSON、根级和模块级边界是否正确)。Codex 客户端升级或 continuation 机制变动后,显式运行 `PROJECT_FLOW_RUN_CODEX_TUI_E2E=1 bash tests/test-codex-stop-hook-e2e.sh`;该测试会调用在线模型,不能混入普通快速回归。329. **收尾**:引导用户开始填根级 `flow/charter.md`;多子项目时一并确认子项目地图和跨模块契约目录。3334幂等:可重复跑,不产生重复或破坏(也是更新老项目详规副本的方式)。3536---3738## 操作 B:收工交接(在进展日志追加一条)3940把当前会话这一棒的进展,**追加到 `flow/进展.md` 最上面**,供下一个 Agent / 会话接力。**一个 append 文件,不是一张张攒卡**;顶部那条 = 当前交接棒。41421. 在 `flow/进展.md` 顶部加一条(模板在文件里),填:43 - **做了什么 / 为什么 / 怎么理解 / 产出(路径)/ 问题→解决 / 下一步**(接手方第一个动作)。44 - **并把这条同时贴在回复里**——用户当场看到 + 能直接复制给别的 Agent。452. 决策追加 `flow/decisions.md`;问题 / 踩坑追加 `flow/踩坑记录.md`。463. **铁律:只带「指针 + 增量」**——「产出」给真实路径,例如 `docs/specs/xxx.md`、`frontend/src/...`、`backend/src/...`;不重抄内容。4748---4950## 一直要守的铁律(来自方法论)51- 审稿模型 ≠ 产出模型;产出落文件;先 plan 后 act;一会话一焦点;从根本解决不打补丁。52- **一个项目边界一个控制面**:单仓多子项目只保留一套根级 `flow/`、`docs/` 和 hook,不在子项目机械复制。53- **目录归属(R1)**:协调 / 推进项目的 → 根级 `flow/`;跨模块知识、方案和交付说明 → 根级 `docs/`;代码 → 对应子项目目录。54- **局部例外**:已有子项目 README、紧贴代码维护的生成文档或开发说明可以就近保留,但根级 `docs/README.md` 要给索引;不要为了集中而搬动现有文件。55- 需要展开规则时按需读 `references/` 下对应详规,别把全文塞进当前上下文。
cy-chenyue