@teamix-evo/skills 0.3.0 → 0.5.0

package/README.md

@@ -42,15 +42,19 @@ pnpm --filter @teamix-evo/skills scaffold:skill
 由 `teamix-evo skills` 子命令族管理（source-mirror 模型见 [ADR 0013](../../docs/adr/0013-skills-source-mirror.md)）：
 
 ```bash
-teamix-evo skills add                # 全量装入 manifest 内所有 skill
-teamix-evo skills add <name...>      # 增量：仅装入指定 skill（可多个）
+teamix-evo skills init               # 自举：按 variant + scope 全装符合条件的 skill（ADR 0034）
+teamix-evo skills add <name...>      # 增量：仅装入指定 skill（必填，至少一个）
 teamix-evo skills list               # 列出全部 skill（默认：已装✓ / 未装○）
-teamix-evo skills update             # 升级到最新版（managed 策略保留你的自定义）
+teamix-evo skills update [name...] [--dry-run]  # 升级已装 skill（ADR 0035 双闸 + version 短路）
 teamix-evo skills sync [name...]     # 源 → IDE 镜像（漂移恢复用）
 teamix-evo skills doctor             # 检测源 / 镜像漂移
 teamix-evo skills uninstall          # 卸载（源 + 镜像 + lock）
 ```
 
+> **verb 分工(ADR 0034)**:`init` 自举(无 ids)/ `add` 增量(必填 ids)。`skills add` 不传 id → commander 报错并输出 help。
+>
+> **scope 过滤(ADR 0033)**:`skills init` 跳过 manifest 里 `scope` 与当前 install scope 不匹配的 entry。entry skill `teamix-evo-manage` 标 `scope: "global"`,因此项目级 init 不会重复装入 —— 它由「全局装机」段一次性装到全局。`skills add` 显式指名 global-only skill 时仍可装入,但会得到 warning。
+
 ### 全局装机（`--scope global`）
 
 ```bash

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://teamix-evo.dev/schema/skills-package/v1.json",
   "schemaVersion": 1,
   "package": "skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "engines": {
     "teamix-evo": ">=0.1.0"
   },
@@ -10,69 +10,86 @@
     {
       "id": "teamix-evo-manage",
       "name": "teamix-evo-manage",
-      "description": "Manage the teamix-evo toolkit lifecycle inside the current project — install, initialize, update, list, or uninstall design / skills / ui / biz-ui / templates packages.\nTRIGGER when: user runs or asks about CLI commands `teamix-evo design init|update|list|list-variants|uninstall`, `teamix-evo skills add|update|list|uninstall|sync|doctor`, `teamix-evo ui init|add|list`, `teamix-evo biz-ui add|list-variants`, `teamix-evo templates add|list-variants`; phrases like \"init teamix-evo\"、\"set up the design system\"、\"装一下 teamix-evo\"、\"升级 teamix-evo\"、\"卸载 teamix-evo\"、\"看看装了哪些 teamix-evo 资源\"、\"加业务组件\"、\"加页面模板\"; user touches `.teamix-evo/config.json` or `.teamix-evo/manifest.json`.\nSKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files, design tokens, or business logic. Those go to teamix-evo-coding-conventions or teamix-evo-design-rules. SKIP if the user is mid-flow inside an already-initialized project asking to \"新增页面 / 加按钮 / 调接口\" — that's coding work, not lifecycle. SKIP placeholder→real UI migration (\"升级 UI\"、\"接入真组件\"、\"replace placeholders\") — that's owned by teamix-evo-ui-upgrade.\nCoordinates with: teamix-evo-ui-upgrade (hand off the placeholder migration loop after `ui add` is in place); otherwise lifecycle is the entry point and precedes content skills rather than co-triggering.",
-      "version": "0.1.0",
-      "source": "skills/teamix-evo-manage",
-      "ides": ["qoder", "claude"],
+      "description": "Single entry point for the teamix-evo lifecycle: scaffold a new project, install the AI coding system into an existing repo, run / update / inspect / remove any teamix-evo package, and drive the placeholder→real UI migration loop after `npm create teamix-evo`.\nTRIGGER when: (CLI) user runs or asks about `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo templates ...` / `teamix-evo lint ...` / `teamix-evo logs ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) \"初始化一个项目\"、\"初始化一个工程\"、\"初始化一个 teamix-evo 工程\"、\"初始化一个 Teamix Evo 项目\"、\"create a teamix-evo project\"、\"set up teamix-evo from scratch\"、\"new teamix-evo app\"; (具名变体初始化) \"初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目\"、\"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程\"、\"new opentrek/uni-manager project\"; (AI coding 接入) \"给现有仓库装 teamix-evo\"、\"现有项目装一下 skills + ui\"、\"接入 AI coding 体系\"、\"装 teamix-evo 进这个项目\"、\"add teamix-evo to existing repo\"、\"install AI coding system\"、\"接入 opentrek 研发体系\"、\"接入 op 研发体系\"、\"接入 OpenTrek 研发体系\"、\"接入 opentrek 研发系统\"、\"接入 op 研发系统\"、\"接入云管研发体系\"、\"接入云管研发系统\"、\"接入 uni-manager 研发体系\"、\"接入 uni-manager 研发系统\"、\"接入统一管理研发体系\"; (更新检测) \"升级 teamix-evo\"、\"看看哪些要升级\"、\"update teamix-evo\"、\"check what needs updating\"、\"refresh installed teamix-evo packages\"; (卸载 / 清单) \"卸载 teamix-evo\"、\"看看装了哪些 teamix-evo 资源\"、\"remove the design system\"、\"list installed\"; (placeholder→real 升级) \"升级 UI\"、\"接入真组件\"、\"替换 placeholder\"、\"upgrade UI\"、\"replace placeholders\"、\"swap in real components\"、\"make the UI real\", or user opens / edits `src/components/_placeholder/**`, project contains `.teamix-evo/create/pending-ui.json`, literal `@teamix-evo:placeholder` tag in code; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`、`.teamix-evo/create/pending-ui.json`.\nSKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the migration loop, design tokens, or business logic. Those go to teamix-evo-code-opentrek or teamix-evo-design-opentrek. SKIP if the user is mid-flow inside an already-initialized project asking to \"新增页面 / 加按钮 / 调接口\" — that's coding work, not lifecycle. SKIP pure styling / token tweaks — those go to ESLint + `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (visual side after a screen is generated)、teamix-evo-code-opentrek (file placement / reuse rules) — manage is the entry point and precedes content skills, never co-triggers.",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-manage",
+      "ides": [
+        "qoder",
+        "claude"
+      ],
       "updateStrategy": "managed",
