cs-roadmap

cs-roadmap

Required reading before starting

Before making any judgment or taking any action, first run the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute it by reading an external AI entry point (see .codestable/reference/execution-conventions.md）。

.codestable/roadmap/ is the project's "planning layer"—each subdirectory carries one large requirement, and the main document consists of three parts:

High-level design: how this large requirement should be structured, which modules / components it should be split into, and each one's responsibilities
Architecture-layer detailed design: interface contracts between modules, shared data structures, and cross-feature protocols
Sub-feature breakdown: decompose the solution into a series of sub-feature seeds with dependency relationships; the feature process consumes one at a time

The three partstogetherserve as the shared constraints for all sub-features of this large requirement—when each sub-feature enters cs-feat-design , the interface contract in part 2 of the roadmap is itshard-constraint input(it cannot be violated; to change it, first go back to roadmap update).

When a roadmap involves cross-module module interfaces, seams, adapters, or dependency-double strategies, perform an inline deep-module check per references/codebase-design.md ; this is not switching to an independent codebase-design skill。

Why the roadmap does not directly write ADRs：ADR（requirements/adrs/) records "stable structural decisions that have already been finalized", whereas a roadmap records forward-looking interface contracts that "have not yet landed and may still change". Once the sub-features actually land and the corresponding interfaces stabilize, the domain impact inventoried by cs-feat-accept triggers cs-domain to write an ADR—after the roadmap completes its transitional mission, it is archived.

Why a separate layer: requirements records "what is wanted + how terms are defined + which decisions have been finalized" (vision + domain), while roadmap records "how to implement it step by step" (execution). Cramming execution planning into requirements mixes up "what is wanted" and "how it is intended to be implemented".

Why a folder rather than a single file: the breakdown process produces drafts / research / option comparisons / whiteboard transcriptions, and cramming them into one md file would be messy yet hard to discard. One subdirectory per roadmap, with the main document as the external-facing statement, and alongside it drafts/ can be piled up freely.

Planning principles: a roadmap is not a "task list", but an executable route design. Before writing, you must think clearly about goals, constraints, risks, dependencies, and verifiable completion signals; every sub-feature broken out must be independently verifiable; before handing the whole roadmap to the user, you must first do a self-critique and fix vague acceptance criteria, wrong dependencies, and over-packaged items.

Advancement principles: whether a long-term software task can advance steadily depends on whether the closed loop of "current state → next step → verification → fix → record" has been clearly designed. In the roadmap phase, you must identify in advance whether the baseline may already be broken, which items carry safety net / polish / harden, which artifacts must be persisted to disk, and which lessons should be written back to the CodeStable knowledge layer. Without these, subsequent features are merely executed in sequence, not recoverable, auditable advancement.

For shared paths and naming conventions, see .codestable/reference/shared-conventions.md. For the full templates of the main document and items, see the same directory reference.md。

Applicable scenarios

The user describes a large requirement that is "obviously too big to finish at a glance" ("add a permission system", "build a notification center", "integrate SSO")
cs-brainstorm is judged as case 3 and handed over here (brainstorm only does triage, not breakdown)
Existing roadmap: add a new sub-feature / change dependencies / adjust order / mark as deprecated
feature-design finds that what needs to be done is actually a set of multiple features; first go back and split

Not applicable: a single feature can contain it → cs-feat; describing what the capability "is, and its boundaries" → cs-req; deciding long-term conventions / architecture choices / adding terminology → cs-domain; operational accumulation → cs-keep。

Mode routing

What the user says	Mode
"Split requirement X", "open a roadmap for X", "I want an X system"	`new`
"add a sub-feature to {existing roadmap}", "reorder", "mark as drop"	`update`

If you cannot determine it, ask the user.

Single-objective rule

Only touch one roadmap at a time. If the user throws out "I want X and Y" at once, choose one first, and do the other next time. The reason is the same as req / arch—if you spit out multiple at once, the user cannot review them all.

Directory structure

