{
  "markdown": "<div align=\"center\">\n\n# CodeStable\n\n[English](./README.en.md) · **中文**\n\n**让 AI 编码在长期项目中保持边界、证据和记忆。**\n\n<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>\n</div>\n\nCodeStable 是一组面向严肃软件开发的轻量 skill 契约：不编排 Agent 团队，也不为项目建立第二套文档系统。模型在明确边界内行动，用证据证明结果，并把知识放回项目已有归宿。\n\n## 30 秒运行模型\n\n```text\n用户诉求\n   ↓\ncs：直接执行 / 当前会话讨论 / 给出建议\n   ↓\nfeat · issue · refactor · epic\n   ↓\n相称的验证 + 必要的 review / owner gate\n   ↓ 代码结果 + 项目已有的 canonical knowledge\n```\n\n团队使用时，可以按职责组合：\n\n- **稳定编码**：使用 CodeStable 明确任务边界、保障、证据和项目记忆；\n- **团队上下文共享**：推荐使用 [Threadshare](https://github.com/team-harness/threadshare)，把 Codex、Claude Code\n  等 Agent 会话转换成只读链接，供团队成员和后续 Agent 阅读、交接；\n- **多 Agent 编码协同**：推荐使用 [cs-agent](https://github.com/codestable/cs-agent-mcp)，在编码过程中统一创建、\n  调用和管理 Codex、Claude 等子 Agent，也可承担异构独立 review。\n\n三者互补：CodeStable 不负责发布会话或编排 Agent，Threadshare 和 cs-agent 也不替代 CodeStable 的工程契约。\n\n你只需要告诉 `cs` 想完成什么：\n\n- **需求清楚时**：它直接开始，并用足够的验证交付结果；\n- **遇到具体风险时**：它只增加与风险对应的确认、测试或 review，不自动启用整套流程；\n- **你想先讨论时**：它先和你对齐目标、术语和边界；未经明确授权，不会修改代码；\n- **名词可能影响理解时**：它先对齐含义，形成当前任务的共享语言；没有歧义时，直接沿用项目已有说法。\n\n纯讨论、咨询和体系导览默认不写项目文件。还没讨论清楚的内容，CodeStable 不会专门保存，也不保证下次会话自动恢复。\n\n## 5 分钟开始\n\n### 安装\n\nCodex plugin marketplace：\n\n```bash\ncodex plugin marketplace add codestable/CodeStable\ncodex plugin add codestable@codestable\n```\n\nClaude plugin marketplace：\n\n```text\n/plugin marketplace add codestable/CodeStable\n/plugin install codestable@codestable\n```\n\n`skills` CLI（v1 用户须先按[升级指南](./UPGRADE.md#从-v104-升级到-v2)精确删除 24 个退役入口，再安装 v2）：\n\n```bash\nnpx skills@latest add codestable/CodeStable/plugins/codestable\n```\n\n如果 marketplace catalog 没有发现插件实体，可改用 `npx skills@latest add codestable/CodeStable/plugins/codestable --full-depth` 深度扫描。\n\n### 接入项目\n\n在仓库根目录运行 `/cs-onboard`。它只创建最小项目记忆骨架，不接管项目文档结构、worktree 或 branch 策略。\n\n### 开始工作\n\n不知道该用哪个入口时调用 `/cs`；也可以直接调用 owning skill。v2 交付 8 个 skill：\n\n| Skill | 用途 |\n|---|---|\n| `cs` | 路由明确行动、会话内讨论、咨询与体系导览 |\n| `cs-onboard` | 为仓库创建最小项目记忆骨架 |\n| `cs-feat` | 实现新功能或改变既有行为 |\n| `cs-issue` | 诊断问题；获授权后用红到绿证据修复 |\n| `cs-refactor` | 在行为等价证据下调整结构或性能 |\n| `cs-epic` | 拆解并按已确认策略推进多个可交付子项 |\n| `cs-review` | 只读叶子执行器；单轮审查，不创建子 agent |\n| `cs-keep` | 管理有证据的项目事实、lesson 生命周期与 canonical 归宿 |\n\n`cs-code-review` 是 `cs-review` 的兼容别名，只转发，不包含独立规则。\n\n## 三个核心原则\n\n### 1. thin harness, thick context\n\nCodeStable 给强模型写责任，不写逐步脚本。skill 只约束目标、硬边界和完成证据；模型结合仓库事实选择路径，工程参考按需加载。\n\n薄不等于没有门槛，而是不使用常驻状态机和阶段产物微操模型。\n\n### 2. 证据先于结论\n\n功能实现需要与风险相称的设计和验证；bug 修复先红后绿；重构先建立行为等价证据。独立审查由外层流程创建只读 reviewer。\n\n人在产品契约变化、重大风险或整体接受时进入，不在每个机械步骤上重复确认。\n\n### 3. 一个事实，一个 canonical owner\n\n项目文档、ADR、代码和既有领域文档继续拥有原有事实。CodeStable 不复制平行档案，只补充少量会话事实、经验和活动游标。\n\n稳定结论由 owning skill 放回唯一归宿；没有归宿时先请 owner 选择。\n\n## 项目记忆\n\n`/cs-onboard` 创建：\n\n```text\n.codestable/\n├── attention.md\n├── lessons/\n└── work/\n```\n\n- `attention.md` 保存每次会话都需要的少量项目事实，最多 25 条。\n- `lessons/` 一条经验一个文件，按 observed / validated / retired 演化，并在写入前查重合并。\n- `work/` 只服务活动中的跨会话任务、多人交接或明确要求的持久记录。\n\nCodeStable 边做边识别晶化时刻：任务中静默观察，普通收尾最多给一条有证据的候选。\n\n能机械化的错误优先进入测试或 checker。新 lesson 仍需明确授权，后续会话核实后再验证或退役。\n\n普通任务不生成 CodeStable 阶段文档。diff、测试输出和交付说明就是证据。会话内讨论不进入 `work/`；只有稳定、值得复用的结论才由 owning skill 毕业到 canonical 归宿。\n\n### Epic 的双层模型\n\n大型需求把长期契约和临时执行状态分开。永久 Epic 文档保存目标、范围、验收、已批准子项、关键决策与最终交付。\n\n当路线尚不清晰时，永久 Epic 文档本身就是路线地图，决策依赖派生 frontier。\n\nagent 解决事实，真正的产品判断与取舍进入 HITL。路线清晰、可审查、可执行后，才进入既有 design review、owner 确认与执行。\n\n临时 work 游标只保存永久文档指针、批准 revision、执行进度、策略与证据。\n\nEpic 优先沿用项目已有的 Epic、RFC 或 initiative 归宿；没有时才按需创建 `.codestable/epics/`。执行结束后删除临时游标，永久文档保留。\n\n完整 owner gate、恢复与终态规则见 [WORKFLOW.md](./WORKFLOW.md)。\n\n## 适用边界\n\nCodeStable 更适合：\n\n- 会持续迭代数月或数年的软件项目；\n- 需要让不同会话、模型或开发者准确召回历史约束；\n- 希望 AI 高效执行，同时由人掌握产品边界和最终接受；\n- 重视可验证结果、独立审查和知识复用的团队。\n\n它不是：\n\n- 多 Agent 团队编排器或自动接力平台；\n- 强制所有任务经过同一流水线的流程引擎；\n- 替代项目现有文档、ADR、issue 或 PR 的第二套系统；\n- 面向一次性原型、且完全不关心长期维护的必要依赖。\n\nCodeStable 可以与 Agent 编排工具共存。它负责软件任务的边界、证据和记忆，不接管宿主如何组织 Agent。\n\n需要多 Agent 协作，或需要在 CodeStable 流程中由异构 Agent 承担独立 review 时，推荐配合\n[cs-agent](https://github.com/codestable/cs-agent-mcp) 使用。\n\n## 深入文档\n\n- [完整工作流与项目结构](./WORKFLOW.md)\n- [8 个 skill 的职责与旧入口映射](./SKILL_CATALOG.md)\n- [安装升级与 v1 项目边界](./UPGRADE.md)\n- [为什么设计 CodeStable](./docs/why-codestable.md)\n- [路线图](./ROADMAP.md)\n- [版本变化](./CHANGELOG.md)\n\n<div align=\"center\">\n\nMIT License · 作者 [@liuzhengdong](https://github.com/liuzhengdong)、[@dafang](https://github.com/dafang)、Codex、Claude\n\n</div>\n",
  "bytes": 4455,
  "sha": "23e0290d104aee8fbca4f1a5a4f43b61729f2cd7ebc40dbf7498ef2226009c51",
  "repo_slug": "codestable/codestable",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_codestable_codestable_cs_note_22422d37/readme"
}