-| 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 & domain | cs-req | Curate / accumulate capability vision docs |
-cs-domain | Maintain requirements/CONTEXT.md glossary + requirements/adrs/ architecture decisions (3-criteria gate + Nygard 4 sections) + single/multi context topology |
-| 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 |
-| Goal | cs-goal | Bounded start/end: write a start report, let AI iterate autonomously, with subagent functional acceptance before completion |
-| 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-code-review | Cross-cutting read-only code review gate before commit; produces {slug}-review.md |
-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-keep | Sink pitfalls / tricks / decisions / exploration into compound/ as plain markdown, searched via grep |
-| Outward docs | cs-doc-tutorial | Outward-facing dev / user guides (task-oriented: how to use X to do Y) |
-cs-doc-api | API reference reverse-engineered from source (entry-by-entry, parts lookup) |
-
+### Recommended main entries
-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.
+| Group | Skill | Purpose |
+|---|---|---|
+| Root | `cs` | Lightweight triage to the right main entry |
+| Onboard | `cs-onboard` | Install CodeStable into a repository |
+| Requirements & domain | `cs-req` / `cs-domain` | Capture capability intent, domain terms, ADRs, and context topology |
+| Epic | `cs-epic` | Large demand planning, review, child feature design, and goal package |
+| Brainstorm | `cs-brainstorm` | Triage fuzzy ideas into feature, epic, or brainstorm notes |
+| Goal | `cs-goal` | Autonomous iteration from a bounded start state to acceptance |
+| Feature | `cs-feat` | End-to-end feature workflow |
+| Issue | `cs-issue` | End-to-end issue workflow |
+| Refactor | `cs-refactor` | Behavior-preserving refactor workflow |
+| Review | `cs-code-review` | Cross-cutting read-only implementation review gate |
+| Audit | `cs-audit` | Scan for bugs, security, performance, maintainability, and architecture drift |
+| Knowledge | `cs-keep` / `cs-note` | Capture durable knowledge or short startup-critical notes |
+| External docs | `cs-docs` | Developer guides, user guides, and API references |
+| Docs hygiene | `cs-docs-neat` | Sync `.codestable/`, README/docs, agent entries, and memory |
+
+### Long-term compatibility entries
+
+Old skill names remain usable but only enter the corresponding main workflow:
+
+- Feature: `cs-feat-design` / `cs-feat-design-review` / `cs-feat-impl` / `cs-feat-qa` / `cs-feat-accept` / `cs-feat-ff`
+- Issue: `cs-issue-report` / `cs-issue-analyze` / `cs-issue-fix`
+- Refactor: `cs-refactor-ff`
+- Docs: `cs-doc-tutorial` / `cs-doc-api`
+- Epic: `cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal`
+
+See [SKILL_CATALOG.en.md](./SKILL_CATALOG.en.md) for the full catalog. In daily use, call `/cs` when you are unsure.
---
## Workflow at a glance
-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.
+CodeStable is layered and event-driven:
```text
-═══════════════════════════════════════════════════════════════════════
- 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/
- optionally release codestable-ai-branch-guard hook
-═══════════════════════════════════════════════════════════════════════
- │
- ▼
-═══════════════════════════════════════════════════════════════════════
- Layer 1 · Long-lived archive ("what the system looks like now")
-───────────────────────────────────────────────────────────────────────
- cs-req ──▶ .codestable/requirements/{slug}.md capability vision
- cs-domain ──▶ .codestable/requirements/CONTEXT.md domain glossary
- .codestable/requirements/adrs/NNN-*.md ADRs (3-criteria gate)
- CONTEXT-MAP.md present → nest per bounded context
-═══════════════════════════════════════════════════════════════════════
- │
- ▼
-═══════════════════════════════════════════════════════════════════════
- 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)
-
- cs-roadmap-review ✦Gate ──▶ independent planning review
- → {slug}-roadmap-review.md
-
- cs-roadmap-impl-goal ──▶ prepare design/checklist/design-review
- for each sub-feature
- → emit ready-to-run /goal prompts
-═══════════════════════════════════════════════════════════════════════
- │
- ▼
-═══════════════════════════════════════════════════════════════════════
- 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-design-review ✦Gate ─▶ │ features │
- cs-feat-impl ─▶ cs-code-review ✦Gate ─▶ │ /YYYY-…/ │
- cs-feat-qa ✦Gate ─▶ cs-feat-accept └──────────┘
-
- cs-feat-ff ──(light lane, skips design/accept)─▶
-
- ▸ Event: fix a defect ┌──────────┐
- cs-issue-report ─▶ cs-issue-analyze ─▶ cs-issue-fix ─▶ │ issues │
- cs-code-review │ /YYYY-…/ │
- └──────────┘
-
- ▸ Event: code rot (beta) ┌──────────┐
- cs-refactor / cs-refactor-ff ─▶ cs-code-review │refactors │
- │ /YYYY-…/ │
- └──────────┘
-
- ▸ Event: bounded goal ┌──────────┐
- cs-goal ──▶ start report ─▶ autonomous impl/verify loop │ goals │
- ─▶ subagent functional acceptance │ /{slug}/ │
- └──────────┘
-═══════════════════════════════════════════════════════════════════════
- │
- ┌───────────────────┴───────────────────┐
- ▼ trigger any time something is reusable ▼ milestone close
-═══════════════════════════════════════════════════════════════════════
- Cross-cut · Knowledge sink & docs cleanup
-───────────────────────────────────────────────────────────────────────
- cs-keep ──▶ .codestable/compound/YYYY-MM-DD-{slug}.md
- plain markdown, no frontmatter, grep to search
- next cs-feat-design / cs-issue-analyze greps it
-
- cs-note ──▶ .codestable/attention.md
-
- cs-docs-neat ──▶ reconcile .codestable/, README/docs,
- CLAUDE.md / AGENTS.md, and agent memory
-═══════════════════════════════════════════════════════════════════════
+cs
+└── cs-onboard
+ ├── cs-req / cs-domain
+ ├── cs-epic # user-facing epic; internally still roadmap storage
+ ├── cs-goal
+ ├── cs-brainstorm
+ ├── cs-feat -> cs-code-review
+ ├── cs-issue -> cs-code-review
+ ├── cs-refactor -> cs-code-review
+ ├── cs-docs
+ └── cs-keep / cs-note / cs-docs-neat
```
-**How to read this diagram:**
+How to read it:
-- **Vertical = layers**, not strict time order; long-lived archives are refreshed repeatedly, while the roadmap layer is entered for large needs.
-- **✦Gate = explicit blocking points**: design-review, code-review, and QA each produce a report; blocking findings route work back to the matching stage.
-- **Layer 3 is event-driven**: new capability goes to feature flow, bugs go to issue flow, rot goes to refactor flow, and bounded outcomes go to goal flow.
-- **Cross-cut is the flywheel**: any flow can sink reusable experience through `cs-keep`; `cs-docs-neat` reconciles docs at milestone boundaries.
+- `cs` only triages to main entries; it no longer routes users to stage skills.
+- `cs-feat`, `cs-issue`, and `cs-refactor` resume from repository facts and stop at human checkpoints.
+- `cs-epic` prepares planning and goal packages; v1 still writes `.codestable/roadmap/`.
+- `cs-code-review` is the cross-cutting gate; `cs-docs-neat` handles hygiene; `cs-docs` writes outward docs.
+- Old stage skills are long-term compatibility entries for historical users.
-See [WORKFLOW.en.md](./WORKFLOW.en.md) for another compact workflow summary.
+See [WORKFLOW.en.md](./WORKFLOW.en.md) for the compact diagram.
---
@@ -402,15 +318,15 @@ your-project/
- `requirements/` is the **long-lived archive** (capability vision + domain glossary CONTEXT.md + decisions adrs/); `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: plain markdown, no frontmatter, searched via `grep -r`.
-- `reference/` is copied in by `cs-onboard`; to change shared conventions, edit the templates under `plugins/codestable/skills/cs-onboard/reference/` so new projects pick them up at onboard time.
+- `.codestable/reference/` is copied in by `cs-onboard` from `plugins/codestable/skills/cs-onboard/references/`; to change shared conventions, edit those skill-package templates so new projects pick them up at onboard time.
### 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.
+> A skill is an independent install unit. At runtime, **each skill can only see files inside its own package**. References like `B-skill/references/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.
-To change shared conventions, edit the templates under `plugins/codestable/skills/cs-onboard/reference/`; new projects pick them up at onboard time. 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 `plugins/codestable/skills/cs-onboard/references/`; new projects pick them up at onboard time. See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full directory model and cross-skill reference constraints.
---
diff --git a/README.md b/README.md
index bb2d83e..9d35974 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
-| 分组 | 技能 | 用途 |
|---|
-| 根入口 | cs | 统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它 |
-| 接入 | cs-onboard | 把 CodeStable 接入到一个新仓库 / 已有零散文档的仓库；释放 reference/、tools/ 和可选的分支保护 hook |
-| 需求 & 领域 | cs-req | 整理 / 沉淀能力愿景 doc |
-cs-domain | 维护 requirements/CONTEXT.md 术语表 + requirements/adrs/ 架构决策（守门 3 判据 + Nygard 四节）+ 单/多 context 拓扑 |
-| 路线图 | cs-roadmap | 承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 / 共享协议）+ 子 feature 拆解清单 |
-cs-roadmap-review | roadmap 人审前的独立规划审查 Gate，支持 Paseo 多 agent 辅助审查，产出 {slug}-roadmap-review.md |
-cs-roadmap-impl-goal | 大需求端到端编排：roadmap → review → 用户确认 → 逐 feature design/checklist/design-review → 输出可粘贴的 /goal 指令 |
-| 讨论入口 | cs-brainstorm | 想法模糊时的统一讨论入口，做分诊：直接 design / 进 feature 写 brainstorm.md / 移交 roadmap |
-| 目标 | cs-goal | 限定起点/终点，写起点报告后让 AI 自主迭代实现/验证，完成前用 subagent 做功能验收 |
-| 特性流程 | cs-feat | 新特性子流程入口，按已有产物自动路由到对应阶段 |
-cs-feat-design | 起草 {slug}-design.md + {slug}-checklist.yaml 作为后续唯一输入 |
-cs-feat-design-review ✦Gate | design 人审前的独立方案审查，支持 Paseo 多 agent，产出 {slug}-design-review.md |
-cs-feat-impl | 按 checklist 推进写代码；也处理 review-fix 和 qa-fix 回流 |
-cs-code-review ✦Gate | 任何流程实现后、commit 前的横切只读代码审查，产出 {slug}-review.md；blocking 时回到 impl |
-cs-feat-qa ✦Gate | 代码审查通过后的本地 QA 验证，产出 {slug}-qa.md；失败时回到 impl 的 qa-fix |
-cs-feat-accept | 对照 design 核实现 + review/QA 报告做验收闭环，回写 requirement / roadmap |
-cs-feat-ff | 超轻量通道：不写 design、不分阶段，让 AI 直接做 |
-| 问题流程 | cs-issue | 问题修复子流程入口 |
-cs-issue-report | 把脑子里的问题落成可复现、可追溯的 report |
-cs-issue-analyze | 找根因、评估修复风险、给方案 |
-cs-issue-fix | 定点修复 + 验证 + 写 fix-note |
-| 重构流程 | cs-refactor | (beta) 重构主流程：scan → design → apply，每步人工放行 |
-cs-refactor-ff | (beta) 轻量重构通道：识别 1-3 条低风险优化，一次确认，原地改 |
-| 审计 | cs-audit | 主动扫描代码：bug 隐患 / 安全漏洞 / 性能问题 / 架构偏离，产出批量发现清单 |
-| 知识沉淀 | cs-keep | 坑点 / 技巧 / 决策 / 调研沉淀到 compound/，纯 markdown，grep 检索 |
-cs-note | 碎片化项目约定（编译 flag / 路径陷阱 / 命令别名）追加到 attention.md |
-| 文档整理 | cs-docs-neat | 阶段/里程碑收尾时同步 .codestable/、README/docs、CLAUDE.md / AGENTS.md 和 agent 记忆，防止文档与代码脱节 |
-| 对外文档 | cs-doc-tutorial | 对外的开发者指南 / 用户指南（任务导向，怎么用 X 做 Y） |
-cs-doc-api | 从源码反推的 API 参考（逐条目，给读者查零件） |
-
+### 推荐主入口
-完整技能目录见 [SKILL_CATALOG.md](./SKILL_CATALOG.md)。日常不知道用哪个时直接调用 `/cs`，它会按诉求路由到对应技能。
+| 分组 | 技能 | 用途 |
+|---|---|---|
+| 根入口 | `cs` | 不知道用哪个时轻量分诊到主入口 |
+| 接入 | `cs-onboard` | 把 CodeStable 接入新仓库或已有零散文档仓库 |
+| 需求 & 领域 | `cs-req` / `cs-domain` | 沉淀能力愿景、领域术语、ADR 和 context 拓扑 |
+| Epic | `cs-epic` | 大需求端到端：规划、review、子 feature design、goal 包 |
+| 讨论入口 | `cs-brainstorm` | 想法模糊时分诊到 feature、epic 或 brainstorm note |
+| 目标 | `cs-goal` | 限定起点/终点后自主迭代到验收 |
+| 特性流程 | `cs-feat` | 新特性端到端：design、review、impl、code review、QA、accept |
+| 问题流程 | `cs-issue` | 问题修复端到端：report、analyze、fix、review |
+| 重构流程 | `cs-refactor` | 行为等价重构，含标准模式和 fastforward mode |
+| 横切审查 | `cs-code-review` | 实现完成后、commit 前的只读代码审查 gate |
+| 审计 | `cs-audit` | 主动扫描 bug、安全、性能、可维护性和架构偏离 |
+| 知识沉淀 | `cs-keep` / `cs-note` | 沉淀 compound 知识或短项目注意事项 |
+| 对外文档 | `cs-docs` | 写开发者指南、用户指南、API 参考 |
+| 文档收尾 | `cs-docs-neat` | 同步 `.codestable/`、README/docs、agent 入口和记忆 |
+
+### 长期兼容入口
+
+旧技能名继续可用，但只转入对应主入口，不维护独立规则：
+
+- Feature：`cs-feat-design` / `cs-feat-design-review` / `cs-feat-impl` / `cs-feat-qa` / `cs-feat-accept` / `cs-feat-ff`
+- Issue：`cs-issue-report` / `cs-issue-analyze` / `cs-issue-fix`
+- Refactor：`cs-refactor-ff`
+- Docs：`cs-doc-tutorial` / `cs-doc-api`
+- Epic：`cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal`
+
+完整技能目录见 [SKILL_CATALOG.md](./SKILL_CATALOG.md)。日常不知道用哪个时直接调用 `/cs`。
---
## 工作流示意
-CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的：根入口路由、onboard、长效档案、roadmap 规划、feature / issue / refactor 执行流，以及横切的知识沉淀。
+CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的：
```text
-═══════════════════════════════════════════════════════════════════════
- 根入口 · 路由 （任何时刻都可以调用）
-───────────────────────────────────────────────────────────────────────
- cs ──▶ 介绍体系 / 把开放式诉求路由到下面任一具体子技能
- （本身不做事，只做分诊和提示）
-═══════════════════════════════════════════════════════════════════════
- │
- ┌───────────────┼───────────────┐
- ▼ ▼ ▼
- （未接入） （已接入） （想了解体系）
- 走阶段 0 直达 1~4 层 / 横切 给速读
- │
- ▼
-═══════════════════════════════════════════════════════════════════════
- 阶段 0 · 接入 （只在新项目跑一次）
-───────────────────────────────────────────────────────────────────────
- cs-onboard ──▶ 生成 .codestable/ 骨架 + 释放 reference/、tools/
- 可选：释放 codestable-ai-branch-guard hook（强制走 worktree）
-═══════════════════════════════════════════════════════════════════════
- │
- ▼
-═══════════════════════════════════════════════════════════════════════
- 第 1 层 · 长效档案（"系统现在长什么样"，只记现状）
-───────────────────────────────────────────────────────────────────────
- cs-req ──▶ .codestable/requirements/{slug}.md 能力愿景
- cs-domain ──▶ .codestable/requirements/CONTEXT.md 领域术语
- .codestable/requirements/adrs/NNN-*.md 架构决策（守门 3 判据）
-═══════════════════════════════════════════════════════════════════════
- │
- ▼
-═══════════════════════════════════════════════════════════════════════
- 第 2 层 · 规划（"接下来打算怎么做这块大需求"，大需求才需要）
-───────────────────────────────────────────────────────────────────────
- cs-roadmap ──▶ .codestable/roadmap/{slug}/
- ① 概设 —— 拆成哪几个模块 / 组件
- ② 架构层详设 —— 接口契约 / 共享协议
- ③ 子 feature —— 多条可执行的 feature 清单
-
- cs-roadmap-review ✦Gate ──▶ 独立规划审查 → {slug}-roadmap-review.md
- 支持 Paseo 多 agent；不通过不能推进实现
-
- cs-roadmap-impl-goal ──▶ 为每个子 feature 完成 design/checklist/design-review
- → 输出可直接粘贴的 /goal 指令
-═══════════════════════════════════════════════════════════════════════
- │
- ▼
-═══════════════════════════════════════════════════════════════════════
- 讨论入口（可选 · 想法模糊时进入，做分诊后路由到下游）
-───────────────────────────────────────────────────────────────────────
- ┌── case 1 已经够清楚 ──▶ cs-feat-design
- cs-brainstorm ────────▶┼── case 2 小需求方向定 ─▶ feature 流（落 brainstorm.md）
- └── case 3 大需求只有一个词 ─▶ cs-roadmap
-═══════════════════════════════════════════════════════════════════════
- │
- ▼
-═══════════════════════════════════════════════════════════════════════
- 第 3 层 · 执行流程（按事件类型选一条进入）
-───────────────────────────────────────────────────────────────────────
-
- ▸ 事件：新增能力 ┌──────────────┐
- │ features/ │
- cs-feat-design │ YYYY-MM-DD- │
- │ │ {slug}/ │
- ▼ │ │
- cs-feat-design-review ✦Gate ── 不通过回 design │ -design.md │
- │ 通过 │ -checklist. │
- ▼ │ yaml │
- cs-feat-impl │ -review.md │
- │ │ -qa.md │
- ▼ │ -acceptance │
- cs-code-review ✦Gate ────── blocking 回 impl │ .md │
- │ 通过 └──────────────┘
- ▼
- cs-feat-qa ✦Gate ────────── 失败回 impl
- │ 通过
- ▼
- cs-feat-accept
-
- cs-feat-ff ──(轻量直通车，跳过 design/gate，直接 impl → review)──▶
-
- ▸ 事件：修复缺陷 ┌──────────────┐
- cs-issue-report ─▶ cs-issue-analyze ─▶ cs-issue-fix │ issues/ │
- ─▶ cs-code-review ✦Gate │
- └──────────────┘
-
- ▸ 事件：代码腐化（beta） ┌──────────────┐
- cs-refactor / cs-refactor-ff ─▶ cs-code-review ✦Gate│ refactors/ │
- └──────────────┘
-
- ▸ 事件：目标驱动 ┌──────────────┐
- cs-goal ──▶ grill 起点报告 ─▶ 自主 impl/验证/迭代 │ goals/ │
- ─▶ subagent 功能验收 └──────────────┘
-═══════════════════════════════════════════════════════════════════════
- │
- ┌───────────────────┴───────────────────┐
- ▼ 任意阶段觉得"这个值得记下来"都能触发 ▼ 阶段/里程碑结束触发
-═══════════════════════════════════════════════════════════════════════
- 横切层 · 知识沉淀 & 文档整理
-───────────────────────────────────────────────────────────────────────
- cs-keep ──▶ .codestable/compound/YYYY-MM-DD-{slug}.md
- 纯 markdown，无 frontmatter，grep 检索
- 下一次 cs-feat-design / cs-issue-analyze 会回头 grep 复用
-
- cs-note ──▶ .codestable/attention.md（碎片约定：flag / 路径 / 别名）
-
- cs-docs-neat ──▶ 同步 .codestable/、README/docs、CLAUDE.md / AGENTS.md
- 防止文档与代码脱节
-═══════════════════════════════════════════════════════════════════════
+cs
+└── cs-onboard
+ ├── cs-req / cs-domain
+ ├── cs-epic # 用户侧大需求入口，内部暂用 roadmap 存储
+ ├── cs-goal
+ ├── cs-brainstorm
+ ├── cs-feat -> cs-code-review
+ ├── cs-issue -> cs-code-review
+ ├── cs-refactor -> cs-code-review
+ ├── cs-docs
+ └── cs-keep / cs-note / cs-docs-neat
```
**怎么读这张图：**
-- **纵向是层次**，不是严格的时间顺序——长效档案层会反复被刷新，规划层只在大需求时进入。
-- **✦Gate 是显式阻断点**：design-review / code-review / qa 三道 Gate 各自产出报告，有 blocking 发现时流程不能向前，必须回到对应 impl 修复后重新过 Gate。
-- **第 3 层是事件入口**：来了新需求走 feature 流，发现 bug 走 issue 流，发现腐化走 refactor 流，目标驱动走 goal 流。
-- **横切层是飞轮**：任何流程跑完发现"这事值得记下来"都可以触发 `cs-keep` 沉淀，沉淀的产物又会被下一次同类工作读到；`cs-docs-neat` 在里程碑收尾时统一整理文档防止漂移。
+- `cs` 只做轻量分诊到主入口，不再把用户导向阶段技能。
+- `cs-feat` / `cs-issue` / `cs-refactor` 是连续编排入口，会按仓库事实恢复阶段，并在 design、review、QA、accept 等 checkpoint 停下等用户确认。
+- `cs-epic` 负责大需求规划和 goal 执行包；第一版内部仍使用 `.codestable/roadmap/`，不批量迁移历史产物。
+- `cs-code-review` 是横切 gate；`cs-docs-neat` 是阶段收尾整理器；`cs-docs` 只写对外指南和 API 参考。
+- 旧阶段技能是长期兼容入口，历史用户可以继续调用，但新文档和新提示词应使用主入口。
完整示意图另见 [WORKFLOW.md](./WORKFLOW.md)。
@@ -360,7 +261,7 @@ CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**
│ │ ├── adrs/
│ │ └── {capability}.md
│ │
-│ ├── roadmap/ # 路线图（"接下来打算怎么走"）
+│ ├── roadmap/ # Epic 内部规划层（历史路径暂不迁移）
│ │ └── {slug}/
│ │ ├── {slug}-roadmap.md # 主文档：背景 / 拆解 / 排期
│ │ ├── {slug}-items.yaml # 机器可读子 feature 清单，acceptance 回写状态
@@ -377,12 +278,12 @@ CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**
│ ├── features/ # 特性流程聚合根
│ │ └── YYYY-MM-DD-{slug}/ # 一个 feature 一个目录
│ │ ├── {slug}-brainstorm.md # 可选（cs-brainstorm 产出）
-│ │ ├── {slug}-design.md # 方案（cs-feat-design）
+│ │ ├── {slug}-design.md # 方案（cs-feat design 阶段）
│ │ ├── {slug}-checklist.yaml # 推进清单（impl 跑、accept 回写）
│ │ ├── {slug}-design-review.md # 人审前方案审查
│ │ ├── {slug}-review.md # 实现后代码审查
│ │ ├── {slug}-qa.md # 代码审查后 QA gate
-│ │ └── {slug}-acceptance.md # 验收报告（cs-feat-accept）
+│ │ └── {slug}-acceptance.md # 验收报告（cs-feat acceptance 阶段）
│ │
│ ├── issues/ # 问题流程聚合根
│ │ └── YYYY-MM-DD-{slug}/
@@ -419,15 +320,15 @@ CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**
- `requirements/` 是**长效档案**（能力愿景 + 领域术语 CONTEXT.md + 拍板决策 adrs/），`roadmap/` 是**规划层**（接下来怎么走），两者刻意分开。
- `features/` `issues/` `refactors/` 用 `YYYY-MM-DD-{slug}/` 一个目录装齐所有相关 spec，不交叉。
- `compound/` 是**唯一**的知识沉淀目录，纯 markdown 无 frontmatter，靠 `grep -r` 检索——好写好搜。
-- `reference/` 是 `cs-onboard` 从技能包复制过来的；要改共享口径，改 `plugins/codestable/skills/cs-onboard/reference/` 模板，新项目 onboard 自动带上新版。
+- `.codestable/reference/` 是 `cs-onboard` 从技能包 `plugins/codestable/skills/cs-onboard/references/` 复制过来的；要改共享口径，改 skill 包内模板，新项目 onboard 自动带上新版。
### 硬约束
-> Skill 是独立安装单元，运行时**每个 skill 只能看到自己包内的文件**。A 技能的 SKILL.md 里写 `B-skill/reference/xxx.md` 这种引用在运行时**根本读不到**。
+> 普通阶段规则不要从一个 skill 直接引用另一个 skill 的深层 `references/xxx.md`。阶段厚规则应放在主入口自己的 `references/` 下，或由 `cs-onboard` 释放到项目 `.codestable/reference/`。
>
-> 跨 skill 共享的参考文档必须走"工作项目"这一层：由 `cs-onboard` 从技能包复制到项目的 `.codestable/reference/`，其他 skill 用项目相对路径读取。
+> 兼容入口是唯一例外：它只读取同级主入口的 `SKILL.md` 进入主协议，不直接读取主入口的深层 reference。
-要改共享口径，改 `plugins/codestable/skills/cs-onboard/reference/` 下的模板，新项目 onboard 时带上新版本。
+要改共享口径，改 `plugins/codestable/skills/cs-onboard/references/` 下的模板，新项目 onboard 时带上新版本。
完整目录说明和跨 skill 引用约束见 [WORKFLOW.md](./WORKFLOW.md)。
diff --git a/SKILL_CATALOG.en.md b/SKILL_CATALOG.en.md
index 6d93286..1d81d29 100644
--- a/SKILL_CATALOG.en.md
+++ b/SKILL_CATALOG.en.md
@@ -1,33 +1,36 @@
# CodeStable Skill Catalog
+Main entries accept optional stage / mode arguments (for example `/cs-feat qa`, `/cs-refactor ff`, `/cs-docs api auth-endpoints`). Arguments are only intent hints; repository facts always win.
+
+## Recommended Main Entries
+
| 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 domain | `cs-req` | Curate and accumulate raw requirement docs |
-| Requirement and domain | `cs-domain` | Maintain the domain model: `.codestable/requirements/CONTEXT.md` glossary + `adrs/` decision records + single/multi-context topology |
-| Roadmap | `cs-roadmap` | Plan big work up front: high-level design, interface contracts, sub-feature breakdown |
-| Roadmap | `cs-roadmap-review` | Independent planning review gate before human roadmap approval |
-| Roadmap | `cs-roadmap-impl-goal` | Turn an approved roadmap into a runnable goal that executes impl / review / QA / accept per feature |
-| Goal-driven | `cs-goal` | Goal-driven autonomous iteration: given a start point and desired end state, iterate until accepted; artifacts land in `.codestable/goals/` |
-| 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-design-review` | Independent feature design review gate before human approval |
-| Feature flow | `cs-feat-impl` | Code in the order the design lays out |
-| Feature flow | `cs-code-review` | Read-only code review gate after implementation |
-| Feature flow | `cs-feat-qa` | QA verification gate after code review; optional independent runner |
-| Feature flow | `cs-feat-accept` | Verify implementation and close the loop; optional read-only auditor |
-| 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-keep` | Sink freshly found pitfalls, tricks, decisions, and research into `.codestable/compound/` as plain markdown, retrieved via grep |
-| Knowledge sink | `cs-note` | Append one-line startup notes to `.codestable/attention.md` |
-| Explore and docs | `cs-audit` | Audit code for bug, security, performance, maintainability, and architecture risks |
-| Explore and docs | `cs-doc-tutorial` | Write outward-facing developer guides |
-| Explore and docs | `cs-doc-api` | Generate reference docs for public library surfaces |
-| Explore and docs | `cs-docs-neat` | Reconcile `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory at phase close |
+| Root | `cs` | Lightweight triage to the right main entry |
+| Onboarding | `cs-onboard` | Install CodeStable into a new or previously informal repository |
+| Requirements and domain | `cs-req` | Capture capability intent documents |
+| Requirements and domain | `cs-domain` | Maintain domain terms, ADRs, and context topology |
+| Epic | `cs-epic` | Large-demand entry: planning, review, child feature design, goal package |
+| Goal | `cs-goal` | Autonomous iteration from a defined start state to accepted end state |
+| Brainstorm | `cs-brainstorm` | Triage unclear ideas into feature, epic, or brainstorm notes |
+| Feature flow | `cs-feat` | End-to-end feature entry: design, review, impl, code review, QA, accept |
+| Issue flow | `cs-issue` | End-to-end issue entry: report, analyze, fix, review |
+| Refactor flow | `cs-refactor` | Behavior-preserving refactor entry with standard and fastforward modes |
+| Cross-cutting review | `cs-code-review` | Read-only implementation review gate |
+| Audit | `cs-audit` | Scan for bugs, security, performance, maintainability, and architecture drift |
+| Knowledge | `cs-keep` | Capture lessons, tricks, decisions, and research in `.codestable/compound/` |
+| Knowledge | `cs-note` | Append short startup-critical notes to `.codestable/attention.md` |
+| External docs | `cs-docs` | Write or update developer guides, user guides, and API references |
+| Docs hygiene | `cs-docs-neat` | Sync `.codestable/`, README/docs, agent entry files, and memory |
+
+## Long-Term Compatibility Entries
+
+These skill names remain usable, but they only enter the corresponding main workflow and do not maintain independent rules.
+
+| Compatibility group | Skills | Enters |
+|---|---|---|
+| Feature | `cs-feat-design`, `cs-feat-design-review`, `cs-feat-impl`, `cs-feat-qa`, `cs-feat-accept`, `cs-feat-ff` | Matching `cs-feat` stage or mode |
+| Issue | `cs-issue-report`, `cs-issue-analyze`, `cs-issue-fix` | Matching `cs-issue` stage |
+| Refactor | `cs-refactor-ff` | `cs-refactor` fastforward mode |
+| Docs | `cs-doc-tutorial`, `cs-doc-api` | `cs-docs` tutorial / api mode |
+| Epic | `cs-roadmap`, `cs-roadmap-review`, `cs-roadmap-impl-goal` | `cs-epic` planning / review / goal-package stage |
diff --git a/SKILL_CATALOG.md b/SKILL_CATALOG.md
index d32344c..cb19c29 100644
--- a/SKILL_CATALOG.md
+++ b/SKILL_CATALOG.md
@@ -1,33 +1,36 @@
# CodeStable 技能目录
+主入口调用时可带阶段 / 模式参数（如 `/cs-feat qa`、`/cs-refactor ff`、`/cs-docs api 认证接口`）。参数只是意图提示，仓库事实始终优先。
+
+## 推荐主入口
+
| 分组 | 技能 | 用途 |
|---|---|---|
-| 根入口 | `cs` | 统一入口，介绍体系并把开放式诉求路由到正确的 `cs-*` 子技能 |
-| 接入 | `cs-onboard` | 把 CodeStable 接入到一个新仓库或已有零散文档的仓库 |
-| 需求与领域 | `cs-req` | 整理和沉淀原始需求文档 |
-| 需求与领域 | `cs-domain` | 维护领域模型：`.codestable/requirements/CONTEXT.md` 术语表 + `adrs/` 决策记录 + 单/多 context 拓扑 |
-| 路线图 | `cs-roadmap` | 为大需求做事前规划：概设、接口契约、子 feature 拆解 |
-| 路线图 | `cs-roadmap-review` | roadmap 人工确认前的独立规划审查 gate |
-| 路线图 | `cs-roadmap-impl-goal` | 把已确认 roadmap 编排成可直接运行的 goal，逐个 feature 执行 impl / review / QA / accept |
-| 目标驱动 | `cs-goal` | 目标驱动的自主迭代：给定起点与期望终态，自动迭代到验收通过，产物落 `.codestable/goals/` |
-| 讨论入口 | `cs-brainstorm` | 想法模糊时分诊：直接 design、进入 feature brainstorm，或移交 roadmap |
-| 特性流程 | `cs-feat` | 新特性子流程入口 |
-| 特性流程 | `cs-feat-design` | 起草 `{slug}-design.md` 作为后续唯一输入 |
-| 特性流程 | `cs-feat-design-review` | feature design 人工确认前的独立方案审查 gate |
-| 特性流程 | `cs-feat-impl` | 按 design 的推进顺序写代码 |
-| 特性流程 | `cs-code-review` | 实现完成后的只读代码审查 gate |
-| 特性流程 | `cs-feat-qa` | 代码审查通过后的 QA 验证 gate，可用独立 runner 辅助 |
-| 特性流程 | `cs-feat-accept` | 对照 design 核对实现并完成验收闭环，可用只读 auditor 复核 |
-| 特性流程 | `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-keep` | 把刚发现的坑、技巧、决策、调研统一沉淀到 `.codestable/compound/`，纯 markdown，靠 grep 检索 |
-| 知识沉淀 | `cs-note` | 把一两行启动必读的项目注意事项追加到 `.codestable/attention.md` |
-| 探索与文档 | `cs-audit` | 主动审计代码中的 bug 隐患、安全、性能、可维护性和架构偏离 |
-| 探索与文档 | `cs-doc-tutorial` | 编写对外开发者指南 |
-| 探索与文档 | `cs-doc-api` | 为库的公开表面生成参考文档 |
-| 探索与文档 | `cs-docs-neat` | 阶段收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 |
+| 根入口 | `cs` | 轻量分诊，只把开放式诉求路由到主入口 |
+| 接入 | `cs-onboard` | 把 CodeStable 接入新仓库或已有零散文档仓库 |
+| 需求与领域 | `cs-req` | 整理和沉淀能力愿景文档 |
+| 需求与领域 | `cs-domain` | 维护领域模型、术语表、ADR 和多 context 拓扑 |
+| Epic | `cs-epic` | 大需求端到端入口：规划、review、子 feature design、goal 包 |
+| 目标驱动 | `cs-goal` | 给定起点与期望终态后自主迭代到验收 |
+| 讨论入口 | `cs-brainstorm` | 想法模糊时分诊到 feature、epic 或 brainstorm note |
+| 特性流程 | `cs-feat` | 新特性端到端入口：design、review、impl、code review、QA、accept |
+| 问题流程 | `cs-issue` | 问题修复端到端入口：report、analyze、fix、review |
+| 重构流程 | `cs-refactor` | 行为等价重构入口：标准模式或 fastforward mode |
+| 横切审查 | `cs-code-review` | 实现完成后的只读代码审查 gate |
+| 审计 | `cs-audit` | 主动扫描 bug、安全、性能、可维护性和架构偏离 |
+| 知识沉淀 | `cs-keep` | 把坑点、技巧、决策、调研沉淀到 `.codestable/compound/` |
+| 知识沉淀 | `cs-note` | 把一两行启动必读项目注意事项追加到 `.codestable/attention.md` |
+| 对外文档 | `cs-docs` | 写或更新开发者指南、用户指南、API 参考 |
+| 文档收尾 | `cs-docs-neat` | 阶段收尾时同步 `.codestable/`、README/docs、agent 入口和记忆 |
+
+## 长期兼容入口
+
+这些技能名继续可用，但只转入对应主入口，不维护独立流程规则。
+
+| 兼容组 | 技能 | 转入 |
+|---|---|---|
+| Feature | `cs-feat-design`, `cs-feat-design-review`, `cs-feat-impl`, `cs-feat-qa`, `cs-feat-accept`, `cs-feat-ff` | `cs-feat` 的对应阶段或模式 |
+| Issue | `cs-issue-report`, `cs-issue-analyze`, `cs-issue-fix` | `cs-issue` 的对应阶段 |
+| Refactor | `cs-refactor-ff` | `cs-refactor` 的 fastforward mode |
+| Docs | `cs-doc-tutorial`, `cs-doc-api` | `cs-docs` 的 tutorial / api mode |
+| Epic | `cs-roadmap`, `cs-roadmap-review`, `cs-roadmap-impl-goal` | `cs-epic` 的 planning / review / goal-package 阶段 |
diff --git a/WORKFLOW.en.md b/WORKFLOW.en.md
index daeb309..1c7b3f2 100644
--- a/WORKFLOW.en.md
+++ b/WORKFLOW.en.md
@@ -2,33 +2,45 @@
## Workflow Layers
-CodeStable skills are layered and event-driven:
+CodeStable is layered and event-driven. Daily use should start from main entries, not stage skill names:
```text
cs
└── cs-onboard
├── cs-req / cs-domain
- ├── cs-roadmap
- │ ├── cs-roadmap-review
- │ └── cs-roadmap-impl-goal
+ ├── cs-epic
+ │ └── internally uses the roadmap storage model and goal package
├── cs-goal
- ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-code-review -> cs-feat-qa -> cs-feat-accept
- ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix -> cs-code-review
- ├── cs-refactor / cs-refactor-ff -> cs-code-review
+ ├── cs-brainstorm
+ ├── cs-feat -> cs-code-review
+ ├── cs-issue -> cs-code-review
+ ├── cs-refactor -> cs-code-review
+ ├── cs-docs
└── cs-keep / cs-note / cs-docs-neat
```
-Vertical means layers, not strict time order. Long-lived archives are refreshed repeatedly; the roadmap layer is entered for large needs, and `cs-goal` is the goal-driven autonomous iteration entry that, given a start point and desired end state, iterates until accepted. Execution is event-driven: new capability goes to feature flow, bugs go to issue flow, and code rot goes to refactor flow; `cs-code-review` is the cross-cutting code review gate that all of feature / issue / refactor pass through to produce `{slug}-review.md`. The cross-cut layer is the knowledge flywheel: any flow sinks reusable experience into compound via `cs-keep`.
-`cs-docs-neat` is the phase-close cleanup skill: it reconciles `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory without adding a new archive document type.
+The vertical layout is layering, not strict time order. Long-lived records are refreshed repeatedly; `cs-epic` is only for large demands and still writes `.codestable/roadmap/` in the first version; `cs-goal` is the autonomous goal workflow.
+
+The event entries are `cs-feat` for new capability, `cs-issue` for bugs, `cs-refactor` for behavior-preserving cleanup, and `cs-docs` for outward documentation. `cs-code-review` remains the cross-cutting implementation review gate.
+
+The knowledge loop remains cross-cutting: any workflow can use `cs-keep`; milestone cleanup uses `cs-docs-neat` to sync `.codestable/`, README/docs, agent entry files, and memory.
+
+Old stage skills remain long-term compatibility entries:
+
+- Feature: `cs-feat-design` / `cs-feat-design-review` / `cs-feat-impl` / `cs-feat-qa` / `cs-feat-accept` / `cs-feat-ff`
+- Issue: `cs-issue-report` / `cs-issue-analyze` / `cs-issue-fix`
+- Refactor: `cs-refactor-ff`
+- Docs: `cs-doc-tutorial` / `cs-doc-api`
+- Epic: `cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal`
## Runtime Structure
-After `/cs-onboard`, the project root gets `.codestable/`:
+After `/cs-onboard`, the project root contains `.codestable/`:
```text
.codestable/
-├── requirements/ # requirement docs + domain model: CONTEXT.md glossary + adrs/ ADRs
-├── roadmap/
+├── requirements/ # requirements + domain model
+├── roadmap/ # internal storage model for epic
├── goals/
├── features/
├── issues/
@@ -42,8 +54,8 @@ After `/cs-onboard`, the project root gets `.codestable/`:
Key constraints:
-- `requirements/` is a long-lived archive of current state: it holds requirement/capability docs as well as the cs-domain domain model — the `CONTEXT.md` glossary and `adrs/` decision records (split into `CONTEXT-MAP.md` plus per-context subdirectories under multi-context).
-- `roadmap/` is the planning layer for large needs; `goals/` holds cs-goal start / iteration / acceptance artifacts.
-- `features/`, `issues/`, and `refactors/` use `YYYY-MM-DD-{slug}/` to group one workflow run; `audits/` and `brainstorms/` likewise hold audit and brainstorm artifacts.
-- `compound/` is the single knowledge sink; `cs-keep` writes pitfalls / tricks / decisions / research there as plain markdown files retrieved via grep.
-- `reference/` is released by `cs-onboard`; cross-skill shared docs must go through project-local `.codestable/reference/`, not direct references to another skill package.
+- `requirements/` stores long-lived current-state facts and the domain model.
+- `roadmap/` remains the internal planning layer used by `cs-epic`; user-facing docs call it epic, but historical paths/doc_type are not migrated yet.
+- `features/`, `issues/`, and `refactors/` use `YYYY-MM-DD-{slug}/` directories.
+- `compound/` is the only knowledge compounding directory, written by `cs-keep`.
+- `reference/` is released by `cs-onboard`; shared workflow conventions are read from project-local `.codestable/reference/`.
diff --git a/WORKFLOW.md b/WORKFLOW.md
index 9d1d1c2..b6fe04e 100644
--- a/WORKFLOW.md
+++ b/WORKFLOW.md
@@ -2,24 +2,36 @@
## 工作流层次
-CodeStable 的技能是分层 + 事件驱动的：
+CodeStable 的技能是分层 + 事件驱动的。日常使用主入口，不需要记阶段技能名：
```text
cs
└── cs-onboard
├── cs-req / cs-domain
- ├── cs-roadmap
- │ ├── cs-roadmap-review
- │ └── cs-roadmap-impl-goal
+ ├── cs-epic
+ │ └── 内部使用 roadmap 存储模型和 goal 执行包
├── cs-goal
- ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-code-review -> cs-feat-qa -> cs-feat-accept
- ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix -> cs-code-review
- ├── cs-refactor / cs-refactor-ff -> cs-code-review
+ ├── cs-brainstorm
+ ├── cs-feat -> cs-code-review
+ ├── cs-issue -> cs-code-review
+ ├── cs-refactor -> cs-code-review
+ ├── cs-docs
└── cs-keep / cs-note / cs-docs-neat
```
-纵向是层次，不是严格时间顺序。长效档案层会反复刷新，规划层只在大需求时进入；`cs-goal` 是目标驱动的自主迭代入口，给定起点与期望终态后自动迭代到验收。第 3 层是事件入口：新需求走 feature，bug 走 issue，腐化走 refactor；`cs-code-review` 是横切代码审查 gate，feature / issue / refactor 链路都经它产 `{slug}-review.md`。横切层是知识飞轮：任何流程都可以把值得复用的经验经 `cs-keep` 沉淀到 compound。
-`cs-docs-neat` 是阶段收尾整理器，负责同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，不新增沉淀文档类型。
+纵向是层次，不是严格时间顺序。长效档案层会反复刷新；`cs-epic` 只在大需求时进入，第一版内部仍写 `.codestable/roadmap/`；`cs-goal` 是目标驱动自主迭代入口。
+
+第 3 层是事件入口：新需求走 `cs-feat`，bug 走 `cs-issue`，腐化走 `cs-refactor`，对外文档走 `cs-docs`。`cs-code-review` 是横切代码审查 gate，feature / issue / refactor 链路都经它产 `{slug}-review.md`。
+
+横切层是知识飞轮：任何流程都可以把值得复用的经验经 `cs-keep` 沉淀到 compound；`cs-docs-neat` 在里程碑收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆。
+
+旧阶段技能仍是长期兼容入口，但不再作为主路径展示：
+
+- Feature：`cs-feat-design` / `cs-feat-design-review` / `cs-feat-impl` / `cs-feat-qa` / `cs-feat-accept` / `cs-feat-ff`
+- Issue：`cs-issue-report` / `cs-issue-analyze` / `cs-issue-fix`
+- Refactor：`cs-refactor-ff`
+- Docs：`cs-doc-tutorial` / `cs-doc-api`
+- Epic：`cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal`
## 运行时结构
@@ -28,7 +40,7 @@ cs
```text
.codestable/
├── requirements/ # 需求文档 + 领域模型：CONTEXT.md 术语表 + adrs/ ADR
-├── roadmap/
+├── roadmap/ # epic 的内部历史存储模型
├── goals/
├── features/
├── issues/
@@ -42,8 +54,8 @@ cs
关键约束：
-- `requirements/` 是长效档案，记现状：既存需求/能力文档，也存 cs-domain 的领域模型——`CONTEXT.md` 术语表与 `adrs/` 决策记录（多 context 时再拆 `CONTEXT-MAP.md` + 各子 context 子目录）。
-- `roadmap/` 是规划层，描述大需求接下来怎么走；`goals/` 存 cs-goal 的目标启动 / 迭代 / 验收产物。
-- `features/`、`issues/`、`refactors/` 用 `YYYY-MM-DD-{slug}/` 聚合单次流程产物；`audits/`、`brainstorms/` 同理存审计与头脑风暴产物。
-- `compound/` 是唯一知识沉淀目录，由 `cs-keep` 把坑 / 技巧 / 决策 / 调研统一写成纯 markdown 文件，靠 grep 检索。
-- `reference/` 由 `cs-onboard` 释放共享口径；跨 skill 共享文档必须通过项目内 `.codestable/reference/`，不能从一个 skill 直接引用另一个 skill 包内文件。
+- `requirements/` 是长效档案，记现状：既存需求/能力文档，也存 cs-domain 的领域模型。
+- `roadmap/` 是 `cs-epic` 第一版继续复用的内部规划层；用户文档叫 epic，历史路径/doc_type 暂不迁移。
+- `features/`、`issues/`、`refactors/` 用 `YYYY-MM-DD-{slug}/` 聚合单次流程产物。
+- `compound/` 是唯一知识沉淀目录，由 `cs-keep` 写纯 markdown 文件，靠 grep 检索。
+- `reference/` 由 `cs-onboard` 释放共享口径；跨工作流共享约定优先读项目内 `.codestable/reference/`。
diff --git a/plugins/codestable/skills/cs-brainstorm/SKILL.md b/plugins/codestable/skills/cs-brainstorm/SKILL.md
index 3ee0818..fcb1102 100644
--- a/plugins/codestable/skills/cs-brainstorm/SKILL.md
+++ b/plugins/codestable/skills/cs-brainstorm/SKILL.md
@@ -23,10 +23,10 @@ brainstorm 是"讨论层"统一入口。
| case | 规模 | 用户状态 | 产物 |
|---|---|---|---|
-| **case 1：已经够清楚** | 不限 | 一句话能说清做什么 / 为谁 / 怎么算成功 / 不做什么 | 不落盘，直接 `cs-feat-design` |
-| **case 2：小需求** | 单 feature | 知道要解决什么问题，对解法 / 边界还摇摆 | `.codestable/features/{feature}/{slug}-brainstorm.md` → `cs-feat-design` |
-| **case 3：大需求，拆解 ready** | 多 feature | 心里已有大致模块划分，想直接做拆解和接口契约 | 不落盘，移交 `cs-roadmap` |
-| **case 4：大需求，想 grill** | 多 feature | 还不想拆——想先 grill、发散、产生想法存着 | `.codestable/brainstorms/{slug}/brainstorm.md` → 之后 `cs-roadmap` 读到 |
+| **case 1：已经够清楚** | 不限 | 一句话能说清做什么 / 为谁 / 怎么算成功 / 不做什么 | 不落盘，直接进 `cs-feat` design 阶段 |
+| **case 2：小需求** | 单 feature | 知道要解决什么问题，对解法 / 边界还摇摆 | `.codestable/features/{feature}/{slug}-brainstorm.md` → `cs-feat` design 阶段 |
+| **case 3：大需求，拆解 ready** | 多 feature | 心里已有大致模块划分，想直接做拆解和接口契约 | 不落盘，移交 `cs-epic` |
+| **case 4：大需求，想 grill** | 多 feature | 还不想拆——想先 grill、发散、产生想法存着 | `.codestable/brainstorms/{slug}/brainstorm.md` → 之后 `cs-epic` 读到 |
判错 case 不是灾难——**允许升降级**。case 2 聊着发现范围越聊越大切 case 3/4，case 3 聊着发现需要先 grill 切 case 4，case 4 grill 完可以直接拆切 case 3，当场切换出口。
@@ -114,7 +114,7 @@ brainstorm 是"讨论层"统一入口。
1. **是事实问题不是偏好问题**——某 API 实际行为 / 库是否真支持 / 性能特征是否成立，不是"哪种风格更好"
2. **结果会改变方向**——验出来不管成败，讨论都能收敛
-3. **成本可控**——你判断 5-30 分钟内能搭出能跑的东西。超过这个量该走 `cs-feat-ff` 直接做或拆成正式 feature
+3. **成本可控**——你判断 5-30 分钟内能搭出能跑的东西。超过这个量该走 `cs-feat` fastforward mode 直接做或拆成正式 feature
提议格式：**"这块靠想不准，我做个最小 demo 验一下 {要验的事}，5-10 分钟，OK 吗？"** 用户秒过 / 拒绝即可。
@@ -151,11 +151,11 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑
**信号**：一句话能说出做什么 / 为谁 / 怎么算成功 / 不做什么；聊两句核心行为 / 成功标准都对上。
**处理**：
-1. 告诉用户"这块你已经想清楚了：{AI 一句话复述}。建议直接 `cs-feat-design`——brainstorm 对你没增量"
+1. 告诉用户"这块你已经想清楚了：{AI 一句话复述}。建议直接进 `cs-feat` design 阶段——brainstorm 对你没增量"
2. **看聊过程有没有非琐碎技术决策**——讨论了具体库选型 / Schema / 接口形态 / 跨模块约定，落一份精简 brainstorm（只填"已敲定的设计点"那节）让 design 直接读到不必重讨；纯方向确认没聊技术细节就裸退不落盘
3. 停下来等用户触发 design
-**退出**："直接触发 `cs-feat-design` 从零写 design"（不落盘）；轻量落盘则"下一步 `cs-feat-design` 会读到 `{路径}` 不必重述"
+**退出**："直接触发 `cs-feat` 从零写 design"（不落盘）；轻量落盘则"下一步 `cs-feat` design 阶段会读到 `{路径}` 不必重述"
---
@@ -180,20 +180,20 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑
文档模板见同目录 `reference.md` 的"feature brainstorm 模板"。frontmatter 字段口径跟 design / acceptance 共用一组，看 `shared-conventions.md` 第 1 节。
-**退出**：如果只是轻确认，主动问"这块够清楚了可以进 design 吗？"；如果需要解释方案 / 代价 / 默认后果，先在 feature 目录写 `approval-report.md` 再让 owner 确认。确认后落盘。如果愿景（用户故事 / 痛点 / 边界）已经聊透了，提示用户可以先 `cs-req draft` 把愿景落成 requirement，design 会读到这份 req 做对齐。告诉用户"下一步 `cs-feat-design` 会读到 `{路径}`"
+**退出**：如果只是轻确认，主动问"这块够清楚了可以进 design 吗？"；如果需要解释方案 / 代价 / 默认后果，先在 feature 目录写 `approval-report.md` 再让 owner 确认。确认后落盘。如果愿景（用户故事 / 痛点 / 边界）已经聊透了，提示用户可以先 `cs-req draft` 把愿景落成 requirement，design 会读到这份 req 做对齐。告诉用户"下一步 `cs-feat` design 阶段会读到 `{路径}`"
---
-### case 3：大需求 → roadmap 直接拆
+### case 3：大需求 → epic 直接拆
**信号**：多 feature 规模，用户心里已有大致模块划分，能说出拆法，想直接做拆解和接口契约。
**处理**：
-1. 告诉用户"听起来是多个 feature 的集合，单 feature 装不下。`cs-roadmap` 会做拆解和依赖梳理，我把讨论交给它"
-2. 把已聊的信息汇总让 roadmap 接手不用重来：真问题 / 大致范围 / 已提到的可能子模块（一句话各一）；**聊到的跨模块接口形态、共享协议、技术选型一并列出**——这些是 roadmap "架构层详设"节的种子
-3. **不落盘**——`roadmap new` 自己建目录和主文档
+1. 告诉用户"听起来是多个 feature 的集合，单 feature 装不下。`cs-epic` 会做拆解和依赖梳理，我把讨论交给它"
+2. 把已聊的信息汇总让 epic planning 接手不用重来：真问题 / 大致范围 / 已提到的可能子模块（一句话各一）；**聊到的跨模块接口形态、共享协议、技术选型一并列出**——这些是内部 roadmap 主文档"架构层详设"节的种子
+3. **不落盘**——`cs-epic` planning 自己建目录和主文档
-**退出**："移交给 `cs-roadmap`"（附聊到的要点汇总），不落盘
+**退出**："移交给 `cs-epic` planning 阶段"（附聊到的要点汇总），不落盘
---
@@ -201,16 +201,16 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑
**信号**：多 feature 规模，但用户说不清模块边界、想先发散探索——"帮我问问清楚"、"先把想法理一理存着"、"方向还乱，聊开了再说"。
-这是创意空间，不是设计文档。目标是产生可留存的想法、方向和洞察，供后续 roadmap 消费。
+这是创意空间，不是设计文档。目标是产生可留存的想法、方向和洞察，供后续 epic planning 消费。
**怎么聊**：启动 grill 档（见上节"对话节奏 > grill 档"），同时自由发散——聊方案、聊类比、聊技术可能性、聊限制。对话比 case 2 更开放，不急着收敛。
**升降级**：
-- grill 完感觉够清楚了想直接拆 → case 3，落 brainstorm.md 后移交 roadmap
+- grill 完感觉够清楚了想直接拆 → case 3，落 brainstorm.md 后移交 `cs-epic`
- 聊着发现其实一个 feature 能装下 → case 2
- 聊着发现已经全清楚 → case 1
-**落盘**：用户说"先这样"/"差不多了"/"存一下"，或 AI 判断 grill 已到 3-5 轮上限，主动说"这块我先帮你落到 brainstorms 里，之后 roadmap 会读到"。
+**落盘**：用户说"先这样"/"差不多了"/"存一下"，或 AI 判断 grill 已到 3-5 轮上限，主动说"这块我先帮你落到 brainstorms 里，之后 `cs-epic` 会读到"。
路径：`.codestable/brainstorms/{slug}/`
@@ -227,9 +227,9 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑
- 比 case 2 模板更自由——不要求"选定方向"，允许保留多个倾向
- 不需要"考虑过的方向"那种结构化对比——那是 design 前的事，这里只是创意记录
-**和 roadmap 的衔接**：`cs-roadmap` 启动时会搜 `.codestable/brainstorms/` 看有没有相关 brainstorm。如果有，roadmap 把 brainstorm 当输入材料读，不重复分诊直接拆。
+**和 epic 的衔接**：`cs-epic` planning 阶段启动时会搜 `.codestable/brainstorms/` 看有没有相关 brainstorm。如果有，内部 roadmap 主文档把 brainstorm 当输入材料读，不重复分诊直接拆。
-**退出**：落盘后告诉用户"想法存到 `{路径}` 了，准备好了就触发 `cs-roadmap`，它会读到这份脑暴记录"。如果 grill 过程中愿景（用户故事 / 痛点 / 边界）已经比较清楚了，提示用户可以先 `cs-req draft` 把愿景落成 requirement，后续 roadmap 拆解和 design 都有稳定对齐基准
+**退出**：落盘后告诉用户"想法存到 `{路径}` 了，准备好了就触发 `cs-epic`，它会读到这份脑暴记录"。如果 grill 过程中愿景（用户故事 / 痛点 / 边界）已经比较清楚了，提示用户可以先 `cs-req draft` 把愿景落成 requirement，后续 epic 拆解和 design 都有稳定对齐基准
---
diff --git a/plugins/codestable/skills/cs-brainstorm/reference.md b/plugins/codestable/skills/cs-brainstorm/reference.md
index 41e4a03..25a9bc2 100644
--- a/plugins/codestable/skills/cs-brainstorm/reference.md
+++ b/plugins/codestable/skills/cs-brainstorm/reference.md
@@ -56,7 +56,7 @@ tags: [...]
# {主题名}
-> 创意空间 | {YYYY-MM-DD} | 下一步：cs-roadmap
+> 创意空间 | {YYYY-MM-DD} | 下一步：cs-epic
## 出发点
{什么触发了这个想法 / 想解决什么问题 / 为什么觉得值得做}
diff --git a/plugins/codestable/skills/cs-code-review/SKILL.md b/plugins/codestable/skills/cs-code-review/SKILL.md
index 4485a48..4bf64ba 100644
--- a/plugins/codestable/skills/cs-code-review/SKILL.md
+++ b/plugins/codestable/skills/cs-code-review/SKILL.md
@@ -1,6 +1,7 @@
---
name: cs-code-review
description: Code review gate。触发：实现完成后、QA/验收/commit 前审本轮 diff。
+argument-hint: "[git range 或范围说明，可空]"
---
# cs-code-review
@@ -20,15 +21,19 @@ description: Code review gate。触发：实现完成后、QA/验收/commit 前
| 来源 | 进入点 | spec 产物 | 通过后去向 |
|---|---|---|---|
-| `cs-feat-impl`（标准 feature） | impl 完成、QA 前 | design + checklist | `cs-feat-qa` |
-| `cs-feat-ff`（feature 快速通道） | ff-note 落盘、commit 前 | ff-note + 用户原始需求 | 收尾提交 |
-| `cs-issue-fix` | fix-note 落盘、commit 前 | report + analysis + fix-note | 收尾提交 |
-| `cs-refactor` | apply-notes 完成、commit 前 | scan + refactor-design + checklist | 收尾提交 |
-| `cs-refactor-ff` | 自证通过、commit 前 | 用户确认的重构范围 + 验证命令 | 收尾提交 |
+| `cs-feat` implementation 阶段 | impl 完成、QA 前 | design + checklist | `cs-feat` QA 阶段 |
+| `cs-feat` fastforward mode | ff-note 落盘、commit 前 | ff-note + 用户原始需求 | 收尾提交 |
+| `cs-issue` fix 阶段 | fix-note 落盘、commit 前 | report + analysis + fix-note | 收尾提交 |
+| `cs-refactor` standard mode | apply-notes 完成、commit 前 | scan + refactor-design + checklist | 收尾提交 |
+| `cs-refactor` fastforward mode | 自证通过、commit 前 | 用户确认的重构范围 + 验证命令 | 收尾提交 |
| ad-hoc / pre-merge | 用户要求 | 用户指定范围 / git range | 给结论 |
**不是 `cs-audit`**：audit 主动扫一片代码找潜在问题；code review 只审当前变更范围。
+本次调用参数：$ARGUMENTS。非空且不是字面 `$ARGUMENTS` 时，按 ad-hoc 来源处理，参数即用户指定的 git range / 审查范围；仍需按「启动检查」核对范围内确有可归因改动。
+
+ad-hoc 参数如果是 git range（如 `main..HEAD`、`origin/main...HEAD` 或一个 commit/ref），审查范围来自 `git diff {range}`，不要求工作区有未提交 diff。参数如果是文件路径、自然语言范围或 pre-merge 说明，则先解析为明确文件 / diff 来源；解析不清时先问清楚。
+
---
## 输入
@@ -39,7 +44,7 @@ description: Code review gate。触发：实现完成后、QA/验收/commit 前
- 来源的 spec 产物（feature 看 `{slug}-design.md` + `{slug}-checklist.yaml`；issue 看 report+analysis+fix-note；refactor 看 scan+refactor-design+checklist；ff / ad-hoc 看用户确认范围）
- 实现完成汇报 / 最近实现记录（如果在对话里，按对话事实引用；如果已落文件，读文件）
- `git status --short`
-- `git diff`（有 staged diff 时也读 `git diff --cached`）
+- `git diff`（有 staged diff 时也读 `git diff --cached`；ad-hoc git range 读 `git diff {range}`）
- diff 涉及的人写代码文件和相邻关键调用点
- spec 指向的 architecture / requirement / roadmap 相关文档（只读，判断改动是否会影响归并；feature 即 design 第 4 节）
- goal / gate 模式下的 evidence pack、gate results、DoD results；缺失时回 implementation gate 补证据，不现场猜测
@@ -53,9 +58,9 @@ description: Code review gate。触发：实现完成后、QA/验收/commit 前
先按「进入来源」表确认本轮来源，再做对应前置校验：
-1. 来源的 spec 产物存在且已定稿——feature 看 `{slug}-design.md`（`doc_type=feature-design`、`status=approved`、`feature` 与目录一致）+ `{slug}-checklist.yaml`（`steps` 全 `done`）；issue 看 report+analysis+fix-note；refactor 看 scan+refactor-design+checklist；ff / ad-hoc 看用户确认范围。缺定稿 spec 时退回对应实现技能，不硬审。
+1. 来源的 spec 产物存在且已定稿——feature 看 `{slug}-design.md`（`doc_type=feature-design`、`status=approved`、`feature` 与目录一致）+ `{slug}-checklist.yaml`（`steps` 全 `done`）；issue 看 report+analysis+fix-note；refactor 看 scan+refactor-design+checklist；ff 看用户确认范围；ad-hoc 看用户指定范围 / git range。缺定稿 spec 时退回对应实现技能，不硬审。
2. goal / gate 模式下，先读取 `{slug}-evidence-pack.md`、`{slug}-gate-results.json` 和 `{slug}-dod-results.json`；缺失或 gate blocking 未解释时退回 implementation.before_review。
-3. 当前 diff 能看到本轮实现改动；完全没有代码或产物改动时退回来源实现技能。
+3. 流程来源必须在当前 unstaged / staged diff 或本轮提交范围里看到实现改动；ad-hoc git range 必须 `git diff {range}` 非空。ad-hoc range 审查允许工作区干净；非 range 且完全没有可归因改动时退回来源实现技能或请用户补范围。
4. 如果已有 `{slug}-review.md`：
- `status: passed` 且 diff 未变化：提示按表进入「通过后去向」。
- `status: changes-requested` / `blocked`：读取旧 findings，确认是否处于 review-fix 后的复审。
@@ -63,107 +68,11 @@ description: Code review gate。触发：实现完成后、QA/验收/commit 前
---
-## 独立 Task agent reviewer（双环节）
+## 独立 reviewer 编排
-本阶段是**双环节 review**，两个环节互补：
+本阶段必须按 `references/independent-review/protocol.md` 执行双环节 review：环节 A 是独立 Task agent review（gate 必需），环节 B 是 OCR 行级扫描（装了就跑）。主 agent 只负责启动、等待、事实核验、合并和落盘，不把本地审查当成环节 A。
-| 环节 | 目的 | 是否 gate 必需 |
-|---|---|---|
-| **A 独立 Task agent review** | spec 视角整体审查，用**独立上下文**避免主 agent 确认偏误 | 是（gate 放行靠它） |
-| **B OCR 行级扫描** | 行级 bug / 安全 / 代码模式扫描，补 A 的盲区 | 否（装了就跑，缺了降级） |
-
-**检测由主 agent 在运行时自检自己的工具**，不靠脚本猜环境——主 agent 最清楚自己手上有哪些工具。
-
----
-
-### 环节 A：独立 Task agent review（gate 必需）
-
-主 agent 按 Task agent 选择规则启动独立 Task agent reviewer（优先 Paseo subagent，否则当前宿主原生 Codex/Claude Task/Agent；都不可用时按 local-only fallback 处理）：
-
-1. **有 `mcp__paseo__create_agent` 工具** → 用 Paseo subagent（**首选**：能换 provider，做到真正异构审查）。
- 先加载 / 读取 `paseo` skill 的当前说明并遵守其规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 provider；文件缺失时用合理默认并在报告说明。
-2. **否则有当前宿主原生 Codex/Claude Task/Agent 工具** → 启动原生 Task agent。独立上下文同样达成；若同模型，在报告里记录降级和残余风险。
-3. **两者都没有** → 记 `local-only`，不能伪装启动。gate 默认不放行，需用户明确降级（见 `reviewer` 字段）。
-
-独立 Task agent reviewer prompt（只给原始材料，不透露主 agent 的任何 review 结论）：
-
-```text
-你是 CodeStable 本次改动的独立代码审查 agent。只读，不修改文件，不更新 checklist/design。
-
-请读取：
-- .codestable/attention.md
-- {design_path}
-- {checklist_path}
-- {evidence_pack_path}、{gate_results_path}、{dod_results_path}（存在时）
-- 当前 git status / git diff / staged diff
-- diff 涉及的人写代码和相邻关键调用点
-
-按严重度输出：blocking / important / nit / suggestion / learning / praise / residual-risk。
-每条 finding 必须有 file:line 或仓库事实证据、影响、建议修复边界。
-执行一次**对抗式审查**：假设本次实现里一定藏着一个生产 bug，主动构造反例，优先攻击 design 不一致、边界值、错误路径、状态转换、并发/时序、权限/数据隔离、持久化/回滚和测试假阳性。
-额外输出 Test And QA Focus：QA 必须重点复核的场景、建议新增或加强的测试、review 无法确认的点。
-不要写 {slug}-review.md；只把审查结果回传给主 agent。
-```
-
----
-
-### 环节 B：OCR 行级扫描（装了就跑）
-
-主 agent 自检 `ocr` CLI 是否可用：
-
-```bash
-which ocr && ocr llm test
-```
-
-可用则自动调用（不需要用户显式要求），用 `--background` 传入 spec 摘要提升质量：
-
-```bash
-ocr review --audience agent --background "{feature slug / 目标 / 本次改动范围}"
-```
-
-**OCR 只能审本轮 scope，不能用裸 workspace 模式发现 scope。**`ocr review` 默认会审 staged + unstaged + **untracked**；Roadmap 多 feature 连续执行时，历史 dirty/untracked 会让 OCR 越扫越大。调用规则：
-
-1. 先建立 `current_scope_files`：优先取 scope-gate / evidence pack 的 `changed_files`，否则取 `{feature-base}..HEAD` 或实现汇报中的本轮文件。
-2. 已提交 diff → 用 `ocr review --audience agent --from {feature-base} --to HEAD`。
-3. 未提交 diff → 只有 `git status --short` 的所有非 ignored 路径都属于 `current_scope_files`，才可裸跑 `ocr review`；否则记 `skipped-scope-ambiguous`，改为本地行级审查 `current_scope_files`。
-4. 合并 OCR finding 前，**丢弃**命中以下路径的 finding，无论 OCR 是否扫到——
- - `.codestable/`（CodeStable 自己的 spec / 工具产物，永远不是行级代码审查对象）
- - 任何 `.` 开头的目录（`.git/`、`.claude/`、`.venv/` 等）
- - `.gitignore` 命中的文件（`git check-ignore 
- 
+ 