-      "managedRegions": ["core"],
-      "template": false
+      "managedRegions": [
+        "core"
+      ],
+      "template": false,
+      "scope": "global"
     },
     {
-      "id": "teamix-evo-design-rules",
-      "name": "teamix-evo-design-rules",
-      "description": "Apply teamix-evo design system rules when AI is asked to generate or review a full UI screen / page (variant-neutral baseline).\nTRIGGER when: user asks to \"新建 / 优化 / 重构 一个页面\"、\"做一个列表页 / 详情页 / 表单页 / 仪表盘\"、\"create / review / refactor a page、screen、dashboard、template\"; intent involves layout structure, page-level information density, or multi-component composition; file write under `src/pages/**` or `src/templates/**`.\nSKIP: single-component edits like \"加个按钮\"、\"改 input 的 label\"、\"调 card 的 padding\"、\"add a tooltip\" — those go to teamix-evo-coding-conventions; pure tokens / theme override edits — those go to ESLint and `tokens.overrides.css`; pure code refactor with no visual change; teamix-evo lifecycle commands — those go to teamix-evo-manage.\nCoordinates with: teamix-evo-design-rules-<variant> (always layered when same-named variant is installed in `.teamix-evo/design/pack.lock.json`); teamix-evo-coding-conventions (run alongside when the screen also creates new files).",
-      "version": "0.6.0",
-      "source": "skills/teamix-evo-design-rules",
-      "ides": ["qoder", "claude"],
+      "id": "teamix-evo-design-opentrek",
+      "name": "teamix-evo-design-opentrek",
+      "description": "Apply OpenTrek design system rules (philosophy, patterns, page-types, brand tone/voice, visual foundations) when AI generates or reviews a full UI screen / page in an OpenTrek-variant project.\nTRIGGER when: user asks to \"新建 / 优化 / 重构 一个页面\"、\"做一个列表页 / 详情页 / 表单页 / 仪表盘\"、\"create / review / refactor a page、screen、dashboard、template\"; intent involves layout structure, page-level information density, or multi-component composition; file write under `src/pages/**` or `src/templates/**`.\nSKIP: single-component edits like \"加个按钮\"、\"改 input 的 label\"; pure tokens/theme overrides; pure code refactor with no visual change; teamix-evo lifecycle commands (defer to teamix-evo-manage).\nCoordinates with: teamix-evo-code-opentrek (run alongside when the screen also creates new files).",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-design-opentrek",
+      "variant": "opentrek",
+      "ides": [
+        "qoder",
+        "claude"
+      ],
       "updateStrategy": "managed",
-      "managedRegions": ["core"],
+      "managedRegions": [
+        "core"
+      ],
       "template": false
     },
     {
-      "id": "teamix-evo-design-rules-opentrek",
-      "name": "teamix-evo-design-rules-opentrek",
-      "description": "Apply OpenTrek brand-specific design rules (tone / voice / brand color usage) on top of the variant-neutral teamix-evo-design-rules baseline.\nTRIGGER when: teamix-evo-design-rules is triggering AND the project's `.teamix-evo/design/pack.lock.json` records `variant: \"opentrek\"`; tasks where brand voice, copywriting tone, or OpenTrek-specific brand color usage is in scope; phrases like \"OpenTrek 风格\"、\"沉稳 / 克制 的文案\"、\"按 OpenTrek 调性写空态 / 标题 / 引导\".\nSKIP: project does not have OpenTrek variant installed; tasks belonging to other variants (`uni-manager` etc.); single-component edits with no copy / brand concern; pure structural / layout decisions with no brand surface.\nCoordinates with: teamix-evo-design-rules (mandatory — this is an overlay, never standalone).",
-      "version": "0.1.0",
-      "source": "skills/teamix-evo-design-rules-opentrek",
+      "id": "teamix-evo-code-opentrek",
+      "name": "teamix-evo-code-opentrek",
+      "description": "Enforce teamix-evo coding conventions in OpenTrek-variant consumer apps — reuse-first against `@teamix-evo/ui` registry, API code under `src/services/`, `src/` layering and import boundaries.\nTRIGGER when: user asks to \"新增 / 重构 / 写一个\" 组件 / 页面 / 接口 / 钩子 / 工具 / hook; phrases like \"create a CRUD page\"、\"add an API call\"、\"extract a hook\"、\"refactor this fetch\"、\"调一下接口\"、\"加个组件\"、\"加个按钮\"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed project.\nSKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-opentrek); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-code-opentrek",
       "variant": "opentrek",
-      "ides": ["qoder", "claude"],
+      "ides": [
+        "qoder",
+        "claude"
+      ],
       "updateStrategy": "managed",
-      "managedRegions": ["core"],
+      "managedRegions": [
+        "core"
+      ],
       "template": false
     },
     {
-      "id": "teamix-evo-design-rules-uni-manager",
-      "name": "teamix-evo-design-rules-uni-manager",
-      "description": "Apply cloud-management-specific design rules (AI scenarios A-G, danger ops, command center / topology patterns) on top of the variant-neutral teamix-evo-design-rules baseline.\nTRIGGER when: teamix-evo-design-rules is triggering AND the project's `.teamix-evo/design/pack.lock.json` records `variant: \"uni-manager\"`; tasks involving 云资源管理 / AI 副驾驶场景 / 高危删除 / 跨区域迁移 / 流量切换 / 指挥官大屏 / 拓扑感知 / 告警诊断; phrases like \"做一个云资源列表 / 大屏 / 命令面板 / 危险操作确认\"; file paths involving `cockpit / topology / cloud-resources / alarm`.\nSKIP: project does not have uni-manager variant installed; tasks belonging to other variants (`opentrek` etc.); pure non-cloud business pages even within a uni-manager project (defer to baseline rules only); single-component edits with no danger-op or scenario surface.\nCoordinates with: teamix-evo-design-rules (mandatory — this is an overlay, never standalone).",
-      "version": "0.1.0",
-      "source": "skills/teamix-evo-design-rules-uni-manager",
+      "id": "teamix-evo-design-uni-manager",
+      "name": "teamix-evo-design-uni-manager",
+      "description": "Apply Uni-Manager design system rules (philosophy, patterns, page-types, brand tone/voice, visual foundations) when AI generates or reviews a full UI screen / page in a Uni-Manager-variant project (专有云 / 混合云 / 云管平台 / hybrid cloud console).\nTRIGGER when: user asks to \"新建 / 优化 / 重构 一个页面\"、\"做一个列表页 / 详情页 / 表单页 / 仪表盘 / 控制台首页\"、\"create / review / refactor a page、screen、dashboard、console、admin template\"; intent involves layout structure, page-level information density, or multi-component composition for hybrid-cloud / multi-tenant / multi-region scenarios; file write under `src/pages/**` or `src/templates/**`.\nSKIP: single-component edits like \"加个按钮\"、\"改 input 的 label\"; pure tokens/theme overrides; pure code refactor with no visual change; teamix-evo lifecycle commands (defer to teamix-evo-manage).\nCoordinates with: teamix-evo-code-uni-manager (run alongside when the screen also creates new files).",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-design-uni-manager",
       "variant": "uni-manager",
-      "ides": ["qoder", "claude"],
+      "ides": [
+        "qoder",
+        "claude"
+      ],
       "updateStrategy": "managed",
-      "managedRegions": ["core"],
+      "managedRegions": [
+        "core"
+      ],
       "template": false
     },
     {
-      "id": "teamix-evo-ui-upgrade",
-      "name": "teamix-evo-ui-upgrade",
-      "description": "Replace `_placeholder/` UI components with real `@teamix-evo/ui` registry entries in projects scaffolded by `npm create teamix-evo -- --preset console`.\nTRIGGER when: user asks to \"升级 UI\"、\"接入真组件\"、\"替换 placeholder\"、\"upgrade UI\"、\"replace placeholders\"、\"swap in real components\"、\"make the UI real\"; user opens / edits a file under `src/components/_placeholder/**`; project contains `.teamix-evo/create/pending-ui.json`; literal `@teamix-evo:placeholder` tag appears in a file the user is touching.\nSKIP: project has no `.teamix-evo/create/pending-ui.json` (placeholders already cleared or never installed); user wants to add a NEW component that isn't on the pending list (defer to teamix-evo-coding-conventions); user is editing component internals, not migrating; user is initializing / updating teamix-evo itself (defer to teamix-evo-manage).\nCoordinates with: teamix-evo-coding-conventions (touch only when migrating import sites — file placement and reuse rules apply); teamix-evo-manage (uses `teamix-evo ui add` under the hood — but this skill drives the migration loop).",
-      "version": "0.1.0",
-      "source": "skills/teamix-evo-ui-upgrade",
-      "ides": ["qoder", "claude"],
-      "updateStrategy": "managed",
-      "managedRegions": ["core"],
-      "template": false
-    },
-    {
-      "id": "teamix-evo-coding-conventions",
-      "name": "teamix-evo-coding-conventions",
-      "description": "Enforce teamix-evo coding conventions in consumer business apps — reuse-first against `@teamix-evo/ui` registry, API code under `src/services/`, `src/` layering and import boundaries.\nTRIGGER when: user asks to \"新增 / 重构 / 写一个\" 组件 / 页面 / 接口 / 钩子 / 工具 / hook; phrases like \"create a CRUD page\"、\"add an API call\"、\"extract a hook\"、\"refactor this fetch\"、\"调一下接口\"、\"加个组件\"、\"加个按钮\"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed project.\nSKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-rules); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-rules (run alongside when the change also creates a UI screen — design-rules handles the visual side, this skill handles file placement and reuse).",
-      "version": "0.1.0",
-      "source": "skills/teamix-evo-coding-conventions",
-      "ides": ["qoder", "claude"],
+      "id": "teamix-evo-code-uni-manager",
+      "name": "teamix-evo-code-uni-manager",
+      "description": "Enforce teamix-evo coding conventions in uni-manager (hybrid-cloud / multi-tenant console) consumer apps — reuse-first against `@teamix-evo/ui` registry + `biz-ui/uni-manager` (um-topbar / CloudBadge), API code under `src/services/` with tenant / region context propagation, `src/` layering and import boundaries.\nTRIGGER when: user asks to \"新增 / 重构 / 写一个\" 组件 / 页面 / 接口 / 钩子 / 工具 / hook in a hybrid-cloud / 专有云 / 多租户 / 多区域 console; phrases like \"create a CRUD page\"、\"add an API call\"、\"extract a hook\"、\"refactor this fetch\"、\"调一下接口\"、\"加个组件\"、\"加个按钮\"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed uni-manager-variant project.\nSKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-uni-manager); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-uni-manager (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-code-uni-manager",
+      "variant": "uni-manager",
+      "ides": [
+        "qoder",
+        "claude"
+      ],
       "updateStrategy": "managed",
-      "managedRegions": ["core"],
+      "managedRegions": [
+        "core"
+      ],
       "template": false
     }
   ]

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@teamix-evo/skills",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Skills (AI IDE capabilities) for Teamix Evo",
   "type": "module",
   "files": [
     "manifest.json",
     "_data.json",
-    "skills",
+    "src",
     "_template"
   ],
   "devDependencies": {
     "@clack/prompts": "^0.8.0",
     "tsx": "^4.0.0",
-    "@teamix-evo/registry": "0.3.0"
+    "@teamix-evo/registry": "0.6.0"
   },
   "publishConfig": {
     "access": "public",

package/src/teamix-evo-code-opentrek/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: teamix-evo-code-opentrek
+description: |
+  Enforce teamix-evo coding conventions in OpenTrek-variant consumer apps — reuse-first against `@teamix-evo/ui` registry, API code under `src/services/`, `src/` layering and import boundaries.
+  TRIGGER when: user asks to "新增 / 重构 / 写一个" 组件 / 页面 / 接口 / 钩子 / 工具 / hook; phrases like "create a CRUD page"、"add an API call"、"extract a hook"、"refactor this fetch"、"调一下接口"、"加个组件"、"加个按钮"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed project.
+  SKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-opentrek); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.
+  Coordinates with: teamix-evo-design-opentrek (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).
+---
+
+# teamix-evo-code-opentrek
+
+This skill bundles the **AI-readable engineering conventions** for OpenTrek-variant consumer business apps that consume `@teamix-evo/*` packages. It complements [`teamix-evo-design-opentrek`](../teamix-evo-design-opentrek/SKILL.md) — design tells AI _what a screen should look like_; this skill tells AI _where the code should live and what to reuse before writing new code_.
+
+<!-- teamix-evo:managed:start id="core" -->
+
+## When to use
+
+Activate this skill whenever AI is about to **write or refactor code** inside a consumer app that has installed teamix-evo. Common signals:
+
+- "新增一个 xxx 页面 / 列表页 / 详情页"
+- "加一个 xxx 接口 / 调用 xxx API"
+- "写一个 xxx 组件"
+- "把这段重构一下"
+- "create a CRUD page for orders"
+- "add an API call to fetch users"
+- Any time AI is about to create a new file under `src/pages/`、`src/components/`、`src/services/`、`src/hooks/`
+
+If the task is purely about _visual design_ of a screen (layout / colors / spacing), use [`teamix-evo-design`](../teamix-evo-design/SKILL.md) instead — or run both in tandem.
+
+## What this skill does
+
+Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-4 are baseline (**必须执行，不得跳过**); steps 5-7 are topic gates (run when the task touches that topic); step 8 is the final self-review (**必须执行，不得跳过**).
+
+1. **🚧 Reuse-first check** — **MUST READ** [`reuse-first.md`](reuse-first.md). Before creating any new component, query the `@teamix-evo/ui` registry (via MCP `list_components` / `find_components`) and grep the local project. Only write new code when no reuse path exists.
+2. **🚧 Layering check** — **MUST READ** [`api-layering.md`](api-layering.md). Any code that talks to a backend goes under `src/services/<domain>.ts`. Components never call `fetch` / `axios` directly. Data hooks live in `src/hooks/` and consume services.
+3. **🚧 Directory check** — **MUST READ** [`file-structure.md`](file-structure.md). Place the new file under the right top-level folder (pages / components / services / hooks / types / utils / lib / stores / contexts). Each folder has a single responsibility and an import boundary.
+4. **🚧 Forms gate** — if the task involves a form, **MUST READ** [`forms-and-validation.md`](forms-and-validation.md). `react-hook-form` + `zod`; schema lives at `src/services/<domain>.schema.ts`. Never wire forms with raw `useState`.
+5. **Error/loading gate** — if the task adds a page or data hook, **MUST READ** [`error-and-loading.md`](error-and-loading.md). Ensure global ErrorBoundary, page-level fallback, and three-state handling (`isPending` / `isError` / data) are in place; mutations report success/error via `toast`.
+6. **Routing gate** — if the task adds a route or page-entry, **MUST READ** [`routing-and-codesplit.md`](routing-and-codesplit.md). Pages use `React.lazy`; auth/role guards live in `src/routes/guards.tsx`; 404 / 403 / 500 fallbacks exist.
+7. **Testing gate** — **MUST READ** [`testing.md`](testing.md). Pure functions and zod schemas are **mandatory** to test; hooks and reusable components are recommended. Test files sit next to the source as `*.test.ts(x)`; `vitest` + `@testing-library/react` + `msw`.
+8. **🚧 Self-review** — **MUST READ** [`checklist.md`](checklist.md). Every item must pass before declaring the change done. Anything failing must be fixed or surfaced to the user.
+
+> ⚠️ **禁止行为**: 跳过 Step 1 (reuse-first) 直接写新组件、跳过 Step 8 (checklist) 不做自检、凭"已有知识"省略任何文件读取。
+
+## Inputs the user provides
+
+- Intent: "add a page", "add a service call", "refactor X", "extract a hook", etc.
+- Optional: domain entity (`order`、`user`、`tenant`、`workflow`)
+- Optional: existing file the change should land near
+
+## Outputs
+
+- Code placed under the conventional path (`src/pages/<id>/`、`src/services/<domain>.ts`、…)
+- Reuse decisions explicitly logged ("reused `Button` from `@teamix-evo/ui`" / "no match found, wrote a new `OrderCard` under `src/components/`")
+- Pass / fail status against [`checklist.md`](checklist.md)
+
+## How to invoke (typical flow)
+
+1. Parse user intent → identify which artifact is being created (page / component / service / hook / util / form / route)
+2. Read [`reuse-first.md`](reuse-first.md) and run the reuse query (MCP first, then local grep)
+3. Read [`file-structure.md`](file-structure.md) to pick the destination directory
+4. If the change touches network / backend, read [`api-layering.md`](api-layering.md)
+5. If the change involves a form, read [`forms-and-validation.md`](forms-and-validation.md)
+6. If the change adds a page / data hook, read [`error-and-loading.md`](error-and-loading.md) for fallback / Skeleton / toast wiring
+7. If the change adds a route or page entry, read [`routing-and-codesplit.md`](routing-and-codesplit.md)
+8. Decide test coverage per [`testing.md`](testing.md); write `*.test.ts(x)` next to source
+9. Write the code; cite each reuse / new-write decision in the response
+10. Run through [`checklist.md`](checklist.md); list pass / fail explicitly
+
+## Files in this skill
+
+| File                                                   | Purpose                                                                                                              |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [`reuse-first.md`](reuse-first.md)                     | Decision flow for reusing existing components / utilities before writing new ones                                    |
+| [`file-structure.md`](file-structure.md)               | Top-level `src/` folder layout、ownership、import boundaries、naming、global-state tier (useState → Context → store) |
+| [`api-layering.md`](api-layering.md)                   | Where API code lives (`src/services/`)、how data flows from service → hook → component                               |
+| [`forms-and-validation.md`](forms-and-validation.md)   | `react-hook-form` + `zod` patterns、schema location、submit/error wiring                                             |
+| [`error-and-loading.md`](error-and-loading.md)         | Global / page ErrorBoundary、react-query three-state、Suspense、toast、reportError                                   |
+| [`routing-and-codesplit.md`](routing-and-codesplit.md) | `React.lazy` per page、guards、404/403/500 fallback、search-params state、Suspense placement                         |
+| [`testing.md`](testing.md)                             | `vitest` + RTL + msw、co-located tests、what is mandatory vs recommended                                             |
+| [`checklist.md`](checklist.md)                         | Multi-section self-review before declaring done                                                                      |
+
+## Relationship to other skills
+
+- [`teamix-evo-design-opentrek`](../teamix-evo-design-opentrek/SKILL.md) — visual / interaction rules for screen generation. Run **alongside** this skill when the task includes UI; this skill never overrides design on visual concerns.
+- [`teamix-evo-manage`](../teamix-evo-manage/SKILL.md) — lifecycle (`init` / `update` / `uninstall` / `skills init` / `skills add`). Out of scope here.
+
+## Why these conventions
+
+- **Single source for UI** — `@teamix-evo/ui` is a source-injected component library (89 entries). Re-implementing `Button`、`Dialog`、`DataTable` etc. inside the consumer app fragments the design system and breaks token discipline.
+- **Stable seams for change** — keeping API calls in `src/services/` means a backend rename only edits one file; keeping components free of fetch logic means they stay easy to test and reuse.
+- **Predictable file location** — when AI (or a new teammate) opens an unfamiliar consumer app, the directory shape is the same across all teamix-evo-bootstrapped projects.
+
+<!-- teamix-evo:managed:end -->

