cs-feat
New feature development is the most complete workflow in CodeStable. When AI directly writes code upon receiving requirements, three recurring problems arise — inconsistent naming with the original code, scope creep during modification, and no archived records after changes. This workflow inserts a solution document between "requirements" and "code" to create a handoff point for both sides.
The entire workflow is as follows:
(Go to cs-brainstorm for triage when the idea is still vague) → Solution Design (including test design) → Phased Implementation → Acceptance Closure
Brainstorm is not part of the feature workflow itself — it is a unified entry point for the discussion layer, which first performs triage: whether you fall into case 1 (clear enough to directly enter design), case 2 (small requirement with a defined direction, continue discussion within the feature and produce
), or case 3 (large requirement that cannot fit into a single feature, hand over to
for decomposition). Only case 2 will actually produce a brainstorm note in
codestable/features/{feature}/
.
This skill itself does not write code or documents; it only does one thing: check which stage the current feature has reached and tell the user which sub-skill to trigger next.
Where to Store Files
All artifacts of the entire feature workflow are gathered under
, with an independent directory for each feature:
codestable/
└── features/
└── {feature}/
├── {slug}-brainstorm.md ← Artifact of Phase 0 (optional, only saved when brainstorm judges it as case 2)
├── {slug}-intent.md ← Optional draft for Phase 1 (semi-finished solution written by the user)
├── {slug}-design.md ← Solution document for Phase 1 (with YAML frontmatter + test design)
├── {slug}-checklist.yaml ← Generated during Phase 1, updated in Phases 2/3
└── {slug}-acceptance.md ← Acceptance report for Phase 3
- The date is taken from the day of first creation and remains unchanged — even if the slug is modified later, the date prefix stays the same
- The slug uses lowercase letters, numbers, and hyphens, and is short enough to clearly indicate what the feature is (such as , )
Why gather all artifacts in one directory? This way, when you later check "how we decided on that CSV export feature last time", the brainstorm, design, and acceptance documents are all in one place, eliminating the need to search around. This is also why feature and issue artifacts are stored separately in
and
— the archiving logic for the two types of issues is different, and mixing them will make it messy to find things later.
If you find a bug while implementing a feature, the correct approach is to record it as a new issue, do not secretly fix it in the feature's PR. Mixing changes will make it unclear "what exactly is the scope of this new addition" during acceptance, and later you won't be able to find why that line of code was modified.
Four Phases
| Phase | Sub-skill | Output | Lead |
|---|
| 0 Brainstorm (optional, independent entry) | | Produces {slug}-brainstorm.md for case 2; no output for case 1 / 3 | AI acts as a thinking partner, user makes the final call |
| 1 Solution Design | | {slug}-design.md + {slug}-checklist.yaml | AI drafts, user conducts overall review |
| 2 Phased Implementation | | Code + phase reports | AI executes according to the solution |
| 3 Acceptance Closure | | {slug}-acceptance.md | AI checks layer by layer, user makes the final approval |
There are manual checkpoints between phases. Why set these? First, to give the user a clear gatekeeping opportunity at the end of each phase; second, to prevent AI from jumping directly from requirements to code, only for the user to discover deviations after implementation. Therefore, by default, the next phase should not start until the user explicitly approves the previous phase.
Phase 0 is optional and is an
external entry point to the feature workflow —
serves both feature and roadmap. Only use it when the idea is clearly vague; start directly from Phase 1 when you can clearly state "what to do, for whom, and how to define success". When brainstorm judges it as case 3 (large requirement), the discussion will be handed over to
and will not return to the feature workflow — after the roadmap breaks down into sub-features, each sub-feature will enter through the "start from roadmap item" entry of
.
Fastforward Mode
When requirements are clear and the scope is small, going through the full four phases can be tedious. In such cases, use fastforward:
User states requirements → AI writes a simplified {slug}-design.md (including acceptance criteria) → User confirms once → Direct implementation
Trigger: When the user says phrases like "fast mode", "fastforward", "start directly", "skip the steps", trigger
.
The
for fastforward shares the same feature directory as the standard workflow, and the frontmatter is consistent, but the body is compressed into 4 sections (requirement summary + design solution + acceptance criteria + implementation steps). The acceptance criteria must be written here without placeholders — because they will be directly extracted during the acceptance phase later.
When not to use fastforward: When the requirement spans multiple subsystems, has a risk of terminology conflicts, or has more than 4 implementation steps. In these cases, advise the user to follow the standard process. The reason is that as the scope expands, skipping the design phase means AI and the user have not jointly confirmed the same solution, which often leads to discrepancies in understanding after implementation.
Routing: Which Sub-skill Should the User Trigger Now
After entering this skill, first Glob
to check existing artifacts.
Do not rely solely on the user's verbal description — the user saying "design is completed" does not necessarily mean it is truly complete; you must read it yourself to be sure.
| Current Status | Trigger Which Sub-skill |
|---|
| Vague idea, unable to clearly state the real problem / boundaries / what not to do | (see below for judgment method) |
| Clear idea (knows what to do, for whom, and how to define success) | |
| User says "initiate a new requirement / draft a sketch / create a new feature" and wants to write a semi-finished solution themselves | "Initialization mode" of (create directory + empty , let the user fill it in before returning) |
| User actively says "let's brainstorm first" / "have an unclear idea" | |
| exists and is filled out, user says ready to enter design | (read intent as input) |
| User says "fast mode", "fastforward", etc. | |
| exists, user says ready to enter design | |
| is approved, code not yet started | |
| Fastforward is confirmed | |
| Code is completed, needs acceptance | |
| User says something like "I want an X system" (large requirement) | Transfer to for triage (most likely judged as case 3 → ) |
| A sub-feature in the roadmap is ready to start | "Start from roadmap item" entry of |
| Unsure if is complete | Read it yourself and match to the above |
How to Judge Whether the User Should Go Through Phase 0
The judgment signal is not "the user's description is short", but whether the user can clearly state these three things:
- What is the real problem to solve
- What is the core behavior perceived by the user
- Is there a clear "what not to do"
If any of the three is vague, brainstorm is worthwhile. But do not force it — respect the user's judgment if they clearly say "I've thought it through, proceed directly to design". Ask the user to choose if unsure. It's better to miss a judgment (let the user enter design directly) than to make a wrong judgment (force a user who has thought it through to do what they consider unnecessary divergence).
How to Choose Between Brainstorm and Intent
Both are prerequisites for design, and the difference lies in who leads the convergence:
- Brainstorm: The user's idea is still vague, hoping to clarify through dialogue, with AI asking questions and the user answering. Note: Brainstorm is an independent entry point that first performs triage; when judged as case 3 (large requirement), the discussion will be handed over to and will not return to the feature workflow. Only case 2 (small requirement) produces
- Intent: The user has already thought out the general approach (such as a 100-word description + related data structures), but is too lazy to dictate it, so writes it directly into for AI to read
When the user triggers with vague phrases like "initiate a new requirement", default to asking "Do you want to clarify through discussion (brainstorm) or write a draft yourself (intent)?", do not choose one to proceed on your own.
Boundary with Issue Workflow
- Feature handles "adding something that never existed" — new functions, new capabilities
- Issue handles "something that should work but is broken" — bugs, exceptions, documentation errors
The gray area has been mentioned earlier: bugs found during feature implementation should be recorded as new issues, not fixed in the feature PR.
Related Documents
codestable/reference/system-overview.md
codestable/reference/shared-conventions.md
- — Full project code specifications, which also apply during feature implementation
- Project architecture entry point — Needed during the solution design phase