invariants

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authoring Invariants Skill

架构约束创建Skill

Overview

概述

This skill turns an architectural rule in the author's head into a registered, enforced catalog entry. It is the on-ramp described in

docs/designs/archive/2026-05-25-invariants-authoring-wizard.md

— an LLM-driven authoring conversation, not a stdin question loop.

The division of labor is strict and load-bearing:

The agent (you) supplies judgment + natural-language elicitation. You interview the author, draft prose, propose globs, and shape the entry.
The verbs own validation + writing. Every mutation goes through a deterministic, schema-validated orchestrate action —
```
invariants_scaffold
```
and
```
invariants_add
```
. You never hand-write or append catalog YAML yourself. The verb renders it; you confirm it.

This shape is the only one consistent with the agent-first philosophy: inputs are constrained at the schema level (INV-5a), mutating verbs default to dry-run (INV-5c), and authoring is event-sourced (INV-1).

本Skill可将作者脑海中的架构规则转化为已注册、可强制执行的目录条目。它是

docs/designs/archive/2026-05-25-invariants-authoring-wizard.md

中描述的入门流程——由LLM驱动的创建对话，而非标准输入式的问答循环。

分工明确且至关重要：

Agent（即你）提供判断与自然语言提取能力。你需要与作者访谈、撰写文案、提出glob路径建议，并梳理条目内容。
指令负责验证与写入操作。所有变更都需经过确定性的、基于schema验证的编排动作——
```
invariants_scaffold
```
和
```
invariants_add
```
。请勿手动编写或追加目录YAML。指令会自动生成YAML，你只需确认即可。

这种模式完全符合Agent优先的理念：输入在schema层面受到约束（INV-5a），变更指令默认采用试运行模式（INV-5c），创建流程基于事件溯源（INV-1）。

When to Use

使用场景

The author wants a new architectural rule enforced on their own SDLC path (surfaced at ideate, turned into acceptance criteria at planning, audited at review by the
```
check_invariant_conformance
```
gate).
An author says "add an invariant", "enforce that X", "make this a rule".

作者希望在自己的SDLC路径上强制执行新的架构规则（在构思阶段提出，在规划阶段转化为验收标准，在评审阶段由
```
check_invariant_conformance
```
gate进行审计）。
作者提出"add an invariant"、"enforce that X"、"make this a rule"等需求时。

When NOT to Use

禁用场景

The author wants to hand-write YAML — point them at the verbs instead; the skill exists so they don't have to.
The rule is a one-off lint, not an architectural invariant → a project linter is the right home.
You are mid-workflow editing state, running a review, or planning — those are other skills. This skill only authors catalog entries.

作者希望手动编写YAML——请引导他们使用指令；本Skill的存在就是为了避免手动编写YAML。
规则是一次性的lint检查，而非架构约束→应使用项目级linter。
你处于工作流状态编辑、评审执行或规划过程中——这些属于其他Skill的范畴。本Skill仅用于创建目录条目。

The verbs (what you drive — never bypass)

指令（你需驱动执行，切勿绕过）

Action (MCP)	CLI facade	What it does
`invariants_scaffold`	`exarchos invariants scaffold`	Create a starter catalog file for a tier; idempotently register it in `.exarchos.yml` . Never overwrites an existing file.
`invariants_add`	`exarchos invariants add`	Validate ONE entry against the v3 schema (including the `.strict()` enforcement DSL — INV-4), then append it. `dryRun` defaults to true: returns the rendered entry + file diff, writes nothing.
`doctor`	`exarchos doctor`	Reuse the existing `invariants-catalog` check — the validator. No new validate verb.
`invariants_effective`	`exarchos view invariants_effective`	The merged, projected catalog the gate will enforce. Post-write confirmation.

The agent never declares an entry valid on its own authority — the verb is the validator.

invariants_add

returns the INV-5b carrier shape: success carries

next_actions

(

["doctor", "view invariants_effective"]

); validation errors carry

validTargets

expectedShape

suggestedFix

sourced from the Zod error, so you can self-correct and re-run rather than re-guess.

动作（MCP）	CLI 接口	功能说明
`invariants_scaffold`	`exarchos invariants scaffold`	为某一层级创建初始目录文件；在 `.exarchos.yml` 中幂等注册该文件。绝不会覆盖现有文件。
`invariants_add`	`exarchos invariants add`	针对v3 schema验证单个条目（包括 `.strict()` 执行DSL——INV-4），然后追加该条目。`dryRun` 默认为true：返回渲染后的条目及文件差异，不执行写入操作。
`doctor`	`exarchos doctor`	复用现有的 `invariants-catalog` 检查——即验证器。无需新增验证指令。
`invariants_effective`	`exarchos view invariants_effective`	gate将强制执行的合并后投影目录。用于写入后的确认。

