@yottameta/yotta-workflow 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-workflow banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-workflow · 跨会话 / 跨项目工作流标准</h1>
+
+<p align="center">一套面向所有 AI 智能体的通用工作流标准：<b>流程全局定、状态就近存；开工必读状态，收工必留锚点</b>。让任何 AI 会话都能无痛接续，避免单会话拉长而失忆。</p>
+<p align="center">状态目录统一 <code>.workflow</code>——同一项目所有智能体会话读写同一份状态（一个真相源）；开工读状态恢复上下文、进行中主动落盘流水 / 任务 / 决策、收工生成自包含交接锚点。</p>
+<p align="center">纯 Markdown 文本，零依赖、不注入、不锁平台；安装一次，Claude Code / Codex / Cursor / OpenCode 等 78+ 智能体通用。</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-workflow"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-workflow" /></a>
+  <a href="https://github.com/YottaMeta/yotta-workflow"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-workflow" /></a>
+  <a href="https://github.com/YottaMeta/yotta-workflow/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-workflow" /></a>
+  <a href="https://github.com/YottaMeta/yotta-workflow"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
+</p>
+
+## 这是什么
+
+AI 会话本身是无状态的：每次对话相互独立，聊得越长越容易失忆，换个会话或换个智能体就接不上前文。各平台自带的记忆方案通常只服务单一智能体，不同智能体各记各的，还会产生多个「真相源」。
+
+yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协议，回答三个问题：
+
+- **状态放哪里、以什么格式记录**——统一由规则判定，不靠各智能体自由发挥。
+- **什么时候读、什么时候写**——开工必读、进行中主动写、收工必留锚点。
+- **交接怎么交**——固定模板生成自包含交接锚点，下个会话只凭锚点即可无痛接续。
+
+它不依赖任何特定智能体或平台：状态就是项目目录下的 Markdown 文件，任何智能体、任何工具都能读能写。
+
+## 核心价值
+
+- **一个真相源**：同一项目所有智能体会话读写同一份 `.workflow\` 状态目录，不再各建目录、各记各的。
+- **状态就近存**：以会话 cwd 为基准判定状态位置，不写死任何默认路径；项目根就近存、工作区按项目名分开存。
+- **主动防失忆**：进行中每完成一件事就落盘流水 / 任务 / 决策，不靠对话记忆（上下文会被自动压缩）。
+- **自包含交接**：收工生成固定格式交接锚点，下个会话只凭锚点 + 状态文件即可恢复全部上下文。
+- **与既有机制兼容**：项目已有自己的交接 / 状态机制时沿用原机制，只需满足两个强制点——开工先读状态、收工更新状态并留锚点。
+
+## 核心优势
+
+| 优势 | 说明 |
+|---|---|
+| **跨智能体统一** | 符合 Agent Skills 开放标准（agentskills.io），安装一次，78+ 智能体共用同一套状态协议 |
+| **一个真相源** | 状态目录统一 `.workflow`，同一项目任何智能体读写同一份状态，杜绝多真相源 |
+| **路径判定自动化** | 先取 cwd → 判断是项目根还是工作区 → 就近存或按项目名分开存；全程不写死路径 |
+| **主动式落盘** | 进行中即时写流水 / 任务 / 决策，上下文压缩也不丢关键状态 |
+| **自包含交接锚点** | 固定模板 + 强制校验（内容必须与状态文件一致），下个会话无痛接续 |
+| **轻量零依赖** | 纯 Markdown 文件，无 daemon / 无数据库 / 无注入；任何平台可读可写 |
+| **渐进采用** | 已有状态机制的项目可沿用原机制，只需满足两个强制点，迁移成本低 |
+| **生态分发** | GitHub + npm 双源同步发布；npx / install.sh / 手动复制三种安装方式，覆盖 17+ 类智能体目录 |
+
+## 协议详解
+
+### 状态文件位置判定（口诀）
+
+**先取 cwd，再看它是不是项目根；是项目根就就近存，是工作区就按项目名分开存；状态目录统一用 `.workflow`，与所用智能体无关；全程不写死任何默认 / 固定路径。**
+
+| base 形态 | 状态目录 |
+|---|---|
+| 项目根目录（含 `.git`、项目配置，或用户明确指向的单一项目） | `<base>\.workflow\` |
+| 工作区根目录（下面并列多个项目子目录） | `<base>\<项目名>\.workflow\` |
+
+> 用户指定的项目目录 / 统一工作区根目录按用户约定作为基准；未指定时以会话开始时的 cwd 为基准。
+
+### 项目状态体系（五类文件）
+
+| 文件 | 内容 |
+|---|---|
+| `STATE.md` | 当前进度 / 最近决定 / 遗留问题 / 下一步（下个会话恢复的关键） |
+| `TASKS.md` | 任务清单（`- [ ]` 待办 / `- [x]` 已完成 / `- [~]` 进行中） |
+| `DECISIONS.md` | 决策记录（每条含背景 / 决定 / 理由 / 备选） |
+| `ROADMAP.md` | 长期目标 + 下一步计划 |
+| `logs\YYYY-MM-DD.md` | 每天一份流水（做了什么 / 产出什么 / 踩了什么坑） |
+
+### 三段式协议
+
+**开工（每次会话开始必做）**：按判定规则定位状态目录 → 存在则完整读取 STATE / TASKS / ROADMAP / DECISIONS 与近期 logs 恢复上下文；不存在则初始化全部文件并向用户确认；一个会话只交付一个里程碑。
+
+**进行中（主动及时写，不靠记忆）**：每完成一件事就追加当天流水；任务状态实时更新 TASKS；方向性决定当场写入 DECISIONS；STATE 的「当前进度」保持最新；关键信息必须已落盘，不能只留在对话里。
+
+**收工（每次会话结束必做）**：更新 STATE / TASKS / ROADMAP → 追加当天流水 → 按模板生成交接锚点，原样输出给用户复制。
+
+### 交接锚点格式
+
+收工时按固定模板输出，锚点必须自包含，内容必须与状态文件一致、不得凭空编写。完整模板见 SKILL.md「五、交接话术模板」，结构要点：
+
+| 段 | 内容 |
+|---|---|
+| 头部 | 项目名（一句话定位）、项目根目录绝对路径、上次会话结束日期 |
+| 进度 | 当前进度、已完成（与 STATE.md 一致） |
+| 后续 | 下一步（按优先级）、关键决定、遗留问题 / 注意 |
+| 结尾 | 开工请先读取：`.workflow\STATE.md`、TASKS.md、ROADMAP.md |
+
+## 使用示例
+
+**开工**——先读状态，再谈任务：
+
+```text
+请先读取 .workflow\STATE.md、TASKS.md、ROADMAP.md，恢复项目上下文。
+```
+
+**进行中**——完成一件事，立即落盘：
+
+```text
+已完成「xxx」，追加到 logs\2026-08-25.md；勾选 TASKS.md 对应项；更新 STATE.md 当前进度。
+```
+
+**收工**——按模板生成交接锚点：
+
+```text
+给你的下个会话锚点
+
+【会话交接锚点】
+项目：<项目名>（<一句话定位>）
+路径：<项目根目录绝对路径>
+上次会话结束于：<日期>
+当前进度：…
+下一步（按优先级）：…
+开工请先读取：.workflow\STATE.md、TASKS.md、ROADMAP.md
+```
+
+## 触发方式
+
+在以下场景使用本技能：
+
+- 开始或结束一个工作会话，或恢复一个项目时。
+- 项目状态发生变化时（完成任务 / 记录决策 / 更新路线图）。
+- 需要给下一个会话留下自包含交接锚点，或读取已有交接锚点时。
+
+针对一次性的只读提问（如「这个函数什么意思」）不必触发本技能。
+
+## 安装
+
+三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
+
+### 方式一：npm（推荐，一行安装）
+```bash
+# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-workflow -g
+npx -y @yottameta/yotta-workflow --dir <你的技能目录>   # 任意智能体：指定目录安装
+```
+> 智能体不在预置列表里？用 `--dir` 指定它的 skills 目录，或手动复制（方式三）。`--list` 可查看各智能体对应的默认目录。
+
+### 方式二：install.sh 一键安装
+获取技能文件夹后（`npm pack` 解包或 `git clone`），进入技能文件夹：
+```bash
+bash install.sh -g    # 用户级；bash install.sh --list 查看全部目录
+bash install.sh --agent codex   # 指定智能体（--list 可查看可用项）
+bash install.sh       # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
+bash install.sh --dir /path/to/skills
+```
+> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
+
+### 方式三：手动复制
+把整个 `yotta-workflow` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
+
+| 智能体 | 用户级目录 | 项目级目录 |
+|---|---|---|
+| Codex | `%USERPROFILE%\.codex\skills\yotta-workflow\` | `.codex\skills\` |
+| Claude Code | `%USERPROFILE%\.claude\skills\yotta-workflow\` | `.claude\skills\` |
+| Cursor | `%USERPROFILE%\.cursor\skills\yotta-workflow\` | `.cursor\skills\` |
+| Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-workflow\` | `.windsurf\skills\` |
+| opencode | `%USERPROFILE%\.config\opencode\skills\yotta-workflow\` | `.opencode\skills\` |
+| Gemini | `%USERPROFILE%\.gemini\skills\yotta-workflow\` | `.gemini\skills\` |
+| Goose | `%USERPROFILE%\.config\goose\skills\yotta-workflow\` | `.goose\skills\` |
+| Amp | `%USERPROFILE%\.config\agents\skills\yotta-workflow\` | `.agents\skills\` |
+| Kiro | `%USERPROFILE%\.kiro\skills\yotta-workflow\` | `.kiro\skills\` |
+| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-workflow\` | `.workbuddy\skills\` |
+| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-workflow\` | `.traecli\skills\` |
+| Trae IDE（国内） | `%USERPROFILE%\.trae-cn\skills\yotta-workflow\` | `.trae\skills\` |
+| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-workflow\` | `.qwen\skills\` |
+| Comate 文心快码 | `%USERPROFILE%\.comate\skills\yotta-workflow\` | `.comate\skills\` |
+| CodeBuddy Code | `%USERPROFILE%\.codebuddy\skills\yotta-workflow\` | `.codebuddy\skills\` |
+| Kimi Code CLI | `%USERPROFILE%\.kimi\skills\yotta-workflow\` | `.kimi\skills\` |
+
+> 通用约定：`.agents/skills` 并非所有智能体都读取（Claude Code 与 Codex 默认不读），仅为 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI 等智能体识别。已修改默认目录的智能体，请用 `--dir` 指定实际路径。
+
+## 升级 / 卸载
+
+- **升级**：重新安装最新版覆盖即可——`npx -y @yottameta/yotta-workflow -g` 或重跑 `bash install.sh -g`。技能目录内的旧文件会被覆盖；项目里的状态文件（`.workflow\`）不受影响。
+- **卸载**：删除目标智能体 skills 目录下的 `yotta-workflow` 文件夹（各智能体目录见上表）。卸载不影响已写入项目的状态文件。
+
+## 常见问题
+
+- **状态目录在哪？** 先看项目下是否存在 `.workflow\`；不存在时按「状态文件位置判定」规则以会话 cwd 为基准定位。
+- **多个智能体状态不同步？** 确认它们指向同一项目目录（同一份 `.workflow\`）。本技能设计为共享一份状态；若各自建了 `.workflow`，说明项目目录不一致。
+- **项目已有自己的交接机制？** 沿用原机制即可，只需满足两个强制点：开工先读状态、收工更新状态并留锚点。
+
+## 开发与校验
+
+本项目内运行：`python tools/validate-skill.py yotta-workflow`。
+
+## 许可证
+
+MIT © YottaMeta

package/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: yotta-workflow
+description: "Universal cross-session, cross-project workflow standard for AI agents: 开工必读状态、状态就近存、进行中自动记流水/任务/决策、收工必留交接锚点。Use when starting or ending a working session, resuming a project, or whenever project state changes. 适合所有 AI 智能体的通用工作流。Not for one-off read-only questions."
+version: 0.1.3
+license: MIT
+agent_created: true
+metadata:
+  short-description: 跨会话/跨项目通用工作流：开工读状态、收工留锚点
+---
+
+# 全局工作流标准（跨会话项目协作协议）
+
+本文件是**全局层标准**：所有项目共享同一套工作流程。状态文件位置按规则判定（见下）。
+
+核心原则：**流程全局定，状态就近存。开工必读状态，收工必留锚点。**
+
+---
+
+## 〇、状态文件位置判定规则
+
+> 说明：**状态目录**是项目内的共享隐藏目录，统一固定为 `.workflow\`（名称以 `.` 开头）。**对同一项目，任何智能体会话（无论 Codex / Cursor / Hermes / OpenCode…）都读写这一份共享状态目录**，以此保证"不同智能体协作共用一套状态"成立——而不是各智能体各建一份（那样会产生多个真相源，上一程记的状态下一程读不到）。技能可被安装分发到多个智能体，但状态目录命名与所用智能体无关，永远落在同一个 `.workflow\`。
+
+**不要假设存在一个固定的"默认项目目录"。** 各个智能体/宿主给"未指定项目"的会话分配的默认工作目录并不相同（有的按会话自动建临时目录，有的叫 `projects` 等），因此必须以**本次会话开始时的当前工作目录（cwd）**为基准来定位状态，而不是写死某个路径。
+
+> 「统一工作区根目录」常为用户自己建的（如为了把项目数据集中到某个盘目录方便备份），那属于**用户的工作约定**，不是智能体默认；用户给了就用它做基准，但在通用技能里不要写成任何具体路径。
+
+**第一步，确定基准目录（base）：**
+- **已指定 / 已锚定项目目录**（含用户自建的统一工作区根目录）→ `base` = 用户指定的项目根目录 / 工作区根目录。
+- **未指定项目目录**（临时会话 / 无固定工作目录）→ `base` = 会话开始时宿主给的**当前工作目录（cwd）**，AI 启动时读取即可，不要写死。
+
+**第二步，根据 base 的形态定状态目录：**
+- `base` **本身就是一个项目根目录**（含项目标识，如 `.git`、项目配置、或用户明确指向的单一项目）→ 状态文件放 `base` 下 `.workflow\`
+  ```
+  <base>\.workflow\
+  ├── STATE.md
+  ├── TASKS.md
+  ├── DECISIONS.md
+  ├── ROADMAP.md
+  └── logs\
+      └── YYYY-MM-DD.md
+  ```
+- `base` 是**工作区根目录**（下面并列多个项目子目录）→ 按项目名建子目录：`<base>\<项目名>\.workflow\`（结构同上）。
+
+判定口诀：**先取 cwd，再看它是不是项目根；是项目根就就近存，是工作区就按项目名分开存；状态目录统一用 `.workflow`，与所用智能体无关；全程不写死任何默认/固定路径。**
+
+项目名取项目根目录名（同名冲突时附加路径哈希）。
+
+---
+
+## 一、项目状态体系
+
+状态文件结构（两种位置下结构一致）。**所有状态文件与流水日志都存放在本项目自己的 `.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. **记忆分层**（按"重要性 + 范围"分三档，别都堆进一个文件）：
+   - **流水**：每件事的即时记录 → `logs/YYYY-MM-DD.md`（项目内）。
+   - **重要 / 长期记忆**：跨会话仍要用的项目事实、决定、进度 → 项目记忆文件 `STATE.md`、`TASKS.md`、`DECISIONS.md`、`ROADMAP.md`（项目内）。
+   - **跨项目记忆**：跨项目/跨会话都要用的通用知识、环境事实、红线 → **永久记忆文件**（如全局 `AGENTS.md`）。该文件保持精简，用**锚点**指向具体文件，不无限堆内容。
+6. **防上下文压缩失忆**：凡是"下一个会话需要记得"的关键信息，**必须已经写进上面的文件**，不能只留在对话里；发现上下文变长/将被压缩时，先把关键状态落盘再继续。
+
+---
+
+## 四、收工协议（每次会话结束必做）
+
+用户说 **"收工"** 或接近收尾的表述时，依次执行；**完成一个里程碑/一个任务后，也主动抛出下个会话的交接锚点**，引导用户开新会话，避免单会话聊太长失忆。
+
+1. 更新 `STATE.md`：重写"当前进度""最近决定""遗留问题""下一步"。
+2. 更新 `TASKS.md`：核对所有任务状态。
+3. 追加 `logs/YYYY-MM-DD.md`：写一条本次会话流水（做了什么、产出什么、遗留什么），跨天则新建当天文件。
+4. 更新 `ROADMAP.md`：勾掉已完成项，调整下一步。
+5. 生成 **交接话术**（下文的锚点），原样输出给用户复制。
+
+---
+
+## 五、交接话术模板（收工锚点）
+
+收工时给用户**原样输出下面这段**，用户直接复制发给下一个会话。**锚点必须自包含**——新会话只凭这段文字就能无痛接续。
+
+**全局统一格式（必须遵守，所有项目/会话完全一致）**：
+- 先输出一行标题：`给你的下个会话锚点`。
+- 再用 **markdown 语言围栏**把锚点正文包起来（三层反引号：开头 ```markdown、结尾 ```）。
+- 禁止用普通段落、非围栏代码块或其它语言标签；确保可一键复制、格式统一。
+
+给你的下个会话锚点
+
+```markdown
+【会话交接锚点】
+项目：<项目名>（<一句话定位>）
+路径：<项目根目录绝对路径>
+
+上次会话结束于：<日期>
+
+当前进度：
+- <要点 1>
+- <要点 2>
+
+已完成：
+- <要点 1>
+- <要点 2>
+
+下一步（按优先级）：
+1. <事项>
+2. <事项>
+
+关键决定（详情见 DECISIONS.md）：
+- <决定 1 及理由>
+
+遗留问题 / 注意：
+- <风险、坑、待确认事项>
+
+开工请先读取：`.workflow\STATE.md`、TASKS.md、ROADMAP.md（状态目录位置见「〇、判定规则」）
+```
+
+收工时锚点里的内容**必须与状态文件一致**，不得凭空编写。
+## 六、强制执行条款
+
+- 任何项目会话，未读状态文件前不得声称"了解项目情况"。
+- 任何会话结束，未更新状态文件前不得声称"已保存进度"。
+- 交接锚点未生成，不得说"下次继续也行"。
+- 状态文件是唯一真相源，与对话记忆冲突时以状态文件为准。
+
+---
+
+## 七、与既有项目机制的协调
+
+- **项目已有自己的交接/状态机制**：沿用其机制，不必强制迁移到本标准结构，但必须满足两个强制点——开工先读状态再声称了解；收工更新状态并留锚点。
+- **新项目 / 无既有机制**：按「〇、判定规则」初始化状态目录，完整执行本协议。

