cs-roadmap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cs-roadmap

codestable/roadmap/

是项目的"规划层"——每个子目录承载一块大需求，里面的主文档把它拆成一串带依赖关系的子 feature 种子，feature 流程一次消费一条。

为什么单独一层：requirements 和 architecture 记录"系统现在长什么样"（现状档案，默认只在 feature-acceptance 时跟着代码同步更新）。"接下来打算做 A、然后做 B、A 完了才能做 C"这种规划信息塞进那两者会把"是什么"和"打算怎么做"混起来——discussion 里查不到系统真实能力，计划改一下又得回头改两份现状文档。roadmap 独立目录，改起来不牵连现状档案。

为什么是文件夹不是单文件：大需求拆解过程里会产生草稿、调研笔记、方案对比、白板照片转述这类材料，塞进一份 md 会变得很乱、又舍不得删。给每个 roadmap 一个子目录，主文档负责对外口径，旁边

drafts/

随便堆。

共享路径与命名约定看
codestable/reference/shared-conventions.md
。主文档和 items 清单的完整模板看同目录
reference.md
。

codestable/roadmap/

is the "planning layer" of the project — each subdirectory carries a large requirement, and the main document inside breaks it into a series of sub-feature seeds with dependency relationships, which are consumed one by one in the feature process.

Why a separate layer: requirements and architecture record "what the system looks like now" (status archives, which are only updated synchronously with code during feature-acceptance by default). Planning information like "We plan to do A first, then B, and C can only be done after A is completed" will mix "what it is" with "how we plan to do it" if stuffed into those two layers — you can't find the real capabilities of the system in discussions, and you have to go back and modify two status documents once the plan changes. The independent roadmap directory allows modifications without affecting the status archives.

Why folders instead of single files: During the breakdown of large requirements, materials like drafts, research notes, solution comparisons, and whiteboard photo transcripts will be generated. Stuffing them into a single md file will make it messy, and you don't want to delete them. Assign a subdirectory to each roadmap, with the main document responsible for external communication, and the

drafts/

folder for random storage.

See
codestable/reference/shared-conventions.md
for shared paths and naming conventions. See the same directory's
reference.md
for the complete template of the main document and items list.

适用场景

Applicable Scenarios

用户描述了一个"一眼看出做不完"的大需求（"加个权限系统"、"做一套通知中心"、"接入 SSO")，塞进单个 feature 不合适
从
```
cs-brainstorm
```
判为 case 3 之后移交过来，本技能接着做拆解（brainstorm 只做分诊，不做拆解）
已有 roadmap 需要加新子 feature、改依赖关系、调整顺序、标废弃
feature-design 阶段发现本次要做的事实际是多个 feature 的集合，需要先退回来拆

不适用：

单个 feature 能装下的需求 → 直接
```
cs-feat
```
用户要描述一个能力"是什么、边界在哪" →
```
cs-req
```
用户要描述系统"结构怎么搭" →
```
cs-arch
```
用户要拍板一条长期规约 / 选型 →
```
cs-decide
```

Users describe a large requirement that is "obviously impossible to finish in one go" (e.g., "Add a permission system", "Build a notification center", "Integrate SSO"), which is not suitable to be stuffed into a single feature
Transferred here after being judged as case 3 from
```
cs-brainstorm
```
, and this skill continues to do the breakdown (brainstorm only does triage, not breakdown)
Existing roadmaps need to add new sub-features, modify dependency relationships, adjust order, or mark as abandoned
During the feature-design phase, it is found that the task to be implemented is actually a collection of multiple features, requiring to step back and break it down first

Not applicable:

Requirements that can fit into a single feature → directly use
```
cs-feat
```
Users want to describe "what a capability is and where its boundaries lie" →
```
cs-req
```
Users want to describe "how to structure the system" →
```
cs-arch
```
Users want to finalize a long-term specification / selection →
```
cs-decide
```

模式分流

Mode Diversion

启动时二选一——AI 根据用户说的话自动判断：

用户说什么	模式
"帮我拆一下 X 需求"、"开一份 X 的 roadmap"、"我想要一个 X 系统"	`new`
"往 {已有 roadmap} 里加一个子 feature"、"重排 {roadmap} 的顺序"、"把 {某条} 标 drop"	`update`

