<div align="center">

CodeStable

English · 中文

让 AI 编码在长期项目中保持边界、证据和记忆。

<p><img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/> <img src="https://img.shields.io/badge/cs--skills-8-6366F1?style=flat-square" alt="CodeStable Skills"/> <img src="https://img.shields.io/badge/license-MIT-10B981?style=flat-square" alt="License"/></p>
</div>

CodeStable 是一组面向严肃软件开发的轻量 skill 契约：不编排 Agent 团队，也不为项目建立第二套文档系统。模型在明确边界内行动，用证据证明结果，并把知识放回项目已有归宿。

30 秒运行模型

用户诉求
   ↓
cs：直接执行 / 当前会话讨论 / 给出建议
   ↓
feat · issue · refactor · epic
   ↓
相称的验证 + 必要的 review / owner gate
   ↓ 代码结果 + 项目已有的 canonical knowledge

团队使用时，可以按职责组合：

• 稳定编码：使用 CodeStable 明确任务边界、保障、证据和项目记忆；
• 团队上下文共享：推荐使用 Threadshare，把 Codex、Claude Code 等 Agent 会话转换成只读链接，供团队成员和后续 Agent 阅读、交接；
• 多 Agent 编码协同：推荐使用 cs-agent，在编码过程中统一创建、 调用和管理 Codex、Claude 等子 Agent，也可承担异构独立 review。

三者互补：CodeStable 不负责发布会话或编排 Agent，Threadshare 和 cs-agent 也不替代 CodeStable 的工程契约。

你只需要告诉 cs 想完成什么：

• 需求清楚时：它直接开始，并用足够的验证交付结果；
• 遇到具体风险时：它只增加与风险对应的确认、测试或 review，不自动启用整套流程；
• 你想先讨论时：它先和你对齐目标、术语和边界；未经明确授权，不会修改代码；
• 名词可能影响理解时：它先对齐含义，形成当前任务的共享语言；没有歧义时，直接沿用项目已有说法。

纯讨论、咨询和体系导览默认不写项目文件。还没讨论清楚的内容，CodeStable 不会专门保存，也不保证下次会话自动恢复。

5 分钟开始

安装

Codex plugin marketplace：

codex plugin marketplace add codestable/CodeStable
codex plugin add codestable@codestable

Claude plugin marketplace：

/plugin marketplace add codestable/CodeStable
/plugin install codestable@codestable

skills CLI（v1 用户须先按升级指南精确删除 24 个退役入口，再安装 v2）：

npx skills@latest add codestable/CodeStable/plugins/codestable

如果 marketplace catalog 没有发现插件实体，可改用 npx skills@latest add codestable/CodeStable/plugins/codestable --full-depth 深度扫描。

接入项目

在仓库根目录运行 /cs-onboard。它只创建最小项目记忆骨架，不接管项目文档结构、worktree 或 branch 策略。

开始工作

不知道该用哪个入口时调用 /cs；也可以直接调用 owning skill。v2 交付 8 个 skill：

cs-code-review 是 cs-review 的兼容别名，只转发，不包含独立规则。

三个核心原则

1. thin harness, thick context

CodeStable 给强模型写责任，不写逐步脚本。skill 只约束目标、硬边界和完成证据；模型结合仓库事实选择路径，工程参考按需加载。

薄不等于没有门槛，而是不使用常驻状态机和阶段产物微操模型。

2. 证据先于结论

功能实现需要与风险相称的设计和验证；bug 修复先红后绿；重构先建立行为等价证据。独立审查由外层流程创建只读 reviewer。

人在产品契约变化、重大风险或整体接受时进入，不在每个机械步骤上重复确认。

3. 一个事实，一个 canonical owner

项目文档、ADR、代码和既有领域文档继续拥有原有事实。CodeStable 不复制平行档案，只补充少量会话事实、经验和活动游标。

稳定结论由 owning skill 放回唯一归宿；没有归宿时先请 owner 选择。

项目记忆

/cs-onboard 创建：

.codestable/
├── attention.md
├── lessons/
└── work/

• attention.md 保存每次会话都需要的少量项目事实，最多 25 条。
• lessons/ 一条经验一个文件，按 observed / validated / retired 演化，并在写入前查重合并。
• work/ 只服务活动中的跨会话任务、多人交接或明确要求的持久记录。

CodeStable 边做边识别晶化时刻：任务中静默观察，普通收尾最多给一条有证据的候选。

能机械化的错误优先进入测试或 checker。新 lesson 仍需明确授权，后续会话核实后再验证或退役。

普通任务不生成 CodeStable 阶段文档。diff、测试输出和交付说明就是证据。会话内讨论不进入 work/；只有稳定、值得复用的结论才由 owning skill 毕业到 canonical 归宿。

Epic 的双层模型

大型需求把长期契约和临时执行状态分开。永久 Epic 文档保存目标、范围、验收、已批准子项、关键决策与最终交付。

当路线尚不清晰时，永久 Epic 文档本身就是路线地图，决策依赖派生 frontier。

agent 解决事实，真正的产品判断与取舍进入 HITL。路线清晰、可审查、可执行后，才进入既有 design review、owner 确认与执行。

临时 work 游标只保存永久文档指针、批准 revision、执行进度、策略与证据。

Epic 优先沿用项目已有的 Epic、RFC 或 initiative 归宿；没有时才按需创建 .codestable/epics/。执行结束后删除临时游标，永久文档保留。

完整 owner gate、恢复与终态规则见 WORKFLOW.md。

适用边界

CodeStable 更适合：

• 会持续迭代数月或数年的软件项目；
• 需要让不同会话、模型或开发者准确召回历史约束；
• 希望 AI 高效执行，同时由人掌握产品边界和最终接受；
• 重视可验证结果、独立审查和知识复用的团队。

它不是：

• 多 Agent 团队编排器或自动接力平台；
• 强制所有任务经过同一流水线的流程引擎；
• 替代项目现有文档、ADR、issue 或 PR 的第二套系统；
• 面向一次性原型、且完全不关心长期维护的必要依赖。

CodeStable 可以与 Agent 编排工具共存。它负责软件任务的边界、证据和记忆，不接管宿主如何组织 Agent。

需要多 Agent 协作，或需要在 CodeStable 流程中由异构 Agent 承担独立 review 时，推荐配合 cs-agent 使用。

深入文档

• 完整工作流与项目结构
• 8 个 skill 的职责与旧入口映射
• 安装升级与 v1 项目边界
• 为什么设计 CodeStable
• 路线图
• 版本变化

<div align="center">

MIT License · 作者 @liuzhengdong、@dafang、Codex、Claude

</div>