Agent绝不能自行声明条目有效——指令才是验证者。

invariants_add

返回INV-5b载体格式：成功时返回

next_actions

（

["doctor", "view invariants_effective"]

）；验证错误时返回源自Zod错误的

validTargets

expectedShape

suggestedFix

，以便你自行修正并重新执行，而非重新猜测。

The interview (6 steps)

访谈流程（6步）

Walk the author through these in order. Elicit in prose, never make them think in YAML field names.

请按顺序引导作者完成以下步骤。用自然语言提取信息，切勿让作者思考YAML字段名。

1. Elicit — the rule →

summary

1. 提取——规则→

summary

Ask the author to state the rule in one sentence. Distill it into a precise

summary

. Probe for the failure it prevents ("what goes wrong if this is violated?") — that sharpens both the summary and the later enforcement.

请作者用一句话描述规则。将其提炼为精准的

summary

。探究该规则要预防的故障（"如果违反此规则会出现什么问题？"）——这会让summary和后续的执行逻辑更清晰。

2. Locate —

dimension

applies-to

, affinities

2. 定位——

dimension

、

applies-to

、关联属性

dimension

: a free-text grouping (e.g.

audit-completeness

error-handling

```
applies-to
```
: the glob(s) the rule governs — ask the author to name the paths (
```
src/handlers/**
```
,
```
**/*.ts
```
). These are author-named globs, never framework-inferred (INV-6: the surface is workload-neutral).

phase-affinity

: phases where it bites (

ideate | plan | delegate | review | synthesize

). Absent ⇒ all phases.

workflow-affinity

: workflow types (

feature | debug | refactor | discovery | oneshot

). Absent ⇒ all.

dimension

：自由文本分组（例如

audit-completeness

、

error-handling

）。

```
applies-to
```
：规则适用的glob路径——请作者指定路径（
```
src/handlers/**
```
、
```
**/*.ts
```
）。这些是作者指定的glob路径，绝不能由框架推断（INV-6：适用范围与工作负载无关）。
```
phase-affinity
```
：规则生效的阶段（
```
ideate | plan | delegate | review | synthesize
```
）。若未指定则默认适用于所有阶段。
```
workflow-affinity
```
：工作流类型（
```
feature | debug | refactor | discovery | oneshot
```
）。若未指定则默认适用于所有类型。

3. Weight —

severity

integrity-class

, and the

tier

you author into

3. 权重设置——

severity

、

integrity-class

，以及你要创建的

tier

```
severity.default
```
:
```
blocking
```
or
```
advisory
```
.
```
severity.by-workflow
```
(optional): downgrade for cheap workflows (e.g.
```
oneshot: advisory
```
).
```
integrity-class
```
(entry field; enum
```
substrate | sdlc | authoring | user
```
): the entry's override authority, not its namespace. For a consumer-authored rule this is
```
user
```
. (
```
substrate
```
/
```
sdlc
```
are exarchos's own classes — you do not author those.)
tier
(the verb arg) picks the catalog namespace, and the choice is exarchos-substrate vs project-authored, NOT "which developers". This is the one that bites — get it wrong and you silently collide with exarchos's own ids:
- tier: user
  →
  U-N
  ids — your project's own invariants. The default for everyone consuming exarchos. If you are authoring a rule for your own repo, this is always the answer (even if your project happens to name its rules
```
INV-N
```
  internally — they map to
```
U-N
```
  here).
- tier: dev
  →
  INV-N
  ids — exarchos's own reserved substrate catalog. Exarchos ships its own
```
INV-1..6
```
  inside the tool, and they merge into every
```
invariants_effective
```
  projection. Authoring into
```
dev
```
  from a consumer repo collides your
  INV-N
  with exarchos's own — a silent namespace clash the
```
doctor
```
  check can't catch (it only flags
```
INV-*
```
  in a user catalog). Use
```
dev
```
  only when working inside the exarchos repo itself. The verbs enforce this:
```
invariants_scaffold
```
  /
```
invariants_add
```
  reject
```
tier: dev
```
  outside the exarchos repo (heuristic:
```
package.json
```
  name ≠
```
@lvlup-sw/exarchos
```
  ) with a
