-| Group | Skill | Purpose |
|---|
-| Root entry | cs | 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 |
-| Onboard | cs-onboard | Bring CodeStable into a new repo or one with scattered docs |
-| Requirement & architecture | cs-req | Curate / accumulate raw requirement docs |
-cs-arch | Draft or update architecture docs under codestable/architecture/ |
-| Roadmap | cs-roadmap | Up-front planning for a big chunk of work: high-level design + interface contracts + sub-feature breakdown |
-| Discussion entry | cs-brainstorm | Triage when ideas are still fuzzy: route to design / continue in a feature / hand off to roadmap |
-| Feature flow | cs-feat | Sub-flow entry for new features |
-cs-feat-design | Draft {slug}-design.md as the single input for what follows |
-cs-feat-impl | Code in the order the design lays out |
-cs-feat-accept | Verify implementation against the design layer by layer; close the loop |
-cs-feat-ff | Ultra-light lane: no design, no phases, AI just does it |
-| Issue flow | cs-issue | Sub-flow entry for issue fixing |
-cs-issue-report | Turn the problem in your head into a reproducible, traceable report |
-cs-issue-analyze | Find root cause, assess fix risk, propose options |
-cs-issue-fix | Targeted fix + verification + write fix-note |
-| Refactor flow | cs-refactor | (beta) Main refactor flow |
-cs-refactor-ff | (beta) Light refactor lane |
-| Knowledge sink | cs-learn | Sink pitfalls / good practices into learning docs |
-cs-trick | Curate reusable patterns / library usage as prescriptive references |
-cs-decide | Record settled tech choices, architectural decisions, long-term constraints as permanent docs |
-| Explore & docs | cs-explore | Targeted code exploration; sink "ask → read → conclude" into evidence |
-cs-guide / cs-libdoc | Outward-facing developer guides / library reference docs |
-
+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.
diff --git a/README.md b/README.md
index ae4ff3c..ff40390 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
-| 分组 | 技能 | 用途 |
|---|
-| 根入口 | cs | 统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它 |
-| 接入 | cs-onboard | 把 CodeStable 接入到一个新仓库 / 已有零散文档的仓库 |
-| 需求 & 架构 | cs-req | 整理 / 沉淀原始需求文档 |
-cs-arch | 起草或更新 codestable/architecture/ 下的架构文档 |
-| 路线图 | cs-roadmap | 承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 / 共享协议）+ 子 feature 拆解清单 |
-| 讨论入口 | cs-brainstorm | 想法模糊时的统一讨论入口，做分诊：直接 design / 进 feature 写 brainstorm.md / 移交 roadmap |
-| 特性流程 | cs-feat | 新特性子流程入口 |
-cs-feat-design | 起草 {slug}-design.md 作为后续唯一输入 |
-cs-feat-impl | 按 design 的推进顺序写代码 |
-cs-feat-accept | 逐层对照 design 核对实现，做完整验收闭环 |
-cs-feat-ff | 超轻量通道：不写 design、不分阶段，让 AI 直接做 |
-| 问题流程 | 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 | 对外的开发者指南 / 库参考文档 |
-
+完整技能目录见 [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)。
---
diff --git a/SKILL_CATALOG.en.md b/SKILL_CATALOG.en.md
new file mode 100644
index 0000000..48c002e
--- /dev/null
+++ b/SKILL_CATALOG.en.md
@@ -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 |
diff --git a/SKILL_CATALOG.md b/SKILL_CATALOG.md
new file mode 100644
index 0000000..a1e2124
--- /dev/null
+++ b/SKILL_CATALOG.md
@@ -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` | 为库的公开表面生成参考文档 |
diff --git a/WORKFLOW.en.md b/WORKFLOW.en.md
new file mode 100644
index 0000000..3298665
--- /dev/null
+++ b/WORKFLOW.en.md
@@ -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.
diff --git a/WORKFLOW.md b/WORKFLOW.md
new file mode 100644
index 0000000..7a044bb
--- /dev/null
+++ b/WORKFLOW.md
@@ -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 包内文件。
- 
+ 