判断不出来就问用户一句，不要硬猜。

Choose one of the two modes when starting — the AI automatically judges based on what the user says:

What the user says	Mode
"Help me break down requirement X", "Create a roadmap for X", "I want an X system"	`new`
"Add a sub-feature to {existing roadmap}", "Reorder {roadmap}", "Mark {item} as drop"	`update`

If you can't judge, ask the user instead of guessing.

单目标规则

Single Target Rule

每次只动一份 roadmap。用户一次扔出两个"我想要 X 和 Y"，先选一个做，另一个下次。理由同 requirements / architecture——一次吐多份 AI 稿用户 review 不过来。

Only modify one roadmap at a time. If the user throws out two requests like "I want X and Y" at once, choose one to do first, and handle the other next time. The reason is the same as requirements / architecture — users can't review multiple AI drafts at once.

目录结构

Directory Structure

codestable/roadmap/{slug}/
├── {slug}-roadmap.md       # 主文档（对外口径：背景 / 范围 / 子 feature 清单 / 排期思路）
├── {slug}-items.yaml       # 机器可读清单（feature-design 读、feature-acceptance 回写）
└── drafts/                 # 可选，调研 / 讨论 / 草稿

```
{slug}
```
小写字母、数字、连字符，和大需求的 slug 一致（如
```
permission-system
```
、
```
notification-center
```
）
平铺，每个大需求一个子目录，不嵌套 epic / sub-epic
```
drafts/
```
按需建，里面内容只服务起草过程，AI 不强制归档

codestable/roadmap/{slug}/
├── {slug}-roadmap.md       # Main document (external communication: background / scope / sub-feature list / scheduling ideas)
├── {slug}-items.yaml       # Machine-readable list (read by feature-design, written back by feature-acceptance)
└── drafts/                 # Optional, for research / discussions / drafts

```
{slug}
```
uses lowercase letters, numbers, and hyphens, consistent with the slug of the large requirement (e.g.,
```
permission-system
```
,
```
notification-center
```
)
Flat structure, one subdirectory per large requirement, no nested epic / sub-epic
```
drafts/
```
is created on demand, and the content inside only serves the drafting process; the AI does not force archiving

工作流

Workflow

Phase 1：锁定目标

Phase 1: Lock the Target

模式（
```
new
```
/
```
update
```
）
目标（new：新 slug + 一句话大需求描述；update：已有 roadmap 路径）
本次覆盖范围（整份起草 / 只加几条 / 只重排顺序）

slug 收敛：new 模式下用户给的"权限系统"、"加个通知功能"，先敲定一个英文 slug。命名风格参考现有 requirements 和 architecture doc 的 slug 习惯。

Mode (
```
new
```
/
```
update
```
)
Target (new: new slug + one-sentence description of the large requirement; update: path of the existing roadmap)
Coverage of this time (full drafting / only add a few items / only reorder)

Slug Convergence: In new mode, first finalize an English slug for user-provided names like "permission system", "add notification function". Refer to the slug conventions of existing requirements and architecture documents for naming style.

Phase 2：读取材料

Phase 2: Read Materials

共同必读：

```
AGENTS.md
```
用户提供的素材（口述、产品想法、白板转述、相关 issue）
```
codestable/roadmap/
```
下其他 roadmap（防止和已有大需求重复或冲突）
```
codestable/requirements/
```
相关 req doc（这块能力的需求写下来没？写了的话拆解要对齐）
```
codestable/architecture/
```
相关 doc（系统现在长什么样，影响拆解顺序）

按情况读：

相关的 compound 沉淀（decision / explore / learning）：

bash

python codestable/tools/search-yaml.py --dir codestable/compound --query "{大需求关键词}"

已有 feature 方案里和这块相关的（可能已经有人做了一部分）

update 模式额外必读：当前 roadmap 主文档全文 + items.yaml 当前状态 + 已启动 / 已完成的子 feature 的 design 和 acceptance 报告。

Mandatory reading for all cases:

