cs-arch

cs-arch

Required reading at startup

Before starting any judgment or action, first read .codestable/attention.md; if missing, treat the skeleton as incomplete, prompt to fill it in first or run cs-onboard, and do not fall back to the external AI entry file.

.codestable/architecture/ is the project's "map"—design reads it to locate things before writing a plan, issue-analyze reads it to understand module boundaries when doing root-cause analysis, and newcomers read it to get a rough idea of what the system looks like. This skill is the unified entry point for the three things: "drafting / refreshing / health-checking".

architecture is an accumulated, self-contained system map, not the detailed plan of some feature, but the master diagram of "what the system currently looks like" distilled from all features that have landed. Readers should be able to open it and understand the overall structure without jumping back to historical designs. Design is a temporary incremental draft; acceptance distills the stabilized nouns / orchestration / constraints back here; design files are archived and only consulted when digging into specific decision details.

Only record the current state, not plans—by default it stays in sync with the code at acceptance, and when necessary this skill proactively backfills / updates.Do not write "what layers will be added in the future" or "the next step is to split out module X"—those belong to cs-roadmap. If the user says "I want to refactor into X architecture", go through roadmap to split features first, and at each acceptance distill the structure actually achieved back into architecture.

Criterion for detail level:whether it is enough for readers to understand the system without jumping around—write in full the layer that is stable and visible across features; module-internal loops, helper functions, and one-off implementation decisions do not come in.

The value of architecture documentation lies inbeing accurate, stable, and verifiable. Several ways AI easily breaks these three points:

Inventing a system from nothing—the doc says AuthManager 协调 TokenService, but the code has no AuthManager
Making decisions for the user—quietly choosing some layering approach, and readers think it is established fact
Restating the code—every section says "what is here", not "why it is divided this way"; the information content equals ls -R
Taking a glance during checks and feeling there is no problem—no specific location evidence given

For shared paths and naming conventions see .codestable/reference/shared-conventions.md. For the document structure template, check coverage items, and report format see the same directory reference.md。

Mode routing

At startup, first determine the mode, choosing one of three (do not make the user choose from a menu):

What the user says	Mode
"refresh {some doc}", "the code changed, sync the architecture doc", "update to the latest"	`update`
"check design for self-consistency", "do the design and the code match", "are several docs conflicting", "do an architecture health check"	`check`
"backfill an architecture doc", "this module has never been documented", "write down the structure of a subsystem that is already running"	`backfill`

If you cannot determine it, ask the user. If the user says "I want to refactor into X / plan to build a new Y module"—that is not this skill's job, switch to cs-roadmap。

Single-target rule

Run only one mode at a time, and lock onto only one target:

backfill: backfill a doc for a module that already exists but has never been documented (architecture/{type}-{slug}.md or update ARCHITECTURE.md）
update: Refresh an existing doc according to the latest code state + user materials
check: One of the three sub-goals
- design-internal — internal consistency of a single design
- design-vs-code — consistency between design and code
- architecture-folder-internal — architecture/ consistency across multiple documents

Why not do multiple things at once? When drafting, outputting multiple documents at once is too much for the user to review; when checking, the three sub-goals have completely different perspectives and materials, and doing them simultaneously means neither side goes deep. If the user raises multiple goals, have them pick one.

Workflow skeleton (6 phases shared by the three modes)

Phase 1：锁定目标
Phase 2：读取材料
Phase 3：执行（backfill/update = 起草；check = 检查）
Phase 4：自查（backfill/update）或 输出报告（check）
Phase 5：用户 review
Phase 6：落盘（backfill/update）或 等用户拍板（check）

Phase 1: Lock down the goal

Confirm: mode + target object + scope.

backfill: new slug + audience + scope (+ confirm the module already exists in the code)
update: path of the existing document
check: sub-goal + check target (feature name / architecture sub-scope)

If the scope does not converge, ask the user to converge it — a single doc "rewrite of all modules" often means there are actually multiple independent subsystems underneath that should be split out; a single check covering the entire architecture/ report reads without any sense of focus.

Phase 2: Read materials

Common required reading：shared-conventions.md + ARCHITECTURE.md + architecture/ other documents under it.

backfill / update additional(see reference.md "Reading list" for details): target module code entry point and core files + user materials + related compound deposits (decision / explore / learning) + related existing feature plans.update specific: full text of the current doc + last_reviewed code changes after that (git log rough scan).

check additional(by sub-goal):

design-internal / design-vs-code: full text of the plan doc + architecture-related docs
design-vs-code additionally: code directly corresponding to sections 2/3 of the design
architecture-folder-internal: the several docs the user circled + the index + referenced documents found by following the thread (do not extend to code)

Phase 3: Execute

backfill / update: write according to reference.md "Document structure"complete first draftDo not output half-finished work in batches — with batch review the user cannot see global consistency, and the structure described in section 2 and the decisions in section 4 often have cross-section contradictions.

check: execute item by item according to reference.md "Check coverage items" (6 categories for each of the three sub-goals). Every inconsistency must be recorded withlocatable position（file:line or design 第X节) + phenomenon + impact + fix suggestion.

Phase 4: Self-check / Output report

backfill / update: run through reference.md "Self-check list" (7 items) in place, and handle problems found before review (delete / mark TODO / rewrite). Report the self-check results briefly — if you found something, say so; do not go through the motions.

check: output the complete report according to reference.md "Report template" (check summary / inconsistency list with severity levels / observations / items with good consistency / suggested next steps).

Phase 5: User review

