CodeStable is a methodology for understanding and advancing software evolution. It uses Vision, Project Spec, Epic, Issue, and codestable/ institutional memory to connect goals, reality, and action; itis nota mandatory pipeline, nor an Agent orchestrator.
Invoking cs does not mean running the full process. First determine whether the user at this moment wants to discuss, understand, design, implement, or wrap up, then adopt a matching level of management intensity.
Communication style: conclusion first, then elaboration
First use the words the user is currently using to briefly state theconclusion and reason. Only expand on frameworks, rules, and details when a trade-off needs to be made, authorization needs to be obtained, or verification and risk evidence must be shown. Brevity does not mean omitting key judgments; rather, first make it easy for the user to understand, then drill down as needed.
Save context (Codex)
In the same session, for SKILL.md, references, templates, or adjacent notes that have already been fully read and have not changed, you must reuse existing understanding and not read them again. Only read the relevant minimal scope when the user asks for a reread, the file has changed, or the current understanding is insufficient to support a judgment.
1. Determine the stance first
From the user's original words and context, chooseone primary stance. Once chosen, immediately read the "required reading," then begin acting; do not pre-read stance files that were not triggered.
| Primary stance | Users often say | Required reading | Read as needed | Default boundary |
|---|---|---|---|---|
| Onboarding | Initialize cs, onboard CodeStable, fill in codestable/ |
onboard | — | Must have explicit authorization; do not fabricate business content |
| Discussion | Chat, clarify first, think it through before doing, help me plan | talk | docs; specific changes → quality；UI → ui-spec | Do not write to disk before user confirmation, and do not create an issue, epic, or vision |
| Vision | What the application will look like in the future, organize vision, product overview | vision | docs; quality direction → quality；UI → ui-spec | Only write the vision after confirmation; do not force creation of development items |
| Spec | Maintain spec, current truth, epic living spec | spec | docs; quality constraints → quality；UI → ui-spec | Only write conclusions that still hold |
| Understand the current state | How it works, this链路, scope of impact | explore | docs; serve specific changes → quality | Explain the current state first; only create an Explore Issue when it is complex and worth reusing |
| Fix bug | Broken, does not meet expectations, debug, fix this bug | complain | debug、economy、quality; structure → code-design | For simple problems, default to a quick fix and leave behind ff; complex problems may be advanced in a managed way |
| Design | How to implement, design first, implementation plan | design | code-design、economy、quality；UI → ui-spec | Do not write code; for high risk, arrange the spike order first |
| Fast delivery | Fast, quick fix, make a small change, just start, skip the process | fast | economy; if necessary quality；UI → ui-spec | Default to light retrieval, verification, and leaving ff; omit only when the user explicitly asks for no trace ff |
| Managed implementation | Do this issue, advance the epic, implement (with documentation), spike / get it working first | do | code-design、economy、quality; current state unclear → explore；UI → ui-spec | Done does not equal closed; spike risks first, then thicken |
| Wrap-up | Close, wrap up, finish and consolidate, graduate and write back | close | docs、quality; bounded simplification → economy | Closing requires user authorization; do not automatically move into done/ |
| Review code | review, code review, take a look at this diff/PR | code-design(Review at the end) | economy; when relevant → quality | Do it only when the user names it; by default only review, do not modify |
| Record knowledge | Note down the pitfall, write a note | note | docs | Update the original note on the same topic, do not create duplicates |
| Learn a process | I'll walk you through it, teach the AI to do a process | maketools | docs | Confirm again before dangerous operations |
How to determine the stance
- The user's own words and authorization take precedence over "it looks like it should go through a heavy process."
- The task is small, the goal is clear, the user wants speed, and no documentation was requested → Quick delivery。
- The goal is vague or the trade-offs are undecided → Discussion; after talking it through, switch to stances such as quick delivery, managed implementation, vision, etc.
- There is already a regular Issue, or the user names an Issue / Epic → Managed implementation, with design first if necessary.
- Existing behavior is broken → Fix bug; new capability → quick delivery or managed implementation, not classified as Complain.
- The user only asks how the system works → Understand current state, do not start modifying by default.
- The intent is unclear, and choosing wrong would materially change what follows, e.g. whether to create an Issue or whether to change code → give a one-sentence recommendation and reason, and ask the user to choose; do not default to a heavy process.
- Writing or modifying Agent skills themselves is not part of CodeStable's responsibilities.
Choose the level of management
| Situation | Default choice |
|---|---|
| Small, low-risk, completable in one go, or the user explicitly wants speed | Quick fix; after completion leave ff, see fast |
| The user explicitly wants no trace or no Issue written | May leave no ff; if the existing truth becomes invalid, spec must still be synced or the drift marked |
| Involves scope trade-offs, multiple rounds of advancement, handover, significant risk, or a long-term quality commitment | Createregular Issue：type: feature|bug|chore|refactor |
| Cross-module, multiple batches, and the spec will continue to evolve within the boundary | Create Epic; slices with a sufficiently clear boundary can be advanced directly within the Epic |
| Technical, integration, or migration risk needs feasibility proven first | Do firstspike, see do, then thicken the implementation |
| The user explicitly requests management or explicitly wants no documentation | Follow the user's choice |
2. World model and workspace
From goals to reality
Vision Spec（目标世界）
│ 摘取一段有界变化
▼
Epic Spec（变化中的活规格） ──推进──> Epic Issues
│ Epic 关闭后毕业
▼
Project Spec（当前现实）
独立 Issue ─────────关闭毕业────────> Project Spec
Vision holds the target world; an Epic carries a bounded major change; an Issue is a closable action; a Project Spec holds only the reality that still holds.
Relying only on Issues loses direction; relying only on a Project Spec cannot accommodate mutually exclusive ideas; mixing future and reality loses temporal boundaries; and a giant Issue is hard to close. Therefore, write only informationworth preserving across sessionsinto codestable/, and place it where it bears the corresponding responsibility.
codestable/ workspace map
CodeStable's institutional memory is stored uniformly under the project's codestable/ .
codestable/
├── vision/ 目标世界、旅程与候选方向
│ ├── index.md Vision 地图
│ └── ... 按旅程或能力展开
├── spec/ 当前稳定真相
│ ├── index.md Project Spec 地图
│ └── ... 按场景或能力展开
├── epics/ 有界的大变化；本树独立编号
│ ├── EEE-o|x-{Epic名}/
│ │ ├── spec.md 该 Epic 唯一权威的活规格
│ │ └── issues/ 只属于该 Epic 的 issues 树
│ └── done/ 用户主动整理后的已关闭 Epic
├── issues/ 不属于单个 Epic 的独立 issues 树
├── notes/ 可复用知识；本树独立编号
│ └── NNN-{主题}.md
├── talks/ 尚未落定的讨论；本树独立编号
│ └── NNN-{议题}.md
└── tools/ 稳定、可重复执行的流程工具
└── ... 说明、脚本及其所需资源
The root issues/ and the issues/ within each Epic use the same structure, but are numbered independently:
issues/
├── NNN-o|x-{事项}.md 常规 Issue
├── NNN-o|x-ff-{事项}.md 快改记录
├── NNN-o|x-{探索名}/ Explore Issue
│ ├── index.md 认知地图、边界、结论与毕业位置
│ └── *.md 按「触发→结果」组织的路径文章
└── done/ 可选整理区；仍参与检索和编号
In the diagram, o|x means take o(open) or x(closed), not a literal character in the path. The path expresses unique belonging: items that belong to only one Epic go into that Epic's issues/, and the rest stay in the root issues/. Regular Issues and ff are single files; only Explore Issues that need an independent investigation workspace use directories. An Epic's issues/ is created only when the first item belonging to it is created.
done/ is only a storage location after the user actively organizes things, not a new lifecycle state. Closing does not automatically move an item;done/ content still participates in retrieval and numbering.
This diagram is a locating map, not a required reading list for every task. Drill down layer by layer according to the current stance and keyword hits, and read only the local part sufficient to support judgment.
What each entity answers
| Entity | Question answered |
|---|---|
| Vision | What the application should ultimately become; what journeys, capabilities, and candidate or mutually exclusive directions exist |
| Project Spec | What stable facts of the project still hold; organized by scenario and capability, not by code directory |
| Epic | What this bounded major change has already determined, what is still changing, and what can be advanced next |
| Issue | Which specific action is to be completed and closed; the physical location expresses unique belonging |
Fast Fix (ff) |
What this small change did, where it changed, how to verify it, and whether it affects institutional memory |
| Explore Issue | What a complex, stoppable, reusable investigation of the current state concluded; simple understanding only does current-state explanation, and no item is created |
| Talk | How an issue that is not yet settled is raised, corrected, and converged, and where the recommendation should continue from |
| Note | Which knowledge, evidence, steps, and pitfalls are still worth reusing in the future |
| Tool | Which process that has already run through is stable enough to be executed repeatedly, and which dangerous boundaries still need to be guarded |
Paths, naming, and numbering
Each numbering tree is numbered separately: the root issues/, and each Epic's issues/、epics/、notes/、talks/ all start from the largest existing leading number in this tree (contains done/) plus 1. Numbers are at least three digits; after exceeding 999, continue using 1000、1001, with no upper limit.
An Issue number is not a global identity. When referencing an Epic Issue, you must give the full path, or write it as Epic NNN / Issue NNN。
| Form | Path |
|---|---|
| Independent Issue | codestable/issues/{NNN}-o|x-{名}.md |
| Epic Issue | codestable/epics/{EEE}-o|x-{epic}/issues/{NNN}-o|x-{名}.md |
| Quick change | Under the owning issues tree {NNN}-o|x-ff-{名}.md；type: ff; template ff-issue.md |
| Explore Issue | Under the owning issues tree {NNN}-o|x-{名}/index.md |
| Epic | codestable/epics/{NNN}-o|x-{名}/spec.md; each Epic has only one authoritative spec |
| Organized items | Under the corresponding issues tree, done/ keep the file or directory with the same name |
| Under the organized Epic, | codestable/epics/done/ keep the directory with the same name |
| Talk / Note | {NNN}-{名}.md, do not use o、x or ff |
Ownership is determined by path:
- An Issue belonging to only one Epic must go into that Epic's
issues/。 - An Issue not belonging to any Epic stays in the root
issues/。 - Items spanning multiple Epics must not be arbitrarily attached to one of them; they should remain as independent Issues, or be escalated to an Epic.
ff, bugs, features, chores, refactors, and Explore Issues all follow the same ownership rule.- New Issues no longer use
epicfrontmatter to express ownership. When ownership changes, move the original item and update explicit references; do not create a second copy.
In the old version, located at the root issues/, relying on epic frontmatter-associatedclosed Issues remain valid and are not automatically migrated. Old Issues still in progress should be moved into their owning Epic on the next substantive update: prefer keeping the original number; if the number conflicts, use the next number in that Epic's issues tree and update explicit references.
When closing an Issue, change the -o- in the target path to -x-, keeping the number and name unchanged, and change status to closed. When closing an Epic, only change the Epic directory name; internal Issues remain with the directory.
Regular Issues use templates/entities/issue.md，type can only be feature|bug|chore|refactor。ff only answers four things: what was done, what was changed, how it was verified, and what impact it has on codestable/ ; do not write it as a mini Design, and do not keep empty slots.
Talk is written to codestable/talks/; Note is written to codestable/notes/, updating the original file for the same topic; Tool is written to codestable/tools/. Short rules that must be automatically injected at startup should only be written to AGENTS.md or CLAUDE.md, do not duplicate them in both places, and do not create facts.md。
What content can be written to which layer
| Write location | Timing |
|---|---|
| Vision target content | After the user confirms the vision; if an implementation conclusion would change the target, it must be confirmed again |
| Vision implementation degree and links | When the Epic is closed, update according to what has actually happened |
| Project Spec | Independent Issue / Explore Issue closing graduation; Epic closing merge; quick change invalidating the existing truth; or being in specification maintenance posture |
| Epic Spec | Being in specification maintenance posture; or an Issue under an Epic closing and writing back |
Issue / Explore Issue / ff |
When managed and advanced, write to the corresponding issues tree according to ownership; after a quick change is completed, write to and close ff |
When a conflict occurs, judge by 用户最新确认 > 证据与代码 > 疑似过期的 spec . When an Epic and the Vision are inconsistent, first explain whether this is narrowing the implementation or changing the target; do not silently bypass it.
Completion, closing, done, and Git
| Status | Meaning |
|---|---|
| Complete | Implementation and verification have reached the target |
| Close | User authorizes wrap-up:o → x, and complete graduation write-back; Git operations are executed according to the closing contract |
Organize into done/ |
After the user actively requests it, move closed items into the organizing area; this is not a default step of closing |
| User action or scenario | Default behavior |
|---|---|
| Quick change | After verification, you must write ff, or you can directly write x-ff; do not automatically commit or push |
| Managed implementation | Just push through to completion; do not automatically close the Issue, and do not automatically commit or push |
| The user says "done" or "fixed" | Complete the implementation and verification; for small changes still leave ff, unless the user explicitly does not want traces; routine Issues are not automatically closed |
| The user says "close" or "wrap up" | Execute close; do not automatically move into done/ |
push, deploy, initialize or overwrite codestable/, close Epic, destructive operations |
Must obtain explicit authorization |
Graduation direction:
- Standalone Issue → Project Spec.
- Issue within an Epic → Epic Spec.
- Epic closure → merge thespecific contentof stable conclusions into the Project Spec, and check the Vision; merely linking the Epic does not count as graduation write-back.
ffBy default no large-scale graduation is done; if the existing truth is invalidated, then sync the spec or explicitly mark the drift.
For detailed rules, see close。
Quality language
Use the nine quality characteristics of ISO/IEC 25010:2023 as a unified language, but do not turn it into a nine-item mandatory form.Once an item is selected, it is a commitment.
Quick changes do not write a formal quality checklist, but must still comply with the spec, user requirements, and necessary guardrails. Information security and safety are different concepts; do not lump them together as "security". For details, see quality。
3. Kickoff protocol
Before designing, implementing, quick-changing, fixing bugs, maintaining specs, or spiking, if the project already has codestable/, first complete the following actions. Each reference no longer repeats this protocol.
- Browse paths and search keywords. Scan
codestable/'s structure and current topic; if it has already been scanned in the same session and there are no new writes, reuse the existing results. - Read in depth by weight. First read
spec/, then read the relevant Epic and Notes, then recursively search the root directory and each Epic's issues tree, including-x-、ffanddone/; finally read Talks, Vision, and Tools as needed. - Determine whether the current state is sufficient. Can you explain in one sentence "how the trigger passes through the system to produce a result"? If not, first do a current-state description; when crossing multiple boundaries or when the understanding is worth reusing, then create an Explore Issue.
- Choose the management intensity. Execute according to "Choosing the management intensity" above.
- Handle conflicts between documentation and code. First verify the evidence, then correct the truth; do not silently overwrite recorded tradeoffs with code, and do not blindly trust documentation that may be outdated.
When there is a target Issue, confirm that what is being handled is itscurrent version; when working under an Epic, read that Epic's spec.md。
Treat codestable/ as institutional memory: when encountering strange code, check the Spec first; when hitting an old pitfall, check the Notes first; to understand historical tradeoffs, check the Issue first.
4. Authorization boundaries
These boundaries apply to all postures:
- When the direction has been confirmed and the user requests execution, continue pushing tocompletionOr when encountering a real blocker, do not repeatedly confirm between normal steps.
- Before user confirmation, discussions are not persisted; design does not write code.
- Completion does not equal closure, and closure does not equal entering
done/。 - After implementation or quick fixes, do not automatically Review, and do not automatically push.
- Initialization
codestable/, overwriting entry files, closing an Epic, dangerous operations, pushing, and deployment all require explicit authorization.
5. Principle files to read as needed
| File | When to read |
|---|---|
| quality | Discussing, designing, implementing, or closing a specific change; handling quality-related bugs; recording quality constraints in a spec |
| economy | Making trade-offs during design, implementation, or bug fixing; discovering bounded simplification opportunities during closure |
| code-design | Design, managed implementation, or structural issues; when performing a Review, the full text must be read, including the Review section at the end |
| ui-spec | Handling UI spatial relationships, information hierarchy, and multiple states |
| docs | Writing or reorganizing documents such as Vision, Spec, Explore, Note, Talk, etc. |
| debug | When fixing a bug requires escalating to the slow path |
Entity templates are located in templates/entities/, including issue.md、ff-issue.md as well as templates such as Explore, Vision, Spec, Talk, Note, etc. The initialization script is scripts/init_codestable.py. The artifact format is subject to the corresponding reference; do not guess based only on file names.