cs-arch

codestable/architecture/

is the "map" of the project — read it to locate before writing feature-design plans, understand module boundaries when conducting issue-analyze for root causes, and new team members read it to grasp the general structure of the system. This map won't generate or maintain accuracy on its own — someone needs to draft, refresh, and audit it at the right time. This skill serves as the unified entry point for these three tasks.

Architecture is an accumulated, self-sufficient system map. It is not the detailed plan for a single feature, but an overall map of "what the system looks like now" accumulated from all delivered features. Readers should be able to understand the overall system structure without frequently jumping back to historical design documents to fill in gaps. Design documents are temporary detailed incremental drafts; stable terms, orchestration, and constraints refined from the architecture are incorporated back here during the acceptance phase; design files themselves are archived and only referenced when investigating specific decision details.

Architecture only records the current state, not plans. By default, it is only updated in sync with code during the feature-acceptance phase; active

new

update

via this skill is only done when necessary. Do not write "what layers will be added in the future" or "plan to split out module X next" — those belong to the planning layer of

cs-roadmap

. When a user proposes a target-state description like "I want to refactor to X architecture", first break it into several features via roadmap, then refine the actual phased structure achieved after each feature acceptance back into the architecture.

This means the criterion for the level of detail in architecture documents is "whether readers can understand the system without jumping" — not "the fewer words the better" nor "moving all details from design documents here". Stable, cross-feature visible layers of the system should be fully documented; internal loops, helper functions, and one-time implementation decisions within a module are excluded.

The value of architecture documents lies in accuracy, stability, and searchability. Several common issues when AI writes or reviews architecture documents directly undermine these three points:

Inventing systems out of thin air — the document states "AuthManager coordinates TokenService", but there is no
```
AuthManager
```
layer in the code at all.
Making architecture decisions on behalf of users — quietly choosing a certain layering approach, leading readers to believe it is an established fact.
Writing documents as code retellings — each section only says "what's here" without explaining "why it's divided this way", resulting in the same amount of information as
```
ls -R
```
.
During checks, "it looks okay at a glance" — no specific location evidence is provided, leaving users unable to judge if it is truly okay.

The entire set of rules below is designed to prevent these situations.

See
codestable/reference/shared-conventions.md
for shared paths and naming conventions. See
reference.md
in the same directory for document structure templates, check coverage lists, and report formats.

Mode Diversion

First determine the mode at startup, choose one of three — AI automatically judges based on user input, no menu selection required:

User Input	Mode
"Fill in an architecture doc", "Draft the architecture document for {module}", "Write down this structure"	`new`
"Refresh {document}", "The code has changed, sync the architecture doc", "Update the architecture directory to the latest"	`update`
"Check if the design is internally consistent", "Does the plan match the code?", "Are there conflicts among several architecture documents?", "Conduct an architecture health check"	`check`

If the mode cannot be determined, ask the user instead of guessing.

Single-Target Rule

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

```
new
```
: Draft a new architecture document (
```
codestable/architecture/{type}-{slug}.md
```
, or update
```
DESIGN.md
```
itself)
```
update
```
: Refresh an existing architecture document based on the latest code status + new user materials
```
check
```
: One of three sub-objectives
- ```
design-internal
```
  — Consistency within a single feature design document
- ```
design-vs-code
```
  — Consistency between a feature design and code
- ```
architecture-folder-internal
```
  — Consistency among multiple architecture documents under
```
codestable/architecture/
```

Why is doing multiple things at once not allowed? When drafting, AI generating multiple documents at once makes it impossible for users to review thoroughly; during checks, the three sub-objectives have completely different perspectives and reference materials, doing them simultaneously leads to superficial checks and unclear responsibility for mixed issues. If the user proposes multiple targets, ask them to choose one and leave the rest for later.

Workflow Skeleton (Shared by All Three Modes)

All modes follow six phases, with details diverging based on the mode:

Phase 1: Lock Target
Phase 2: Read Materials
Phase 3: Execute (new/update = draft; check = inspect)
Phase 4: Self-Inspection (new/update) or Output Report (check)
Phase 5: User Review
Phase 6: Finalize (new/update) or Wait for User's Next Decision (check)

Phase 1: Lock Target (All Modes)

Confirm three things:

Mode (
```
new
```
/
```
update
```
/
```
check
```
)
Target object:
- ```
new
```
  : New slug + audience + scope
- ```
update
```
  : Path of existing document
- ```
check
```
  : Sub-objective + inspection target (feature name / architecture sub-scope)
Scope covered this time (entire document / specific sections / specific documents)

If the scope is not converged, ask the user to narrow it down — rewriting an entire module in an architecture document often means there are multiple relatively independent subsystems underneath, which should be split into separate tasks; a check covering the entire

architecture/

directory will result in a report that is hard to focus on.

Phase 2: Read Materials

Mandatory reading for all modes:

