cs-roadmap

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

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

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

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       # 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: Lock the Target

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: Read Materials

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: Breakdown and Drafting

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: Self-Check List

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: User 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: Finalize

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.

Connection with Feature Process

Feature Starts from Roadmap

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.

Automatic Write-Back during Acceptance

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/

Lifecycle of Roadmap Itself

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

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

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

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

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

cs-roadmap

NPX Install

Tags

SKILL.md Content (Chinese)

cs-roadmap

Applicable Scenarios

Mode Diversion

Single Target Rule

Directory Structure

Workflow

Phase 1: Lock the Target

Phase 2: Read Materials

Phase 3: Breakdown and Drafting

Phase 4: Self-Check List

Phase 5: User Review

Phase 6: Finalize

Connection with Feature Process

Feature Starts from Roadmap

Automatic Write-Back during Acceptance

Lifecycle of Roadmap Itself

Hard Boundaries

Exit Conditions

Relationship with Other Workflows

Common Mistakes