superself

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Superself

Superself is an Apache-2.0 CLI (

npm install -g superself@0.6.1

, Node 22.12+) that version-controls a project's state — goals, decisions, work units, reports — as an append-only event log in a git repository separate from the code. The state is derived on demand, so nothing in it is hand-maintained. This skill tells an agent how to read and write that state through the

self

CLI. It is maintained by the Superself authors: https://github.com/fxylabs/superself

Superself是一款基于Apache-2.0协议的CLI工具（安装命令：

npm install -g superself@0.6.1

，要求Node 22.12+），它将项目状态——包括目标、决策、工作单元、报告——作为仅追加的事件日志，存储在与代码分离的Git仓库中进行版本控制。项目状态是按需生成的，无需手动维护。本技能指导Agent如何通过

self

CLI读取和写入该状态。本技能由Superself官方维护：https://github.com/fxylabs/superself

When this skill applies

本技能的适用场景

The project's
```
AGENTS.md
```
or
```
CLAUDE.md
```
contains a block between
```

```
, or
```
self setup
```
prints the workspace, project, and store this directory resolves to.
Skip the skill when
```
self --version
```
fails: the project does not use Superself, and nothing below should be invented by hand. This skill is written against
```
superself@0.6.1
```
; a different major or minor version may have moved a verb or flag, so check
```
self <command> --help
```
before relying on one.

项目的
```
AGENTS.md
```
或
```
CLAUDE.md
```
文件中包含
```

```
之间的代码块，或执行
```
self setup
```
后显示该目录已解析到对应的工作区、项目和存储库。
若执行
```
self --version
```
失败，则跳过本技能：该项目未使用Superself，请勿手动编造以下操作内容。本技能基于
```
superself@0.6.1
```
版本编写；不同的主版本或次版本可能调整了命令或参数，因此在使用前请先执行
```
self <command> --help
```
查看说明。

Session start

会话开始

Run
```
self context
```
and treat its output as current truth: the goal, active decisions and conventions, open work, recent reports. It is folded from the log, never written by hand.
Something missing from context was placed out of the rendered set on purpose;
```
self search <query>
```
finds live records context left out, and
```
self work show <id>
```
prints one unit's full brief and report history.

执行
```
self context
```
并将其输出视为当前真实状态：包括目标、已生效的决策与约定、未完成的工作、近期报告。这些内容由日志生成，绝非手动编写。
若上下文中缺少某些内容，可能是故意未纳入渲染范围；可通过
```
self search <query>
```
查找上下文未展示的有效记录，或执行
```
self work show <id>
```
查看某一工作单元的完整概要和报告历史。

While working

工作过程中

Substantive work attaches to a work unit. Create one with
```
self work add "<required outcome>"
```
— the outcome is what must become true, not the task — then
```
self work start <id>
```
.
```
start
```
reads the brief and records that this session picked the unit up; if another session holds it, the CLI says who and since when and does not refuse. Judge and proceed.
After committing, report progress:
```
self report <id> "<what happened>"
```
. The current HEAD commit is attached as evidence automatically;
```
--evidence <commit|note>
```
attaches something else,
```
--file <path>
```
attaches a longer brief.
Record a decision the user confirmed:
```
self decide "<text>" --why "<reason>"
```
. Use
```
--proposed
```
when the user has not confirmed it. One decision per event.

Blocked?

self work block <id> --on decision|dependency|external --why "..."

. Superseded or moved?

self work retire <id> --why "..." [--successor <id>]

. Never mark such a unit done, and never leave it falsely blocked.

Found a gap between an objective and the current state? Propose the work with
```
self work propose
```
and its brief; the user accepts or declines it.
The user approved a next step or a continuation? Register it at once with
```
self work add
```
and the context behind it. A plan that lives only in the conversation is lost when the conversation ends.

实质性工作需关联到工作单元。执行
```
self work add "<required outcome>"
```
创建工作单元——其中的outcome是必须达成的结果，而非具体任务——然后执行
```
self work start <id>
```
。
```
start
```
命令会读取工作概要并记录当前会话已接手该单元；若该单元已被其他会话占用，CLI会显示占用者及占用时间，但不会阻止操作，请自行判断并继续。
提交代码后，报告进度：执行
```
self report <id> "<what happened>"
```
。当前HEAD提交会自动作为证据附加；使用
```
--evidence <commit|note>
```
可附加其他内容，
```
--file <path>
```
可附加更长的概要说明。
记录用户已确认的决策：执行
```
self decide "<text>" --why "<reason>"
```
。若用户尚未确认，使用
```
--proposed
```
参数。每次事件仅记录一项决策。
遇到阻塞？执行
```
self work block <id> --on decision|dependency|external --why "..."
```
。工作单元被取代或转移？执行
```
self work retire <id> --why "..." [--successor <id>]
```
。请勿标记此类单元为已完成，也不要虚假标记其为阻塞状态。
发现目标与当前状态之间存在差距？执行
```
self work propose
```
并提交工作概要以提议新工作；用户会接受或拒绝该提议。
用户批准了下一步计划或继续当前工作？立即执行
```
self work add
```
并记录相关上下文。仅存在于对话中的计划会在对话结束后丢失。