codestable/reference/shared-conventions.md

```
codestable/architecture/DESIGN.md
```
(main entry point)
Other architecture documents under
```
codestable/architecture/
```
(to judge whether to reference each other or if there are duplicates)

Additional mandatory reading for new / update modes (see "Reading List" in

reference.md

Code entry and core files of the target module / subsystem (identified by the user or grep first then report candidates for user confirmation)
Materials provided by the user (oral descriptions, scattered documents, transcribed whiteboard photos)
Relevant compound records (decision / explore / learning)
Existing feature plans related to this module
Update-specific: Full text of the current version of the document + code changes since the document's
```
last_reviewed
```
(rough scan via
```
git log
```
)

Additional mandatory reading for check mode (varies by sub-objective, see

reference.md

for details):

```
design-internal
```
/
```
design-vs-code
```
: Full text of the plan doc + relevant documents in the architecture center directory
```
design-vs-code
```
additionally: Code files directly corresponding to sections 2/3 of the design
```
architecture-folder-internal
```
: Specific
```
codestable/architecture/**/*.md
```
documents circled by the user (or all documents of the same type under a certain type) + index + referenced documents found via tracing (no expansion to code)

Phase 3: Execute

new / update modes: Write a complete first draft according to the "Document Structure" in

reference.md

, do not output semi-finished products in batches. Batch review prevents users from seeing global consistency — contradictions often exist between the structure described in section 2 and the decisions recorded in section 4, which can only be detected when viewed together.

check mode: Execute item by item according to the "Check Coverage Items" in

reference.md

(6 categories for each of the three sub-objectives). Record locatable positions (

file:line

or "Section X of design") + phenomenon + impact + repair suggestion for each inconsistency.

Phase 4: Self-Inspection (new/update) or Output Report (check)

new / update: Run through the "Self-Inspection List" (7 items) in

reference.md

on the spot, and fix issues before submitting to the user for review (delete / mark TODO / rewrite). Briefly report the self-inspection results to the user — if issues are found, state what was found and how it was handled, do not treat it as an invisible "formality" step.

check: Output a complete report according to the "Report Template" in

reference.md

, including inspection summary / inconsistency list (table with severity levels) / observation items (out of scope) / consistent items / suggested next steps.

Phase 5: User Review

new / update: Paste the complete first draft to the user and prompt review. Revise according to user feedback until the user explicitly confirms "this doc is ready".

check: Send the report to the user and wait for confirmation of conclusions — whether to accept, whether to add another type of check, or proceed to the next step decided by the user. This skill does not make decisions on behalf of the user.

Phase 6: Finalize (new/update) or End (check)

new mode:

Write to

codestable/architecture/{type}-{slug}.md

(see section 0 of

codestable/reference/shared-conventions.md

for naming rules), fill in frontmatter

status: current

and

last_reviewed

with the current date

Aggregation check for similar documents (mandatory before finalization): Judge whether the number of documents of a certain type in the root directory of
```
architecture/
```
reaches ≥6 after this finalization according to the "Grouping Rules for Architecture Docs" in shared-conventions — if the threshold is met, move all such documents to the
```
architecture/{type}/
```
subdirectory, remove the filename prefix, and synchronize all relevant links in
```
DESIGN.md
```
; the relocation list must be reviewed by the user in Phase 5
Index update: Open
```
codestable/architecture/DESIGN.md
```
to add a reference link to the new document — this must be done in new mode; without it, the document will be written but never read; changes to DESIGN.md must also be reviewed by the user, do not modify secretly

update mode:

Overwrite the existing file, update
```
last_reviewed
```
to the current date
If there are major structural changes, add an entry "YYYY-MM-DD: {one-sentence description}" in the "Change Log" section at the end of the document
Only update DESIGN.md if changes to scope or summary affect the index description

check mode: No finalization, end the process. Users may decide to trigger

new

update

or other workflows based on the report — that will be handled in the next round.

Hard Boundaries

Anchor only to code, do not invent systems (new / update) — each structured assertion must be anchored to
```
file:line
```
; if it cannot be anchored, mark it as
```
TODO: To be confirmed
```
, do not allow "speculation based on naming".
Do not make decisions on behalf of users (new / update) — substantive content in key decision sections must come from the user or traceable decision documents. AI only drafts the structure and connecting language.
Only inspect, do not repair (check) — prohibit modifying design / code / configuration. Separate inspection and repair so users can see the complete inconsistency list before deciding priorities as a whole.
Evidence-based (check) — each inconsistency must have a locatable position (
```
file:line
```
or "Section X of design").
Executable suggestions (check) — specific to "what to modify and how to modify", but do not finalize.
Single-target (all modes) — run only one mode at a time, and lock only one target within that mode.
Do not modify code or spec (all modes) — this skill only writes architecture docs or generates inspection reports. If issues are found in code / plan docs / decisions, record them as "observation items" and leave it to the user to decide whether to start another workflow.
Do not diverge (all modes) — do not expand to issues outside the user's described scope, just record them as observation items.

Exit Conditions

Common to all modes:

Single mode and single target have been locked
User has explicitly approved the review (new / update) or confirmed the inspection conclusion of this round (check)
No code / plan docs / decision documents have been modified without permission
No additional document changes outside the scope

Additional for new / update:

The self-inspection list in
```
reference.md
```
has been run through item by item, and the processing results have been reported
Document frontmatter is complete, with
```
doc_type: architecture
```
,
```
status
```
, and
```
last_reviewed
```
all filled in
Each structured assertion is either anchored to
```
file:line
```
or marked as
```
TODO: To be confirmed
```
Before finalization, it has been judged whether similar documents reach ≥6 according to the "Grouping Rules", and if the threshold is met, the relocation list has been reviewed by the user
new: A link to the new document has been added to
```
DESIGN.md
```
(or the user has explicitly decided not to add it for now)
update: If there are structural changes, an entry has been added to the "Change Log" section

Additional for check:

The inspection items corresponding to the sub-objective have been fully covered (see
```
reference.md
```
)
The report includes an inconsistency list + repair suggestions
The report does not contain any actual repair actions

Relationship with Other Workflows

Direction	Relationship
Collaboration with `cs-req`	Requirements describe "why this capability is needed", this skill describes "what structure is used to implement it"; the frontmatter `implements` of architecture docs links back to the req slug it supports
Upstream of `cs-feat-design`	When writing "which part of the architecture this feature integrates with" in design, read the docs produced by this skill; after design is completed, the check mode can be triggered to conduct an internal consistency health check
Downstream of `cs-feat-accept`	During the acceptance phase, actually update the docs produced by this skill (acceptance does the merging itself, does not call back this skill's new/update); trigger the `design-vs-code` sub-objective of check mode to confirm alignment between implementation and design
Collaboration with `cs-decide`	After an architecture decision is finalized, this skill's `update` can add references to section 4 of relevant architecture docs
Reader of `cs-issue-analyze`	Read the docs produced by this skill to locate module boundaries during root cause analysis
Creator of `cs-onboard`	Create a placeholder `DESIGN.md` during onboarding, then fill it in / expand it via this skill
Collaboration with `cs-roadmap`	Architecture records "what the system looks like now", roadmap records "how to push it to the next step". When drafting the roadmap, read the docs produced by this skill to understand the current state, but do not modify it; "target-state architecture" belongs to planning and is not included in architecture docs

Common Mistakes

Common mistakes in new / update:

Writing "what it will be refactored into": Architecture is a current-state archive; target-state structure belongs to the roadmap planning layer
Inventing systems out of thin air: A "coordination layer / hub / manager" that does not exist in the code appears in the document
Making architecture decisions on behalf of users: The selection reasons in key decision sections are actually made up by AI
Retelling code: Each section only lists "what's here" without explaining "why it's divided this way"
Drafting semi-finished products in batches: Users cannot see cross-section contradictions, leading to superficial review
Term conflicts: Newly introduced names conflict with existing ones in code / other architecture docs / compounds without awareness
Writing / modifying multiple documents at once: Cannot be reviewed thoroughly, resulting in rough integration of all contents
Continuing despite conflicts with existing decisions: Writing a version that contradicts established decisions
Forgetting to add an index in
```
DESIGN.md
```
after finalizing in new mode: The document is written but cannot be found
Adding new content without code basis in update mode: Just "reads more complete", which is the start of content deviating from reality
Modifying code / plan docs along the way: Overstepping boundaries, this skill only modifies architecture docs
Continuing to place documents in the root directory when similar documents reach ≥6: Triggering the grouping rule but not relocating
Filename does not follow
```
{type}-{slug}.md
```
: Similar documents cannot be aggregated in the future, making the grouping rule ineffective

Common mistakes in check:

Doing multiple sub-objectives at once (only one of design-internal / design-vs-code / architecture-folder-internal can be selected)
Reading code to verify during
```
architecture-folder-internal
```
— that is the task of
```
design-vs-code
```
Modifying code or documents immediately when issues are found
Only saying "something is wrong here" without providing evidence location
Suggestions are too abstract ("optimize the architecture")
Expanding infinitely from one target to full repository audit

cs-arch

NPX Install

Tags

SKILL.md Content (Chinese)

cs-arch

Mode Diversion

Single-Target Rule

Workflow Skeleton (Shared by All Three Modes)

Phase 1: Lock Target (All Modes)

Phase 2: Read Materials

Phase 3: Execute

Phase 4: Self-Inspection (new/update) or Output Report (check)

Phase 5: User Review

Phase 6: Finalize (new/update) or End (check)

Hard Boundaries

Exit Conditions

Relationship with Other Workflows

Common Mistakes