.codestable/roadmap/{slug}/
├── {slug}-roadmap.md       主文档：背景 / 范围 / 模块拆分（概设）/ 接口契约（架构层详设）/ 子 feature 清单 / 排期
├── {slug}-items.yaml       机器可读清单（feature-design 读、feature-acceptance 回写）
├── {slug}-roadmap-review.md 独立规划审查报告（人审前 gate）
└── drafts/                 可选，调研 / 讨论 / 草稿

{slug} Lowercase letters / numbers / hyphens, consistent with large requirements (permission-system、notification-center). Flat, no nested epic / sub-epic.drafts/ Created as needed; AI does not force archiving.

Workflow

Phase 1: Lock the objective

Mode + objective + scope. For new mode, first settle on an English slug (refer to the existing req / arch slug conventions).

Phase 2: Read materials

Common required reading：.codestable/attention.md + user materials + roadmap/ other roadmaps (to prevent duplication) + requirements/ related reqs + requirements/CONTEXT.md + requirements/adrs/ related ADRs.

Read as appropriate：

Related compound accumulation:grep -r "{大需求关键词}" .codestable/compound/
Existing related feature plans
Project available verification commands / known baselines: find build / typecheck / lint / test / e2e / browser verification entry points from .codestable/attention.md, architecture docs, historical acceptance, README / package scripts / CI configuration. The roadmap does not directly run the complete commands, but it needs to know what each subsequent feature will be verified by

Additional for update: the full current main document + the current state of items.yaml + the design / acceptance of started / completed sub-features.

Phase 3: Decomposition and drafting

Write according to reference.md "main document structure" and "items.yaml format"Complete first draftnot in batches.

First do Granularity Gate: confirm why this requirement should enter the roadmap, rather than being a single feature or brainstorm; write the conclusion into Section 2 of the main document, and see reference.md。

First write a deep planning draft(can be written into Sections 6 / 7 of the main document, and does not need to be a separate file):

Objective completion signal: what observable state this large requirement must reach to count as complete; do not write feeling words like "capability is complete"
Top 3 risks and mitigations: the three things most likely to go wrong / hardest to roll back / easiest to miss until after launch; for each, clearly write how this roadmap reduces the risk
Non-obvious dependencies: external systems, data migrations, existing module constraints, user decision items; which ones will block subsequent features
Key assumptions: judgments that are not the user's exact words but that this planning depends on being true; during review, let the user be able to precisely refute them
Baseline and verification entry points: Which commands / manual verification entry points should subsequent features prioritize; if the current repository is very likely lacking tests or has an unstable baseline, arrange safety net / characterization items in the breakdown
Deliverable landing points: Where each sub-feature should actually land after completion in code / configuration / documentation / roadmap status, to avoid only saying it is complete in a report
Knowledge write-back points: Which conventions, environment pitfalls, and cross-feature rules, if verified to hold, should be captured into attention / learning / decide / guide when acceptance is wrapped up

Also maintain Goal Coverage Matrix: each roadmap goal / completion signal must trace to at least one item, verification entry point, and evidence type; when there is no traceable item, adjust the breakdown first rather than leaving the gap to subsequent feature-design.

Breakdown discipline：