```
AGENTS.md
```
Materials provided by users (oral descriptions, product ideas, whiteboard transcripts, related issues)
Other roadmaps under
```
codestable/roadmap/
```
(to avoid duplication or conflicts with existing large requirements)
Related req docs under
```
codestable/requirements/
```
(Has the requirement for this capability been written down? If yes, the breakdown must align with it)
Related docs under
```
codestable/architecture/
```
(What the system looks like now, which affects the breakdown order)

Read as needed:

Relevant compound records (decision / explore / learning):

bash

python codestable/tools/search-yaml.py --dir codestable/compound --query "{large requirement keywords}"

Related content in existing feature solutions (someone may have already implemented part of it)

Additional mandatory reading for update mode: Full text of the current roadmap's main document + current status of items.yaml + design and acceptance reports of sub-features that have been started / completed.

Phase 3：拆解与起草

Phase 3: Breakdown and Drafting

按

reference.md

的"主文档结构"和"items.yaml 格式"写出完整初稿，不分批吐半成品。

拆解的判断纪律：

每条子 feature 要能当作一次独立 feature 流程跑完——能单独写 design、单独实现、单独验收。跑不下来说明颗粒度不对，继续拆或合并
依赖图要是 DAG——A 依赖 B 就写清楚，别写循环依赖
依赖关系要有具体理由——"B 依赖 A，因为 A 提供 XX 表结构" 而不是 "B 依赖 A，因为 A 先做"
先列一条最小闭环——整个大需求里，哪条子 feature 做完后能端到端跑通最窄的一条路径？标成第一条。后续都在这条基础上叠
明确不做的边界——用户脑子里的"权限系统"可能包括审计日志 / 数据脱敏，如果本 roadmap 不打算覆盖就写进"明确不做"
不替用户决定优先级——子 feature 之间的先后顺序除了技术依赖之外，还有产品优先级。技术依赖之外的排序要让用户拍板，不要 AI 自作主张

Write a complete first draft according to the "main document structure" and "items.yaml format" in

reference.md

, do not deliver semi-finished products in batches.

Discipline for breakdown judgment:

Each sub-feature must be able to run through an independent feature process — can write design separately, implement separately, and accept separately. If it can't, the granularity is wrong; continue to break down or merge
The dependency graph must be a DAG — clearly write that A depends on B, do not write circular dependencies
Dependency relationships must have specific reasons — "B depends on A because A provides XX table structure" instead of "B depends on A because A is done first"
First list a minimum closed loop — Among all sub-features of the large requirement, which one can run through the narrowest end-to-end path after completion? Mark it as the first one. All subsequent features are built on this basis
Clarify the boundaries of what will not be done — The "permission system" in the user's mind may include audit logs / data desensitization; if this roadmap does not plan to cover them, write them into "Clearly Not Done"
Do not decide priorities for users — The order of sub-features depends on both technical dependencies and product priorities. For sorting beyond technical dependencies, let the user make the decision, do not make arbitrary decisions by AI

Phase 4：自查清单

Phase 4: Self-Check List

用户 review 前自己先跑一遍，汇报处理结果：

每条子 feature 的 slug 是不是规范？（英文小写连字符，不和已有 feature 目录冲突 → grep
```
codestable/features/
```
确认）
每条描述是不是一句话能讲清楚？讲不清就是拆得还不够或者 scope 太模糊
依赖关系是不是 DAG？有没有谁指向自己、或 A→B→A 的回环
最小闭环是不是真的最小？第一条做完能独立给用户演示点什么？做不到就还不够小
"明确不做"有没有写？没写的话就说"没有明确不做"，不要空着
和已有 requirement / architecture 有没有矛盾？有的话在主文档里写"和 req-X 冲突待用户决定"，不要偷偷选一边
update 专项：本次新加 / 改的条目是否都有对应的素材依据？凭空"再加一条让看起来更完整"是漂移的开端

Run through this list before user review and report the processing results:

