Required reading before starting
Before starting any judgment or action, first execute CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read external AI entry points as a substitute (see details in .codestable/reference/execution-conventions.md）。
cs is the unified entry point for the CodeStable workflow family. When the user speaks, there is a high probability they will not name a specific cs-xxx—they may only say "I want to add permission validation", "there is a bug here", "introduce codestable", or even just send a cs. This skill is responsible for catching open-ended input, clarifying intent, and routing to the right sub-skill.
Two things, only these two：
- The user brings a specific request → match the scenario routing table, tell the user which
cs-*should be triggered, and briefly explain why - The user wants to understand the system / cannot clearly say what they want to do → provide a concise system quick read + let the user choose or describe a more specific request
This skill does not do the work: it does not write specs / does not read or write content artifacts under .codestable/ / does not run the process on behalf of sub-skills. The only output is "which sub-skill is recommended to trigger".
Scan to perform first upon receiving a call
Perform every time before responding (a few tool calls are enough):
- Check whether the repository has onboarded CodeStable——
Glob .codestable/check the top-level directory - Exists—must first
Read .codestable/attention.md(if missing, indicate the skeleton is incomplete; first complete it or reruncs-onboard); thenRead .codestable/reference/system-overview.md(if present);Globbriefly checkfeatures/issues/roadmap/to see work in progress (getting the directory names is enough; do not read each file thoroughly) - Does not exist—later prompt the user to first go through
cs-onboard - Look at the user's original words—open-ended or with a specific request? If with a request, match the routing table; if no request, give a system introduction
Only respond after scanning. Make the user feel you have a clear picture.
One-diagram quick read of the system (say this when the user has no specific request / asks you to introduce it)
CodeStable models development activities as 8 entities + 4 flows, with all artifacts gathered in .codestable/：
.codestable/
├── requirements/ 需求 + 领域模型（VISION + capability + CONTEXT.md + adrs/）
├── roadmap/ 规划层（roadmap / roadmap-review / goal 执行包）
├── goals/ 目标实体（限定起点/终点，自主迭代 + Task agent 功能验收）
├── features/ 新增能力 spec 聚合根（design / design-review / impl / review / qa / accept）
├── issues/ 修 bug spec 聚合根（report / analyze / fix）
├── refactors/ 重构 spec 聚合根（beta）
├── audits/ 审计实体（主动扫描发现清单，不定修）
└── compound/ 知识沉淀（cs-keep 写自由 markdown，grep 检索）
Four flows：
- Add capability：
cs-feat-design→cs-feat-design-review→cs-feat-impl→cs-code-review→cs-feat-qa→cs-feat-accept(if the idea is vague, first docs-brainstormtriage) - Goal achievement：
cs-goal(define start/end → interview/grill to write the starting-point report → autonomous implementation/validation/iteration → Task agent functional acceptance before completion) - Fix bug：
cs-issue-report→cs-issue-analyze→cs-issue-fix - Refactor（beta）：
cs-refactor/cs-refactor-ff
Cross-cutting: before commit, go through cs-code-review independent review; after the process finishes, if you find something "worth recording" → cs-keep precipitate it into compound/(pure markdown, grep searchable).
Core philosophy: what is orchestrated is the lifecycle of the software itself (requirements, domain model, features, bugs, decisions), not the Agent. Human in the loop—the programmer is responsible for overall control, and AI is an efficient execution body.
If the project has already been onboarded, for a more detailed overview see
.codestable/reference/system-overview.md。
Scenario routing table
Match the user's words to a row in the table, and tell the user: "For your request, it is recommended to go through cs-xxx, because {one-sentence reason}".
Route Governance
cs must remain lightweight and only do routing, but every route should explain the governance boundary. The default output is a short route brief:
Route: {目标 skill 或阶段}
Context: {L0-L4}
Reason: {为什么这条路由合适}
Not routing to: {排除的相邻流程，如有歧义}
Escalation: {什么情况会抬升 context level}
Next: {用户该触发什么，或这条路由会决定什么}
Context level only explains weight,cs stage does not generate heavy artifacts:
- L0: pure state / validation / sync.
- L1: local, reversible, does not change long-term intent.
- L2: requires owner to choose, authorize, accept, defer, or sign off.
- L3: changes the long-term spec, future agent inputs, capability boundary, or public contract.
- L4: old spec drift, conflict, unclear source-of-truth, requires inventory / rehabilitation.
When L2/L3 requires owner approval/choice/authorization/risk acceptance, the sub-process first follows .codestable/reference/approval-conventions.md to write in the corresponding unit approval-report.md(waived if the stage report for design / issue analysis / acceptance, etc. already carries the approval context).cs itself usually only routes; the only exception: when the route choice itself requires an owner choice and there is no clear unit, treat it as an intake decision and write .codestable/brainstorms/{slug}/approval-report.md then owner-stop; do not give only a chat-only brief.
Escalation triggers: requires owner judgment on direction/authorization/risk acceptance/finish-merge readiness; may change long-term requirement / architecture / roadmap / decision / guide / skill; fast path discovers capability boundary / public contract / future-agent instruction / spec drift; old documents conflict or it is uncertain which is canonical. If routing is uncertain, stop according to the above rules and let the user choose; do not guess.
| What the user says / wants to do | Route to |
|---|---|
The repo does not yet have .codestable/ |
First cs-onboard— all other cs-* depend on this directory |
| Limit the start and end points / clarify acceptance results / "help me achieve this goal" / "iterate autonomously until complete" / "grill me then start" | cs-goal(start / iteration report; implementation is driven autonomously by AI; Task agent functional acceptance before completion) |
| The idea is still vague / "I have an idea but have not thought it through" / "let's talk first" / "not sure if it is a new feature" | cs-brainstorm(after triage, route to design / feature-brainstorm for persistence / roadmap) |
| New feature / "add an X" / "implement XX" | cs-feat(route design / ff / impl / accept) |
| BUG / anomaly / error / "this is wrong" / "the docs are wrong" | cs-issue(route report / analyze / fix) |
| Code optimization / refactoring / rewriting (behavior unchanged) | cs-refactor / cs-refactor-ff |
| Review the system / scan for bugs / audit code / "what problems are there" / "where can it be optimized" | cs-audit(proactive scanning for discovery, only list findings and do not decide fixes) |
| Add / update requirement documents | cs-req |
| Make technical decisions / add domain terminology / the project needs to be divided into subsystems | cs-domain |
| Large requirement decomposition / "I want an X system" / scheduling planning / module decomposition + interface contracts | cs-roadmap |
| Planning review before manual roadmap confirmation / "review this roadmap" | cs-roadmap-review |
| Advance an existing roadmap / execute the entire roadmap / "continue the roadmap" / "use goals to steadily advance the roadmap" | cs-roadmap-impl-goal |
| Solution review before manual feature design confirmation / "review this design" | cs-feat-design-review |
| Review before merging / "code review" / "code review" / prepare PR / merge | cs-code-review(perform an independent review of the current diff, quality gate) |
| Terminology / domain model / architecture decision (ADR) / "which context does this belong to" | cs-domain |
| Code exploration research / pitfall retrospective / technology selection / long-term constraints / coding conventions / reusable patterns / library usage / "worth recording" | cs-keep |
| One or two lines of project notes / special build settings / command pitfalls / "record to attention.md" | cs-note |
| Developer guide / user guide | cs-doc-tutorial |
| Library API reference | cs-doc-api |
Phase wrap-up / organizing docs / syncing CLAUDE.md or AGENTS.md / onboarding a newcomer |
cs-docs-neat |
| User asks "what's next" in the middle of a feature / issue flow | Route to the corresponding entry point (cs-feat / cs-issue), letting that entry point determine the current phase |
Cannot determine / too abstract: "Sounds like {guess}, but in your description {what's missing}. Is it {option A} or {option B}?" Let the user choose; don't guess.
Route Level Quick Reference
| Route | Default context | Escalate when |
|---|---|---|
cs-onboard |
L2/L4 | Legacy docs need inventory, migration, or trusted/stale classification |
cs-goal |
L1/L2 | Missing acceptance/starting state requires grill + starting-state report; completion requires a Task agent functional acceptance; spec/public contract changes or repeated blockers → owner-stop |
cs-brainstorm |
L1→L2 | Owner accepts a direction or wants the next executable item |
cs-roadmap / cs-roadmap-review / cs-roadmap-impl-goal |
L2/L3 | Roadmap involves spec changes, capability boundaries, or requirement deltas |
cs-feat |
L1 | Phase unclear or user must choose design / ff / impl / accept |
cs-feat-design / cs-feat-design-review |
L2/L3 | Design touches long-term specs or future agent input |
cs-feat-impl |
L0/L3 | Implementation deviates from confirmed design/checklist/spec |
cs-code-review / cs-feat-qa |
L1/L3 | Review/verification finds behavioral deviations, contract or spec impact |
cs-feat-accept |
L3 | Acceptance writes to or validates long-term architecture / requirement / roadmap / finish readiness |
cs-feat-ff |
L1/L3 | Fast track finds capability-boundary, public contract, or spec impact |
cs-issue / cs-issue-report |
L1 | Routing unclear or reproduction/impact needs owner confirmation |
cs-issue-analyze |
L2 | Owner must choose a fix approach or accept the risk |
cs-issue-fix |
L0/L3 | Fix exposes a wrong spec, capability boundary, or public behavior change |
cs-refactor / cs-refactor-ff |
L1/L2 | Cross-module, risky, or uncertain behavioral boundaries |
cs-code-review |
L1/L3 | Review finds Critical/Important or touches long-term spec / public contract |
cs-req |
L3 | Always: requirements work changes the future agent's source-of-truth |
cs-domain |
L1/L3 | code/doc/intent conflict appears |
cs-audit |
L1/L2 | Owner must decide fix / defer / ignore |
cs-keep |
L1/L3 | Distillation escalates to a decision / rule / spec change or long-term constraint |
cs-note |
L1/L2 | Experience escalates to a standing instruction |
cs-doc-tutorial / cs-doc-api / cs-docs-neat |
L1/L2 | Docs change user-facing contracts or public understanding |
codestable-maintainer |
L2/L3 | Modify CodeStable's own skills/harness/installed copy |
Several situations requiring special attention
Repo not yet onboarded
Any cs-* flow but .codestable/ doesn't exist → point this out with a suggestionFirst cs-onboard. Do not route directly to cs-feat / cs-issue—their SKILL.md files all assume .codestable/ already exists.
Large requirement mistaken for a feature
Requests like "I want a permissions system / notification center / SSO integration" that areobviously not completable as one feature → do not route to cs-feat, route to cs-brainstorm(most likely judged case 3 → cs-roadmap) or directly to cs-roadmap. Reason: starting a feature directly will become a giant design that doesn't fit.
"Change X" but X is an existing feature
First ask whether this is a bug fix(X currently behaves incorrectly) or a requirement change(X currently behaves correctly, but the policy has changed):
- bug →
cs-issue - Requirement change →
cs-reqchange requirement doc + thencs-featrun implementation
Work in progress
Scan and see features/ or issues/ already has a related directory under it → mention "I see features/2026-04-22-xxx/ already exists, should we continue with this?" and let the user confirm whether to continue or start something new.
Two entry points for accumulation
- Write to
.codestable/compound/a standalone markdown (pitfalls / tips / decisions / research, searched via grep) →cs-keep - one or two persistent lines saying "the CodeStable skill must know X every time it starts" (write to
.codestable/attention.md）→cs-note
If you can't tell, ask the user: "Should this be written as a standalone doc (cs-keep), or one or two lines that must be read at startup (cs-note)?"
Introduction mode (the user only says they want to learn / doesn't know what to do)
Explain in this order,don't dump everything at once：
- In one sentence: CodeStable is an AI coding workflow for serious engineering, orchestrating the software lifecycle rather than the Agent
- Quick-read diagram of 9 entities + 4 flows
- Ask the user "where do you most want to start right now?", and give three prompts:
- "I have a new feature I want to build" → cs-feat
- "There's a bug in the code" → cs-issue
- "The project hasn't onboarded CodeStable yet" → cs-onboard
Stop there, don't explain every sub-skill detail. Expand only if the user asks about something specific.
Exit
This skill has no "write to disk". There is one exit condition:
- has already told the user which specific
cs-*sub-skill to trigger next (or confirmed the user is only here to learn and doesn't want to do anything)
Output looks like:
For your request, I suggest going with
cs-xxx——{one-sentence reason}. After triggering, it will {briefly describe what will happen: it will first scan existing specs / it will ask you to describe first / it will enter triage / ...}. Switch tocs-xxxnow?
Things not to do
- Don't read or write
.codestable/content artifacts——those are the sub-skills' job - Don't make decisions on behalf of sub-skills——don't do brainstorm triage in this skill, don't decide for cs-domain whether to write an ADR
- Don't recommend multiple skills at once——point to only one path each time; two independent requests go in two rounds
- Don't repeat system overview details——
.codestable/reference/system-overview.mdis the authoritative complete version - Don't bypass
cs-onboard——if the repo hasn't onboarded, onboard first