```
RESERVED_TIER
```
  error that redirects to
```
user
```
  ; a genuine exarchos fork opts in with
```
allowReservedTier: true
```
  .

```
severity.default
```
：
```
blocking
```
或
```
advisory
```
。
```
severity.by-workflow
```
（可选）：针对低成本工作流降低级别（例如
```
oneshot: advisory
```
）。
```
integrity-class
```
（条目字段；枚举值
```
substrate | sdlc | authoring | user
```
）：条目的覆盖权限，而非命名空间。对于用户创建的规则，该值为
```
user
```
。（
```
substrate
```
/
```
sdlc
```
是exarchos自身的类别——你无需创建这些类别下的条目。）
tier
（指令参数）决定了目录的命名空间，选择依据是exarchos底层 vs 项目自定义，而非"面向哪些开发者"。这一点至关重要——若选择错误，会与exarchos自身的ID发生静默冲突：
- tier: user
  →
  U-N
  格式ID——你的项目自定义约束。所有使用exarchos的用户默认选择此选项。若你为自己的仓库创建规则，这始终是正确选择（即使你的项目内部将规则命名为
```
INV-N
```
  ——它们在此处会映射为
```
U-N
```
  ）。
- tier: dev
  →
  INV-N
  格式ID——exarchos自身保留的底层目录。 Exarchos工具内置了自己的
```
INV-1..6
```
  规则，它们会合并到每个
```
invariants_effective
```
  投影中。在用户仓库中创建
```
dev
```
  层级的条目会导致你的
  INV-N
  与exarchos自身的规则冲突——这是
```
doctor
```
  检查无法捕获的静默命名空间冲突（它仅会标记用户目录中的
```
INV-*
```
  规则）。仅在exarchos仓库内部工作时使用
```
dev
```
  层级。指令会强制执行此限制：在exarchos仓库外使用
```
invariants_scaffold
```
  /
```
invariants_add
```
  并指定
```
tier: dev
```
  时（判断依据：
```
package.json
```
  名称≠
```
@lvlup-sw/exarchos
```
  ），会返回
```
RESERVED_TIER
```
  错误并引导用户选择
```
user
```
  层级；真正的exarchos分支可通过设置
```
allowReservedTier: true
```
  来启用此选项。

4. Enforce — DEFAULT

mode: audit

mode: check

is opt-in

4. 执行——默认

mode: audit

，

mode: check

为可选高级功能

Default to
mode: audit
. You draft the

audit-prompt

from the elicited rule — a question the review subagent answers against the diff. Audit mode is pure judgment and always portable:

yaml

enforcement:
  mode: audit
  audit-prompt: >-
    Does this diff let a request handler return before emitting an audit event?
    Cite the offending file + line.

Offer

mode: check

only as an advanced opt-in when the rule is mechanically checkable. If the author opts in, propose a declarative combinator tree over grep/structural/heuristic leaves and validate it live via
invariants_add
with
dryRun: true
before showing it. See

@references/check-mode.md

for the combinator vocabulary and the opt-in flow. The enforcement DSL is

.strict()

and declarative-only: there is no

script

exec

code

escape hatch (INV-4), so you cannot emit an executable check even if asked.

默认使用
mode: audit
。你需根据提取的规则编写

audit-prompt

——即评审子Agent针对代码差异需回答的问题。审计模式完全基于判断，且始终具备可移植性：

yaml

enforcement:
  mode: audit
  audit-prompt: >-
    Does this diff let a request handler return before emitting an audit event?
    Cite the offending file + line.

仅当规则可通过机械方式检查时，才将

mode: check

作为高级可选功能提供给作者。若作者选择此选项，请基于grep/结构化/启发式规则提出声明式组合树，并在展示前通过
invariants_add
的
dryRun: true
模式实时验证。有关组合器词汇和可选流程，请参阅

@references/check-mode.md

。执行DSL是

.strict()

且仅支持声明式：不存在

script

exec

code

逃逸机制（INV-4），因此即使被要求，你也无法输出可执行的检查逻辑。

5. Number — auto-id in the target namespace

5. 编号——目标命名空间中的自动ID

Do not pick an id.

invariants_add

auto-assigns the next free id in the target catalog's namespace (

U-N

for user,

INV-N

for dev). Mention the id the verb assigned when you show the dry-run.

请勿手动选择ID。

invariants_add

会自动为目标目录的命名空间分配下一个可用ID（用户层级为

