@yottameta/yotta-workflow 0.2.3 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +104 -99
- package/README.zh-CN.md +199 -0
- package/SKILL.md +1 -1
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
|
+
<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
|
|
2
|
+
|
|
1
3
|
<p align="center">
|
|
2
4
|
<img src="assets/banner.png" alt="yotta-workflow banner" width="100%" />
|
|
3
5
|
</p>
|
|
4
6
|
|
|
5
|
-
<h1 align="center">yotta-workflow ·
|
|
7
|
+
<h1 align="center">yotta-workflow · 元序 (Yuanxu)</h1>
|
|
6
8
|
|
|
7
|
-
<p align="center"
|
|
8
|
-
<p align="center"
|
|
9
|
-
<p align="center"
|
|
9
|
+
<p align="center">A universal workflow standard for all AI agents: <b>the process is set globally, the state is stored nearby; read the state on start, always leave a handoff anchor on finish</b>. Lets any AI conversation resume painlessly and avoids amnesia from overlong single sessions.</p>
|
|
10
|
+
<p align="center">State directory is unified as <code>.workflow</code> — all agent sessions of the same project read and write the same state (one source of truth); on start, read the state to restore context; while working, actively persist logs / tasks / decisions; on finish, generate a self-contained handoff anchor.</p>
|
|
11
|
+
<p align="center">Pure Markdown text, zero dependencies, no injection, no platform lock; install once, works across 78+ agents such as Claude Code / Codex / Cursor / OpenCode.</p>
|
|
10
12
|
|
|
11
13
|
<p align="center">
|
|
12
14
|
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
|
|
@@ -17,145 +19,145 @@
|
|
|
17
19
|
<a href="https://github.com/YottaMeta/yotta-workflow"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
|
|
18
20
|
</p>
|
|
19
21
|
|
|
20
|
-
##
|
|
22
|
+
## What it is
|
|
21
23
|
|
|
22
|
-
AI
|
|
24
|
+
AI sessions are inherently stateless: each conversation is independent, and the longer a chat grows the more memory it loses; switching sessions or agents means the previous context is gone. The built-in memory solutions of each platform usually serve a single agent, so different agents each keep their own records and produce multiple "sources of truth".
|
|
23
25
|
|
|
24
|
-
yotta-workflow
|
|
26
|
+
yotta-workflow distills "cross-session collaboration" into an agent-agnostic protocol that answers three questions:
|
|
25
27
|
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
28
|
+
- **Where is the state stored and in what format?** — determined by rules, not left to each agent's free choice.
|
|
29
|
+
- **When to read, when to write?** — read on start, write actively while working, always leave an anchor on finish.
|
|
30
|
+
- **How to hand off?** — a fixed template generates a self-contained handoff anchor; the next session resumes painlessly from just that anchor.
|
|
29
31
|
|
|
30
|
-
|
|
32
|
+
It depends on no specific agent or platform: the state is just Markdown files under the project directory, readable and writable by any agent or tool.
|
|
31
33
|
|
|
32
|
-
##
|
|
34
|
+
## Core value
|
|
33
35
|
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
36
|
+
- **One source of truth** — all agent sessions of the same project read and write the same `.workflow\` state directory, instead of each building its own and keeping separate records.
|
|
37
|
+
- **State stored nearby** — state location is decided from the session cwd, never a hard-coded default path; a project root stores nearby, a workspace root stores per-project by name.
|
|
38
|
+
- **Proactive anti-amnesia** — every completed action is written to logs / tasks / decisions while working, not relied on in-conversation memory (context gets auto-compressed).
|
|
39
|
+
- **Self-contained handoff** — on finish, generate a fixed-format handoff anchor; the next session restores full context from the anchor plus state files.
|
|
40
|
+
- **Compatible with existing mechanisms** — if the project already has its own handoff / state mechanism, keep it, only satisfying two mandatory points: read state on start, update state and leave an anchor on finish.
|
|
39
41
|
|
|
40
|
-
##
|
|
42
|
+
## Core advantages
|
|
41
43
|
|
|
42
|
-
|
|
|
44
|
+
| Advantage | Description |
|
|
43
45
|
|---|---|
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
|
|
|
51
|
-
|
|
|
46
|
+
| **Cross-agent unified** | follows the Agent Skills open standard (agentskills.io); install once, 78+ agents share one state protocol |
|
|
47
|
+
| **One source of truth** | unified `.workflow` state directory; any agent of the same project reads/writes the same state, eliminating multiple sources of truth |
|
|
48
|
+
| **Automated path detection** | take cwd → decide project root vs workspace → store nearby or separated by project name; never hard-code a path |
|
|
49
|
+
| **Proactive persistence** | immediately write logs / tasks / decisions while working, so context compression never loses key state |
|
|
50
|
+
| **Self-contained handoff anchor** | fixed template + enforced validation (content must match state files); next session resumes painlessly |
|
|
51
|
+
| **Lightweight zero-dependency** | plain Markdown files, no daemon / database / injection; readable and writable on any platform |
|
|
52
|
+
| **Gradual adoption** | projects with an existing state mechanism keep it, only satisfying the two mandatory points; low migration cost |
|
|
53
|
+
| **Ecosystem distribution** | GitHub + npm dual-source sync release; npx / install.sh / manual copy — three install methods covering 17+ agent directories |
|
|
52
54
|
|
|
53
|
-
##
|
|
55
|
+
## Protocol details
|
|
54
56
|
|
|
55
|
-
###
|
|
57
|
+
### State file location rule (memo)
|
|
56
58
|
|
|
57
|
-
|
|
59
|
+
**First take the cwd, then see whether it is a project root; if it is a project root, store nearby; if it is a workspace, store per project name; the state directory is always `.workflow`, independent of the agent used; never hard-code any default / fixed path.**
|
|
58
60
|
|
|
59
|
-
| base
|
|
61
|
+
| base form | state directory |
|
|
60
62
|
|---|---|
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
+
| project root directory (contains `.git`, project config, or explicitly pointed-to single project) | `<base>\.workflow\` |
|
|
64
|
+
| workspace root directory (multiple project subdirs side by side) | `<base>\<project name>\.workflow\` |
|
|
63
65
|
|
|
64
|
-
>
|
|
66
|
+
> A user-specified project directory / unified workspace root uses the user's convention as the base; if unspecified, use the session start cwd as the base.
|
|
65
67
|
|
|
66
|
-
###
|
|
68
|
+
### Project state system (five file types)
|
|
67
69
|
|
|
68
|
-
|
|
|
70
|
+
| File | Content |
|
|
69
71
|
|---|---|
|
|
70
|
-
| `STATE.md` |
|
|
71
|
-
| `TASKS.md` |
|
|
72
|
-
| `DECISIONS.md` |
|
|
73
|
-
| `ROADMAP.md` |
|
|
74
|
-
| `logs\YYYY-MM-DD.md` |
|
|
72
|
+
| `STATE.md` | current progress / recent decisions / open issues / next steps (key for the next session to resume) |
|
|
73
|
+
| `TASKS.md` | task list (`- [ ]` todo / `- [x]` done / `- [~]` in progress) |
|
|
74
|
+
| `DECISIONS.md` | decision log (each with background / decision / rationale / alternatives) |
|
|
75
|
+
| `ROADMAP.md` | long-term goals + next-step plan |
|
|
76
|
+
| `logs\YYYY-MM-DD.md` | one daily log (what was done / produced / pitfalls hit) |
|
|
75
77
|
|
|
76
|
-
###
|
|
78
|
+
### Three-phase protocol
|
|
77
79
|
|
|
78
|
-
|
|
80
|
+
**On start (every session)** — locate the state directory by the rule → if present, fully read STATE / TASKS / ROADMAP / DECISIONS and recent logs to restore context; if absent, initialize all files and confirm with the user; a session delivers one milestone.
|
|
79
81
|
|
|
80
|
-
|
|
82
|
+
**While working (write actively, don't rely on memory)** — append to the day's log after each completed action; update TASKS status in real time; write directional decisions into DECISIONS on the spot; keep STATE "current progress" up to date; key info must be persisted, not left only in the conversation.
|
|
81
83
|
|
|
82
|
-
|
|
84
|
+
**On finish (every session)** — update STATE / TASKS / ROADMAP → append the day's log → generate a handoff anchor by template and output it verbatim for the user to copy.
|
|
83
85
|
|
|
84
|
-
###
|
|
86
|
+
### Handoff anchor format
|
|
85
87
|
|
|
86
|
-
|
|
88
|
+
On finish, output by the fixed template; the anchor must be self-contained and its content must match the state files (never invented). The full template is in SKILL.md "五、交接话术模板". Structure points:
|
|
87
89
|
|
|
88
|
-
|
|
|
90
|
+
| Section | Content |
|
|
89
91
|
|---|---|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
92
|
+
| header | project name (one-line positioning), project root absolute path, last session end date |
|
|
93
|
+
| progress | current progress, completed (consistent with STATE.md) |
|
|
94
|
+
| next | next steps (by priority), key decisions, open issues / notes |
|
|
95
|
+
| footer | on start please read: `.workflow\STATE.md`, TASKS.md, ROADMAP.md |
|
|
94
96
|
|
|
95
|
-
##
|
|
97
|
+
## Usage examples
|
|
96
98
|
|
|
97
|
-
|
|
99
|
+
**On start** — read state, then talk about the task:
|
|
98
100
|
|
|
99
101
|
```text
|
|
100
|
-
|
|
102
|
+
Please read .workflow\STATE.md, TASKS.md, ROADMAP.md first to restore the project context.
|
|
101
103
|
```
|
|
102
104
|
|
|
103
|
-
|
|
105
|
+
**While working** — after completing one thing, persist it immediately:
|
|
104
106
|
|
|
105
107
|
```text
|
|
106
|
-
|
|
108
|
+
Completed "xxx", append to logs\2026-08-25.md; tick the TASKS.md item; update STATE.md current progress.
|
|
107
109
|
```
|
|
108
110
|
|
|
109
|
-
|
|
111
|
+
**On finish** — generate a handoff anchor by template:
|
|
110
112
|
|
|
111
113
|
```text
|
|
112
|
-
|
|
114
|
+
Handoff anchor for your next session
|
|
113
115
|
|
|
114
116
|
【会话交接锚点】
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
117
|
+
项目：<project name>（<one-line positioning>）
|
|
118
|
+
路径：<project root absolute path>
|
|
119
|
+
上次会话结束于：<date>
|
|
118
120
|
当前进度：…
|
|
119
121
|
下一步（按优先级）：…
|
|
120
122
|
开工请先读取：.workflow\STATE.md、TASKS.md、ROADMAP.md
|
|
121
123
|
```
|
|
122
124
|
|
|
123
|
-
##
|
|
125
|
+
## When to trigger
|
|
124
126
|
|
|
125
|
-
|
|
127
|
+
Use this skill in these scenarios:
|
|
126
128
|
|
|
127
|
-
-
|
|
128
|
-
-
|
|
129
|
-
-
|
|
129
|
+
- When starting or ending a work session, or resuming a project.
|
|
130
|
+
- When the project state changes (completing a task / recording a decision / updating the roadmap).
|
|
131
|
+
- When you need to leave a self-contained handoff anchor for the next session, or read an existing one.
|
|
130
132
|
|
|
131
|
-
|
|
133
|
+
It is not needed for one-off read-only questions (e.g. "what does this function mean").
|
|
132
134
|
|
|
133
|
-
##
|
|
135
|
+
## Installation
|
|
134
136
|
|
|
135
|
-
|
|
137
|
+
Pick any of the three methods; skill files are always fetched from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
|
|
136
138
|
|
|
137
|
-
###
|
|
139
|
+
### Method 1: npm (recommended, one-liner)
|
|
138
140
|
```bash
|
|
139
|
-
#
|
|
141
|
+
# Optional China mirror: npm config set registry https://registry.npmmirror.com
|
|
140
142
|
npx -y @yottameta/yotta-workflow -g
|
|
141
|
-
npx -y @yottameta/yotta-workflow --dir
|
|
143
|
+
npx -y @yottameta/yotta-workflow --dir <your skills dir> # any agent: install to a custom directory
|
|
142
144
|
```
|
|
143
|
-
>
|
|
145
|
+
> Agent not in the preset list? Use `--dir` to point at its skills directory, or copy manually (Method 3). `--list` shows the default directory of each agent. To grab the files yourself, run `npm pack @yottameta/yotta-workflow` and unpack, then use Method 2 or 3.
|
|
144
146
|
|
|
145
|
-
###
|
|
146
|
-
|
|
147
|
+
### Method 2: install.sh
|
|
148
|
+
After obtaining the skill folder (`npm pack` unpack or `git clone`), enter the folder:
|
|
147
149
|
```bash
|
|
148
|
-
bash install.sh -g #
|
|
149
|
-
bash install.sh --agent codex #
|
|
150
|
-
bash install.sh #
|
|
150
|
+
bash install.sh -g # user-level; bash install.sh --list shows all directories
|
|
151
|
+
bash install.sh --agent codex # a specific agent (see --list)
|
|
152
|
+
bash install.sh # project-level: auto-detect existing skills directories
|
|
151
153
|
bash install.sh --dir /path/to/skills
|
|
152
154
|
```
|
|
153
|
-
>
|
|
155
|
+
> Covers 17 agent families, including Trae / Qwen / Comate / CodeBuddy / Kimi.
|
|
154
156
|
|
|
155
|
-
###
|
|
156
|
-
|
|
157
|
+
### Method 3: manual copy
|
|
158
|
+
Copy the whole `yotta-workflow` folder into the target agent's skills directory. Common user-level locations (`%USERPROFILE%` on Windows, `~` on Linux/macOS):
|
|
157
159
|
|
|
158
|
-
|
|
|
160
|
+
| Agent | User-level directory | Project-level directory |
|
|
159
161
|
|---|---|---|
|
|
160
162
|
| Codex | `%USERPROFILE%\.codex\skills\yotta-workflow\` | `.codex\skills\` |
|
|
161
163
|
| Claude Code | `%USERPROFILE%\.claude\skills\yotta-workflow\` | `.claude\skills\` |
|
|
@@ -168,29 +170,32 @@ bash install.sh --dir /path/to/skills
|
|
|
168
170
|
| Kiro | `%USERPROFILE%\.kiro\skills\yotta-workflow\` | `.kiro\skills\` |
|
|
169
171
|
| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-workflow\` | `.workbuddy\skills\` |
|
|
170
172
|
| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-workflow\` | `.traecli\skills\` |
|
|
171
|
-
| Trae IDE
|
|
173
|
+
| Trae IDE (CN) | `%USERPROFILE%\.trae-cn\skills\yotta-workflow\` | `.trae\skills\` |
|
|
172
174
|
| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-workflow\` | `.qwen\skills\` |
|
|
173
|
-
| Comate
|
|
174
|
-
| CodeBuddy
|
|
175
|
-
| Kimi
|
|
175
|
+
| Comate | `%USERPROFILE%\.comate\skills\yotta-workflow\` | `.comate\skills\` |
|
|
176
|
+
| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-workflow\` | `.codebuddy\skills\` |
|
|
177
|
+
| Kimi | `%USERPROFILE%\.kimi\skills\yotta-workflow\` | `.kimi\skills\` |
|
|
178
|
+
| Generic AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-workflow\` | `.agents\skills\` |
|
|
179
|
+
|
|
180
|
+
> If Codex's `CODEX_HOME` is set, it overrides the default; the same applies to opencode's `XDG_CONFIG_HOME`. `.agents\skills` is not a universal directory — only OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot etc. read it; **Claude Code and Codex do not read it by default**. When unsure, use `--dir` or let the agent install it.
|
|
176
181
|
|
|
177
|
-
>
|
|
182
|
+
> Project-level: run `npx -y @yottameta/yotta-workflow` or `bash install.sh` inside the project to install into the detected project-level directory.
|
|
178
183
|
|
|
179
|
-
##
|
|
184
|
+
## Upgrade / uninstall
|
|
180
185
|
|
|
181
|
-
-
|
|
182
|
-
-
|
|
186
|
+
- **Upgrade**: reinstall the latest version to overwrite — `npx -y @yottameta/yotta-workflow -g` or rerun `bash install.sh -g`. Old files inside the skill directory are overwritten; the project state files (`.workflow\`) are unaffected.
|
|
187
|
+
- **Uninstall**: delete the `yotta-workflow` folder under the target agent's skills directory (see the table above). Uninstalling does not affect state files already written into a project.
|
|
183
188
|
|
|
184
|
-
##
|
|
189
|
+
## FAQ
|
|
185
190
|
|
|
186
|
-
-
|
|
187
|
-
-
|
|
188
|
-
-
|
|
191
|
+
- **Where is the state directory?** First check whether `.workflow\` exists under the project; if not, locate it by the "state file location rule" using the session cwd as the base.
|
|
192
|
+
- **Multiple agents out of sync?** Confirm they point to the same project directory (the same `.workflow\`). This skill is designed to share one state; if each built its own `.workflow`, the project directory differs.
|
|
193
|
+
- **Project already has its own handoff mechanism?** Keep it, only satisfying the two mandatory points: read state on start, update state and leave an anchor on finish.
|
|
189
194
|
|
|
190
|
-
##
|
|
195
|
+
## Development & checks
|
|
191
196
|
|
|
192
|
-
|
|
197
|
+
Run inside this project: `python tools/validate-skill.py yotta-workflow`.
|
|
193
198
|
|
|
194
|
-
##
|
|
199
|
+
## License
|
|
195
200
|
|
|
196
|
-
MIT © YottaMeta
|
|
201
|
+
MIT © YottaMeta
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
<p align="center"><b>Language</b>: <a href="./README.md">English</a> · 中文</p>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="assets/banner.png" alt="yotta-workflow banner" width="100%" />
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">yotta-workflow · 元序</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center">一套面向所有 AI 智能体的通用工作流标准：<b>流程全局定、状态就近存；开工必读状态，收工必留锚点</b>。让任何 AI 会话都能无痛接续，避免单会话拉长而失忆。</p>
|
|
10
|
+
<p align="center">状态目录统一 <code>.workflow</code>——同一项目所有智能体会话读写同一份状态（一个真相源）；开工读状态恢复上下文、进行中主动落盘流水 / 任务 / 决策、收工生成自包含交接锚点。</p>
|
|
11
|
+
<p align="center">纯 Markdown 文本，零依赖、不注入、不锁平台；安装一次，Claude Code / Codex / Cursor / OpenCode 等 78+ 智能体通用。</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
|
|
15
|
+
<a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
|
|
16
|
+
<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>
|
|
17
|
+
<a href="https://github.com/YottaMeta/yotta-workflow"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-workflow" /></a>
|
|
18
|
+
<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>
|
|
19
|
+
<a href="https://github.com/YottaMeta/yotta-workflow"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
|
|
20
|
+
</p>
|
|
21
|
+
|
|
22
|
+
## 这是什么
|
|
23
|
+
|
|
24
|
+
AI 会话本身是无状态的：每次对话相互独立，聊得越长越容易失忆，换个会话或换个智能体就接不上前文。各平台自带的记忆方案通常只服务单一智能体，不同智能体各记各的，还会产生多个「真相源」。
|
|
25
|
+
|
|
26
|
+
yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协议，回答三个问题：
|
|
27
|
+
|
|
28
|
+
- **状态放哪里、以什么格式记录**——统一由规则判定，不靠各智能体自由发挥。
|
|
29
|
+
- **什么时候读、什么时候写**——开工必读、进行中主动写、收工必留锚点。
|
|
30
|
+
- **交接怎么交**——固定模板生成自包含交接锚点，下个会话只凭锚点即可无痛接续。
|
|
31
|
+
|
|
32
|
+
它不依赖任何特定智能体或平台：状态就是项目目录下的 Markdown 文件，任何智能体、任何工具都能读能写。
|
|
33
|
+
|
|
34
|
+
## 核心价值
|
|
35
|
+
|
|
36
|
+
- **一个真相源**：同一项目所有智能体会话读写同一份 `.workflow\` 状态目录，不再各建目录、各记各的。
|
|
37
|
+
- **状态就近存**：以会话 cwd 为基准判定状态位置，不写死任何默认路径；项目根就近存、工作区按项目名分开存。
|
|
38
|
+
- **主动防失忆**：进行中每完成一件事就落盘流水 / 任务 / 决策，不靠对话记忆（上下文会被自动压缩）。
|
|
39
|
+
- **自包含交接**：收工生成固定格式交接锚点，下个会话只凭锚点 + 状态文件即可恢复全部上下文。
|
|
40
|
+
- **与既有机制兼容**：项目已有自己的交接 / 状态机制时沿用原机制，只需满足两个强制点——开工先读状态、收工更新状态并留锚点。
|
|
41
|
+
|
|
42
|
+
## 核心优势
|
|
43
|
+
|
|
44
|
+
| 优势 | 说明 |
|
|
45
|
+
|---|---|
|
|
46
|
+
| **跨智能体统一** | 符合 Agent Skills 开放标准（agentskills.io），安装一次，78+ 智能体共用同一套状态协议 |
|
|
47
|
+
| **一个真相源** | 状态目录统一 `.workflow`，同一项目任何智能体读写同一份状态，杜绝多真相源 |
|
|
48
|
+
| **路径判定自动化** | 先取 cwd → 判断是项目根还是工作区 → 就近存或按项目名分开存；全程不写死路径 |
|
|
49
|
+
| **主动式落盘** | 进行中即时写流水 / 任务 / 决策，上下文压缩也不丢关键状态 |
|
|
50
|
+
| **自包含交接锚点** | 固定模板 + 强制校验（内容必须与状态文件一致），下个会话无痛接续 |
|
|
51
|
+
| **轻量零依赖** | 纯 Markdown 文件，无 daemon / 无数据库 / 无注入；任何平台可读可写 |
|
|
52
|
+
| **渐进采用** | 已有状态机制的项目可沿用原机制，只需满足两个强制点，迁移成本低 |
|
|
53
|
+
| **生态分发** | GitHub + npm 双源同步发布；npx / install.sh / 手动复制三种安装方式，覆盖 17+ 类智能体目录 |
|
|
54
|
+
|
|
55
|
+
## 协议详解
|
|
56
|
+
|
|
57
|
+
### 状态文件位置判定（口诀）
|
|
58
|
+
|
|
59
|
+
**先取 cwd，再看它是不是项目根；是项目根就就近存，是工作区就按项目名分开存；状态目录统一用 `.workflow`，与所用智能体无关；全程不写死任何默认 / 固定路径。**
|
|
60
|
+
|
|
61
|
+
| base 形态 | 状态目录 |
|
|
62
|
+
|---|---|
|
|
63
|
+
| 项目根目录（含 `.git`、项目配置，或用户明确指向的单一项目） | `<base>\.workflow\` |
|
|
64
|
+
| 工作区根目录（下面并列多个项目子目录） | `<base>\<项目名>\.workflow\` |
|
|
65
|
+
|
|
66
|
+
> 用户指定的项目目录 / 统一工作区根目录按用户约定作为基准；未指定时以会话开始时的 cwd 为基准。
|
|
67
|
+
|
|
68
|
+
### 项目状态体系（五类文件）
|
|
69
|
+
|
|
70
|
+
| 文件 | 内容 |
|
|
71
|
+
|---|---|
|
|
72
|
+
| `STATE.md` | 当前进度 / 最近决定 / 遗留问题 / 下一步（下个会话恢复的关键） |
|
|
73
|
+
| `TASKS.md` | 任务清单（`- [ ]` 待办 / `- [x]` 已完成 / `- [~]` 进行中） |
|
|
74
|
+
| `DECISIONS.md` | 决策记录（每条含背景 / 决定 / 理由 / 备选） |
|
|
75
|
+
| `ROADMAP.md` | 长期目标 + 下一步计划 |
|
|
76
|
+
| `logs\YYYY-MM-DD.md` | 每天一份流水（做了什么 / 产出什么 / 踩了什么坑） |
|
|
77
|
+
|
|
78
|
+
### 三段式协议
|
|
79
|
+
|
|
80
|
+
**开工（每次会话开始必做）**：按判定规则定位状态目录 → 存在则完整读取 STATE / TASKS / ROADMAP / DECISIONS 与近期 logs 恢复上下文；不存在则初始化全部文件并向用户确认；一个会话只交付一个里程碑。
|
|
81
|
+
|
|
82
|
+
**进行中（主动及时写，不靠记忆）**：每完成一件事就追加当天流水；任务状态实时更新 TASKS；方向性决定当场写入 DECISIONS；STATE 的「当前进度」保持最新；关键信息必须已落盘，不能只留在对话里。
|
|
83
|
+
|
|
84
|
+
**收工（每次会话结束必做）**：更新 STATE / TASKS / ROADMAP → 追加当天流水 → 按模板生成交接锚点，原样输出给用户复制。
|
|
85
|
+
|
|
86
|
+
### 交接锚点格式
|
|
87
|
+
|
|
88
|
+
收工时按固定模板输出，锚点必须自包含，内容必须与状态文件一致、不得凭空编写。完整模板见 SKILL.md「五、交接话术模板」，结构要点：
|
|
89
|
+
|
|
90
|
+
| 段 | 内容 |
|
|
91
|
+
|---|---|
|
|
92
|
+
| 头部 | 项目名（一句话定位）、项目根目录绝对路径、上次会话结束日期 |
|
|
93
|
+
| 进度 | 当前进度、已完成（与 STATE.md 一致） |
|
|
94
|
+
| 后续 | 下一步（按优先级）、关键决定、遗留问题 / 注意 |
|
|
95
|
+
| 结尾 | 开工请先读取：`.workflow\STATE.md`、TASKS.md、ROADMAP.md |
|
|
96
|
+
|
|
97
|
+
## 使用示例
|
|
98
|
+
|
|
99
|
+
**开工**——先读状态，再谈任务：
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
请先读取 .workflow\STATE.md、TASKS.md、ROADMAP.md，恢复项目上下文。
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
**进行中**——完成一件事，立即落盘：
|
|
106
|
+
|
|
107
|
+
```text
|
|
108
|
+
已完成「xxx」，追加到 logs\2026-08-25.md；勾选 TASKS.md 对应项；更新 STATE.md 当前进度。
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
**收工**——按模板生成交接锚点：
|
|
112
|
+
|
|
113
|
+
```text
|
|
114
|
+
给你的下个会话锚点
|
|
115
|
+
|
|
116
|
+
【会话交接锚点】
|
|
117
|
+
项目：<项目名>（<一句话定位>）
|
|
118
|
+
路径：<项目根目录绝对路径>
|
|
119
|
+
上次会话结束于：<日期>
|
|
120
|
+
当前进度：…
|
|
121
|
+
下一步（按优先级）：…
|
|
122
|
+
开工请先读取：.workflow\STATE.md、TASKS.md、ROADMAP.md
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## 触发方式
|
|
126
|
+
|
|
127
|
+
在以下场景使用本技能：
|
|
128
|
+
|
|
129
|
+
- 开始或结束一个工作会话，或恢复一个项目时。
|
|
130
|
+
- 项目状态发生变化时（完成任务 / 记录决策 / 更新路线图）。
|
|
131
|
+
- 需要给下一个会话留下自包含交接锚点，或读取已有交接锚点时。
|
|
132
|
+
|
|
133
|
+
针对一次性的只读提问（如「这个函数什么意思」）不必触发本技能。
|
|
134
|
+
|
|
135
|
+
## 安装
|
|
136
|
+
|
|
137
|
+
三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
|
|
138
|
+
|
|
139
|
+
### 方式一：npm（推荐，一行安装）
|
|
140
|
+
```bash
|
|
141
|
+
# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
|
|
142
|
+
npx -y @yottameta/yotta-workflow -g
|
|
143
|
+
npx -y @yottameta/yotta-workflow --dir <你的技能目录> # 任意智能体：指定目录安装
|
|
144
|
+
```
|
|
145
|
+
> 智能体不在预置列表里？用 `--dir` 指定它的 skills 目录，或手动复制（方式三）。`--list` 可查看各智能体对应的默认目录。想手动拿文件也可 `npm pack @yottameta/yotta-workflow` 解包后按方式二/三安装。
|
|
146
|
+
|
|
147
|
+
### 方式二：install.sh 一键安装
|
|
148
|
+
获取技能文件夹后（`npm pack` 解包或 `git clone`），进入技能文件夹：
|
|
149
|
+
```bash
|
|
150
|
+
bash install.sh -g # 用户级；bash install.sh --list 查看全部目录
|
|
151
|
+
bash install.sh --agent codex # 指定智能体（--list 可查看可用项）
|
|
152
|
+
bash install.sh # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
|
|
153
|
+
bash install.sh --dir /path/to/skills
|
|
154
|
+
```
|
|
155
|
+
> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
|
|
156
|
+
|
|
157
|
+
### 方式三：手动复制
|
|
158
|
+
把整个 `yotta-workflow` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
|
|
159
|
+
|
|
160
|
+
| 智能体 | 用户级目录 | 项目级目录 |
|
|
161
|
+
|---|---|---|
|
|
162
|
+
| Codex | `%USERPROFILE%\.codex\skills\yotta-workflow\` | `.codex\skills\` |
|
|
163
|
+
| Claude Code | `%USERPROFILE%\.claude\skills\yotta-workflow\` | `.claude\skills\` |
|
|
164
|
+
| Cursor | `%USERPROFILE%\.cursor\skills\yotta-workflow\` | `.cursor\skills\` |
|
|
165
|
+
| Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-workflow\` | `.windsurf\skills\` |
|
|
166
|
+
| opencode | `%USERPROFILE%\.config\opencode\skills\yotta-workflow\` | `.opencode\skills\` |
|
|
167
|
+
| Gemini | `%USERPROFILE%\.gemini\skills\yotta-workflow\` | `.gemini\skills\` |
|
|
168
|
+
| Goose | `%USERPROFILE%\.config\goose\skills\yotta-workflow\` | `.goose\skills\` |
|
|
169
|
+
| Amp | `%USERPROFILE%\.config\agents\skills\yotta-workflow\` | `.agents\skills\` |
|
|
170
|
+
| Kiro | `%USERPROFILE%\.kiro\skills\yotta-workflow\` | `.kiro\skills\` |
|
|
171
|
+
| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-workflow\` | `.workbuddy\skills\` |
|
|
172
|
+
| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-workflow\` | `.traecli\skills\` |
|
|
173
|
+
| Trae IDE (CN) | `%USERPROFILE%\.trae-cn\skills\yotta-workflow\` | `.trae\skills\` |
|
|
174
|
+
| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-workflow\` | `.qwen\skills\` |
|
|
175
|
+
| Comate | `%USERPROFILE%\.comate\skills\yotta-workflow\` | `.comate\skills\` |
|
|
176
|
+
| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-workflow\` | `.codebuddy\skills\` |
|
|
177
|
+
| Kimi | `%USERPROFILE%\.kimi\skills\yotta-workflow\` | `.kimi\skills\` |
|
|
178
|
+
| Generic AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-workflow\` | `.agents\skills\` |
|
|
179
|
+
|
|
180
|
+
> 通用约定：`.agents/skills` 并非所有智能体都读取（Claude Code 与 Codex 默认不读），仅为 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI 等智能体识别。已修改默认目录的智能体，请用 `--dir` 指定实际路径。
|
|
181
|
+
|
|
182
|
+
## 升级 / 卸载
|
|
183
|
+
|
|
184
|
+
- **升级**：重新安装最新版覆盖即可——`npx -y @yottameta/yotta-workflow -g` 或重跑 `bash install.sh -g`。技能目录内的旧文件会被覆盖；项目里的状态文件（`.workflow\`）不受影响。
|
|
185
|
+
- **卸载**：删除目标智能体 skills 目录下的 `yotta-workflow` 文件夹（各智能体目录见上表）。卸载不影响已写入项目的状态文件。
|
|
186
|
+
|
|
187
|
+
## 常见问题
|
|
188
|
+
|
|
189
|
+
- **状态目录在哪？** 先看项目下是否存在 `.workflow\`；不存在时按「状态文件位置判定」规则以会话 cwd 为基准定位。
|
|
190
|
+
- **多个智能体状态不同步？** 确认它们指向同一项目目录（同一份 `.workflow\`）。本技能设计为共享一份状态；若各自建了 `.workflow`，说明项目目录不一致。
|
|
191
|
+
- **项目已有自己的交接机制？** 沿用原机制即可，只需满足两个强制点：开工先读状态、收工更新状态并留锚点。
|
|
192
|
+
|
|
193
|
+
## 开发与校验
|
|
194
|
+
|
|
195
|
+
本项目内运行：`python tools/validate-skill.py yotta-workflow`。
|
|
196
|
+
|
|
197
|
+
## 许可证
|
|
198
|
+
|
|
199
|
+
MIT © YottaMeta
|
package/SKILL.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: yotta-workflow
|
|
3
3
|
description: "跨会话/跨项目通用工作流标准：让任何 AI 智能体活过会话——开工必读状态、状态就近存 .workflow、进行中自动记流水/任务/决策、收工必留交接锚点。触发：开工/接手项目、续测、收工、跨会话恢复、要落盘、多步开发、项目状态变化、跨智能体协作。项目型会话自动初始化 .workflow 状态目录并按本协议全程执行；轻量一次性问答不强制初始化。所有 AI 智能体通用。"
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.2.5
|
|
5
5
|
license: MIT
|
|
6
6
|
agent_created: true
|
|
7
7
|
metadata:
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yottameta/yotta-workflow",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.5",
|
|
4
|
+
"description": "Cross-session / cross-project workflow standard for all AI agents: read the state on start, store state nearby in a unified .workflow directory, persist logs/tasks/decisions while working, and leave a self-contained handoff anchor on finish. Triggers when starting/handing over/resuming/shutting down a project or doing multi-step development. Works for all AI agents.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"agent-skills",
|
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
"references",
|
|
20
20
|
"scripts",
|
|
21
21
|
"assets",
|
|
22
|
-
"bin"
|
|
22
|
+
"bin",
|
|
23
|
+
"README.zh-CN.md"
|
|
23
24
|
],
|
|
24
25
|
"repository": {
|
|
25
26
|
"type": "git",
|