Closing

会话结束

```
self work done <id>
```
closes a unit only when a report carries a commit or an artifact, or the done itself states what verifiably happened:
```
self work done <id> --report "<what verifiably happened>"
```
. A bare claim is refused, and declared criteria gate it until each is covered.
A record's text is immutable once confirmed. Correct it by restating:
```
--supersedes <id>
```
on any add verb records the new wording and keeps the lineage.
```
retract
```
withdraws a record with nothing replacing it.

只有当报告附带提交记录或工件，或
```
done
```
命令本身明确说明可验证的结果时，才能执行
```
self work done <id>
```
关闭工作单元：例如
```
self work done <id> --report "<what verifiably happened>"
```
。仅提交空泛声明会被拒绝，必须满足所有既定标准才能完成。
记录的文本一经确认便不可修改。如需更正，可重新表述并在添加类命令中使用
```
--supersedes <id>
```
参数，记录新表述并保留历史关联。使用
```
retract
```
参数可撤回记录且不替换内容。

Rules that keep the state trustworthy

确保状态可信的规则

Records — events, decisions, reports, conventions — are written in English so whoever opens them next can read them; answer the person in their own language.
A branch reaches main through a pull request: PR review and CI own merge control. Superself owns context and the work graph, not the merge gate.
Never hand-edit generated state files or anything under
```
.superself/
```
.
In a project without a superself block, run
```
self setup
```
first. If it resolves the directory to a registered project, ask the user once whether to run
```
self connect
```
, which writes the managed block into
```
AGENTS.md
```
or
```
CLAUDE.md
```
. If it resolves no project, ask once whether to register it with
```
self project init
```
. Never register or connect a project on your own.

记录——包括事件、决策、报告、约定——需使用英文编写，以便后续查看者能够理解；但可使用用户的母语与其交流。
分支需通过拉取请求（PR）合并到主分支：PR审核和CI负责合并控制。Superself仅管理上下文和工作图，不负责合并权限。
请勿手动编辑生成的状态文件或
```
.superself/
```
目录下的任何内容。
对于未包含Superself代码块的项目，先执行
```
self setup
```
。若该目录被解析到已注册项目，需询问用户是否执行
```
self connect
```
，该命令会将托管代码块写入
```
AGENTS.md
```
或
```
CLAUDE.md
```
。若未解析到任何项目，需询问用户是否执行
```
self project init
```
注册项目。请勿自行注册或连接项目。

Going deeper

深入了解

self --help

lists every verb;

self <command> --help

prints one command's flags without touching state. Topic guides ship with the CLI:

```
self help agents
```
— how a session drives this CLI, start to finish
```
self help context
```
— what
```
self context
```
renders, and why something is missing from it
```
self help records
```
— one entity behind every record kind, and how a record is corrected
```
self help placement
```
— scope, priority and exposure — how a record earns its place in context
```
self help work
```
— the work graph: outcomes, evidence, criteria, and proposals
```
self help goals
```
— long-term goals, objectives, milestones, and what reaching one takes
```
self help workspace
```
— the store, the projects in it, and moving it between machines

执行

self --help

可查看所有命令；执行

self <command> --help

可查看单个命令的参数，且不会修改状态。CLI附带主题指南：

```
self help agents
```
—— 如何通过会话全程驱动该CLI
```
self help context
```
——
```
self context
```
渲染的内容，以及某些内容未展示的原因
```
self help records
```
—— 每种记录类型背后的实体，以及如何更正记录
```
self help placement
```
—— 范围、优先级和曝光度——记录如何获得在上下文中的展示位置
```
self help work
```
—— 工作图：结果、证据、标准和提议
```
self help goals
```
—— 长期目标、具体目标、里程碑，以及达成目标所需的条件
```
self help workspace
```
—— 存储库、其中的项目，以及如何在不同机器间迁移存储库