元序（yotta-workflow）

本文件是全局层标准：所有项目共享同一套工作流程。状态文件位置按规则判定（见下）。

核心原则：流程全局定，状态跟项目根目录。开工必读状态，收工必留锚点。

快速判定（先看这节，30 秒决定要不要用）

这是全局层工作流标准，装上它就是为了让 AI 自动按此执行，不需要用户每次提醒。

这个技能与智能体自带记忆的关系（本质）

它不取代任何智能体的记忆，而是补足"自带记忆做不到"的那部分：跨智能体共享、跨会话续接、统一的项目状态真相源 + 强制流程。

智能体自带的记忆（如 AGENTS.md、CLAUDE.md、rules、memory/、会话内上下文）通常是单机、单智能体、无统一结构的，有几个局限：

• 只在"这一个智能体"里生效，别的智能体不读。
• 各产品各写各的，项目状态会碎成多份、产生多个真相源。
• 只提供"能存"，不规定"何时读、何时写、写什么"，靠 AI 自觉，容易漏。

本技能单独存在的价值：

• 跨智能体共用一套 .workflow 状态：任何智能体读同一份 → 单一真相源。
• 跨会话持久 + 无缝续接：进度/任务/决策/流水落成文件，下个会话一读即续。
• 强制流程纪律：开工必读 → 进行中必记 → 收工必留锚点，不依赖 AI 自觉。
• 状态结构统一：STATE / TASKS / DECISIONS / ROADMAP / logs，AI 一读即知项目在哪、下一步做什么。

适用判断：

• 值得单独用：多智能体协作同一项目、项目要长远跨会话做、或希望项目状态不碎成 N 份。
• 不必单独用：只用单一智能体、自带记忆够用、项目很轻 → 自带记忆即可，本技能是锦上添花。

〇、路径模型与状态目录判定

这一节解决一个高频混淆：项目根目录不等于源码目录，.git 也不能单独决定项目根目录。 状态跟着项目根目录走，不跟着某一个代码仓库走。

1. 三个概念（一句话分清）

一句话：项目根目录 = 状态锚点；源码目录 = 实现位置；工作区根 = 项目容器。

标准形态（默认按这个理解）：

<项目根目录>\
├── .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. 判定顺序（从强到弱）

项目根目录只认两种证据，按顺序执行：

1. 用户明确指定项目根目录（直接说项目根目录、给出交接锚点的“路径”，或确认“当前目录就是项目根目录”）→ 这是项目根目录。
2. 从 cwd 向上查找已有 .workflow\STATE.md → 找到最近的一份；它所在的父目录就是项目根目录。已有 .workflow 永不自动迁移、复制或重建。
3. 两种证据都没有 → 停止初始化，先问一个问题：这个任务的项目根目录是哪一个？ 不得用 .git、package.json、src、README、cwd 或目录结构自行猜测。

如果用户明确说 cwd 就是项目根目录，则使用 cwd；如果用户说项目根目录在上层，则使用上层；如果用户给的是工作区根，则继续问具体项目根目录。判断依据永远来自用户或已有 .workflow，不来自目录里有什么文件。

定位时只处理项目根目录；源码目录如何组织，不参与 .workflow 的位置判定。

4. 不要写死任何默认路径。 不同宿主给未指定项目的会话分配的 cwd 可能不同；不能把某个盘符或目录当通用默认。

项目名取项目根目录名；同名冲突时附加路径哈希。

兼容红线：本次规则只影响首次初始化和解释口径。任何已经存在的 .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 首行：# 路线图，分 ## 长期目标、## 下一步计划

二、开工协议（每次会话开始必做）

1. 按「〇、路径模型与状态目录判定」确定状态目录，检查 .workflow\STATE.md 是否存在。
2. 存在 → 完整读取 STATE.md、TASKS.md、ROADMAP.md、DECISIONS.md，最近几天的 logs/*.md 首屏，恢复上下文。
3. 不存在 → 视为新项目，按「一、项目状态体系」初始化全部文件，写入项目背景和首个目标，然后向用户确认定位是否准确。
4. 一个会话一个里程碑：根据 ROADMAP.md 确定本次只交付一个里程碑/目标，不散开做多件事；做完就收工开新会话，别让单个会话聊太长而失忆。
5. 若用户给了交接话术（收工锚点），优先按锚点内容恢复上下文，再与状态文件交叉核对。

三、进行中协议（主动及时写，不靠记忆）

整个会话过程中主动维护状态，不靠对话记忆（上下文会被自动压缩）：

1. 任务推进：每开始/完成一项任务，同步更新 TASKS.md（勾选、移状态），用 todo 工具辅助跟踪。
2. 主动及时写流水：每做完一件事就追加到当天的 logs/YYYY-MM-DD.md（不存在则新建），不攒到收工。流水记"做了什么、产出什么、踩了什么坑"。
3. 决策落盘：做出影响项目方向的决定（技术选型、命名、放弃某方案）时，当场写入 DECISIONS.md，写明背景和理由。
4. 进度快照：STATE.md 的"当前进度"保持最新，这是下个会话恢复的关键，不能滞后。
5. 记忆分层（该记什么 / 不记什么）：
   • 要记（写入本项目 .workflow）：
     • 项目进度快照（当前做到哪、下步是什么）→ STATE.md
     • 任务清单与状态（待办/进行中/完成）→ TASKS.md
     • 影响方向的决策（技术选型/命名/放弃方案 + 背景理由）→ DECISIONS.md
     • 长期目标与下一步计划 → ROADMAP.md
     • 每天做了什么、产出、踩坑 → logs/YYYY-MM-DD.md
   • 不记 / 不写：
     • 一次性闲聊、纯礼貌话、无长期价值的临时话
     • AI 人格 / 用户偏好 / 称呼 / 关系 / 跨项目通用知识（非项目状态，不写入本技能状态文件）
6. 防上下文压缩失忆：凡是"下一个会话需要记得"的关键信息，必须已经写进上面的文件，不能只留在对话里；发现上下文变长/将被压缩时，先把关键状态落盘再继续。

四、收工协议（每次会话结束必做）

用户说 "收工" 或接近收尾的表述时，依次执行；完成一个里程碑/一个任务后，也主动抛出下个会话的交接锚点，引导用户开新会话，避免单会话聊太长失忆。

1. 更新 STATE.md：重写"当前进度""最近决定""遗留问题""下一步"。
2. 更新 TASKS.md：核对所有任务状态。
3. 追加 logs/YYYY-MM-DD.md：写一条本次会话流水（做了什么、产出什么、遗留什么），跨天则新建当天文件。
4. 更新 ROADMAP.md：勾掉已完成项，调整下一步。
5. 生成 交接话术（下文的锚点），原样输出给用户复制。

五、交接话术模板（收工锚点）

收工时给用户原样输出下面这段，用户直接复制发给下一个会话。锚点必须自包含——新会话只凭这段文字就能无痛接续。

全局统一格式（必须遵守，所有项目/会话完全一致）：

• 先输出一行标题：给你的下个会话锚点。
• 再用 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