Cs Arch
Keep a living `.codestable/architecture/` map aligned with shipped code via update, check, and backfill without mixing in future roadmap plans.
Overview
cs-arch is an agent skill most often used in Build (also Ship review, Operate iterate) that maintains `.codestable/architecture/` as an evidence-backed map of the system as it exists now via update, check, and backfill m
Install
npx skills add https://github.com/liuzhengdongfortest/codestable --skill cs-archWhat is this skill?
- Three routed modes: `update`, `check`, and `backfill` from natural-language triggers (no menu picking)
- Maintains cumulative, self-contained architecture map—not per-feature design drafts or `cs-roadmap` futures
- Forces read of `.codestable/attention.md` first; missing skeleton → prompt `cs-onboard` instead of external AI entry fil
- Check mode targets doc-vs-code drift, cross-doc conflicts, and evidence-backed findings—not “looks fine” passes
- Explicit anti-patterns: no invented subsystems, no silent architectural decisions, no directory-listing noise
- Three operational modes: update, check, and backfill
- Canonical store path: `.codestable/architecture/`
Adoption & trust: 959 installs on skills.sh; 902 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your team has design drafts and moving code but no trustworthy, current architecture map—and docs either fantasize components that do not exist or devolve into folder listings.
Who is it for?
CodeStable adopters who need architecture truth synced after acceptance, before new design work, or when onboarding someone to module boundaries.
Skip if: Greenfield “we want architecture X next quarter” planning, one-off feature specs, or repos without `.codestable/attention.md` and onboarding skeleton in place.
When should I use this skill?
User says refresh architecture, run an architecture check, backfill module architecture docs, ask if plan and code align, or a feature phase needs an architecture step first—not roadmap restructuring.
What do I get? / Deliverables
After a cs-arch run you get architecture files that reflect shipped reality (or a concrete check report with locations), with roadmap fiction deferred to cs-roadmap and feature design kept separate.
- Updated or new architecture markdown under `.codestable/architecture/`
- Architecture check report with concrete location evidence when in check mode
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Architecture docs are the canonical “what exists now” artifact teams read before design and during feature work, which situates the skill on the build/docs shelf even though check and backfill also support review and upkeep. The skill writes and refreshes system-map documentation under `.codestable/architecture/`, not application code or deploy config.
Where it fits
Before writing a new feature design, you read and optionally update architecture so proposals attach to real module names and flows.
A feature ticket requires an architecture action first; cs-arch backfills the subsystem that has been running without a map entry.
You ask whether the design doc and implementation still match; check mode hunts contradictions with cited file evidence.
After several acceptance merges, you run update so newcomers are not learning structure from stale archived designs.
How it compares
Use for cumulative system-map hygiene under CodeStable—not ad-hoc README edits or roadmap feature breakdowns.
Common Questions / FAQ
Who is cs-arch for?
Solo and small-team builders using the CodeStable workflow who need a single, queryable picture of how modules and orchestration work after features land—not consultants writing aspirational target architectures.
When should I use cs-arch?
In Build/docs when refreshing docs after code changes or backfilling a subsystem; in Ship/review when asking if design and code still agree or documents conflict; in Operate/iterate when keeping the living map honest before the next feature or incident analysis.
Is cs-arch safe to install?
It is documentation and verification guidance that reads and edits repo-local `.codestable/` files; review the Security Audits panel on this Prism page and your agent’s write permissions before granting broad filesystem access.
SKILL.md
READMESKILL.md - Cs Arch
# cs-arch ## 启动必读 开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 `.codestable/architecture/` 是项目"地图"——design 写方案前读它定位、issue-analyze 做根因时读它理解模块边界、新人读它知道系统大致长什么样。本技能是"起草 / 刷新 / 体检"三件事的统一入口。 **architecture 是累积的、自给自足的系统地图**，不是某次 feature 的详细方案，而是所有已落地 feature 沉淀下来的"系统现在长什么样"总图。读者打开应能看懂整体结构而不需要跳回历史 design。design 是临时增量稿，acceptance 把稳定下来的名词 / 编排 / 约束提炼回这里；design 文件归档，只在追究具体决策细节时翻。 **只记现状不记计划**——默认在 acceptance 跟着代码同步，必要时本技能主动 backfill / update。**不写"未来会加什么层"、"下一步打算拆出 X 模块"**——那些归 `cs-roadmap`。用户说"我想重构成 X 架构"先走 roadmap 拆 feature，每次 acceptance 把实际达到的结构提炼回 architecture。 详略判据：**够不够让读者不跳转就读懂系统**——稳定、跨 feature 可见的那一层写全；模块内部循环、辅助函数、一次性实现决定不进来。 架构文档价值在**准、稳、可查**。AI 容易破坏这三点的几种问题： - **凭空造系统**——文档说 `AuthManager 协调 TokenService`，代码里根本没 `AuthManager` - **替用户拍板**——悄悄选某种分层方式，读者以为是既定事实 - **代码复述**——每节都说"这里有什么"，不说"为什么这么分"，信息量等于 `ls -R` - **检查时看一眼感觉没问题**——没给具体位置证据 > 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。文档结构模板、check 覆盖项、报告格式看同目录 `reference.md`。 --- ## 模式分流 启动先判断模式三选一（不让用户选菜单）： | 用户说什么 | 模式 | |---|---| | "刷新 {某文档}"、"代码变了把架构 doc 同步"、"更新到最新" | `update` | | "检查 design 自洽"、"方案和代码对得上吗"、"几份文档有没有打架"、"做架构体检" | `check` | | "补一份架构 doc"、"这块模块一直没写档"、"把已经在跑的子系统结构写下来" | `backfill` | 判断不出问用户。用户说"我想重构成 X / 打算新做 Y 模块"——不是本技能的事，转 `cs-roadmap`。 --- ## 单目标规则 每次只跑一个模式，且只锁定一个目标： - `backfill`：给已存在但从没写过档的模块补一份（`architecture/{type}-{slug}.md` 或更新 `ARCHITECTURE.md`） - `update`：按代码最新状态 + 用户素材刷新一份已有 doc - `check`：三个子目标之一 - `design-internal` — 一份 design 内部一致性 - `design-vs-code` — design 与代码一致性 - `architecture-folder-internal` — `architecture/` 多份文档间一致性 为什么不一次做多件？起草时一次吐多份用户 review 不过来；检查时三个子目标视角和材料完全不同，同时做每边都不深。用户提多个目标让 TA 选一个。 --- ## 工作流骨架（三模式共用 6 阶段） ``` Phase 1：锁定目标 Phase 2：读取材料 Phase 3：执行（backfill/update = 起草；check = 检查） Phase 4：自查（backfill/update）或 输出报告（check） Phase 5：用户 review Phase 6：落盘（backfill/update）或 等用户拍板（check） ``` ### Phase 1：锁定目标 确认：模式 + 目标对象 + 范围。 - backfill：新 slug + 受众 + 范围（+ 确认模块在代码里已存在） - update：已有文档路径 - check：子目标 + 检查对象（feature 名 / architecture 子范围） 范围不收敛就问用户收敛——一份 doc"全模块重写"往往意味着底下其实有多个独立子系统应该拆；一次检查覆盖整个 `architecture/` 报告读起来抓不到重点。 ### Phase 2：读取材料 **共同必读**：`shared-conventions.md` + `ARCHITECTURE.md` + `architecture/` 下其他文档。 **backfill / update 额外**（详见 `reference.md` "读取清单"）：目标模块代码入口和核心文件 + 用户素材 + 相关 compound 沉淀（decision / explore / learning）+ 相关已有 feature 方案。**update 专项**：当前 doc 全文 + `last_reviewed` 之后的代码变更（`git log` 粗扫）。 **check 额外**（按子目标）： - `design-internal` / `design-vs-code`：方案 doc 全文 + 架构相关 doc - `design-vs-code` 再额外：与 design 第 2/3 节直接对应的代码 - `architecture-folder-internal`：用户圈定的几份 doc + 索引 + 顺藤摸到的被引用文档（不扩展到代码） ### Phase 3：执行 **backfill / update**：按 `reference.md` "文档结构"写**完整初稿**不分批吐半成品——分批 review 用户看不到全局一致性，第 2 节描述的结构和第 4 节决策经常有跨节矛盾。 **check**：按 `reference.md` "检查覆盖项"（三个子目标各 6 类）逐条执行。每条不一致都要记**可定位位置**（`file:line` 或 `design 第X节`）+ 现象 + 影响 + 修复建议。 ### Phase 4：自查 / 输出报告 **backfill / update**：按 `reference.md` "自查清单"（7 条）就地跑一遍，发现问题在 review 前处理掉（删 / 标 TODO / 改写）。自查结果简短汇报——发现了就说，不要走过场。 **check**：按 `reference.md` "报告模板"输出完整报告（检查摘要 / 不一致清单带严重级别 / 观察项 / 一致性良好项 / 建议下一步）。 ### Phase 5：用户 review **backfill / update**：完整初稿贴给用户 review。 **check**：报告给用户，等确认结论。本技能不替用户拍板。 ### Phase 6：落盘 / 结束 **backfill**： - 写入 `architecture/{type}-{slug}.md`（命名规则见 `shared-conventions.md` 第 0 节），frontmatter `status: current`、`last_reviewed` 填当天 - **同类聚合检查**（落盘前必跑）：按"架构 doc 分组规则"判断本次落盘后某 type 在根目录 ≥6 份——命中就把这类全搬进 `architecture/{type}/`、去掉文件名前缀、同步改 `ARCHITECTURE.md` 链接；搬迁清单在 Phase 5 一并 review - **索引更新**：`ARCHITECTURE.md` 加新文档引用——backfill **必定**要加，否则写了没人会读；改动同样 review，不偷偷改 **update**：覆盖已有文件，`last_reviewed` 更新当天；结构性改动大时文末 `变更日志` 节加一条；`ARCHITECTURE.md` 只在 scope/summary 影响索引描述时更新。 **check**：不落盘结束。用户可能基于报告决定触发 backfill/update——那是下一轮的事。 --- ## 硬性边界 1. **只锚代码不造系统**（backfill/update）——每条