Do the architecture plan before breaking down features——Order: first think through module decomposition (Section 3 of the high-level design) → interfaces between modules / data structures / protocols (Section 4 of the detailed design) → only then decompose the plan into sub-features (Section 5).If the architecture plan is unclear and you force a feature breakdown, the result is that each feature reinvents the wheel on its own and the interfaces do not line up
Interface contracts must be written to the level where features can use them as hard constraints——At the level of function signatures / data structures / protocol fields / error codes, and explain seam placement, dependency strategy, and whether an adapter is actually needed. If you cannot get to that level, go back and think. If there is no cross-module interface (such as a pure frontend style adjustment), explicitly write "no cross-module interface"
Each sub-feature can be run through the independent feature process and verified independently——It can have its design / implementation / acceptance written separately, and after completion can produce clear evidence (commands, tests, screenshots, interface responses, document consolidation). If it cannot be run through, the granularity is wrong
The dependency graph must be a DAG——Write clearly that A depends on B, and do not create cycles
Dependency relationships must have concrete reasons——"B depends on A because A provides the XX table structure" rather than "A is done first"
List one minimal closed loop first——Mark the first one that, once done, can run the narrowest path end to end
Clarify the boundaries of what will not be done——The "permission system" in the user's mind may include audit logs / data masking; if you do not plan to cover them, write them into "explicitly not doing"
Do not decide priorities for the user——Let the user make the final call on ordering beyond technical dependencies
Finally, there must be awareness of wrap-up / hardening——For large requirements such as UI, full stack, permissions, security, and migration, if the preceding items only cover feature launch, add a wrap-up sub-feature or explicitly cover it in the last item: error states, empty states, boundary inputs, security, performance, regression cleanup, document consolidation
The number of items is determined by the shape of the task——Do not merge / split just to make a fixed number. If it can be verified independently and delivers one coherent thing, it is one item; if the name needs "and / as well as", that usually means two items were stuffed into one
Acceptance wording must be falsifiable——Do not write empty words like "improve / optimize / connect through" in each sub-feature's description and notes; change them to "when input A is given, B is obtained", "page X displays Y", "command Z passes"
When a safety net is needed, build the safety net first— For brownfield refactoring, migrations, core path changes, or when historical tests are weak, the first item or first few items should first add characterization / baseline tests / observability means, then change behavior.
Each item must be resumable from a checkpoint.— The items.yaml's status / feature is the recovery anchor. In the item notes, clearly write the blockers, skip reasons, and external dependencies; do not rely on conversation memory.

Phase 4: Self-check list

Before independent review, run through the report handling yourself:

Is the module split clearly explained? Can each module's responsibility be stated in one sentence?
Are the interface contracts written to an executable level? After reading feature-design, can implementation proceed directly without needing to come back and ask?
Is each sub-feature's slug compliant? (grep .codestable/features/ to confirm no conflicts)
Is each description clear in one sentence? If not, it is not split enough or the scope is too vague.
Are the dependencies a DAG? Is there any self-reference / A→B→A cycle?
Is the minimum closed loop really minimal? After the first item is done, can something be independently demonstrated to the user?
Is "explicitly not doing" written? If not, write "no explicit non-goals".
Is there any conflict with existing req / arch? If so, write "conflicts with req-X pending user decision"; do not secretly pick a side.
update-specific: Do all newly added / changed items this time have source material support? Adding one out of thin air "to look more complete" is drift.
update-specific: If the interface contract was changed, are sub-features already in-progress / done affected? List affected ones under "observation items" to alert the user.
Falsifiability self-check: Is each completion signal yes/no? Are there words that cannot be verified, such as "better experience / more stable / improved support"?
Item atomicity self-check: Does any single item actually contain two independently acceptable deliverables? Recheck especially when "and / as well as / at the same time" appears in the name or description.
Weakest dependency self-check: Which item's failure would drag down the most subsequent items? Are its prerequisite verification and risk mitigation early enough?
Closing coverage self-check: Does it cover polish / harden / regression sweep? If not, clearly write why this roadmap does not need them.
Baseline self-check: Do you know the verification entry point for subsequent features? When the current baseline is unstable / tests are weak, has a safety net been arranged?
Deliverable self-check: After each item is done, can the artifact be seen from repository facts, rather than only from reports?
Knowledge write-back self-check: Which rules or pitfalls will affect subsequent features? Have they been placed in observation items, to trigger the corresponding consolidation process after acceptance verification?
Goal Coverage self-check: Has each goal / completion signal been mapped to an item, verification entry point, and evidence type? Core goals cannot rely only on vague descriptions or be deferred until later.
Interface depth self-check: Are cross-module interfaces deep? Are there pass-through modules, fake seams, or single-adapter indirection layers?

Phase 5: Candidate persisted to disk + independent review gate

First write the candidate draft to the standard roadmap directory, giving cs-roadmap-review stable input:

