superself 是做什么的？
Superself 是一个 Apache-2.0 许可的 CLI 工具（npm install -g [email protected]，需要 Node 22.12+），它通过一个独立的 git 仓库（与代码仓库分离）以仅追加的事件日志形式对项目状态进行版本控制——包括目标、决策、工作单元和报告。状态按需衍生，因此无需手动维护。该技能指导代理如何通过 self CLI 读取和写入该状态。它由 Superself 作者维护：https://github.com/fxylabs/superself
何时适用此技能
- 项目的
AGENTS.md或CLAUDE.md中包含一个介于<!-- superself:begin和<!-- superself:end -->之间的块，或者self setup命令打印出了当前目录所解析的工作区、项目及存储库。 - 当
self --version失败时跳过此技能：该项目未使用 Superself，且以下所有内容不应手动创建。此技能针对[email protected]编写；不同的大版本或小版本可能移动了某个动词或标志，因此在依赖它们之前请使用self <command> --help进行检查。
会话开始
- 运行
self context，并将其输出视为当前的真实状态：包括目标、活跃决策和约定、进行中的工作、最近的报告。这些内容由日志折叠生成，绝不手动编写。 - 如果上下文中缺少某些内容，是因为它们被有意排除在渲染集之外；
self search <query>可以找到上下文遗漏的活跃记录，self work show <id>打印单个工作单元的完整简介和报告历史。
工作过程中
- 实质性工作应附加到一个工作单元。使用
self work add "<必需的结果>"创建一个——结果是指必须成为现实的状态，而非任务——然后使用self work start <id>。start会读取简介并记录当前会话接管了该单元；如果另一个会话已持有它，CLI 会显示谁以及从何时开始持有，但不会拒绝。请自行判断并继续。 - 提交后，使用
self report <id> "<发生了什么>"报告进度。当前 HEAD 提交会自动作为证据附加；--evidence <commit|note>附加其他内容，--file <path>附加更长的简介。 - 记录用户已确认的决策：
self decide "<文本>" --why "<原因>"。当用户尚未确认时使用--proposed。每个事件记录一个决策。 - 遇到阻塞？使用
self work block <id> --on decision|dependency|external --why "..."。任务被替代或移动？使用self work retire <id> --why "..." [--successor <id>]。切勿将此类单元标记为完成，也不应错误地标记为阻塞。 - 发现目标与当前状态之间存在差距？使用
self work propose及其简介来提议工作；用户接受或拒绝。 - 用户批准了下一步或继续？立即使用
self work add及其背景进行注册。仅存在于对话中的计划会在对话结束时丢失。
结束工作
self work done <id>仅当报告包含提交或工件时，或者“完成”本身说明了可验证发生的事件时才关闭一个工作单元：self work done <id> --report "<可验证发生的事情>"。空声明会被拒绝，并且声明的标准会阻止关闭，直到每一条都得到满足。- 记录文本一旦确认即不可变。通过重新声明进行更正：在任何添加动词上使用
--supersedes <id>记录新措辞并保持谱系。retract撤回一条记录，且不替换它。
保持状态可信的规则
- 记录——事件、决策、报告、约定——使用英文编写，以便后续任何人可以阅读；用用户自己的语言回答他们的问题。
- 分支通过拉取请求合并到主分支：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——会话如何从头到尾驱动此 CLIself help context——self context渲染什么，以及为何某些内容缺失self help records——每种记录类型背后的实体，以及如何更正记录self help placement——范围、优先级和曝光度——记录如何获得在上下文中的位置self help work——工作图：结果、证据、标准和提议self help goals——长期目标、目标、里程碑以及实现目标所需的条件self help workspace——存储库、其中的项目以及如何在机器间移动它