backfill / update: paste the complete first draft for the user to review. check: give the report to the user and wait for confirmation of the conclusion. This skill does not make decisions on the user's behalf.

Phase 6: Persist / Finish

backfill：

Write to architecture/{type}-{slug}.md(naming rules see shared-conventions.md section 0), frontmatter status: current、last_reviewed filled with the current day
Same-category aggregation check(must run before persisting): according to the "architecture doc grouping rules", determine whether after this persistence a certain type has ≥6 documents in the root directory — if so, move all documents of that type into architecture/{type}/, remove the filename prefix, and update the ARCHITECTURE.md link accordingly; the migration checklist will be reviewed together in Phase 5
Index update：ARCHITECTURE.md Add references to new docs—backfill mustbe added, otherwise no one will read what was written; changes are likewise reviewed, no sneaky edits

update: overwrite existing files,last_reviewed update to the current day; when structural changes are large, add an entry to the 变更日志 section at the end of the document;ARCHITECTURE.md only update when scope/summary affects the index description.

check: end without writing to disk. The user may decide based on the report to trigger backfill/update—that's a matter for the next round.

Hard boundaries

Anchor only to code, don't invent systems(backfill/update)—every structured assertion must be anchorable to file:line; if it can't be anchored, mark it TODO: 待确认. If a module hasn't been written in the code yet, it shouldn't go through backfill—that's a matter of planning turning into cs-roadmap
Don't make decisions on the user's behalf(backfill/update)—the substantive content of the key decisions section must come from the user or a traceable decision; the AI only drafts the structure and connective language
Only check, don't fix(check)—modifying design / code / configuration is prohibited. Check and fix are done separately, so the user can see the complete list of inconsistencies and then decide priorities as a whole
Evidence-based(check)—every inconsistency has a locatable position
Actionable suggestions(check)—specific to "where to change, how to change", but without writing to disk
Single objective(all modes)
Don't change code, don't touch spec(all modes)—only write architecture doc or produce a report. Problems found in code / solution / decision are recorded as "observation items"
No divergence—out-of-scope issues are not expanded on, they are recorded as observation items

Exit conditions

Common：

A single mode and a single objective have been locked in
The user has explicitly passed review (backfill/update) or confirmed the conclusions (check)
No incidental modifications to code / solution doc / decision
No out-of-scope document changes

Additional for backfill / update：

The self-check checklist has been run through item by item and the handling reported
frontmatter is complete (doc_type: architecture / status / last_reviewed）
Every structured assertion has a file:line anchor or is marked TODO: 待确认
Before writing to disk, it has been judged per the "grouping rules" whether there are ≥6 of the same kind; if so, the migration checklist has been reviewed
backfill：ARCHITECTURE.md A link has been added (or the user has explicitly decided not to add it for now)
update: structural changes have 变更日志 entries

Additional for check：

The check items corresponding to the sub-objectives have been covered
The report contains a list of inconsistencies + fix suggestions
The report does not contain any actual fix actions

Relationship with other workflows

Direction	Relationship
`cs-req` with	req writes "why this capability exists", this skill writes "what structure to use to implement it"; frontmatter `implements` links back to the req slug
`cs-feat-design` upstream	design reads the doc produced by this skill when writing "which part of the architecture this feature interfaces with"; after design is written, check can be triggered for a health check
`cs-feat-accept` downstream	In the acceptance phase, actually update the docs produced by this skill (acceptance merges them itself and does not call back to this skill); trigger check when you want to confirm that the implementation vs design match up `design-vs-code`
`cs-decide` Coordinate with	After the architecture decision is finalized, in update mode add the reference into Section 4 of the relevant doc
`cs-issue-analyze` Readers	Root cause analysis: read this skill's doc to locate module boundaries
`cs-onboard` Creator	onboard creates `ARCHITECTURE.md` placeholders, which are later filled in by this skill
`cs-roadmap` Coordinate with	architecture records the current state, roadmap records the plan. When drafting roadmap, read this skill's doc to understand the current state but do not modify it; the target-state architecture belongs to roadmap

Common mistakes

backfill / update：

Writing in "what we plan to refactor it into"—the target state belongs to roadmap
Inventing a system out of thin air—a "coordination layer / hub / manager" appears that does not exist in the code
Making decisions for the user—the rationale for the choices is made up by AI
Code restatement—each section only lists "what is here" without saying "why it is divided this way"
Dribbling out half-finished work in batches—the user cannot see contradictions across sections
Terminology conflicts—new names conflict with the code / other architecture docs / what compound already has
Writing / modifying multiple copies at once—they cannot all be reviewed and are all roughly merged in
Not stopping when conflicting with an existing decision—writing a contradictory statement yourself
Forgetting to add after backfill is written to disk ARCHITECTURE.md index—it is written but no one can discover it
Running backfill on modules that have not yet been running in the code—that is the target state turning into roadmap
update adds new content but has no code basis—the beginning of the content drifting away from reality
Conveniently modifying the code / proposal docs as well—overstepping boundaries
Still flattening ≥6 files of the same type into the root directory—the grouping rule was triggered but no migration happened
File names do not follow {type}-{slug}.md—the grouping rule exists in name only

check：

Doing multiple sub-goals at the same time
architecture-folder-internal Conveniently reading code—that is design-vs-code
Conveniently modifying code or docs when a problem is found
Only saying "this is not quite right" without giving the location of the evidence
Suggestions are too abstract ("optimize the architecture a bit")
Expanding infinitely from one goal to an audit of the whole repository