superself 是做什麼的？
Superself 是一個 Apache-2.0 授權的命令列工具（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>僅在報告附有提交或工件，或者 done 本身說明了可驗證發生的事情時，才會關閉一個單元：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— 儲存庫、其中的專案，以及在機器之間移動儲存庫