cs-feat

cs-feat

Required reading at startup

Before starting any judgment or action, first run CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read external AI entry points as a substitute (see .codestable/reference/execution-conventions.md）。

The new-feature flow inserts a design document between "requirements" and "code," giving the two sides a handoff point—if AI writes code directly upon receiving requirements, three old problems arise: names don't match the original code, scope creeps during changes, and no archive is left after the changes.

(想法模糊先去 cs-brainstorm 分诊) → 方案设计（名词层 + 编排层 + 验收契约 + 推进策略切片）→ 分步实现 → 代码审查 → QA 验证 → 验收闭环

brainstorm is an independent entry point at the discussion layer, and will triage: case 1 (clear → directly design) / case 2 (small requirement, continue discussing → produce brainstorm note) / case 3 (large requirement → hand over to cs-roadmap). Only case 2 produces a brainstorm note in the feature directory.

This skill does not write code or documents; it does only one thing: see which step the current feature is at, and tell the user which sub-skill to trigger.

Where files go

.codestable/features/{feature}/
├── {slug}-brainstorm.md       ← 阶段 0 产物（仅 case 2 落盘）
├── {slug}-intent.md           ← 阶段 1 可选前置草稿（用户自己写半成品）
├── {slug}-design.md           ← 阶段 1 方案文件
├── {slug}-design-review.md    ← 阶段 1.5 人审前方案审查报告
├── {slug}-checklist.yaml      ← 阶段 1 生成 steps + checks，2/3 阶段更新 status
├── {slug}-review.md           ← 阶段 2.5 代码审查报告
├── {slug}-qa.md               ← 阶段 2.6 QA 验证报告
└── {slug}-acceptance.md       ← 阶段 3 验收报告

Directory naming YYYY-MM-DD-{英文 slug}, the date is set to the day of first creation and does not change; slug uses lowercase letters / digits / hyphens.

Why keep them together: later, when checking "how was that export CSV feature decided at the time," brainstorm / design / review / QA / acceptance are all in one place. feature and issue are placed in .codestable/features/ and .codestable/issues/ respectively because the archiving logic is different.

Bugs found incidentally while implementing a feature → record as a new issue,do not sneak-fix them in the feature PR—at acceptance time the scope cannot be distinguished, and git blame cannot find why it was changed.

Standard stages

Stage	Sub-skill	Output	Who leads
0 brainstorm (optional, independent entry point)	`cs-brainstorm`	Produces a brainstorm note in case 2	AI thinking partner, user makes the call
1 Solution design	`cs-feat-design`	design.md + checklist.yaml	AI drafts candidate solutions
1.5 Solution review	`cs-feat-design-review`	design-review.md	Task agent / AI review before human review
2 Step-by-step implementation	`cs-feat-impl`	Code + stage reports	AI executes according to the plan
2.5 Code review	`cs-code-review`	review.md	AI read-only review, user decides whether to fix
2.6 QA verification	`cs-feat-qa`	qa.md	AI runs evidence, user confirms risk
3 Acceptance closure	`cs-feat-accept`	acceptance.md	AI checks layer by layer, user gives final approval

There are gates and human checkpoints between stages. The plan first goes through design-review, then is handed to the user for overall confirmation; if the user has not explicitly given the go-ahead, do not start the next stage—this prevents AI from running all the way from requirements to code in one breath and only discovering it went off track after running it.

Stage 0 is optional and is the feature flow'sexternal entry point——cs-brainstorm It serves both feature and roadmap. In case 3 (large requirement), the discussion is handed over to cs-roadmap and no longer returns to the feature flow; after roadmap splits out a sub-feature, it enters from cs-feat-design 's "start from roadmap item" entry.

Fastforward mode

When requirements are clear + the scope is small, the standard flow is too verbose. fastforward compresses design into 4 sections (requirements summary / design plan / acceptance criteria / advancement steps), and after one confirmation by the user, implementation starts directly. Trigger: "quick mode", "fastforward", "just start working", "not so many steps"; go to cs-feat-ff。

Do not go fastforward: spans multiple subsystems, carries terminology conflict risk, and involves more than 4 advancement steps — in these cases, skipping design means the AI and the user have never jointly confirmed the same plan, and after implementation it is easy to discover that each side understood it differently.

Routing: which sub-skill the user should go to now

Upon entering this skill, first Glob .codestable/features/ to see existing artifacts.Do not just listen to the user's verbal description— the user saying "the design is finished" does not necessarily mean it is actually complete; read it yourself.

Current state	Which sub-skill is triggered
The idea is vague; cannot clearly state the real problem / boundaries / what not to do	`cs-brainstorm`
The idea is clear (knows what to do / for whom / how success is measured)	`cs-feat-design`
The user says "start a new requirement / draft / create new feature" and wants to write a half-finished version themselves	`cs-feat-design` 's "initialization mode" (create directory + empty intent, let the user fill it in and then come back)
The user proactively says "brainstorm first" or "I have an idea that is not fully thought through"	`cs-brainstorm`
`{slug}-intent.md` is already filled in	`cs-feat-design`(read intent as input)
The user says "fast mode / fastforward"	`cs-feat-ff`
`{slug}-brainstorm.md` already exists, and you need to enter design	`cs-feat-design`
`{slug}-design.md` is draft and there is no `{slug}-design-review.md`	`cs-feat-design-review`
`{slug}-design-review.md` changes-requested / blocked	`cs-feat-design` after revision, rerun `cs-feat-design-review`
`{slug}-design-review.md` passed, but design has not yet been approved	Hand it to the user for an overall review; after confirmation, return to `cs-feat-design` mark approved
`{slug}-design.md` is already approved, code has not been touched	`cs-feat-impl`
fastforward design has been confirmed	`cs-feat-impl`
Code has been written but there is no `{slug}-review.md`	`cs-code-review`
`{slug}-review.md` has unresolved blocking findings	`cs-feat-impl` 's review-fix mode
`{slug}-review.md` has passed, but there is no `{slug}-qa.md`	`cs-feat-qa`
`{slug}-qa.md` failed / blocked	`cs-feat-impl` 's qa-fix mode (after fixing, rerun review → QA)
`{slug}-qa.md` has passed, and the code needs acceptance	`cs-feat-accept`
The user directly says "the code is written and needs acceptance" but there is no review report	First `cs-code-review`, do not jump to accept
The user directly says "the code is written and needs acceptance" but there is no QA report	After review passed, first `cs-feat-qa`, do not jump to accept
The user says "I want an X system" as a large requirement	Switch to `cs-brainstorm` triage (high probability case 3 → `cs-roadmap`）
A certain sub-feature in the roadmap should be started	`cs-feat-design` 's "start from a roadmap item" entry point
Unsure whether the design is complete	Read it yourself, and match it against the above

How to determine whether stage 0 should be followed

The judgment signal is not "the user's description has few words", but whether the user can clearly state three things: the real problem to be solved / the core behavior / one explicit "what not to do". If any one of the three is vague, it is worth brainstorming.

But do not push hard — if the user clearly says "I have thought it through, go straight to design", respect that. When unsure, ask a question and let the user choose.Better to miss a judgment than to misjudge— forcing a user who has thought it through to diverge is a waste.

brainstorm vs intent

Both are prerequisites for design; the difference lies inwho is leading convergence：

brainstorm: the user's mind is vague; the AI asks, the user answers. When judging case 3, hand over to cs-roadmap and do not return to feature; only case 2 produces a brainstorm note
intent: the user has already thought out the general approach (100-word description + related data structures), and if they can't be bothered to say it out loud, they write it as {slug}-intent.md for the AI to read

When the user vaguely triggers "start a new requirement", by default ask "do you want to talk it through first (brainstorm) or write a draft yourself (intent)?" Don't decide for them.

Boundary with the issue workflow

feature: something that never existed needs to be added (new feature / new capability)
issue: something that should have been fine is broken (bug / anomaly / documentation error)

Gray area: bugs found while implementing a feature are recorded as a new issue, not fixed casually in the feature PR.

About this skill