cs-domain

cs-domain

First run CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read external AI entry points as a substitute (see .codestable/reference/execution-conventions.md）。

cs-domain manages three things:terms（CONTEXT.md）、decisions（ADR）、topology(single context ↔ multi context). All artifacts are under .codestable/requirements/ .

Topology check

At each startup, take a quick look to determine which topology the project is currently in:

• .codestable/requirements/CONTEXT-MAP.md exists → multi context mode
• only .codestable/requirements/CONTEXT.md → single context
• neither → the project has not yet started domain docs, create them lazily as needed

Single context path

.codestable/requirements/
├── CONTEXT.md              # 术语表
├── adrs/                   # 顺序编号 ADR
│   ├── 001-xxx.md
│   └── 002-xxx.md
└── {capability}.md         # 能力 doc（cs-req 产出，不归本技能管）

Multi context path

.codestable/requirements/
├── CONTEXT-MAP.md          # 子 context 列表 + 关系
├── adrs/                   # 系统级 ADR（跨 context）
├── ordering/
│   ├── CONTEXT.md          # 子 context 术语
│   └── adrs/               # 子 context 特定 ADR
└── billing/
    ├── CONTEXT.md
    └── adrs/

CONTEXT.md writing conventions

CONTEXT.md is aglossary, not a spec. Only write "what X is", not "how X is implemented".

Format:

# {Context 名}

{一两句描述这个 context 是什么、为什么存在。}

## Language

**Order**:
{一两句话定义。}
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

Rules:

• Define, do not describe behavior— write "what X is", not "what X does"
• List synonyms in _Avoid_— when multiple words refer to the same concept, pick the best one and list the others as forbidden
• Only include project-specific terms— general programming concepts (timeout, error type) do not go in
• Use subheadings for clustering— if terms from the same domain naturally group together, give them a section

ADR writing

When to write (3 gate criteria, all must be satisfied)

1. Hard to reverse— changing your mind later has an obvious cost
2. Hard to understand without context— readers will ask "why was it done this way"
3. The result of a real tradeoff— there were alternatives, and one was chosen for a specific reason

If one of the three is missing,do not write. Do not write decisions that can easily be reversed, do not write decisions that are not surprising, and do not write decisions without real alternatives.

Paths and numbering

• Single context:.codestable/requirements/adrs/NNN-{slug}.md
• Multi context subsystem ADR:.codestable/requirements/{ctx}/adrs/NNN-{slug}.md
• Multi context system-level ADR (cross-context):.codestable/requirements/adrs/NNN-{slug}.md
• Numbering is 3 digits (001, 002...); scan the corresponding adrs/ directory for the highest number + 1
• {slug} kebab-case, so people can recall the decision content at a glance

Frontmatter

---
id: 001
title: 选择 X 而不是 Y
status: proposed | accepted | superseded | deprecated | partially-superseded
date: YYYY-MM-DD
supersedes: [003]                          # 可选
superseded_by: [015, 017]                  # 可选
relates_to: [requirements/{slug}, 002]     # 可选
---

Body (Nygard four sections)

# {Title}

## Context
{决策面对的问题、约束、当时的状况。}

## Decision
{我们决定做什么。}

## Consequences
{这个决定带来的正负影响、新出现的约束。}

## Alternatives Considered
{讨论过的备选方案 + 为什么没选。}

When writing an ADR, use terms already defined in CONTEXT.md; if you use a new term, conveniently _Avoid_ add the alias to CONTEXT.md.

Single → multi context upgrade

Explicit trigger— the user must explicitly say "this project is going to be split into subsystems" before upgrading. Do not automatically suggest it just because CONTEXT.md is long.

Upgrade process:

1. Align with the user on the list of sub-contexts (typically 2-4; if more than 5, first question whether it is being split too finely)
2. Create CONTEXT-MAP.md: list sub-contexts + the relationships between them (event flows, shared types, call directions)
3. Create a subdirectory for each sub-context + CONTEXT.md + adrs/
4. Split the terms from the original CONTEXT.md to each sub-context according to ownership; terms spanning multiple contexts remain in the CONTEXT-MAP.md top-level Language section
5. Move the original adrs/ The ADRs under it are classified by scope of impact: those spanning contexts stay in place (system-level), while those within a single context are moved to the corresponding {ctx}/adrs/
6. unchanged {capability}.md—the capability doc is managed by cs-req, and cs-req follows up on classification during upgrades (cs-domain does not do it on its behalf)

Exit criteria

• Writing an ADR: file written to disk + numbering correct + frontmatter complete + all four Nygard sections present
• Writing CONTEXT: terms go in the right place (single/multi-context topology judged correctly) + synonyms listed in _Avoid_
• Upgrade topology: CONTEXT-MAP.md + subdirectories created + terms split + ADRs classified