package/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "工作流标准"
+  short_description: "跨会话/跨项目通用工作流：开工读状态、进行中记流水、收工留锚点"
+  brand_color: "#3B82F6"
+  default_prompt: "Use $yotta-workflow to start this working session: read the project state, then plan and execute per the standard."

package/bin/install.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * yotta-workflow 跨平台安装器（YottaSkills）
+ * 用法:
+ *   npx -y @yottameta/yotta-workflow --agent <name>  # 按智能体默认用户级目录安装（推荐）
+ *   npx -y @yottameta/yotta-workflow --dir PATH      # 装到指定目录（用户改了目录的智能体）
+ *   npx -y @yottameta/yotta-workflow -g              # 安装到全部已知智能体用户级目录
+ *   npx -y @yottameta/yotta-workflow                 # 安装到检测到的项目级目录
+ *   npx -y @yottameta/yotta-workflow --list          # 列出智能体 -> 默认目录
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'yotta-workflow';
+const PKG_ROOT = path.join(__dirname, '..');
+
+// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
+// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
+// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
+  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
+  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
+  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
+  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
+  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
+  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
+  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
+  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
+  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
+};
+
+// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function installTo(dest) {
+  const target = path.join(dest, SKILL_NAME);
+  fs.mkdirSync(target, { recursive: true });
+  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
+  console.log('installed -> ' + target);
+}
+
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(d, { recursive: true });
+      copyDir(s, d, skip);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const isGlobal = args.includes('-g') || args.includes('--global');
+  const list = args.includes('--list') || args.includes('-l');
+  let explicitDir = null;
+  const di = args.indexOf('--dir');
+  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
+  let agent = null;
+  const ai = args.indexOf('--agent');
+  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
+
+  if (list) {
+    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
+    for (const [key, v] of Object.entries(AGENT_DIRS)) {
+      const resolved = v.dirs.map(displayDir);
+      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
+    }
+    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
+    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
+    return;
+  }
+
+  if (explicitDir) { installTo(explicitDir); return; }
+
+  if (agent) {
+    const info = AGENT_DIRS[agent];
+    if (!info) {
+      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
+      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
+      return;
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    console.log('完成。');
+    return;
+  }
+
+  if (isGlobal) {
+    const seen = new Set();
+    for (const v of Object.values(AGENT_DIRS)) {
+      for (const d of v.dirs) {
+        if (seen.has(d)) continue;
+        seen.add(d);
+        installTo(resolveUserDir(d));
+      }
+    }
+    console.log('完成。');
+    return;
+  }
+
+  const PROJECT_DIRS = [
+    '.claude/skills',
+    '.cursor/skills',
+    '.codex/skills',
+    '.config/goose/skills',
+    '.config/agents/skills',
+    '.opencode/skills',
+    '.codeium/windsurf/skills',
+    '.workbuddy/skills',
+    '.kiro/skills',
+    '.traecli/skills',
+    '.gemini/skills',
+    '.trae-cn/skills',
+    '.qwen/skills',
+    '.comate/skills',
+    '.codebuddy/skills',
+    '.kimi/skills',
+    '.agents/skills',
+  ];
+  let installedAny = false;
+  for (const d of PROJECT_DIRS) {
+    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
+  }
+  if (!installedAny) {
+    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+  }
+}
+
+main();

