superself

Superself

Superself 是一个 Apache-2.0 命令行工具（npm install -g [email protected]，需要 Node 22.12+），它以仅追加的事件日志形式，将项目状态——目标、决策、工作单元、报告——纳入版本控制，存放在与代码分离的 git 仓库中。状态按需派生，因此其中没有任何内容是手工维护的。本技能告诉 Agent 如何通过 self 命令行读取和写入该状态。本技能由 Superself 作者维护：https://github.com/fxylabs/superself

本技能适用的场景

• 项目的 AGENTS.md 或 CLAUDE.md 包含位于 `` 之间的块，或者 self setup 打印出该目录所解析到的 工作区、项目和存储。
• 当 self --version 失败时跳过本技能：该项目未使用 Superself，下文任何内容都不应手工臆造。本技能是针对 [email protected] 编写的；不同的大版本或次版本可能 移动了某个动词或标志，因此在依赖某一项之前，请先检查 self <command> --help。

会话开始

1. 运行 self context，并将其输出视为当前事实：目标、生效中的 决策与约定、未完成的工作、最近的报告。它由日志折叠而来，绝不 手工写入。
2. 上下文中缺失的内容是有意被置于渲染集合之外的；self search <query> 可以找到 上下文略去的活跃记录，self work show <id> 会打印某个单元的完整简报和 报告历史。

工作期间

• 实质性工作会挂接到某个工作单元。用 self work add "<required outcome>" 创建一个——该成果是必须变为 事实的东西，而不是任务——然后运行 self work start <id>。start 会读取简报并 记录本次会话接手了该单元；如果另一个会话持有它， 命令行会说明是谁以及从何时起，但不会拒绝。自行判断并继续。
• 提交之后，报告进展：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 注册它，并附上其背后的上下文。只存在于 对话中的计划，会在对话结束时丢失。

收尾

• 只有当某份报告带有提交或产物，或者 done 本身陈述了可验证地 发生的事情时，self work done <id> 才会关闭该单元： self work done <id> --report "<what verifiably happened>"。仅有声称会被 拒绝，而已声明的标准会对其进行把关，直到每一项都得到满足。
• 记录一经确认，其文本即不可更改。通过重述来更正它： 任何 add 动词上的 --supersedes <id> 会记录新的措辞并保留 谱系。retract 会撤回记录，且没有任何内容替代它。

让状态值得信赖的规则

• 记录——事件、决策、报告、约定——以英文书写，这样下一个打开它们的人都能读懂；用对方自己的语言回答对方。
• 分支通过拉取请求进入 main：PR 评审和 CI 掌握合并控制权。Superself 掌握上下文和工作图，而不是合并门禁。
• 切勿手动编辑生成的状态文件或 .superself/ 下的任何内容。
• 在没有 superself 块的项目中，先运行 self setup。如果它将该目录解析为一个已注册项目，就询问用户一次是否要运行 self connect，该命令会把托管块写入 AGENTS.md 或 CLAUDE.md。如果它没有解析出任何项目，就询问一次是否要用 self project init 注册它。切勿自行注册或连接项目。

深入了解

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 —— 存储库、其中的项目，以及在机器之间迁移它