Is the slug of each sub-feature standardized? (English lowercase with hyphens, no conflict with existing feature directories → confirm with grep
```
codestable/features/
```
)
Can each description be clearly explained in one sentence? If not, it means the breakdown is not sufficient or the scope is too vague
Is the dependency graph a DAG? Is there any self-pointing or loop like A→B→A
Is the minimum closed loop really minimal? Can you demonstrate something independently to the user after completing the first one? If not, it's not minimal enough
Is "Clearly Not Done" written? If not, state "No clearly not done items" instead of leaving it blank
Is there any conflict with existing requirements / architecture? If yes, write "Conflict with req-X, pending user decision" in the main document, do not secretly choose one side
Update-specific check: Are all newly added / modified items supported by corresponding materials? Adding items out of thin air "to make it look more complete" is the beginning of drift

Phase 5：用户 review

Phase 5: User Review

把主文档 + items.yaml 完整贴给用户，提示 review。用户提意见就改，反复直到用户明确"这份可以了"。

Paste the complete main document + items.yaml to the user and prompt for review. Modify according to user feedback until the user clearly says "This is acceptable".

Phase 6：落盘

Phase 6: Finalize

new

模式：

建
```
codestable/roadmap/{slug}/
```
目录

写入

{slug}-roadmap.md

，frontmatter

status: active

、

created

last_reviewed

填当天

写入

{slug}-items.yaml

，每条

status: planned

、

feature: null

用

validate-yaml.py --file {slug}-items.yaml --yaml-only

校验

```
update
```
模式：
- 改主文档，
```
last_reviewed
```
  更新为当天；结构性改动在文末
```
变更日志
```
  加一条
- 改 items.yaml 对应条目，用户标 drop 的条目不删，
```
status: dropped
```
  留存（理由一同保留）
- 重新校验 yaml

不需要改 requirements / architecture——roadmap 是规划层，那两层只描述现状。如果拆解过程发现 req 或架构描述确实过时了（比如用户说"先把现在的 X 模块改成 Y 才能接着做"），在主文档"观察项"节记一句交给用户，不要顺手改那两层的文档。

new

mode:

Create the
```
codestable/roadmap/{slug}/
```
directory
Write
```
{slug}-roadmap.md
```
with frontmatter
```
status: active
```
, fill in
```
created
```
/
```
last_reviewed
```
with the current date

Write

{slug}-items.yaml

, set each item's

status: planned

and

feature: null

Validate with

validate-yaml.py --file {slug}-items.yaml --yaml-only

```
update
```
mode:
- Modify the main document, update
```
last_reviewed
```
  to the current date; add a record in the "Change Log" section at the end for structural changes
- Modify the corresponding items in items.yaml; do not delete items marked as drop by the user, set
```
status: dropped
```
  and retain the reason
- Re-validate the yaml

Do not modify requirements / architecture — the roadmap is the planning layer, and those two layers only describe the current status. If it is found during the breakdown that the req or architecture description is indeed outdated (e.g., the user says "We need to modify the current X module to Y first before proceeding"), record it in the "Observations" section of the main document and hand it over to the user, do not modify those two layers of documents casually.

和 feature 流程的衔接

Connection with Feature Process

feature 从 roadmap 起头

Feature Starts from Roadmap

当用户说"开始做 roadmap 里的 {子 feature slug}"时：

```
cs-feat-design
```
（或 fastforward / brainstorm）起 feature 目录

design frontmatter 带两个字段：

roadmap: {roadmap-slug}

roadmap_item: {子 feature slug}

design 流程同时把

codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml

对应条目

status

改为

in-progress

、

feature

填为 feature 目录名（

YYYY-MM-DD-{slug}

）

这一步的职责在 feature-design 技能里，不在本技能里。

When the user says "Start implementing {sub-feature slug} in the roadmap":

Initiate the feature directory with
```
cs-feat-design
```
(or fastforward / brainstorm)

Add two fields to the design frontmatter:

roadmap: {roadmap-slug}

roadmap_item: {sub-feature slug}

During the design process, simultaneously change the
```
status
```
of the corresponding item in
```
codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml
```
to
```
in-progress
```
, and fill in
```
feature
```
with the feature directory name (
```
YYYY-MM-DD-{slug}
```
)

This step is the responsibility of the feature-design skill, not this skill.

acceptance 自动回写