new: create .codestable/roadmap/{slug}/; write the main document status: draft; write items.yaml (each item status: planned、feature: null）；validate-yaml.py validation.
update: Directly update the candidate content of the main document / items.yaml, add a changelog at the end for structural changes; re-validate yaml.

Then run cs-roadmap-review：

passed: only then can the roadmap be handed to the user for review.
changes-requested: Fix roadmap/items according to the finding, re-validate and re-run cs-roadmap-review。
blocked: fill in the inputs, wait for an independent Task agent reviewer, or have the user explicitly downgrade to local-only before re-running.

Phase 6: User review

Paste the main document + items.yaml + {slug}-roadmap-review.md in full to the user, along with the Phase 4 self-check conclusions, Top 3 risks and mitigations, key assumptions, review findings / residual risk. Iterate until the user explicitly says "it's good". If the user's changes cause substantial changes to the roadmap/items, go back to Phase 5 and re-run the review gate.

Phase 7: Confirm persistence

After user confirmation, in new mode change the main document status to active、last_reviewed to the current day; in update mode update last_reviewed to the current day. Re-validate yaml.

Do not modify requirements / architecture— the roadmap is the planning layer; those two layers only describe the current state. If during decomposition you find req / architecture is outdated, note it in an "observations" line in the main document for the user, and do not change it on the side.

If the user wants to automatically push the entire roadmap through to the end, after confirming persistence suggest that the next step can be cs-roadmap-impl-goal: it will first complete all sub-feature designs + design reviews, then have the user confirm a second time, and finally output a directly runnable goal instruction.

After confirming persistence, also suggest: "This roadmap has changed the entry point for subsequent work and the document index. Would you like to do a round of document and memory cleanup? (cs-docs-neat)" If the user says no, skip it; this is a wrap-up guide, not a roadmap pass condition.

Connection with the feature process

feature starts from roadmap

When the user says "start working on {sub-feature} in the roadmap":

cs-feat-design(or ff / brainstorm) to create the feature directory
design frontmatter carries roadmap: {slug} + roadmap_item: {子 slug}
the corresponding items.yaml entry status: in-progress、feature: YYYY-MM-DD-{slug}

The responsibility lies in cs-feat-design not in this skill.

feature-design must treat the roadmap interface contract as a hard constraint

Section 4 "Interface Contract" of the roadmap main document is a hard-constraint input for the feature— not a reference; it must not be violated, and if it needs to change, first go back to roadmap update. This is why the roadmap must settle the architecture plan before decomposing features: so that the external interfaces stay aligned when multiple features are implemented in parallel / serially.

If feature-design finds the interface contract unreasonable / missing / inaccurately described → go back to cs-roadmap update change it and then continue, do not secretly bypass it within the feature (bypassing will cause the next feature in the same module to connect to the old contract, leading to a second conflict).

acceptance automatically writes back

cs-feat-accept At wrap-up, if the design frontmatter has a roadmap field, change the corresponding roadmap_item of status: done, and at the same time sync the checked state of the sub-feature list in the main document. The responsibility lies in cs-feat-accept not in this skill.

roadmap's own lifecycle

After all items done / dropped the main document status: completed, keep the directory as a historical archive
No progress for a long time:status: paused, add the reason to the main document

Hard boundaries

Do not write internal implementation details of a single feature——The roadmap stops at "module boundaries / interface contracts / shared protocols"; how a single module is implemented internally belongs to feature-design. Criteria:Will be commonly observed by multiple featuresBelongs to roadmap,Used only within a certain featureBelongs to feature-design
Do not change the vision and architecture files——Do not conveniently modify requirements / architecture / code / existing features. Record problems as "observations"
Do not make product priority decisions for the user——Let the user decide the ordering apart from technical dependencies
Single objective——Only touch one document at a time
Do not diverge——Record out-of-scope problems as observations and do not expand
Interface contracts must either be at the executable level or explicitly state "no cross-module interfaces"——"To be determined / discuss later" is not allowed. Vague interfaces will inevitably be filled in inconsistently across the various feature-design entries

Exit conditions

A single mode + single objective has been locked in
The frontmatter of the main document is complete (doc_type: roadmap / slug / status / created / last_reviewed / tags）
The main document contains: background / scope and explicit non-goals / module breakdown / interface contracts / child feature list / schedule / observations
In the module breakdown section, each module's responsibility is clearly stated in one sentence
In the interface contracts section, write to the level that feature-design can use as hard constraints (function signatures / data structures / protocol fields / error codes) or explicitly state "no cross-module interfaces"
When cross-module interface / seam / adapter is involved, depth / locality / dependency strategy and adapter conclusions have been recorded
Each entry in items.yaml has slug / description / depends_on / status / feature
The dependency graph is a DAG with no cycles
The minimal closed-loop entries have been marked
Top 3 risks, non-obvious dependencies, and key assumptions have been written into the main document or review summary
Each child feature has an independently verifiable completion signal / evidence type
The Granularity Gate and Goal Coverage Matrix have been completed; every core objective can be traced to an item and evidence
Self-checks for falsifiability / item atomicity / weakest dependency / closure coverage have been done and reported
Verification entry points / baseline risks have been identified; safety net entries have been split out when necessary
The deliverables of each child feature can be verified by subsequent acceptance from repository facts
Convention / learning / guide / attention candidates that need to be subsequently captured have been written into observations
items.yaml passes validate-yaml.py validation
The Phase 4 self-check list has been run through item by item and reported
{slug}-roadmap-review.md Has passed cs-roadmap-review, with no unresolved blocking finding
User review has passed
Did not conveniently modify req / arch / code / existing features

Relationship with other workflows

Direction	Relationship
`cs-req` Cooperate	req records "why this capability exists", roadmap records "how it is planned to be built step by step". A large requirement may have multiple reqs; if a req is missing, prompt the user to first `cs-req`
`cs-domain` Cooperate	adrs/ records decisions that have been made, roadmap records forward-looking interface contracts. Read the ADR to understand the current state but do not modify it
`cs-feat` Downstream	Each sub-feature is the seed of a future feature workflow; at the start, the design frontmatter carries `roadmap` / `roadmap_item`
`cs-feat-accept` write-back party	acceptance automatically changes items.yaml to `done`, this skill only defines the format and is not responsible for write-back
`cs-roadmap-impl-goal` downstream	After the user confirms the roadmap, all sub-feature designs and the subsequent impl / review / QA / accept can be orchestrated into a resumable goal
`cs-onboard` creator	create `roadmap/` empty directory
`cs-brainstorm` upstream	case 3 hands off to this skill, with a one-sentence summary of "real problem / rough scope / possible submodules". This skill does not repeat triage and splits directly

Common mistakes

Skipping the architecture plan and splitting tasks directly——listing sub-features right away, without thinking through module boundaries / interfaces, so each feature-design reinvents the wheel
Writing interface contracts vaguely——"the two sides will discuss it", "to be determined", "use a unified event bus"——without getting down to the field / signature / protocol level. feature-design cannot treat this as a hard constraint
Creating pass-through modules or fake seams with only one adapter——seemingly decoupled, but actually just adding a layer of synchronization cost
Writing single-feature internal details into the roadmap (how a module divides files internally / which library to use)——that belongs to feature-design
Unbalanced granularity——one item can hold three independent features, while another only changes a config
Relying on guesswork for dependencies——unable to explain why the dependency exists
Prioritizing on the user's behalf
Not stopping when conflicting with existing req / arch——choosing one side yourself and masking the real disagreement
Doing multiple roadmaps at once
Conveniently modifying req / arch
Directly deleting dropped items——history is lost
The roadmap drifting into writing a detailed plan for a single sub-feature
Changing interface contracts in an update without assessing the impact on existing items——no one sees that a feature already in-progress / done has had its contract changed
Skipping cs-roadmap-review and letting the user decide directly——the user can only see the surface of the plan, not the independent review conclusions on interfaces, dependencies, and acceptance strategy