元序（yotta-workflow）
本文件是全局层标准：所有项目共享同一套工作流程。状态文件位置按规则判定（见下）。
核心原则：流程全局定，状态跟项目根目录。开工必读状态，收工必留锚点。
快速判定（先看这节，30 秒决定要不要用）
> 这是全局层工作流标准，装上它就是为了让 AI 自动按此执行，不需要用户每次提醒。
| 判断项 | 结论 |
|---|---|
| 这是什么 | 跨会话 / 跨项目的工作流协议：开工读状态 → 进行中记流水/任务/决策 → 收工留锚点。状态统一存本项目 .workflow。 |
| 何时触发 | 涉及「项目」「续测」「跨会话」「要落盘」「多步开发」「收工」即触发；一次性只读问答不触发。 |
| 怎么用（三步） | ① 先按「〇」定位项目根目录，再定状态目录 → ② 存在就读 STATE/TASKS/ROADMAP/DECISIONS + 近期 logs；不存在就初始化 → ③ 全程按「二/三/四」执行，收工输出「五」锚点。 |
是否初始化 .workflow |
项目型会话（能确定项目根目录 / 要落盘 / 多步开发）→ 自动初始化并全程执行；轻量临时会话（纯问答 / 一次性）→ 不初始化，只按需提示。 |
| AI 该记住什么 | 只记「项目状态类」：进度 / 任务 / 决策 / 流水。不记：AI 人格 / 用户偏好 / 关系 / 跨项目通用知识（非项目状态，不写入本技能状态文件）。 |
| --- |
这个技能与智能体自带记忆的关系（本质）
> 它不取代任何智能体的记忆，而是补足"自带记忆做不到"的那部分：跨智能体共享、跨会话续接、统一的项目状态真相源 + 强制流程。
智能体自带的记忆（如 AGENTS.md、CLAUDE.md、rules、memory/、会话内上下文）通常是单机、单智能体、无统一结构的，有几个局限：
- 只在"这一个智能体"里生效，别的智能体不读。
- 各产品各写各的，项目状态会碎成多份、产生多个真相源。
- 只提供"能存"，不规定"何时读、何时写、写什么"，靠 AI 自觉，容易漏。
本技能单独存在的价值：
- 跨智能体共用一套 .workflow 状态：任何智能体读同一份 → 单一真相源。
- 跨会话持久 + 无缝续接：进度/任务/决策/流水落成文件，下个会话一读即续。
- 强制流程纪律：开工必读 → 进行中必记 → 收工必留锚点，不依赖 AI 自觉。
- 状态结构统一：STATE / TASKS / DECISIONS / ROADMAP / logs，AI 一读即知项目在哪、下一步做什么。
适用判断：
- 值得单独用：多智能体协作同一项目、项目要长远跨会话做、或希望项目状态不碎成 N 份。
- 不必单独用：只用单一智能体、自带记忆够用、项目很轻 → 自带记忆即可，本技能是锦上添花。
〇、路径模型与状态目录判定
> 这一节解决一个高频混淆：项目根目录不等于源码目录，.git 也不能单独决定项目根目录。 状态跟着项目根目录走，不跟着某一个代码仓库走。
1. 三个概念（一句话分清）
| 概念 | 定义 | 是否放 .workflow |
|---|---|---|
| 项目根目录 | 拥有这个项目全部状态的目录；源码、文档、素材、配置都可以放在它里面。它不要求有 Git。 | 放这里：<项目根目录>\.workflow\ |
| 源码目录 | 存放代码、资源或某个 Git 仓库的目录；它只是项目内部的一个位置。 | 不放；除非用户明确说明“它同时就是项目根目录” |
| 工作区根目录 | 下面并列放着多个项目根目录的父目录；它不拥有某一个项目的状态。 | 不放；先选具体项目根目录，再放到项目根目录下 |
一句话：项目根目录 = 状态锚点；源码目录 = 实现位置；工作区根 = 项目容器。
标准形态（默认按这个理解）：
<项目根目录>\
├── .workflow\ # 工作流；始终直接放在项目根目录
└── <源码目录>\ # 代码目录；位于项目根目录之下
标准只规定两件事：.workflow 必须直接放在项目根目录下；源码目录属于项目根目录内部。 实际项目里源码目录叫什么、放在哪一层、是否有特殊布局，由用户按项目情况调整，本技能不替用户改造项目结构。
2. 唯一状态目录
状态目录固定为 项目根目录下的 .workflow\：
<项目根目录>\.workflow\
├── STATE.md
├── TASKS.md
├── DECISIONS.md
├── ROADMAP.md
└── logs\
└── YYYY-MM-DD.md
对同一项目，任何智能体会话（无论 Codex / Cursor / Hermes / OpenCode…）都读写这一份 .workflow\，不得因为使用的智能体不同而另建一份。
以下信号都不能单独判定项目根目录：.git、package.json、src、app、README、当前目录是不是 Git 仓库根。它们只能说明当前目录“像源码”，不能说明它“拥有整个项目”。
3. 判定顺序（从强到弱）
项目根目录只认两种证据，按顺序执行：
- 用户明确指定项目根目录（直接说项目根目录、给出交接锚点的“路径”，或确认“当前目录就是项目根目录”）→ 这是项目根目录。
- 从 cwd 向上查找已有
.workflow\STATE.md→ 找到最近的一份；它所在的父目录就是项目根目录。已有.workflow永不自动迁移、复制或重建。 - 两种证据都没有 → 停止初始化，先问一个问题：
这个任务的项目根目录是哪一个？不得用.git、package.json、src、README、cwd 或目录结构自行猜测。
如果用户明确说 cwd 就是项目根目录，则使用 cwd；如果用户说项目根目录在上层，则使用上层；如果用户给的是工作区根，则继续问具体项目根目录。判断依据永远来自用户或已有 .workflow，不来自目录里有什么文件。
定位时只处理项目根目录；源码目录如何组织，不参与 .workflow 的位置判定。
- 不要写死任何默认路径。 不同宿主给未指定项目的会话分配的 cwd 可能不同；不能把某个盘符或目录当通用默认。
项目名取项目根目录名；同名冲突时附加路径哈希。
> 兼容红线：本次规则只影响首次初始化和解释口径。任何已经存在的 .workflow\ 保持原位，不因源码仓库嵌套、目录改名或规则升级而迁移。
〇·一、快速定位例子
| 场景 | 项目根目录 | 状态目录 |
|---|---|---|
| 标准形态 | <项目根目录> |
<项目根目录>\.workflow\ |
| 用户明确指定项目根目录 | 用户指定的目录 | <项目根目录>\.workflow\ |
向上找到已有 .workflow |
.workflow 的父目录 |
已有 .workflow\，原地沿用 |
没有用户指定，也没有已有 .workflow |
先问 | 不创建 |
更完整的路径走查见 references/path-model.md。
一、项目状态体系
状态文件结构固定一致。所有状态文件与流水日志都存放在本项目根目录的 .workflow\ 状态目录下（位置见「〇」），项目之间互不共享、互不读写：
文件首行格式约定：
- STATE.md 首行：# 项目状态，下面依次为 ## 当前进度、## 最近决定、## 遗留问题、## 下一步
- TASKS.md 首行：# 任务清单，用 - [ ] 待办 / - [x] 已完成 / - [~] 进行中
- logs/：每天一个文件，文件名用日期 YYYY-MM-DD.md（如 2026-08-05.md）。首行 # 流水日志 YYYY-MM-DD，同一天内按时间先后顺序追加；跨天则新建当天文件。短期回顾读当天文件，长期回顾用目录按需翻查
- DECISIONS.md 首行：# 决策记录，每条 ### 决策：一句话 | 日期，含背景、决定、理由、备选
- ROADMAP.md 首行：# 路线图，分 ## 长期目标、## 下一步计划
二、开工协议（每次会话开始必做）
- 按「〇、路径模型与状态目录判定」确定状态目录，检查
.workflow\STATE.md是否存在。 - 存在 → 完整读取
STATE.md、TASKS.md、ROADMAP.md、DECISIONS.md，最近几天的logs/*.md首屏，恢复上下文。 - 不存在 → 视为新项目，按「一、项目状态体系」初始化全部文件，写入项目背景和首个目标，然后向用户确认定位是否准确。
- 一个会话一个里程碑：根据
ROADMAP.md确定本次只交付一个里程碑/目标，不散开做多件事；做完就收工开新会话，别让单个会话聊太长而失忆。 - 若用户给了交接话术（收工锚点），优先按锚点内容恢复上下文，再与状态文件交叉核对。
三、进行中协议（主动及时写，不靠记忆）
整个会话过程中主动维护状态，不靠对话记忆（上下文会被自动压缩）：
- 任务推进：每开始/完成一项任务，同步更新
TASKS.md（勾选、移状态），用 todo 工具辅助跟踪。 - 主动及时写流水：每做完一件事就追加到当天的
logs/YYYY-MM-DD.md（不存在则新建），不攒到收工。流水记"做了什么、产出什么、踩了什么坑"。 - 决策落盘：做出影响项目方向的决定（技术选型、命名、放弃某方案）时，当场写入
DECISIONS.md，写明背景和理由。 - 进度快照：
STATE.md的"当前进度"保持最新，这是下个会话恢复的关键，不能滞后。 - 记忆分层（该记什么 / 不记什么）：
- 要记（写入本项目.workflow）：- 项目进度快照（当前做到哪、下步是什么）→
STATE.md - 任务清单与状态（待办/进行中/完成）→
TASKS.md - 影响方向的决策（技术选型/命名/放弃方案 + 背景理由）→
DECISIONS.md - 长期目标与下一步计划 →
ROADMAP.md - 每天做了什么、产出、踩坑 →
logs/YYYY-MM-DD.md - 不记 / 不写：
- 一次性闲聊、纯礼貌话、无长期价值的临时话
- AI 人格 / 用户偏好 / 称呼 / 关系 / 跨项目通用知识（非项目状态，不写入本技能状态文件）
- 项目进度快照（当前做到哪、下步是什么）→
- 防上下文压缩失忆：凡是"下一个会话需要记得"的关键信息，必须已经写进上面的文件，不能只留在对话里；发现上下文变长/将被压缩时，先把关键状态落盘再继续。
四、收工协议（每次会话结束必做）
用户说 "收工" 或接近收尾的表述时，依次执行；完成一个里程碑/一个任务后，也主动抛出下个会话的交接锚点，引导用户开新会话，避免单会话聊太长失忆。
- 更新
STATE.md：重写"当前进度""最近决定""遗留问题""下一步"。 - 更新
TASKS.md：核对所有任务状态。 - 追加
logs/YYYY-MM-DD.md：写一条本次会话流水（做了什么、产出什么、遗留什么），跨天则新建当天文件。 - 更新
ROADMAP.md：勾掉已完成项，调整下一步。 - 生成 交接话术（下文的锚点），原样输出给用户复制。
五、交接话术模板（收工锚点）
收工时给用户原样输出下面这段，用户直接复制发给下一个会话。锚点必须自包含——新会话只凭这段文字就能无痛接续。
全局统一格式（必须遵守，所有项目/会话完全一致）：
- 先输出一行标题：给你的下个会话锚点。
- 再用 markdown 语言围栏把锚点正文包起来（三层反引号：开头 markdown、结尾）。
- 禁止用普通段落、非围栏代码块或其它语言标签；确保可一键复制、格式统一。
给你的下个会话锚点
【会话交接锚点】
项目：<项目名>（<一句话定位>）
路径：<项目根目录绝对路径>
上次会话结束于：<日期>
当前进度：
- <要点 1>
- <要点 2>
已完成：
- <要点 1>
- <要点 2>
下一步（按优先级）：
1. <事项>
2. <事项>
关键决定（详情见 DECISIONS.md）：
- <决定 1 及理由>
遗留问题 / 注意：
- <风险、坑、待确认事项>
开工请先读取：`.workflow\STATE.md`、TASKS.md、ROADMAP.md（状态目录位置见「〇、判定规则」）
收工时锚点里的内容必须与状态文件一致，不得凭空编写。
六、强制执行条款
- 任何项目会话，未读状态文件前不得声称"了解项目情况"。
- 任何会话结束，未更新状态文件前不得声称"已保存进度"。
- 交接锚点未生成，不得说"下次继续也行"。
- 状态文件是唯一真相源，与对话记忆冲突时以状态文件为准。
七、与既有项目机制的协调
- 项目已有自己的交接/状态机制：沿用其机制，不必强制迁移到本标准结构，但必须满足两个强制点——开工先读状态再声称了解；收工更新状态并留锚点。
- 新项目 / 无既有机制：按「〇、判定规则」初始化状态目录，完整执行本协议。
八、参考文档
- 常见问题：
references/faq.md - 路径模型：
references/path-model.md - 复杂场景走查：
references/walkthroughs.md - 异常恢复手册：
references/exception-playbook.md