U-N

，开发层级为

INV-N

）。在展示试运行结果时，请提及指令分配的ID。

6. Commit — dry-run → confirm → write → verify

6. 提交——试运行→确认→写入→验证

This step is a gate, not a formality. Always:

Call
```
invariants_add
```
with
```
dryRun: true
```
(the default). This renders the entry + diff and writes nothing.
Show the author the rendered entry and the file diff verbatim. Make the confirmation explicit: ask "commit this entry?" — do not silently re-invoke.
Only on explicit confirmation, re-invoke
```
invariants_add
```
with
```
dryRun: false
```
. This appends the entry, wires
```
.exarchos.yml
```
if the catalog is unregistered, and emits
```
invariant.authored
```
(+
```
catalog.registered
```
on first registration — INV-1).
Run
```
doctor
```
(the
```
invariants-catalog
```
check) to validate the resolved catalog.
Show the
```
invariants_effective
```
delta so the author sees exactly what the gate will now enforce.

invariants_add

returns a

CATALOG_NOT_FOUND

error, the target catalog does not exist yet — run

invariants_scaffold

first (the error's

suggestedFix

names the call), then resume at step 6.

此步骤是关键环节，而非形式流程。请始终遵循以下步骤：

调用
```
invariants_add
```
并设置
```
dryRun: true
```
（默认值）。这会渲染条目及差异，但不执行写入操作。
向作者展示渲染后的条目和文件差异原文。明确要求确认：询问"是否提交此条目？"——请勿静默重新调用指令。
仅在获得明确确认后，重新调用
```
invariants_add
```
并设置
```
dryRun: false
```
。这会追加条目，若目录未注册则更新
```
.exarchos.yml
```
，并触发
```
invariant.authored
```
事件（首次注册时还会触发
```
catalog.registered
```
事件——INV-1）。
运行
```
doctor
```
（
```
invariants-catalog
```
检查）以验证解析后的目录。
展示
```
invariants_effective
```
的变化，让作者清楚了解gate现在将强制执行的规则。

若

invariants_add

CATALOG_NOT_FOUND

错误，说明目标目录尚未存在——请先运行

invariants_scaffold

（错误信息的

suggestedFix

会指定调用方式），然后回到步骤6继续。

Tool invocations

工具调用

Scaffold a user catalog (idempotent; never overwrites):

exarchos:exarchos_orchestrate({
  action: "invariants_scaffold",
  tier: "user",
  path: ".exarchos/invariants.md"
})

Dry-run preview (DEFAULT — writes nothing):

exarchos:exarchos_orchestrate({
  action: "invariants_add",
  tier: "user",
  catalog: ".exarchos/invariants.md",
  entry: { /* the fields from steps 1-4; NO id — auto-assigned */ }
})

Commit after explicit confirmation:

exarchos:exarchos_orchestrate({
  action: "invariants_add",
  tier: "user",
  catalog: ".exarchos/invariants.md",
  entry: { /* same entry */ },
  dryRun: false
})

Use

exarchos:exarchos_orchestrate({ action: "describe" })

(or the CLI

--help

) to discover the exact schema at runtime — flags auto-emit from each action's Zod schema (the CLI is schema-driven; do not assume hand-added flags).

创建用户目录（幂等操作；绝不会覆盖现有文件）：

exarchos:exarchos_orchestrate({
  action: "invariants_scaffold",
  tier: "user",
  path: ".exarchos/invariants.md"
})

试运行预览（默认设置——不执行写入）：

exarchos:exarchos_orchestrate({
  action: "invariants_add",
  tier: "user",
  catalog: ".exarchos/invariants.md",
  entry: { /* 步骤1-4中的字段；无需ID——自动分配 */ }
})

获得明确确认后提交：

exarchos:exarchos_orchestrate({
  action: "invariants_add",
  tier: "user",
  catalog: ".exarchos/invariants.md",
  entry: { /* 相同条目 */ },
  dryRun: false
})

使用

exarchos:exarchos_orchestrate({ action: "describe" })

（或CLI的

--help

）在运行时发现精确的schema——参数会自动从每个动作的Zod schema生成（CLI基于schema驱动；请勿假设存在手动添加的参数）。

Worked example

示例

For one

U-*

entry authored end-to-end through all 6 steps, see

@references/worked-example.md

有关通过完整6步流程创建一个

U-*

条目的示例，请参阅

@references/worked-example.md

。

Anti-Patterns

反模式