Automatic Write-Back during Acceptance

cs-feat-accept

走到收尾时，如果 design frontmatter 有

roadmap

字段，就去

codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml

把对应

roadmap_item

的

status

改为

done

。同时在主文档的子 feature 清单里把对应行的勾选状态同步。

这一步的职责在 feature-acceptance 技能里，不在本技能里。roadmap 文档本身是项目产物，任何 skill 都可以按 items.yaml 的 schema 读写——这不算 skill 间耦合，和各 skill 都读写

codestable/features/

是一回事。

When

cs-feat-accept

reaches the final stage, if the design frontmatter has the

roadmap

field, go to

codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml

and change the

status

of the corresponding

roadmap_item

done

. At the same time, synchronize the check status of the corresponding line in the sub-feature list of the main document.

This step is the responsibility of the feature-acceptance skill, not this skill. The roadmap document itself is a project product, and any skill can read and write according to the schema of items.yaml — this is not considered skill coupling, just like all skills read and write

codestable/features/

roadmap 本身的生命周期

Lifecycle of Roadmap Itself

所有 items 都
```
done
```
/
```
dropped
```
后，主文档 frontmatter
```
status
```
改为
```
completed
```
，目录不删，留作历史档案
roadmap 停摆（长期无进展）：
```
status: paused
```
，主文档加一句理由

After all items are
```
done
```
/
```
dropped
```
, change the
```
status
```
in the main document's frontmatter to
```
completed
```
, do not delete the directory, keep it as a historical archive
If the roadmap is suspended (no progress for a long time): set
```
status: paused
```
, add a reason in the main document

硬性边界

Hard Boundaries

不写实现细节——roadmap 是"拆成几块、先做哪块"，不是"每块怎么实现"。每条子 feature 一句话描述就够，细节到 design 阶段才写
不改现状档案——不顺手改 requirements / architecture / 代码 / 已有 feature。发现它们有问题就记为"观察项"交给用户
不替用户拍产品优先级——技术依赖之外的排序让用户决定
单目标——一次只动一份 roadmap
不发散——用户描述范围外的问题记成观察项，不扩大 roadmap 范围

Do not write implementation details — the roadmap is about "breaking into pieces and which to do first", not "how to implement each piece". A one-sentence description for each sub-feature is sufficient; details are written in the design phase
Do not modify status archives — do not casually modify requirements / architecture / code / existing features. If problems are found, record them as "Observations" and hand them over to the user
Do not make product priority decisions for users — let users decide the order beyond technical dependencies
Single target — only modify one roadmap at a time
Do not diverge — record issues outside the user's described scope as observations, do not expand the roadmap scope

退出条件

Exit Conditions

已锁定单一模式（new / update）和单一目标 roadmap

主文档 frontmatter 完整（

doc_type: roadmap

slug

status

created

last_reviewed

tags

）

主文档包含：背景 / 范围与明确不做 / 子 feature 清单 / 排期思路 / 观察项
items.yaml 每条都有
```
slug
```
/
```
description
```
/
```
depends_on
```
/
```
status
```
/
```
feature
```
依赖图是 DAG，无循环
最小闭环条目已明确标记
items.yaml 通过
```
validate-yaml.py --yaml-only
```
校验
Phase 4 自查清单逐条跑过，并已汇报处理结果
用户明确 review 通过
没有顺手改 requirements / architecture / 代码 / 已有 feature

Single mode (
```
new
```
/
```
update
```
) and single target roadmap have been locked

Main document frontmatter is complete (

doc_type: roadmap

slug

status

created

last_reviewed

tags

)

Main document includes: Background / Scope and Clearly Not Done / Sub-feature List / Scheduling Ideas / Observations
Each item in items.yaml has
```
slug
```
/
```
description
```
/
```
depends_on
```
/
```
status
```
/
```
feature
```
Dependency graph is a DAG with no loops
Minimum closed loop item has been clearly marked
items.yaml passes validation with
```
validate-yaml.py --yaml-only
```
Phase 4 self-check list has been run through, and processing results have been reported
User has clearly confirmed review approval
No casual modifications to requirements / architecture / code / existing features

