skills/codestable__codestable
1
0
Fork 0
mirror of https://github.com/codestable/CodeStable.git synced 2026-09-19 09:03:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: split codestable overview docs

Browse Source
This commit is contained in:
dafang
2026-06-18 16:28:16 +08:00
parent 27a17bbb8f
commit a559f8a6f6
7 changed files with 157 additions and 364 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -1,3 +1,4 @@
.claude
__pycache__
*.pyc
.DS_Store
README.en.md
+6 -181
View File
@@ -12,7 +12,7 @@ Tired of OpenSpec's flimsiness, Oh-My-OpenAgent's over-engineering, and Superpow
<p>
<img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/>
<img src="https://img.shields.io/badge/skills-22-6366F1?style=flat-square" alt="Skills"/>
<img src="https://img.shields.io/badge/skills-23-6366F1?style=flat-square" alt="Skills"/>
<img src="https://img.shields.io/badge/license-MIT-10B981?style=flat-square" alt="License"/>
</p>
@@ -114,198 +114,23 @@ CodeStable models real coding work as **6 entities** and **3 flows**.
## Skill catalog
<table>
<tr><th>Group</th><th>Skill</th><th>Purpose</th></tr>
<tr><td><b>Root entry</b></td><td><code>cs</code></td><td>Unified entry — introduces the system and routes open-ended intents to the right cs-* skill. Call it when you don't know which one fits</td></tr>
<tr><td><b>Onboard</b></td><td><code>cs-onboard</code></td><td>Bring CodeStable into a new repo or one with scattered docs</td></tr>
<tr><td rowspan="2"><b>Requirement & architecture</b></td><td><code>cs-req</code></td><td>Curate / accumulate raw requirement docs</td></tr>
<tr><td><code>cs-arch</code></td><td>Draft or update architecture docs under <code>codestable/architecture/</code></td></tr>
<tr><td><b>Roadmap</b></td><td><code>cs-roadmap</code></td><td>Up-front planning for a big chunk of work: high-level design + interface contracts + sub-feature breakdown</td></tr>
<tr><td><b>Discussion entry</b></td><td><code>cs-brainstorm</code></td><td>Triage when ideas are still fuzzy: route to design / continue in a feature / hand off to roadmap</td></tr>
<tr><td rowspan="5"><b>Feature flow</b></td><td><code>cs-feat</code></td><td>Sub-flow entry for new features</td></tr>
<tr><td><code>cs-feat-design</code></td><td>Draft <code>{slug}-design.md</code> as the single input for what follows</td></tr>
<tr><td><code>cs-feat-impl</code></td><td>Code in the order the design lays out</td></tr>
<tr><td><code>cs-feat-accept</code></td><td>Verify implementation against the design layer by layer; close the loop</td></tr>
<tr><td><code>cs-feat-ff</code></td><td>Ultra-light lane: no design, no phases, AI just does it</td></tr>
<tr><td rowspan="4"><b>Issue flow</b></td><td><code>cs-issue</code></td><td>Sub-flow entry for issue fixing</td></tr>
<tr><td><code>cs-issue-report</code></td><td>Turn the problem in your head into a reproducible, traceable report</td></tr>
<tr><td><code>cs-issue-analyze</code></td><td>Find root cause, assess fix risk, propose options</td></tr>
<tr><td><code>cs-issue-fix</code></td><td>Targeted fix + verification + write fix-note</td></tr>
<tr><td rowspan="2"><b>Refactor flow</b></td><td><code>cs-refactor</code></td><td>(beta) Main refactor flow</td></tr>
<tr><td><code>cs-refactor-ff</code></td><td>(beta) Light refactor lane</td></tr>
<tr><td rowspan="3"><b>Knowledge sink</b></td><td><code>cs-learn</code></td><td>Sink pitfalls / good practices into learning docs</td></tr>
<tr><td><code>cs-trick</code></td><td>Curate reusable patterns / library usage as prescriptive references</td></tr>
<tr><td><code>cs-decide</code></td><td>Record settled tech choices, architectural decisions, long-term constraints as permanent docs</td></tr>
<tr><td rowspan="2"><b>Explore & docs</b></td><td><code>cs-explore</code></td><td>Targeted code exploration; sink "ask → read → conclude" into evidence</td></tr>
<tr><td><code>cs-guide</code> / <code>cs-libdoc</code></td><td>Outward-facing developer guides / library reference docs</td></tr>
</table>
See [SKILL_CATALOG.en.md](./SKILL_CATALOG.en.md) for the full catalog. In daily use, call `/cs` when you are unsure; it routes your intent to the right skill.
---
## Workflow at a glance
CodeStable's skills aren't a single linear pipeline — they're **layered + event-driven**:
CodeStable's skills are **layered + event-driven**: root routing, onboard, long-lived archives, roadmap planning, feature / issue / refactor execution flows, and cross-cut knowledge sinking.
```
═══════════════════════════════════════════════════════════════════════
Root entry · routing (callable any time)
───────────────────────────────────────────────────────────────────────
cs ──▶ Introduce the system / route open-ended intent to a sub-skill
(does nothing itself — only triages and points)
═══════════════════════════════════════════════════════════════════════
│
┌───────────────┼───────────────┐
▼ ▼ ▼
(not onboarded) (onboarded) (just want to learn)
go to phase 0 jump to L1~4 / cross-cut quick read
│
▼
═══════════════════════════════════════════════════════════════════════
Phase 0 · Onboard (runs once per project)
───────────────────────────────────────────────────────────────────────
cs-onboard ──▶ Generate codestable/ skeleton + release reference/, tools/
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
Layer 1 · Long-lived archive ("what the system looks like now")
───────────────────────────────────────────────────────────────────────
cs-req ──▶ codestable/requirements/{slug}.md
cs-arch ──▶ codestable/architecture/ARCHITECTURE.md
└─ {type}-{slug}.md (subsystems)
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
Layer 2 · Planning ("how we plan to deliver this big thing next")
───────────────────────────────────────────────────────────────────────
cs-roadmap ──▶ codestable/roadmap/{slug}/
Turn "I want X" into a complete up-front plan:
① High-level design — module / component split
② Architectural detail — interface contracts
③ Sub-features — broken into executable units
② is a hard input for feature-design
(Small needs skip this layer and go straight to L3)
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
Discussion entry (optional · enter when fuzzy, route after triage)
───────────────────────────────────────────────────────────────────────
┌── case 1 clear enough ──▶ cs-feat-design
cs-brainstorm ────────▶┼── case 2 small + decided ─▶ feature flow
└── case 3 big with one word ─▶ cs-roadmap
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
Layer 3 · Execution flows (pick one per event type)
───────────────────────────────────────────────────────────────────────
▸ Event: new capability ┌──────────┐
cs-feat-design ──▶ cs-feat-impl ──▶ cs-feat-accept │ features │
cs-feat-ff ──(light lane, skips design/accept)─▶│ /YYYY-…/ │
└──────────┘
▸ Event: fix a defect ┌──────────┐
cs-issue-report ──▶ cs-issue-analyze ──▶ cs-issue-fix│ issues │
│ /YYYY-…/ │
└──────────┘
▸ Event: code rot (beta) ┌──────────┐
cs-refactor / cs-refactor-ff │refactors │
│ /YYYY-…/ │
└──────────┘
═══════════════════════════════════════════════════════════════════════
│
▼ trigger any time something is worth recording ▼
═══════════════════════════════════════════════════════════════════════
Cross-cut · Knowledge sink (compounding engineering)
───────────────────────────────────────────────────────────────────────
cs-learn ──▶ ┐
cs-trick ──▶ ├─▶ codestable/compound/YYYY-MM-DD-{doc_type}-{slug}.md
cs-decide ──▶ │ doc_type ∈ { learning, trick, decision, explore }
cs-explore ──▶ ┘
↑
Next cs-arch / cs-feat-design / cs-issue-analyze
reads back compound/ so experience is reused
═══════════════════════════════════════════════════════════════════════
```
**How to read this diagram:**
- **Vertical = layers**, not strict time order — Layer 1 is refreshed repeatedly, Layer 2 is only entered for big needs
- **Layer 3 is event-driven**: new need → feature flow, bug → issue flow, rot → refactor flow
- **Cross-cut is the flywheel**: any flow can trigger a sink when something is worth keeping; the next round of work reads it back. This is the physical implementation of CodeStable's "compounding"
See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full diagram.
---
## Runtime structure
After `/cs-onboard`, a `codestable/` directory appears at your project root — the aggregate root for all CodeStable artifacts and the **only** workspace each skill reads/writes at runtime.
After `/cs-onboard`, a `codestable/` directory appears at your project root as the aggregate root for requirements, architecture, roadmap, features, issues, refactors, compound, tools, and reference.
```
your-project/
├── codestable/
│ ├── requirements/ # Requirement entities ("why this capability exists")
│ │ └── {slug}.md # One file per capability, flat (no grouping)
│ │
│ ├── architecture/ # Architecture entities ("what structure delivers it")
│ │ ├── ARCHITECTURE.md # Architecture entry point / index
│ │ └── {type}-{slug}.md # Subsystem architecture doc (auto-grouped at ≥6 of same type)
│ │
│ ├── roadmap/ # Roadmaps ("how we plan to walk next")
│ │ └── {slug}/
│ │ ├── {slug}-roadmap.md # Main doc: background / breakdown / sequencing
│ │ ├── {slug}-items.yaml # Machine-readable sub-feature list, acceptance writes status back
│ │ └── drafts/ # Optional: drafts / research
│ │
│ ├── features/ # Feature flow aggregate root
│ │ └── YYYY-MM-DD-{slug}/ # One directory per feature
│ │ ├── {slug}-brainstorm.md # Optional (cs-brainstorm output)
│ │ ├── {slug}-design.md # Design (cs-feat-design)
│ │ ├── {slug}-checklist.yaml # Progress checklist (impl runs it, accept writes back)
│ │ └── {slug}-acceptance.md # Acceptance report (cs-feat-accept)
│ │
│ ├── issues/ # Issue flow aggregate root
│ │ └── YYYY-MM-DD-{slug}/
│ │ ├── {slug}-report.md # Issue report
│ │ ├── {slug}-analysis.md # Root-cause analysis (only when non-obvious)
│ │ └── {slug}-fix-note.md # Fix record
│ │
│ ├── refactors/ # Refactor flow aggregate root (beta)
│ │ └── YYYY-MM-DD-{slug}/
│ │ ├── {slug}-scan.md
│ │ ├── {slug}-refactor-design.md
│ │ ├── {slug}-checklist.yaml
│ │ └── {slug}-apply-notes.md
│ │
│ ├── compound/ # Knowledge sink (compounding engineering), unified directory
│ │ └── YYYY-MM-DD-{doc_type}-{slug}.md
│ │ # doc_type ∈ {learning, trick, decision, explore}
│ │
│ ├── tools/ # Cross-workflow shared scripts (released by onboard)
│ └── reference/ # Shared reference docs (released by onboard)
│ ├── shared-conventions.md # Cross-skill conventions / paths / metadata
│ ├── system-overview.md # CodeStable system overview + scenario routing
│ └── ...
│
└── AGENTS.md # At project root, not under codestable/
```
**Key points:**
- All artifacts aggregate under `codestable/`, so "how did we handle that feature / bug last time" is three seconds away
- `requirements/` and `architecture/` are **long-lived archives** (current state only); `roadmap/` is the **planning layer** (what's next) — deliberately separated
- `features/` `issues/` `refactors/` use `YYYY-MM-DD-{slug}/` to bundle all related specs in one directory, no crossing
- `compound/` is the **single** knowledge sink directory — learning / trick / decision / explore are distinguished by the `doc_type` field, not by sub-directories. Easier to search
- `reference/` is copied in by `cs-onboard` from the skill package; to change shared conventions, edit the templates under `cs-onboard/reference/` — new projects pick up the new version on onboard
### Hard constraint
> A skill is an independent install unit. At runtime, **each skill can only see files inside its own package**. References like `B-skill/reference/xxx.md` written in skill A's SKILL.md are **simply unreachable** at runtime.
>
> Cross-skill shared references must go through the "working project" layer: `cs-onboard` copies them from the skill package to the project's `codestable/reference/`, and other skills read them via the project-relative path.
See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full directory model and cross-skill reference constraints.
To change shared conventions, edit the templates under `cs-onboard/reference/`; new projects pick them up at onboard time.
README.md
+6 -183
View File
@@ -12,7 +12,7 @@
<p>
<img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/>
<img src="https://img.shields.io/badge/skills-22-6366F1?style=flat-square" alt="Skills"/>
<img src="https://img.shields.io/badge/skills-23-6366F1?style=flat-square" alt="Skills"/>
<img src="https://img.shields.io/badge/license-MIT-10B981?style=flat-square" alt="License"/>
</p>
@@ -116,200 +116,23 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成
## 技能总览
<table>
<tr><th>分组</th><th>技能</th><th>用途</th></tr>
<tr><td><b>根入口</b></td><td><code>cs</code></td><td>统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它</td></tr>
<tr><td rowspan="1"><b>接入</b></td><td><code>cs-onboard</code></td><td>把 CodeStable 接入到一个新仓库 / 已有零散文档的仓库</td></tr>
<tr><td rowspan="2"><b>需求 & 架构</b></td><td><code>cs-req</code></td><td>整理 / 沉淀原始需求文档</td></tr>
<tr><td><code>cs-arch</code></td><td>起草或更新 <code>codestable/architecture/</code> 下的架构文档</td></tr>
<tr><td><b>路线图</b></td><td><code>cs-roadmap</code></td><td>承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 / 共享协议）+ 子 feature 拆解清单</td></tr>
<tr><td><b>讨论入口</b></td><td><code>cs-brainstorm</code></td><td>想法模糊时的统一讨论入口，做分诊：直接 design / 进 feature 写 brainstorm.md / 移交 roadmap</td></tr>
<tr><td rowspan="5"><b>特性流程</b></td><td><code>cs-feat</code></td><td>新特性子流程入口</td></tr>
<tr><td><code>cs-feat-design</code></td><td>起草 <code>{slug}-design.md</code> 作为后续唯一输入</td></tr>
<tr><td><code>cs-feat-impl</code></td><td>按 design 的推进顺序写代码</td></tr>
<tr><td><code>cs-feat-accept</code></td><td>逐层对照 design 核对实现，做完整验收闭环</td></tr>
<tr><td><code>cs-feat-ff</code></td><td>超轻量通道：不写 design、不分阶段，让 AI 直接做</td></tr>
<tr><td rowspan="4"><b>问题流程</b></td><td><code>cs-issue</code></td><td>问题修复子流程入口</td></tr>
<tr><td><code>cs-issue-report</code></td><td>把脑子里的问题落成可复现、可追溯的 report</td></tr>
<tr><td><code>cs-issue-analyze</code></td><td>找根因、评估修复风险、给方案</td></tr>
<tr><td><code>cs-issue-fix</code></td><td>定点修复 + 验证 + 写 fix-note</td></tr>
<tr><td rowspan="2"><b>重构流程</b></td><td><code>cs-refactor</code></td><td>(beta) 重构主流程</td></tr>
<tr><td><code>cs-refactor-ff</code></td><td>(beta) 轻量重构通道</td></tr>
<tr><td rowspan="3"><b>知识沉淀</b></td><td><code>cs-learn</code></td><td>把踩过的坑 / 好做法沉淀成 learning 文档</td></tr>
<tr><td><code>cs-trick</code></td><td>把可复用的编程模式 / 库用法整理成处方性参考</td></tr>
<tr><td><code>cs-decide</code></td><td>把已拍板的技术选型、架构决定、长期约束记成永久文档</td></tr>
<tr><td rowspan="2"><b>探索 & 文档</b></td><td><code>cs-explore</code></td><td>定向代码探索，把"提问 → 读代码 → 得结论"沉淀成证据</td></tr>
<tr><td><code>cs-guide</code> / <code>cs-libdoc</code></td><td>对外的开发者指南 / 库参考文档</td></tr>
</table>
完整技能目录见 [SKILL_CATALOG.md](./SKILL_CATALOG.md)。日常不知道用哪个时直接调用 `/cs`，它会按诉求路由到对应技能。
---
## 工作流示意
CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的：
CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的：根入口路由、onboard、长效档案、roadmap 规划、feature / issue / refactor 执行流，以及横切的知识沉淀。
```
═══════════════════════════════════════════════════════════════════════
根入口 · 路由 （任何时刻都可以调用）
───────────────────────────────────────────────────────────────────────
cs ──▶ 介绍体系 / 把开放式诉求路由到下面任一具体子技能
（本身不做事，只做分诊和提示）
═══════════════════════════════════════════════════════════════════════
│
┌───────────────┼───────────────┐
▼ ▼ ▼
（未接入） （已接入） （想了解体系）
走阶段 0 直达 1~4 层 / 横切 给速读
│
▼
═══════════════════════════════════════════════════════════════════════
阶段 0 · 接入 （只在新项目跑一次）
───────────────────────────────────────────────────────────────────────
cs-onboard ──▶ 生成 codestable/ 骨架 + 释放 reference/、tools/
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 1 层 · 长效档案（"系统现在长什么样"，只记现状）
───────────────────────────────────────────────────────────────────────
cs-req ──▶ codestable/requirements/{slug}.md
cs-arch ──▶ codestable/architecture/ARCHITECTURE.md
└─ {type}-{slug}.md（子系统）
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 2 层 · 规划（"接下来打算怎么做这块大需求"，大需求才需要）
───────────────────────────────────────────────────────────────────────
cs-roadmap ──▶ codestable/roadmap/{slug}/
把一个"我想要 X 系统"做成完整的事前规划：
① 概设 —— 拆成哪几个模块 / 组件
② 架构层详设 —— 模块间接口契约 / 共享协议
③ 子 feature —— 把方案分解成多条可执行的 feature
② 是 feature-design 的硬约束输入
（小需求可跳过本层，直接进第 3 层）
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
讨论入口（可选 · 想法模糊时进入，做分诊后路由到下游）
───────────────────────────────────────────────────────────────────────
┌── case 1 已经够清楚 ──▶ cs-feat-design
cs-brainstorm ────────▶┼── case 2 小需求方向定 ─▶ feature 流（落 brainstorm.md）
└── case 3 大需求只有一个词 ─▶ cs-roadmap
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 3 层 · 执行流程（按事件类型选一条进入）
───────────────────────────────────────────────────────────────────────
▸ 事件：新增能力 ┌──────────┐
cs-feat-design ──▶ cs-feat-impl ──▶ cs-feat-accept │ features │
cs-feat-ff ──(轻量直通车，跳过 design/accept)─▶ │ /YYYY-…/ │
└──────────┘
▸ 事件：修复缺陷 ┌──────────┐
cs-issue-report ──▶ cs-issue-analyze ──▶ cs-issue-fix│ issues │
│ /YYYY-…/ │
└──────────┘
▸ 事件：代码腐化（beta） ┌──────────┐
cs-refactor / cs-refactor-ff │refactors │
│ /YYYY-…/ │
└──────────┘
═══════════════════════════════════════════════════════════════════════
│
▼ 任意阶段觉得"这个值得记下来"都能触发 ▼
═══════════════════════════════════════════════════════════════════════
横切层 · 知识沉淀（复利工程）
───────────────────────────────────────────────────────────────────────
cs-learn ──▶ ┐
cs-trick ──▶ ├─▶ codestable/compound/YYYY-MM-DD-{doc_type}-{slug}.md
cs-decide ──▶ │ doc_type ∈ { learning, trick, decision, explore }
cs-explore ──▶ ┘
↑
下一次 cs-arch / cs-feat-design / cs-issue-analyze
会回头读 compound/，让经验在新工作里被复用
═══════════════════════════════════════════════════════════════════════
```
**怎么读这张图：**
- **纵向是层次**，不是严格的时间顺序——长效档案层会反复被刷新，规划层只在大需求时进入
- **第 3 层是事件入口**：来了新需求走 feature 流，发现 bug 走 issue 流，发现腐化走 refactor 流
- **横切层是飞轮**：任何流程跑完发现"这事值得记下来"都可以触发沉淀，沉淀的产物又会被下一次同类工作读到——这是 CodeStable "复利"的物理实现
完整示意图见 [WORKFLOW.md](./WORKFLOW.md)。
---
## 运行时结构
`/cs-onboard` 跑完后，会在你的项目根下生成一个 `codestable/` 目录——这是 CodeStable 所有产物的聚合根，也是各个子技能在运行时**唯一**会读写的工作区。
`/cs-onboard` 跑完后，会在你的项目根下生成 `codestable/`，作为 requirements、architecture、roadmap、features、issues、refactors、compound、tools 和 reference 的聚合根。
```
你的项目/
├── codestable/
│ ├── requirements/ # 需求实体（"为什么要有这个能力"）
│ │ └── {slug}.md # 一个能力一份，扁平不分组
│ │
│ ├── architecture/ # 架构实体（"用什么结构实现"）
│ │ ├── ARCHITECTURE.md # 架构总入口 / 索引
│ │ └── {type}-{slug}.md # 子系统架构 doc（同类 ≥6 份自动收进子目录）
│ │
│ ├── roadmap/ # 路线图（"接下来打算怎么走"）
│ │ └── {slug}/
│ │ ├── {slug}-roadmap.md # 主文档：背景 / 拆解 / 排期
│ │ ├── {slug}-items.yaml # 机器可读子 feature 清单，acceptance 回写状态
│ │ └── drafts/ # 可选：草稿 / 调研
│ │
│ ├── features/ # 特性流程聚合根
│ │ └── YYYY-MM-DD-{slug}/ # 一个 feature 一个目录
│ │ ├── {slug}-brainstorm.md # 可选（cs-brainstorm 产出）
│ │ ├── {slug}-design.md # 方案（cs-feat-design）
│ │ ├── {slug}-checklist.yaml # 推进清单（impl 跑、accept 回写）
│ │ └── {slug}-acceptance.md # 验收报告（cs-feat-accept）
│ │
│ ├── issues/ # 问题流程聚合根
│ │ └── YYYY-MM-DD-{slug}/
│ │ ├── {slug}-report.md # 问题报告
│ │ ├── {slug}-analysis.md # 根因分析（不显然时才有）
│ │ └── {slug}-fix-note.md # 修复记录
│ │
│ ├── refactors/ # 重构流程聚合根（beta）
│ │ └── YYYY-MM-DD-{slug}/
│ │ ├── {slug}-scan.md
│ │ ├── {slug}-refactor-design.md
│ │ ├── {slug}-checklist.yaml
│ │ └── {slug}-apply-notes.md
│ │
│ ├── compound/ # 知识沉淀（复利工程）统一目录
│ │ └── YYYY-MM-DD-{doc_type}-{slug}.md
│ │ # doc_type ∈ {learning, trick, decision, explore}
│ │
│ ├── tools/ # 跨工作流共享脚本（onboard 释放）
│ └── reference/ # 共享参考文档（onboard 释放）
│ ├── shared-conventions.md # 跨技能口径 / 路径命名 / 元数据规范
│ ├── system-overview.md # CodeStable 体系总览 + 场景路由
│ └── ...
│
└── AGENTS.md # 在项目根，不在 codestable/ 里
```
**几条要点：**
- 所有产物都聚在 `codestable/` 下，让"上次那个 feature / bug 当时怎么搞的"三秒能找到
- `requirements/` 和 `architecture/` 是**长效档案**（只记现状），`roadmap/` 是**规划层**（接下来怎么走），两者刻意分开
- `features/` `issues/` `refactors/` 用 `YYYY-MM-DD-{slug}/` 一个目录装齐所有相关 spec，不交叉
- `compound/` 是**唯一**的知识沉淀目录，learning / trick / decision / explore 通过 `doc_type` 字段区分而不是分目录——好搜
- `reference/` 是 `cs-onboard` 从技能包复制过来的；要改共享口径，改 `cs-onboard/reference/` 模板，新项目 onboard 自动带上新版
### 硬约束
> Skill 是独立安装单元，运行时**每个 skill 只能看到自己包内的文件**。A 技能的 SKILL.md 里写 `B-skill/reference/xxx.md` 这种引用在运行时**根本读不到**。
>
> 跨 skill 共享的参考文档必须走"工作项目"这一层：由 `cs-onboard` 从技能包复制到项目的 `codestable/reference/`，其他 skill 用项目相对路径读取。
要改共享口径，改 `cs-onboard/reference/` 下的模板，新项目 onboard 时带上新版本。
完整目录说明和跨 skill 引用约束见 [WORKFLOW.md](./WORKFLOW.md)。
---
SKILL_CATALOG.en.md
+28
View File
@@ -0,0 +1,28 @@
# CodeStable Skill Catalog
| Group | Skill | Purpose |
|---|---|---|
| Root entry | `cs` | Unified entry that introduces the system and routes open-ended intents to the right `cs-*` skill |
| Onboard | `cs-onboard` | Bring CodeStable into a new repo or one with scattered docs |
| Requirement and architecture | `cs-req` | Curate and accumulate raw requirement docs |
| Requirement and architecture | `cs-arch` | Draft or update architecture docs under `codestable/architecture/` |
| Roadmap | `cs-roadmap` | Plan big work up front: high-level design, interface contracts, sub-feature breakdown |
| Roadmap | `cs-roadmap-impl` | Advance the next executable item in an existing roadmap, initialize its feature, and hand off to design / impl / accept |
| Discussion entry | `cs-brainstorm` | Triage fuzzy ideas: direct design, feature brainstorm, or roadmap |
| Feature flow | `cs-feat` | Sub-flow entry for new features |
| Feature flow | `cs-feat-design` | Draft `{slug}-design.md` as the single input for what follows |
| Feature flow | `cs-feat-impl` | Code in the order the design lays out |
| Feature flow | `cs-feat-accept` | Verify implementation against the design and close the loop |
| Feature flow | `cs-feat-ff` | Ultra-light lane: no design, no phases, direct implementation |
| Issue flow | `cs-issue` | Sub-flow entry for issue fixing |
| Issue flow | `cs-issue-report` | Turn a problem into a reproducible, traceable report |
| Issue flow | `cs-issue-analyze` | Find root cause, assess risk, propose options |
| Issue flow | `cs-issue-fix` | Targeted fix, verification, and fix-note |
| Refactor flow | `cs-refactor` | Beta main refactor flow |
| Refactor flow | `cs-refactor-ff` | Beta light refactor lane |
| Knowledge sink | `cs-learn` | Sink pitfalls or good practices into learning docs |
| Knowledge sink | `cs-trick` | Curate reusable patterns or library usage as prescriptive references |
| Knowledge sink | `cs-decide` | Record settled tech choices, architectural decisions, and long-term constraints |
| Explore and docs | `cs-explore` | Targeted code exploration; sink “ask -> read -> conclude” into evidence |
| Explore and docs | `cs-guide` | Write outward-facing developer guides |
| Explore and docs | `cs-libdoc` | Generate reference docs for public library surfaces |
SKILL_CATALOG.md
+28
View File
@@ -0,0 +1,28 @@
# CodeStable 技能目录
| 分组 | 技能 | 用途 |
|---|---|---|
| 根入口 | `cs` | 统一入口，介绍体系并把开放式诉求路由到正确的 `cs-*` 子技能 |
| 接入 | `cs-onboard` | 把 CodeStable 接入到一个新仓库或已有零散文档的仓库 |
| 需求与架构 | `cs-req` | 整理和沉淀原始需求文档 |
| 需求与架构 | `cs-arch` | 起草或更新 `codestable/architecture/` 下的架构文档 |
| 路线图 | `cs-roadmap` | 为大需求做事前规划：概设、接口契约、子 feature 拆解 |
| 路线图 | `cs-roadmap-impl` | 推进已有 roadmap 的下一条可执行 item，初始化 feature 并衔接 design / impl / accept |
| 讨论入口 | `cs-brainstorm` | 想法模糊时分诊：直接 design、进入 feature brainstorm，或移交 roadmap |
| 特性流程 | `cs-feat` | 新特性子流程入口 |
| 特性流程 | `cs-feat-design` | 起草 `{slug}-design.md` 作为后续唯一输入 |
| 特性流程 | `cs-feat-impl` | 按 design 的推进顺序写代码 |
| 特性流程 | `cs-feat-accept` | 对照 design 核对实现并完成验收闭环 |
| 特性流程 | `cs-feat-ff` | 超轻量通道：不写 design、不分阶段，直接实现 |
| 问题流程 | `cs-issue` | 问题修复子流程入口 |
| 问题流程 | `cs-issue-report` | 把问题落成可复现、可追溯的 report |
| 问题流程 | `cs-issue-analyze` | 找根因、评估修复风险、给方案 |
| 问题流程 | `cs-issue-fix` | 定点修复、验证并写 fix-note |
| 重构流程 | `cs-refactor` | beta 重构主流程 |
| 重构流程 | `cs-refactor-ff` | beta 轻量重构通道 |
| 知识沉淀 | `cs-learn` | 把踩过的坑或好做法沉淀成 learning 文档 |
| 知识沉淀 | `cs-trick` | 把可复用模式或库用法整理成处方性参考 |
| 知识沉淀 | `cs-decide` | 把已拍板的技术选型、架构决定、长期约束记成永久文档 |
| 探索与文档 | `cs-explore` | 定向代码探索，把“提问 → 读代码 → 得结论”沉淀成证据 |
| 探索与文档 | `cs-guide` | 编写对外开发者指南 |
| 探索与文档 | `cs-libdoc` | 为库的公开表面生成参考文档 |
WORKFLOW.en.md
+44
View File
@@ -0,0 +1,44 @@
# CodeStable Workflow and Runtime Structure
## Workflow Layers
CodeStable skills are layered and event-driven:
```text
cs
└── cs-onboard
├── cs-req / cs-arch
├── cs-roadmap
│ └── cs-roadmap-impl
├── cs-feat-design -> cs-feat-impl -> cs-feat-accept
├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix
├── cs-refactor / cs-refactor-ff
└── cs-learn / cs-trick / cs-decide / cs-explore
```
Vertical means layers, not strict time order. Long-lived archives are refreshed repeatedly; the roadmap layer is entered for large needs. Execution is event-driven: new capability goes to feature flow, bugs go to issue flow, and code rot goes to refactor flow. The cross-cut layer is the knowledge flywheel.
## Runtime Structure
After `/cs-onboard`, the project root gets `codestable/`:
```text
codestable/
├── requirements/
├── architecture/
├── roadmap/
├── features/
├── issues/
├── refactors/
├── compound/
├── tools/
└── reference/
```
Key constraints:
- `requirements/` and `architecture/` are long-lived archives and record current state.
- `roadmap/` is the planning layer for large needs.
- `features/`, `issues/`, and `refactors/` use `YYYY-MM-DD-{slug}/` to group one workflow run.
- `compound/` is the single knowledge sink; `doc_type` distinguishes learning / trick / decision / explore.
- `reference/` is released by `cs-onboard`; cross-skill shared docs must go through project-local `codestable/reference/`, not direct references to another skill package.
WORKFLOW.md
+44
View File
@@ -0,0 +1,44 @@
# CodeStable 工作流与运行结构
## 工作流层次
CodeStable 的技能是分层 + 事件驱动的：
```text
cs
└── cs-onboard
├── cs-req / cs-arch
├── cs-roadmap
│ └── cs-roadmap-impl
├── cs-feat-design -> cs-feat-impl -> cs-feat-accept
├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix
├── cs-refactor / cs-refactor-ff
└── cs-learn / cs-trick / cs-decide / cs-explore
```
纵向是层次，不是严格时间顺序。长效档案层会反复刷新，规划层只在大需求时进入。第 3 层是事件入口：新需求走 feature，bug 走 issue，腐化走 refactor。横切层是知识飞轮：任何流程都可以把值得复用的经验沉淀到 compound。
## 运行时结构
`/cs-onboard` 后，项目根下会出现 `codestable/`：
```text
codestable/
├── requirements/
├── architecture/
├── roadmap/
├── features/
├── issues/
├── refactors/
├── compound/
├── tools/
└── reference/
```
关键约束：
- `requirements/` 和 `architecture/` 是长效档案，只记现状。
- `roadmap/` 是规划层，描述大需求接下来怎么走。
- `features/`、`issues/`、`refactors/` 用 `YYYY-MM-DD-{slug}/` 聚合单次流程产物。
- `compound/` 是唯一知识沉淀目录，靠 `doc_type` 区分 learning / trick / decision / explore。
- `reference/` 由 `cs-onboard` 释放共享口径；跨 skill 共享文档必须通过项目内 `codestable/reference/`，不能从一个 skill 直接引用另一个 skill 包内文件。