Don't	Do Instead
Hand-write or `Edit` catalog YAML	Always route mutations through `invariants_add`
Declare an entry valid yourself	The verb validates; you confirm
Default to `mode: check`	Default to `mode: audit` ; `check` is opt-in ( `@references/check-mode.md` )
Skip the dry-run	`dryRun: true` first, ALWAYS, then explicit confirm
Silently re-invoke with `dryRun: false`	Make the confirmation step explicit
Pick an id by hand	The verb auto-assigns the next free id in the namespace
Author into `dev` / `INV-N` from a consumer repo	`dev` is exarchos's reserved substrate namespace — use `user` / `U-N` (the verb rejects consumer `tier: dev` )
Infer globs from the framework	Ask the author to name the globs (INV-6)
Skip `doctor` + `invariants_effective` after commit	Verify the resolved catalog and show the delta

错误做法	正确做法
手动编写或 `Edit` 目录YAML	始终通过 `invariants_add` 处理变更
自行声明条目有效	由指令验证，你只需确认
默认使用 `mode: check`	默认使用 `mode: audit` ； `check` 为可选功能（ `@references/check-mode.md` ）
跳过试运行	始终先执行 `dryRun: true` ，再获得明确确认
静默重新调用并设置 `dryRun: false`	明确要求确认步骤
手动选择ID	由指令自动分配命名空间中的下一个可用ID
在用户仓库中创建 `dev` / `INV-N` 层级条目	`dev` 是exarchos保留的底层命名空间——使用 `user` / `U-N` （指令会拒绝用户使用 `tier: dev` ）
从框架推断glob路径	请作者指定glob路径（INV-6）
提交后跳过 `doctor` + `invariants_effective` 检查	验证解析后的目录并展示变化

invariants

Original

Translation

Authoring Invariants Skill

架构约束创建Skill

Overview

概述

When to Use

使用场景

When NOT to Use

禁用场景

The verbs (what you drive — never bypass)

指令（你需驱动执行，切勿绕过）

The interview (6 steps)

访谈流程（6步）

1. Elicit — the rule →
`summary`

1. 提取——规则→
`summary`

2. Locate —
`dimension`
,
`applies-to`
, affinities

2. 定位——
`dimension`
、
`applies-to`
、关联属性

3. Weight —
`severity`
,
`integrity-class`
, and the
`tier`
you author into

3. 权重设置——
`severity`
、
`integrity-class`
，以及你要创建的
`tier`

4. Enforce — DEFAULT
`mode: audit`
,
`mode: check`
is opt-in

4. 执行——默认
`mode: audit`
，
`mode: check`
为可选高级功能

5. Number — auto-id in the target namespace

5. 编号——目标命名空间中的自动ID

6. Commit — dry-run → confirm → write → verify

6. 提交——试运行→确认→写入→验证

Tool invocations

工具调用

Worked example

示例

Anti-Patterns

反模式

invariants

Original

Translation

Authoring Invariants Skill

架构约束创建Skill

Overview

概述

When to Use

使用场景

When NOT to Use

禁用场景

The verbs (what you drive — never bypass)

指令（你需驱动执行，切勿绕过）

The interview (6 steps)

访谈流程（6步）

1. Elicit — the rule → summary

1. 提取——规则→summary

2. Locate — dimension, applies-to, affinities

2. 定位——dimension、applies-to、关联属性

3. Weight — severity, integrity-class, and the tier you author into

3. 权重设置——severity、integrity-class，以及你要创建的tier

4. Enforce — DEFAULT mode: audit, mode: check is opt-in

4. 执行——默认mode: audit，mode: check为可选高级功能

5. Number — auto-id in the target namespace

5. 编号——目标命名空间中的自动ID

6. Commit — dry-run → confirm → write → verify

6. 提交——试运行→确认→写入→验证

Tool invocations

工具调用

Worked example

示例

Anti-Patterns

反模式

1. Elicit — the rule →
`summary`

1. 提取——规则→
`summary`

2. Locate —
`dimension`
,
`applies-to`
, affinities

2. 定位——
`dimension`
、
`applies-to`
、关联属性

3. Weight —
`severity`
,
`integrity-class`
, and the
`tier`
you author into

3. 权重设置——
`severity`
、
`integrity-class`
，以及你要创建的
`tier`

4. Enforce — DEFAULT
`mode: audit`
,
`mode: check`
is opt-in

4. 执行——默认
`mode: audit`
，
`mode: check`
为可选高级功能