@teamix-evo/mcp 0.3.0 → 0.4.0

package/dist/data/adr/0015-skill-description-trigger-contract.md

@@ -0,0 +1,122 @@
+# 0015. Skill description = AI 触发契约,采用 TRIGGER / SKIP / Coordinates 三段结构
+
+- **Status**: Accepted
+- **Date**: 2026-05-21
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0013 Skills source-mirror 模型](0013-skills-source-mirror.md) / [0011 MCP 单包多 group](0011-mcp-single-package-multi-group.md)
+
+## Context
+
+`SKILL.md` 的 frontmatter `description` 字段是 **AI 唯一的触发依据** —— Claude Code / Qoder 在每条用户输入上扫所有已装 skill 的 description,语义匹配命中才把对应 SKILL.md 注入上下文。description 写得粗,要么过触发(示例:用户说"加个按钮"也触发了 `teamix-evo-design-rules`,被迫读 5 个 `.md` 进上下文),要么欠触发(`teamix-evo-ui-upgrade` 描述里若不含 `teamix-evo ui upgrade` 这个 CLI 提示语,真跑 upgrade 时 skill 不激活)。
+
+当前 5 个 skill 的 description 是**自由形式自然语言**,无统一约定。审视踩坑:
+
+| 现状 description 形态 | 问题 |
+| --- | --- |
+| 只列正向触发词 | 不知道哪些情况**不该**自己上,过触发风险高 |
+| 把 description 写成"功能介绍" | "做什么"挤走了"何时触发",AI 匹配信号弱 |
+| 中英混排无结构 | 跨 IDE 语义对齐弱(Cursor `.mdc` / Claude SKILL.md 同源时尤其麻烦) |
+
+业界两套成熟方案值得对照:
+
+- **Cursor Rules**(`.cursor/rules/*.mdc`)将触发条件做成**声明字段**:`alwaysApply` / `globs` / `agentRequested + description`,把"何时进上下文"从约定上升为协议(对齐 P1)
+- **Anthropic 官方 skill / cookbook 仓库** 收敛出 `TRIGGER when: ... SKIP: ...` 双段式,在 description 内**用纯文本约定结构**
+
+teamix-evo 的 SKILL.md frontmatter 是工具中立的(同时被 Qoder + Claude 读),所以走"description 内文本约定"路线 —— 不依赖 IDE 提供声明字段,可移植性最高。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| --- | --- | --- |
+| ① 维持自由形式 | 实现成本零 | 过/欠触发问题持续;skill 多起来后审计无标尺 |
+| ② 在 manifest.json 加结构化字段(triggers / skipPatterns / coordinates) | 强 schema,可校验 | IDE 不读 manifest,只读 SKILL.md frontmatter — 等于在 skill 包内多搞一层数据,与 IDE 协议脱节 |
+| ③ 让 description 自身承载结构(本决策) | 单源(SKILL.md 内),跨 IDE 一致;字符约束逼写作者收敛 | 文本结构不能在 schema 校验,要靠 lint / 写法约定 |
+
+## Decision
+
+### 1. description 三段结构(必填两段 + 可选一段)
+
+```yaml
+description: |
+  <一句话能力声明>(必填,≤ 100 字符)
+  TRIGGER when: <正向触发的具体场景 / 短语 / 文件路径模式,逗号分隔>(必填)
+  SKIP: <显式列出**不该**自己上的相邻情形>(必填)
+  Coordinates with: <可同时激活的相邻 skill,声明协作关系>(可选)
+```
+
+### 2. 各段写法规则
+
+**第一行(能力声明)**
+- 一句话,以动词开头,陈述这个 skill 解决的问题
+- 不写"how"(那是 SKILL.md 主体的事),只写"what"
+- ≤ 100 字符 —— 这是 AI 在 skill 列表扫描时第一个决策依据,长了被截断
+
+**TRIGGER when**
+- 正向枚举,**具体优于抽象**:写"用户说『新增 CRUD 页』 / 『加列表页』"而不是"用户提到页面研发"
+- 优先列动词短语 + 中英对照 + 文件路径 glob —— 三类信号 AI 都吃
+- 至少 3 个、至多 8 个 —— 太少漏触发,太多稀释信号
+
+**SKIP**(强制字段,这是与现状最大的差别)
+- 负向边界,**显式**写出哪些相邻情形该让位给别的 skill / 不上
+- 一定要列与本 skill 容易混淆的"近邻反例",这是过触发的解药
+- 至少 2 条;每条点明"该走 X 而不是本 skill"
+
+**Coordinates with**(可选)
+- 当本 skill 与某个 sibling skill 应当**同时**激活时声明,避免互斥
+- 例:design-rules + design-rules-<variant> 的叠加关系
+- 不滥用 —— 大多数 skill 不需要这段
+
+### 3. 约定的强制场景
+
+| 场景 | 必填段 |
+| --- | --- |
+| 任何 skill 新建 | description 必须三段齐全(SKIP 强制) |
+| 现有 skill 的 description 改写 | 走本约定;不允许半结构化的中间态 |
+| skill 在 manifest.json 中的 description 字段 | 与 SKILL.md frontmatter 完全一致(单源) |
+
+### 4. 校验
+
+- `pnpm --filter @teamix-evo/skills validate` 增加一条结构检查:扫每个 SKILL.md frontmatter `description`,匹配正则 `/TRIGGER when:.*\nSKIP:/s`;不命中则 fail,报错信息引用本 ADR
+- 不强制 `Coordinates with` 字段 —— 该字段按需出现
+
+### 5. 影响域
+
+**仅限 `packages/skills/`**。不推到 `.claude/agents/<id>.md`(subagent 描述写法)— 那是 Anthropic 自己的协议,且 teamix-evo 当前 4 个 subagent 已用 Anthropic 官方风格写成,改造风险大于收益。Subagent 写法约定如有需要,起独立 ADR。
+
+### 6. description 范例
+
+**反例(改造前 `teamix-evo-design-rules`)**:
+```yaml
+description: Apply teamix-evo design system rules when generating or reviewing UI screens. Bundles a 6-step generation flow, hard boundaries, a 10-section checklist, and a ready-to-use page-design prompt template. Triggers on phrases like "generate a page with teamix-evo design", "review this screen against the design system", "create a CRUD page following design rules". Variant-specific overlays (brand voice, AI scenarios, danger ops) ship as separate sibling skills (teamix-evo-design-rules-<variant>) and stack on top of this baseline.
+```
+问题:无 SKIP,过触发风险高;能力声明被淹没;coordinates 信息混在 trigger 里。
+
+**正例(改造后)**:
+```yaml
+description: |
+  Apply teamix-evo design system rules when AI is asked to generate or review a full UI screen / page.
+  TRIGGER when: user asks to "新建 / 优化 / 重构 一个页面"、"create / review / refactor a page、screen、dashboard"; intent involves layout structure, page-level information density, multi-component composition; file write under src/pages/** or src/templates/**.
+  SKIP: single-component edits ("加个按钮"、"改这个 input 的 label"、"调整这个 card 的 padding") — those go to teamix-evo-coding-conventions; pure tokens / theme override edits — those go to ESLint and tokens.overrides.css.
+  Coordinates with: teamix-evo-design-rules-<variant> (always layered when same-named variant is installed), teamix-evo-coding-conventions (run alongside when the screen also creates new files).
+```
+
+## Consequences
+
+- **Positive**:
+  - 触发精度可观测可调:示例 3"加按钮"明确进入 SKIP,不再被 design-rules 误捕
+  - skill 作者写 description 时被强制思考"这个 skill **不**该处理什么",避免 scope 扩张
+  - 跨 IDE 一致 —— Cursor 适配(v0.7)写 `.cursor/rules/<id>.mdc` 时,description 字段同源可直用
+  - 检视新 skill 时有标尺 —— PR review 直接看三段是否齐
+- **Negative**:
+  - description 长度从 ~150 字符上升到 ~400 字符,manifest.json 体积小幅增长
+  - 写作成本上升,作者需要主动想 SKIP 反例(这恰是收益)
+  - 三段结构不能强 schema 校验,只能正则 + 人审
+- **Trade-off**:
+  - 用"description 写作复杂度↑ + 手工约定"换"AI 触发可控性大幅提升 + 跨 skill 边界清晰"
+
+## Source
+
+- 2026-05-21 用户与 Claude 的架构推演会话(三层瀑布 + 示例 3 "加按钮"反例 → SKIP 约定动因)
+- [Cursor Rules 文档](https://docs.cursor.com/context/rules) — 三态触发模型(alwaysApply / globs / agentRequested)对照
+- [Anthropic claude-cookbooks](https://github.com/anthropics/claude-cookbooks) — TRIGGER / SKIP 写法范本
+- [`docs/principles.md` P1](../principles.md#p1--protocol-over-template) — 触发条件下沉到协议字段;本 ADR 是 P1 在 skill 描述层的具象

package/dist/data/adr/0016-design-md-brand-charter.md

@@ -0,0 +1,93 @@
+# 0016. DESIGN.md is a brand charter, not a content silo
+
+- **Status**: Accepted
+- **Date**: 2026-05-21
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0010](./0010-design-default-and-variants.md) (default + variants), [0013](./0013-skills-source-mirror.md) (source-mirror), [0015](./0015-skill-description-trigger-contract.md) (skill trigger contract)
+
+## Context
+
+After installing `@teamix-evo/design`, a consumer project ends up with three top-level markdown files at root —
+`AGENTS.md`, `CLAUDE.md`, `DESIGN.md` — plus a `.teamix-evo/design/**` content tree.
+
+The existing `packages/design/variants/opentrek/DESIGN.md` is **280 lines** and inlines:
+
+- Brand identity (§1)
+- Design philosophy & four principles (§2)
+- Business semantics (§3)
+- AI scenarios A–G (§4)
+- Foundation rules — color / typography / spacing / radius / shadow / motion (§5)
+- Component normative summary (§6)
+- Page patterns (§7)
+- AI generation rules (§8)
+
+**Every one of those sections also exists** as canonical files under `.teamix-evo/design/{brand,philosophy,business,scenarios,foundations,patterns,ai-rules}/`. The project ships the same content twice.
+
+This is a P2 (single source of truth) violation:
+
+- A user editing `DESIGN.md §5.3 间距` does not update `.teamix-evo/design/foundations/spacing.md` — the two drift.
+- The skill `teamix-evo-design-rules` reads from `.teamix-evo/design/**`. It never reads `DESIGN.md`. So edits to `DESIGN.md` look effective to a human but are invisible to AI generation.
+- The duplication cost compounds: every variant must inline all the rules; updating a foundation rule means editing N+1 files.
+
+The structural question is: **what is `DESIGN.md` actually for, given that:**
+
+- AI's task-time context comes from skills (`teamix-evo-design-rules{,-<variant>}`), which read `.teamix-evo/design/**` (per ADR 0013 source-mirror)
+- AI's session-bootstrap context comes from `AGENTS.md` / `CLAUDE.md`, which point to skills + canonical paths
+- Designers / new humans onboarding need a single short document to learn "what this design system stands for and where to find rules"
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| A. Keep DESIGN.md verbose (status quo) | Single doc to read for humans; works without tools | Duplicates `.teamix-evo/design/**`; drift risk; per-variant maintenance cost N+1 |
+| B. Delete DESIGN.md entirely; AGENTS.md does both jobs | Maximum dedup | AGENTS.md is AI-shaped (硬约束 / 检查清单). Humans want a brand statement, not a rule list. Tools other than Claude Code may not auto-load AGENTS.md |
+| C. DESIGN.md = thin brand charter (≤ 80 lines): identity, principles, index, pointers — no normative rules | Single source upheld; humans get an entry doc; AGENTS.md keeps its AI focus | Reduces what humans see in DESIGN.md; users must follow a pointer to read the actual rule |
+
+## Decision
+
+**Adopt Option C.** `DESIGN.md` is the **human-facing brand charter** — short, opinionated, navigational. It contains:
+
+1. **Brand identity** — one paragraph: who this design language is for, what it values.
+2. **Four design principles** — names + one-line definitions only. Detail lives in `.teamix-evo/design/philosophy/principles.md`.
+3. **Index** — a table mapping topic → canonical file under `.teamix-evo/design/**`.
+4. **Where AI looks** — a pointer that AI-generation rules live in `@teamix-evo/skills/teamix-evo-design-rules{,-<variant>}`, not in this file. (One paragraph; no rule lists.)
+5. **Project notes** — managed-region-free section the user owns.
+
+Hard caps and rules:
+
+- Total ≤ 80 lines.
+- Zero normative rules (no "use 4px grid", no "rounded-md = 6px", no AI generation flow). Those live in the canonical files.
+- Zero duplication of content found in `.teamix-evo/design/**`.
+- `managedRegions` reduced to a single `core` region — every other section is user-owned project notes.
+
+`AGENTS.md` keeps its current job: AI session entry, hard constraints, AI execution checklist, pointers.
+
+`CLAUDE.md` continues to be a thin pointer to `AGENTS.md` + `DESIGN.md`.
+
+## Consequences
+
+- **Positive**:
+  - One place per fact (P2 satisfied). A foundation rule change edits exactly one file.
+  - DESIGN.md becomes a 60-second read for humans onboarding — useful again.
+  - Variants no longer need to duplicate baseline content in their DESIGN.md; they only restate brand identity.
+  - Lower per-variant maintenance: adding a new variant means writing ~30 lines, not 280.
+  - Skill router (W4) can confidently route AI to `.teamix-evo/design/**` knowing nothing authoritative lives in DESIGN.md.
+
+- **Negative**:
+  - Existing consumer projects with edits inside the `foundation` / `components` / `patterns` managed regions of DESIGN.md will lose those regions on next `design update`. We accept the loss for projects on `>= 0.6.0`; older projects are pre-GA.
+  - A user reading DESIGN.md alone no longer sees the full design system at a glance — they must follow pointers. Mitigated by keeping the index table tight.
+
+- **Trade-off**:
+  - We trade "one document tells you everything" for "one document tells you where everything is." The first is comfortable, the second is correct.
+
+## Implementation
+
+1. **Rewrite** `packages/design/variants/opentrek/DESIGN.md` — apply the new shape.
+2. **Add** `DESIGN.md`, `AGENTS.md`, `CLAUDE.md` to `packages/design/variants/uni-manager/` and `packages/design/variants/_template/` so every variant ships consistent root files.
+3. **Update** [`packages/cli/src/core/design-pack-classify.ts`](../../packages/cli/src/core/design-pack-classify.ts) — reduce `DESIGN.md`'s `managedRegions` from `['foundation', 'components', 'patterns']` to `['core']`.
+4. **Add** a check to `packages/design/scripts/validate-pack.ts` (or equivalent) — for each variant, fail if `DESIGN.md` exceeds 100 lines or contains forbidden inline-rule patterns (a soft heuristic: matches like `4px 倍数`, `rounded-(sm|md|lg|xl|full)`, `--radius` with a value, `prefers-reduced-motion`).
+5. **Document** the new shape in [`packages/design/AGENTS.md`](../../packages/design/AGENTS.md).
+
+## Source
+
+Multi-turn architecture conversation 2026-05-21 (compacted). User's explicit approval: "第六节按你的倾向就好，所有任务全部开始。"

package/dist/data/adr/0017-mcp-design-group.md

@@ -0,0 +1,107 @@
+# 0017. MCP design group — five tools to query the consumer's design system at runtime
+
+- **Status**: Accepted
+- **Date**: 2026-05-21
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0009](./0009-registry-mcp-protocol-layer.md) (registry/MCP protocol layer), [0010](./0010-design-default-and-variants.md) (default + variants), [0011](./0011-mcp-single-package-multi-group.md) (single package / multi group), [0016](./0016-design-md-brand-charter.md) (DESIGN.md as charter)
+
+## Context
+
+The `@teamix-evo/mcp` server already exposes `registry`, `adr`, and `skills` groups. The
+[server's group registration site](../../packages/mcp/src/server.ts) reserves a slot:
+
+```ts
+// Future: createDesignGroup(opts.design), // ADR 0011, v0.6+
+```
+
+The `teamix-evo-design-rules` skill currently routes AI to specific files under
+`.teamix-evo/design/**` via project-root-relative paths. That works in IDEs that auto-resolve
+relative paths and have read access to the project tree. It breaks down when:
+
+- The IDE provides AI with **only the active editor + skill context** (no general FS access).
+- The `.teamix-evo/design/` tree is large (foundations + patterns + scenarios + variant) and
+  the model needs a focused slice ("just the principles", "just the spacing rule").
+- A reviewer wants to ask "do we have a pattern for X?" without first opening the right file.
+
+The skills group has shown that exposing structured content over MCP — list / get / find — gives
+AI a much cheaper path to the right slice than a `Read` of the whole file. Design content benefits
+from the same shape, with a few content-aware verbs (e.g. fetching just the principles list, or
+just the brand voice).
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| A. Skip MCP; rely on file-path dispatch in skills | No new code | AI without FS access can't read content; "just give me principles" requires reading whole files |
+| B. Single `design_get_file` tool that returns any path under `.teamix-evo/design/**` | Maximum generality, minimal API surface | Pushes routing logic to the AI; defeats the point of having a structured tool group |
+| C. Five content-aware tools (`design_list_principles`, `design_get_tokens`, `design_list_patterns`, `design_get_pattern`, `design_get_brand`) — one verb per major design-system concept | AI gets focused slices with clear semantics; matches the structure consumers actually use | Adds ~5 tools to the surface area; requires a content loader that knows the design tree shape |
+
+## Decision
+
+**Adopt Option C.** Add a `design` MCP group with five tools, all reading from `.teamix-evo/design/**`
+in the project the MCP server is launched from:
+
+| Tool | Purpose | Returns |
+| --- | --- | --- |
+| `design_list_principles` | Surface the four design principles + one-line definitions | id, name, oneLineDef, sourcePath |
+| `design_get_tokens` | Fetch token tables (semantic, base, theme.css) | parsed JSON of `base.tokens.json` + `semantic.tokens.json`; raw text of `tokens.theme.css` and `tokens.overrides.css` if present |
+| `design_list_patterns` | List all available patterns (page-types, journeys, flows + variant-specific cloud-* etc.) | array of {id, title, sourcePath, variantSpecific} |
+| `design_get_pattern` | Fetch one pattern's full markdown body by id | markdown text + sourcePath |
+| `design_get_brand` | Fetch tone / voice / examples (variant-specific; empty if no `brand/` exists) | object {tone?, voice?, examples?} of raw markdown |
+
+Implementation rules:
+
+1. **Loader** lives at `packages/mcp/src/design-loader.ts`. It walks the consumer project's
+   `.teamix-evo/design/` (resolved via `process.cwd()` by default; override via `loaded` option for tests).
+2. The group **does not depend on `@teamix-evo/design` source** — it only reads the consumer tree. This
+   keeps the dev-vs-consumer split clean (per ADR 0010 the consumer tree is the authoritative install).
+3. `design_list_principles` parses `philosophy/principles.md` for headings of the form `## P1 · <Name>`
+   (the canonical structure agreed in `packages/design/default/philosophy/principles.md`). If the file is
+   absent, return an empty list with a clear `note` field rather than erroring — projects that haven't
+   run `design init` should be told *what* is missing, not get a stack trace.
+4. `design_get_tokens` returns parsed JSON for `*.tokens.json` files but raw text for `*.css` files
+   — JSON is for AI to introspect, CSS is for AI to copy. Do not try to parse CSS.
+5. `design_list_patterns` discovers patterns by globbing `patterns/*.md` (default) and
+   `patterns/cloud-*.md` / `patterns/<variant>-*.md` (variant-specific markers). The `variantSpecific`
+   flag lets AI prefer a variant pattern over the baseline when both exist.
+6. `design_get_pattern` accepts the pattern's filename stem (e.g. `page-types`, `cloud-page-types`)
+   or its full registry-style id, returning raw markdown.
+7. `design_get_brand` returns up to three optional sub-files (`tone.md`, `voice.md`, `examples.md`).
+   Variants like `_template` and `default` ship no `brand/` — that's not an error, return `{}`.
+8. Tool names follow ADR 0011 §5: `<group>_<verb>_<noun>` for verbs that need a noun, or `<group>_<verb>`
+   for unique-noun verbs. (`design_list_principles` not `design_principles_list`.)
+
+## Consequences
+
+- **Positive**:
+  - AI editors with MCP but no FS access can fully participate in page generation.
+  - W8 can rewrite `teamix-evo-design-rules`'s SKILL.md to dispatch via MCP calls (faster and more
+    structured than file-path reads).
+  - Adds a debug surface for humans: `mcp inspect` can show what design content the project actually
+    exposes.
+
+- **Negative**:
+  - +5 tools on the public surface. Naming + descriptions matter; bad descriptions make AI invoke
+    the wrong tool and waste a round trip.
+  - The loader has to keep up with new files added to `.teamix-evo/design/` over time. The
+    "discover by glob" rule in §5 above is the cheapest way to absorb new variants without coupling.
+
+- **Trade-off**:
+  - We trade a tiny MCP API for a much shorter AI prompt cycle. The break-even is ~3 design-rule
+    queries per session, which a single page-generation task already exceeds.
+
+## Implementation
+
+1. **Create** `packages/mcp/src/design-loader.ts` with `loadDesign()` returning a typed snapshot
+   (principles, tokens, patterns, brand) read from `.teamix-evo/design/**`.
+2. **Create** `packages/mcp/src/groups/design.ts` exposing the five tools.
+3. **Register** in `packages/mcp/src/server.ts` — replace the `Future:` comment with a real call.
+4. **Test** with vitest under `packages/mcp/src/__tests__/groups-design.test.ts` — fixture project
+   tree, tool calls, expected JSON shape.
+5. Follow up in **W8** by rewriting `teamix-evo-design-rules`'s SKILL.md to prefer MCP calls over
+   file-path Reads, with a fallback paragraph for IDEs without MCP.
+
+## Source
+
+Multi-turn architecture conversation 2026-05-21 (compacted). User's explicit approval of all
+workstreams: "第六节按你的倾向就好，所有任务全部开始。"

package/dist/data/adr/0018-ai-context-routing.md

@@ -0,0 +1,112 @@
+# 0018. AI context routing — three-tier waterfall (AGENTS / SKILL / DESIGN) with single content source
+
+- **Status**: Accepted
+- **Date**: 2026-05-21
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0007](./0007-governance-docs-at-root.md) (governance docs at root), [0010](./0010-design-default-and-variants.md) (default + variants), [0013](./0013-skills-source-mirror.md) (skills source-mirror), [0015](./0015-skill-description-trigger-contract.md) (skill description as AI trigger), [0016](./0016-design-md-brand-charter.md) (DESIGN.md as charter), [0017](./0017-mcp-design-group.md) (MCP design group)
+
+## Context
+
+By v0.5 the consumer-side AI context split across **four overlapping surfaces**, each accumulating rules and routing logic:
+
+1. `AGENTS.md` / `CLAUDE.md` — repo-root and per-package, often duplicating each other.
+2. `DESIGN.md` — variant-shipped, started as a thin charter but grew to 280+ lines re-stating tokens, spacing rules, motion guidance.
+3. `.qoder/skills/<id>/SKILL.md` and `.claude/skills/<id>/SKILL.md` — skill descriptions used both as trigger contracts and as content.
+4. `.teamix-evo/design/**` — the actual canonical content (philosophy / foundations / patterns / brand).
+
+Symptoms:
+
+- **Triple-quoted rules.** "List page must show empty state" appeared in DESIGN.md (variant), in SKILL.md (skill body), and in `patterns/page-types.md` (design source). Update one, the other two drift.
+- **Description-as-content confusion.** Skills used long prose `description` fields that the AI partly read as the trigger and partly as the rules — neither role got served well. (Resolved separately in [ADR 0015](./0015-skill-description-trigger-contract.md).)
+- **No clear precedence.** When DESIGN.md and `patterns/page-types.md` disagreed, AI behavior was undefined. Reviewers had to guess which one was canonical.
+- **MCP-less IDEs starved.** AI editors that only see "active editor + skill context" had no way to read `.teamix-evo/design/**`, so SKILL.md tried to inline the rules — fueling triple-quoting.
+
+The root cause: **no single architecture statement** said where each kind of information lives, who reads it when, and how the AI is supposed to walk between them. ADRs 0010 / 0013 / 0015 / 0016 / 0017 each fixed one corner. This ADR wires them into one coherent waterfall.
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| A. Keep all four surfaces editable; rely on docs to discourage drift | No new code | The drift already happened — the very condition that produced it is unchanged |
+| B. Collapse everything into a single "AI manual" file per project | Single source physically | Loses task-scoped routing — every AI invocation re-reads the whole manual |
+| C. Three-tier waterfall: AGENTS (session) → SKILL (task) → DESIGN (project) → `.teamix-evo/design/**` (content); each tier has a strict role and **no normative content** above the source tier | Each tier earns its keep; rules live in exactly one place; AI walks down the waterfall by the trigger that fired | Requires hardening (validators, dispatch tables, MCP group) — already done in ADRs 0015 / 0016 / 0017 |
+
+## Decision
+
+**Adopt Option C** as the canonical AI context architecture for teamix-evo consumer projects:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Tier 1 — Session entry (AGENTS.md / CLAUDE.md, repo-root)       │
+│    Purpose: route new conversations to the right tier-2 surface  │
+│    Content: navigation table only — no normative rules           │
+└──────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  Tier 2 — Task-scoped skills (SKILL.md, package skills/)         │
+│    Purpose: AI trigger contract + behavioral procedure           │
+│    Content: description (trigger), short body (dispatch table +  │
+│             behavioral helpers); content lookup goes via MCP     │
+│             or file path into tier 4                             │
+└──────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  Tier 3 — Project charter (DESIGN.md, variant)                   │
+│    Purpose: brand statement + index into tier 4                  │
+│    Content: ≤80 lines body, single managed region, zero rules    │
+└──────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  Tier 4 — Canonical content (.teamix-evo/design/**)              │
+│    Purpose: single source of truth for design knowledge          │
+│    Content: philosophy / foundations / patterns / brand          │
+│    Access: MCP design group (preferred) or filesystem read       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+**Strict rules:**
+
+1. **Normative content lives only at tier 4.** Tier 1 / 2 / 3 may quote, summarize, or point — they may not authoritatively define spacing, color, motion, copy, or any other design rule. Validators enforce this on tier 3 ([ADR 0016](./0016-design-md-brand-charter.md) regex patterns).
+
+2. **Every tier-2 skill has a single-line trigger contract.** Per [ADR 0015](./0015-skill-description-trigger-contract.md), the SKILL.md `description` follows `TRIGGER when: / SKIP: / Coordinates with:` shape and is the only place the AI matches against to decide whether the skill fires.
+
+3. **AI walks downward, not sideways.** From tier 2 the AI either fetches tier 4 content via MCP (preferred — [ADR 0017](./0017-mcp-design-group.md) `design_*` tools) or reads `.teamix-evo/design/**` directly. It does not read sibling skills' rules, and it does not extract rules from DESIGN.md.
+
+4. **Sources are mirrored, never duplicated.** Per [ADR 0013](./0013-skills-source-mirror.md), `.teamix-evo/skills/` is the source for `.qoder/skills/` and `.claude/skills/`. Per [ADR 0010](./0010-design-default-and-variants.md), `default + variant` is the source for `.teamix-evo/design/`. Edits to mirrors are reverted on next CLI sync.
+
+5. **MCP-less IDEs degrade gracefully.** Every tier-2 skill that recommends an MCP call must list the equivalent file path as fallback. The content is identical; only the access path differs.
+
+## Consequences
+
+- **Positive**:
+  - "Where do I find / change / verify rule X?" has exactly one answer: tier 4 (`.teamix-evo/design/**`).
+  - Adding a new variant or new pattern is a single-file edit; the dispatch table in `teamix-evo-design-rules` and the `design_list_patterns` MCP tool both surface it automatically.
+  - Validators have a clear contract: tier-3 size cap, tier-2 trigger schema, tier-4 single-source.
+  - AI prompt cycles shrink: focused MCP calls return the slice the task needs, not the whole file.
+
+- **Negative**:
+  - Five ADRs (0010 / 0013 / 0015 / 0016 / 0017) had to land before this one closed — the architecture only works as a whole.
+  - Onboarding cost: contributors who previously edited DESIGN.md to add a rule must learn that rules go to `.teamix-evo/design/**` instead.
+  - MCP fallback paragraphs add a few lines to each tier-2 skill — small but recurring tax.
+
+- **Trade-off**:
+  - We trade per-tier autonomy ("just write rules where it feels natural") for global coherence (every rule has one address). For a system AI walks autonomously, the second matters more.
+
+## Implementation status
+
+| Tier | Mechanism | Status | ADR |
+| ---- | --------- | ------ | --- |
+| 1 — Session entry | Repo-root `AGENTS.md` + `CLAUDE.md` (navigation tables only) | ✅ Landed | [0007](./0007-governance-docs-at-root.md) |
+| 2 — Task skills | 6 skills with [ADR 0015](./0015-skill-description-trigger-contract.md)-shaped descriptions | ✅ Landed (W1 / W2) | [0015](./0015-skill-description-trigger-contract.md) |
+| 3 — Project charter | `DESIGN.md` ≤80 lines, single managed region | ✅ Landed (W3) | [0016](./0016-design-md-brand-charter.md) |
+| 4 — Canonical content | `.teamix-evo/design/**` (default + variant overlay) | ✅ Landed | [0010](./0010-design-default-and-variants.md) |
+| Access path A — MCP | `@teamix-evo/mcp` design group, 5 tools | ✅ Landed (W7) | [0017](./0017-mcp-design-group.md) |
+| Access path B — filesystem | Direct read of `.teamix-evo/design/**` | ✅ Always available | — |
+| Tier-2 dispatch | `teamix-evo-design-rules` SKILL.md MCP-first dispatch table | ✅ Landed (W4 / W8) | [0015](./0015-skill-description-trigger-contract.md) |
+
+## Source
+
+Multi-turn architecture conversation 2026-05-21 (compacted, 9 workstreams). User's explicit approval of all workstreams: "第六节按你的倾向就好，所有任务全部开始。" This ADR is the master entry that closes the loop opened in W1; the supporting ADRs (0015 / 0016 / 0017) carry the per-tier decisions.

package/dist/data/adr/0019-project-upgrade-flow.md

@@ -0,0 +1,156 @@
+## 0019. 已有工程升级 Teamix Evo 的语义合并 / 变体迁移 / cva codemod 流程
+
+- **Status**: Accepted (partial — `tokens update` implemented in v0.4; full cross-package codemod still planned)
+- **Date**: 2026-05-21
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0003 update 三态](0003-update-strategy-tri-state.md) / [0006 UI 升级无 baseline](0006-ui-upgrade-no-baseline.md) / [0010 design default + variants](0010-design-default-and-variants.md) / [0013 skills source-mirror](0013-skills-source-mirror.md) / [0014 ui/biz-ui/templates 三层](0014-ui-biz-ui-templates-tier.md) / [0018 AI 上下文路由](0018-ai-context-routing.md)
+
+## Context
+
+v0.5 提供的是**装机**能力(`design init` / `skills add` / `ui add`)。**升级**能力当前只有局部:
+
+| 已实现              | 现状                                                                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `skills update`     | 覆盖 SKILL.md(source-mirror,ADR 0013),只处理 skills 包,无跨包协同                                                            |
+| `ui upgrade <id>`   | placeholder skill,只换 `_placeholder/` → 真组件                                                                              |
+| `design update`     | **v0.7 stub**([`packages/cli/src/commands/design/update.ts`](../../packages/cli/src/commands/design/update.ts)),目前直接报错 |
+| `teamix-evo update` | **不存在**,无顶层 orchestrator                                                                                               |
+
+用户视角的 gap(2026-05-21 讨论结论):
+
+1. **已有工程接入 Teamix Evo** —— 没有"对当前工程安装 Teamix Evo"的入口流(只能从空目录 `npm create`)
+2. **升级现有 Teamix Evo 工程** —— 没有"按已记录配置升级到最新"的入口流
+3. **token 重命名 / 移除 / 新增** —— design 包改了 token 名,消费者代码里用 `bg-old-name` 的位置无任何提示
+4. **variant 切换** —— 不支持(`pack.lock` 写明 variant,但切换时既没差异展示也没 codemod)
+5. **frozen 文件升级** —— 默认行为是装机一次后永远不动,但若上游修了 bug,用户无路径感知
+6. **失败恢复** —— 任何一步 update 失败都可能让 `.teamix-evo/` 处于半成品状态,无快照 / 回滚
+
+这些都是 [ADR 0003](0003-update-strategy-tri-state.md) 三态语义在**多包协同 + AI 协助**场景下的展开。三态本身只回答"单文件如何处理",不回答"升级整个工程的 orchestration / 跨包依赖 / token 漂移"。本 ADR 锁方向。
+
+## Options Considered
+
+### 顶层 orchestrator 的形态
+
+| 选项                                                                                      | 优点                                                                    | 缺点                                                 |
+| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
+| A. 全部由 AI 串(skill 驱动 update)                                                        | 灵活;能利用 AI 做语义合并                                               | 不可重放;CI 不可用;失败定位难                        |
+| B. CLI orchestrator 串子命令(`teamix-evo update`),AI 仅在需要语义合并的子步骤介入(本决策) | 可重放;CI 可跑;AI 介入边界明确(只在两方语义合并 / codemod 提示这两个点) | 需要严格分层,设计成本高                              |
+| C. 完全 CLI(零 AI 介入)                                                                   | 最简单                                                                  | 任何上游 token 改名就破;managed 区合并退化为冲突标记 |
+
+### 失败恢复策略
+
+| 选项                                                                            | 缺点                                                                        |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| 不做(失败留半成品)                                                              | 不可接受                                                                    |
+| 用 git 让用户自己恢复                                                           | 业务消费方不一定 commit `.teamix-evo/`;且 update 跨多文件,git diff 不够清晰 |
+| **每步 update 前快照 `.teamix-evo/` 到 `.teamix-evo/.snapshots/<ts>/`(本决策)** | 占盘,但快照可定期清理                                                       |
+
+## Decision
+
+### D1. 顶层入口三件套
+
+```
+teamix-evo init                    # 在已有工程中初始化 Teamix Evo (新增,不仅仅是 design init)
+teamix-evo update                  # 升级整个工程到最新版本 (orchestrator,串调子命令)
+teamix-evo doctor                  # 健康度报告 (drift / 版本差距 / 兼容性,沿用 v0.9 计划)
+```
+
+`teamix-evo init` 不同于 `design init`:它是**在已有工程目录上**装一整套(design + skills + biz-ui 占位 + AGENTS.md / DESIGN.md + 视情况 ui add),覆盖用户故事中的 **B 入口**(已有工程接入)。`create-teamix-evo` 仍负责"从空目录起手"(用户故事 A 入口)。
+
+### D2. `design update` 走两阶段
+
+1. **walk-and-merge 重派生** —— 跑完整 [ADR 0010](0010-design-default-and-variants.md) 流程产出新版 pack 树
+2. **三态分流写入消费者**:
+   - `regenerable` → 直接重写
+   - `managed` → **managed-region 语义合并**:CLI 解析 `<!-- teamix-evo:managed:start id="..." -->` 块,**只重写块内容**,块外用户改动逐字保留;若用户删了 marker 锚点 → 报错并指引恢复路径(沿用 [ADR 0003](0003-update-strategy-tri-state.md))
+   - `frozen` → diff 展示 + 用户决定是否合并(默认保留用户文件,只有用户显式 `--accept-upstream <path>` 才覆盖)
+
+### D3. variant 迁移(切换 variant)
+
+- `pack.lock.json` 已记 `variant`,迁移命令:`teamix-evo design switch <new-variant>`
+- 流程:跑 walk-and-merge(以新 variant) → 与当前装机产出做 file-level diff → 展示给用户(`--apply` 才真写)
+- 旧 variant 专属文件(variant adds)落入弃用区,提示用户决定保留 / 删除
+
+### D4. token 重命名 / 移除的 cva codemod 提示(语义层)
+
+design 包改 token 名(如 `--color-fg-muted` → `--color-text-muted`),`design update` 时:
+
+1. 把 token rename 表写入 `.teamix-evo/.upgrade-hints/tokens-<ts>.json`
+2. 引导业务侧 AI 调用 skill `teamix-evo-upgrade`(新)
+3. AI 读 hint + 扫 `src/components/ui/*.tsx` 等位置,**给出 codemod 建议**(不自动改,因为 frozen 文件归用户)
+4. 用户决定是否接受
+
+> **不做**:运行时 codemod 自动改源码 —— frozen 边界优先,把"哪些组件可能受影响"的清单交给 AI 与用户讨论即可
+
+### D5. 失败恢复:`.teamix-evo/.snapshots/`
+
+- 每次 `update` / `init`(在已有工程上) / `switch` 之前,把 `.teamix-evo/` 整体快照到 `.teamix-evo/.snapshots/<utc-iso-ts>/`
+- 失败时:打印恢复命令 `teamix-evo restore <ts>`(同步实现)
+- 保留策略:默认保留最近 5 个快照,通过 `--keep-snapshots <n>` 调
+
+### D6. lock 文件协议扩展
+
+`.teamix-evo/design/pack.lock.json` 增加字段:
+
+```jsonc
+{
+  "variant": "opentrek",
+  "schemaVersion": 2, // 新增:lock schema 版本
+  "priorVariant": "uni-manager", // 新增:上一次 switch 之前的 variant(为 codemod 推断 baseline)
+  "lastUpdate": "2026-05-21T10:30:00Z", // 新增:最近一次成功 update 时间
+  "tokenRenameHistory": [
+    // 新增:可累计的 token 重命名记录(driver D4 codemod)
+    {
+      "from": "--color-fg-muted",
+      "to": "--color-text-muted",
+      "at": "2026-05-21T10:30:00Z"
+    }
+  ]
+}
+```
+
+### D7. 对 tokens 路径迁移的处理
+
+[ADR 0010 §amendment](0010-design-default-and-variants.md) 最终把 tokens 装机路径确定为消费者项目根 `tokens/`。`design update` 在检测到旧路径（`.teamix-evo/tokens/` 或 `.teamix-evo/design/foundations/tokens/`）仍有 tokens 时:
+
+1. 自动把旧路径下的 regenerable 文件迁到新路径
+2. `tokens.overrides.css` 也迁,但保留用户内容(frozen 语义)
+3. 删旧路径空目录(若彻底空)
+4. 在 update report 中告知用户
+
+## Consequences
+
+- **Positive**:
+  - 用户 B / C 入口闭环 —— 已有工程能装、能升、能切 variant
+  - 失败可回滚 —— `.snapshots/` 让用户敢点 update
+  - token 重命名不是断崖 —— 有 codemod hint + AI 协助
+  - lock 文件协议可演进 —— `schemaVersion` 给后续兼容预留
+- **Negative**:
+  - 实现量大 —— 估 v0.7 全 phase(~15 人日),需 managed-region 解析器、snapshot 管理、新 skill `teamix-evo-upgrade`、lock schema v2、整套 update 单测
+  - 跨包协同复杂 —— design / skills / biz-ui / ui 都得对齐 lock schema
+  - 用户教育 —— `init` / `update` / `switch` / `restore` / `doctor` 五个命令,文档站要拎清
+- **Trade-off**:
+  - 用"实现复杂度"换"业务消费方真实可用的升级路径";如果不做,Teamix Evo 等于一次性脚手架,价值大幅缩水
+
+## Implementation status
+
+- **本 ADR**:仅锁方向;**不实现代码**
+- **目标版本**:v0.7
+- **拆解任务**(留给 v0.7 PR):
+  1. lock schema v2 + migration(0.5)
+  2. snapshot 模块 + `restore` 命令(1)
+  3. managed-region 解析器(1.5)
+  4. `design update` 真实现 + 三态分流(2.5)
+  5. `teamix-evo init`(已有工程接入)(2)
+  6. `teamix-evo update` orchestrator(1)
+  7. `design switch` + variant migration(1.5)
+  8. token rename hint 写入 + skill `teamix-evo-upgrade`(2)
+  9. W1.4 tokens 提层兼容迁移(0.5)
+  10. 文档站 5 命令导引 + 端到端 example(1.5)
+
+## Source
+
+- 2026-05-21 用户讨论(简化包面 + 升级流程):用户故事 A/B/C 三入口、frozen + managed + regenerable 三态在升级时的语义、对 W1.4 tokens 提层的迁移要求
+- [PLAN §10.9 UI 升级机制](../../PLAN.md):已有 UI 部分的 baseline 决策(ADR 0006)
+- [`packages/cli/src/commands/design/update.ts`](../../packages/cli/src/commands/design/update.ts):当前 v0.7 placeholder
+- [`packages/cli/src/core/skills-update.ts`](../../packages/cli/src/core/skills-update.ts):skills 升级现状(参考实现)