package/{skills/teamix-evo-coding-conventions → src/teamix-evo-code-opentrek}/api-layering.md

@@ -1,5 +1,7 @@
 # API 数据层规范
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 2 的强制读取项。任何涉及后端通信的代码必须先读本文件。
+
 > **核心原则**:组件不直接 fetch。所有与后端通信的代码都落在 `src/services/`,通过 `src/hooks/` 暴露给组件。
 
 ---
@@ -80,6 +82,7 @@ export async function createOrder(input: CreateOrderInput): Promise<Order> {
 ```
 
 要点:
+
 - **纯函数**(不依赖 React 上下文,可以在 SSR / Node 测试中单独跑)
 - **类型来自 `src/types/`**,不要在 service 文件里就地定义 domain 类型
 - **错误不在 service 层处理** —— 抛出去给 hook / 全局 interceptor 处理(归一化在 `src/lib/http.ts`)
@@ -201,11 +204,11 @@ src/types/
 
 某些场景**允许**绕过本规范,但需要在代码注释里说明原因:
 
-| 场景 | 允许 |
-| --- | --- |
-| 静态资源 fetch(读 `public/` 下的 json) | 组件直接 `fetch` 可,不用进 service |
-| 第三方 SDK(地图、支付)有自己的客户端 | 包装层放 `src/lib/<sdk>.ts`,不强制走 services |
-| 一次性的诊断 / 调试代码 | 临时 fetch 可,但 PR 合并前必须清理或归位 |
+| 场景                                   | 允许                                          |
+| -------------------------------------- | --------------------------------------------- |
+| 静态资源 fetch(读 `public/` 下的 json) | 组件直接 `fetch` 可,不用进 service            |
+| 第三方 SDK(地图、支付)有自己的客户端   | 包装层放 `src/lib/<sdk>.ts`,不强制走 services |
+| 一次性的诊断 / 调试代码                | 临时 fetch 可,但 PR 合并前必须清理或归位      |
 
 ---
 

package/{skills/teamix-evo-coding-conventions → src/teamix-evo-code-opentrek}/checklist.md

@@ -1,5 +1,7 @@
 # 编码自检清单
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 8 的强制读取项。AI 写完/改完代码后必须读取并逐项核对。不得跳过。
+
 > AI 写完 / 改完代码后,**必须**逐项核对。任何一项未通过都不应交付,需要先修复或显式告诉用户哪条不通过、为什么。
 
 ---
@@ -124,7 +126,7 @@
 
 (若改动包含 UI)
 
-- [ ] 视觉部分按 [`teamix-evo-design-rules`](../teamix-evo-design-rules/SKILL.md) 自检过 token / 间距 / 圆角 / 动效
+- [ ] 视觉部分按 [`teamix-evo-design-opentrek`](../teamix-evo-design-opentrek/SKILL.md) 自检过 token / 间距 / 圆角 / 动效
 - [ ] 没有硬编码颜色 / 间距 / 字号(交给 ui 包 + design token)
 
 ---
@@ -159,7 +161,7 @@
 - 数据层: ✅ services/order.ts 纯函数;✅ hooks/useOrderList.ts 包 react-query;✅ 组件未 fetch
 - 目录: ✅ 页面在 pages/orders/;✅ 跨页面组件在 components/
 - 命名: ✅ kebab 目录 / Pascal 组件 / camel hook
-- 边界: ✅ 全部走 @/*;✅ 无反向依赖
+- 边界: ✅ 全部走 @/\*;✅ 无反向依赖
 - 类型: ✅ types/order.ts 集中声明
 - 表单(若涉及): ✅ useForm + zodResolver;✅ schema 在 services/order.schema.ts
 - 错误/加载(若涉及): ✅ 三态全处理;✅ ErrorBoundary 已在 App 根;✅ mutation toast

package/{skills/teamix-evo-coding-conventions → src/teamix-evo-code-opentrek}/error-and-loading.md

@@ -1,6 +1,8 @@
 # 错误与加载态规范
 
-> **核心约定**:渲染错误用 `ErrorBoundary`,异步加载用 `react-query` 的 `isPending/isError`(必要时叠 `Suspense`),全局兜底必须存在。**不允许**白屏 / 红屏直出给用户。
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 5 的条件读取项。任务涉及页面或数据 hook 时必须读取。
+
+> **核心约定**:渲染错误用 `ErrorBoundary`,异步加载用 `react-query` 的 `isPending/isError`(必要时叠 `Suspense`),全局兗底必须存在。**不允许**白屏 / 红屏直出给用户。
 
 ---
 
@@ -62,13 +64,21 @@ createRoot(document.getElementById('root')!).render(
 // src/components/GlobalErrorFallback.tsx
 import { Button } from '@teamix-evo/ui';
 
-export function GlobalErrorFallback({ resetErrorBoundary }: { resetErrorBoundary: () => void }) {
+export function GlobalErrorFallback({
+  resetErrorBoundary,
+}: {
+  resetErrorBoundary: () => void;
+}) {
   return (
     <div className="flex min-h-screen items-center justify-center">
       <div className="text-center">
         <h1 className="text-2xl font-semibold">页面出错了</h1>
-        <p className="text-muted-foreground mt-2">已记录,可尝试刷新或返回首页</p>
-        <Button className="mt-4" onClick={resetErrorBoundary}>重新加载</Button>
+        <p className="text-muted-foreground mt-2">
+          已记录,可尝试刷新或返回首页
+        </p>
+        <Button className="mt-4" onClick={resetErrorBoundary}>
+          重新加载
+        </Button>
       </div>
     </div>
   );
@@ -130,19 +140,19 @@ function OrderListPage() {
 
 ### 三种状态都要处理
 
-| 状态 | 必须输出 |
-| --- | --- |
-| `isPending`(首次加载) | Skeleton / Spinner,**不允许**显示空 div |
-| `isError` | 错误面板 + 重试按钮,**不允许**直接 `throw` |
-| `isFetching`(后台刷新) | 表格右上角小转圈即可,不要遮罩 |
+| 状态                   | 必须输出                                   |
+| ---------------------- | ------------------------------------------ |
+| `isPending`(首次加载)  | Skeleton / Spinner,**不允许**显示空 div    |
+| `isError`              | 错误面板 + 重试按钮,**不允许**直接 `throw` |
+| `isFetching`(后台刷新) | 表格右上角小转圈即可,不要遮罩              |
 
 ### Skeleton vs Spinner 怎么选
 
-| 场景 | 用 |
-| --- | --- |
-| 列表 / 卡片 / 详情 | Skeleton(撑住布局,避免 CLS) |
-| 短动作(按钮提交、< 500ms 加载) | Spinner |
-| 全屏切换 | PageSkeleton 或 logo loading |
+| 场景                           | 用                           |
+| ------------------------------ | ---------------------------- |
+| 列表 / 卡片 / 详情             | Skeleton(撑住布局,避免 CLS)  |
+| 短动作(按钮提交、< 500ms 加载) | Spinner                      |
+| 全屏切换                       | PageSkeleton 或 logo loading |
 
 ---
 
@@ -177,14 +187,17 @@ react-query v5 支持 `useSuspenseQuery`,可把 loading 转给 `<Suspense>`:
 
 ```tsx
 function OrderListPage() {
-  const { data } = useSuspenseQuery({ queryKey: ['orders'], queryFn: listOrders });
+  const { data } = useSuspenseQuery({
+    queryKey: ['orders'],
+    queryFn: listOrders,
+  });
   return <OrderTable data={data} />; // 不需要 isPending 分支
 }
 
 // 父级:
 <Suspense fallback={<TableSkeleton rows={10} />}>
   <OrderListPage />
-</Suspense>
+</Suspense>;
 ```
 
 **何时用**:
@@ -232,15 +245,15 @@ window.addEventListener('error', (e) => reportError(e.error));
 
 ## 反模式速查
 
-| 反模式 | 为什么禁 | 应该 |
-| --- | --- | --- |
-| 没有全局 ErrorBoundary | 异常直接白屏 | App 根挂一层 |
-| `useState(false)` + `useEffect` 管 loading | 重复造轮,易漏 cancel | 走 react-query / useSuspenseQuery |
-| 只判 `isLoading` 不判 `isError` | 错误态显示空白 | 三态都处理 |
-| `if (data) return <>...</> else return null` | 无 skeleton,布局抖动 + CLS | 加 Skeleton |
-| `alert('保存失败')` | 阻断用户、丑、不可样式化 | `toast.error()` |
-| ErrorBoundary 不上报 | 错过线上 bug | `onError` 接 `reportError` |
-| service 里 `try/catch` 吞错 | 上层失去判断依据 | 让 error 抛上来,hook / boundary 决定 |
+| 反模式                                       | 为什么禁                   | 应该                                 |
+| -------------------------------------------- | -------------------------- | ------------------------------------ |
+| 没有全局 ErrorBoundary                       | 异常直接白屏               | App 根挂一层                         |
+| `useState(false)` + `useEffect` 管 loading   | 重复造轮,易漏 cancel       | 走 react-query / useSuspenseQuery    |
+| 只判 `isLoading` 不判 `isError`              | 错误态显示空白             | 三态都处理                           |
+| `if (data) return <>...</> else return null` | 无 skeleton,布局抖动 + CLS | 加 Skeleton                          |
+| `alert('保存失败')`                          | 阻断用户、丑、不可样式化   | `toast.error()`                      |
+| ErrorBoundary 不上报                         | 错过线上 bug               | `onError` 接 `reportError`           |
+| service 里 `try/catch` 吞错                  | 上层失去判断依据           | 让 error 抛上来,hook / boundary 决定 |
 
 ---