和其他工作流的关系

Relationship with Other Workflows

方向	关系
`cs-req` 配合	req 记"为什么要有这个能力"，roadmap 记"打算怎么分步把它做出来"。大需求下可能有多份 req；拆解过程中发现缺 req 就提示用户先触发本技能之前跑 `cs-req`
`cs-arch` 配合	architecture 记"系统现在长什么样"，roadmap 记"接下来想把它变成什么样的若干步"。拆解时要读 architecture 理解现状，但不改它
`cs-feat` 下游	roadmap 里每条子 feature 都是未来一次 feature 流程的种子；feature 从 roadmap 起头时在 design frontmatter 带 `roadmap` / `roadmap_item` 字段
`cs-feat-accept` 回写方	acceptance 走完时自动改 items.yaml 对应条目为 `done` ，本技能只定义格式不负责回写
`cs-onboard` 创建者	onboarding 建 `codestable/roadmap/` 空目录
`cs-brainstorm` 上游	brainstorm 判为 case 3 时把讨论移交给本技能，并带上已聊到的真问题 / 大致范围 / 可能子模块做一句话汇总。本技能不重复做分诊，直接进拆解

Direction	Relationship
Collaboration with `cs-req`	req records "why this capability is needed", while the roadmap records "how to implement it step by step". There may be multiple reqs under a large requirement; if it is found that reqs are missing during breakdown, prompt the user to run `cs-req` before triggering this skill
Collaboration with `cs-arch`	architecture records "what the system looks like now", while the roadmap records "several steps to turn it into what we want next". Read architecture to understand the current status during breakdown, but do not modify it
Downstream of `cs-feat`	Each sub-feature in the roadmap is the seed of a future feature process; when a feature starts from the roadmap, add `roadmap` / `roadmap_item` fields to the design frontmatter
Write-back target of `cs-feat-accept`	Automatically change the corresponding item in items.yaml to `done` when acceptance is completed; this skill only defines the format and does not take responsibility for write-back
Created by `cs-onboard`	`cs-onboard` creates the empty `codestable/roadmap/` directory
Upstream of `cs-brainstorm`	When `cs-brainstorm` judges it as case 3, transfer the discussion to this skill, and bring a one-sentence summary of the real problems discussed, approximate scope, and possible sub-modules. This skill does not repeat triage and directly starts breakdown

常见错误

Common Mistakes

把 roadmap 写成超大 design——每条子 feature 描述了半页实现细节。实现细节到 feature-design 再写，roadmap 里一句话就够
颗粒度失衡——一条子 feature 大到能装下三个独立功能、另一条小到只是改个配置项。都要重新拆
依赖关系靠脑补——"B 依赖 A" 但讲不清为什么依赖，回去想清楚再写
替用户排优先级——技术依赖之外的顺序让用户拍板
和已有 requirement / architecture 冲突不停下——自己偷偷选一边会掩盖真实分歧
一次做多份 roadmap——用户 review 不过来
顺手改 requirements 或 architecture——越界，那两层是现状档案，动它们走各自技能
把 drop 的条目直接删掉——历史状态丢失，后人看不到"这条为什么被放弃"
roadmap 跑偏不登记——拆解跑着跑着变成给单条子 feature 写详细方案

Writing the roadmap as an oversized design — each sub-feature describes half a page of implementation details. Implementation details are written in feature-design; a one-sentence description is sufficient in the roadmap
Unbalanced granularity — one sub-feature is large enough to contain three independent functions, while another is as small as modifying a configuration item. Both need to be re-broken down
Dependencies based on imagination — "B depends on A" but can't explain why; go back and think clearly before writing
Prioritizing for users — let users decide the order beyond technical dependencies
Not stopping when conflicting with existing requirements / architecture — secretly choosing one side will cover up real disagreements
Working on multiple roadmaps at once — users can't review them all
Casually modifying requirements or architecture — overstepping boundaries; those two layers are status archives, modify them through their respective skills
Directly deleting dropped items — losing historical status, later developers can't see "why this item was abandoned"
Not recording roadmap drift — the breakdown process diverges into writing a detailed plan for a single sub-feature