package/install.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# yotta-workflow 多智能体安装脚本（YottaSkills）
+# 用法:
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
+#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
+#   bash install.sh -g              # 装到全部已知智能体用户级目录
+#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh --list          # 列出智能体 -> 默认目录
+set -euo pipefail
+
+SKILL_NAME="yotta-workflow"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*)
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    ;;
+esac
+
+# 智能体 -> 用户级默认目录（--agent 装到第一个）
+# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
+# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
+_IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
+esac
+dirs_for() {
+  case "$1" in
+    claude)     echo ".claude/skills" ;;
+    cursor)     echo ".cursor/skills .agents/skills" ;;
+    codex)      echo "__CODEX__" ;;
+    gemini)     echo ".gemini/skills .agents/skills" ;;
+    goose)      echo ".config/goose/skills .agents/skills" ;;
+    amp)        echo ".config/agents/skills .agents/skills" ;;
+    opencode)   echo "__OPENCODE__" ;;
+    windsurf)   echo ".codeium/windsurf/skills" ;;
+    workbuddy)  echo ".workbuddy/skills" ;;
+    kiro)       echo ".kiro/skills" ;;
+    trae)       echo ".traecli/skills" ;;
+    trae-cn)    echo ".trae-cn/skills" ;;
+    qwen)       echo ".qwen/skills" ;;
+    comate)     echo ".comate/skills" ;;
+    codebuddy)  echo ".codebuddy/skills" ;;
+    kimi)       echo ".kimi/skills" ;;
+    agents)     echo ".agents/skills" ;;
+    *)          return 1 ;;
+  esac
+}
+
+codex_dir() {
+  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
+}
+opencode_dir() {
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
+}
+resolve_user() {
+  case "$1" in
+    __CODEX__)    codex_dir ;;
+    __OPENCODE__) opencode_dir ;;
+    *)            printf '%s' "$HOME/$1" ;;
+  esac
+}
+
+install_to() {
+  mkdir -p "$1/$SKILL_NAME"
+  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
+  rm -rf "$1/$SKILL_NAME/.git"
+  echo "installed -> $1/$SKILL_NAME"
+}
+
+list() {
+  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+    local dirs first
+    dirs="$(dirs_for "$a")"
+    first="${dirs%% *}"
+    case "$first" in
+      __CODEX__)    first=".codex/skills" ;;
+      __OPENCODE__) first=".config/opencode/skills" ;;
+    esac
+    if [ "$_IS_WINDOWS" = "1" ]; then
+      first="%USERPROFILE%\\${first//\//\\}"
+    else
+      first="~/$first"
+    fi
+    printf '  %-10s %s\n' "$a" "$first"
+  done
+  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
+  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
+}
+
+main() {
+  local agent="" dir="" global=0 show_list=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --agent) shift; agent="${1:-}" ;;
+      --dir)   shift; dir="${1:-}" ;;
+      -g|--global) global=1 ;;
+      --list|-l) show_list=1 ;;
+      *) echo "未知参数: $1" >&2; exit 2 ;;
+    esac
+    shift
+  done
+
+  if [ "$show_list" = "1" ]; then list; return; fi
+  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ -n "$agent" ]; then
+    local dirs first
+    if ! dirs="$(dirs_for "$agent")"; then
+      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+    fi
+    first="${dirs%% *}"
+    install_to "$(resolve_user "$first")"; echo "完成。"; return
+  fi
+  if [ "$global" = "1" ]; then
+    echo "安装到全部已知智能体用户级目录..."
+    local dirs rel
+    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+      dirs="$(dirs_for "$a")"
+      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+    done
+    echo "完成。"; return
+  fi
+  local installed=0 d
+  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
+    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+  done
+  if [ "$installed" = "0" ]; then
+    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+  fi
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@yottameta/yotta-workflow",
+  "version": "0.2.0",
+  "description": "Universal cross-session, cross-project workflow standard for AI agents: 开工读状态、状态就近存、进行中记流水/任务/决策、收工留交接锚点。适合所有 AI 智能体的通用工作流。",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "yotta-workflow",
+    "workflow",
+    "project-state",
+    "handoff"
+  ],
+  "files": [
+    "SKILL.md",
+    "LICENSE",
+    "README.md",
+    "install.sh",
+    "agents",
+    "references",
+    "scripts",
+    "assets",
+    "bin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YottaMeta/yotta-workflow.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "yotta-workflow": "bin/install.js"
+  }
+}