@captain_z/zsk-skills 1.4.3 → 1.6.0

package/README.md

@@ -1,285 +1,193 @@
 # @captain_z/zsk-skills
 
-ZNorth Standard Kit 的内容包：**51 颗原子 skill**，按领域分簇组织，通过 `npx @captain_z/zsk add` 可安装到 Claude / Codex / Gemini 等多 harness。
+ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从根级 `skills/` 生成的 **core harness-first skills**；旧 `.best-practices/` 不再批量生成 installable skills，只作为扁平参考资料。
+
+包内共有 **19 颗 installable skills**，全部来自根级 `skills/`。
 
 ## 合规审查（ARCHITECTURE §4.4 硬指标）
 
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
-| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 51/51 | 结构化 lint 通过                                      |
-| `name` 以 `zsk:` 前缀，扁平 slug                                                         | ✓ 51/51 | 命名空间统一                                          |
-| `description` 使用直接陈述风格，触发词放入 `triggers`                                   | ✓ 51/51 | 触发语义由 description + triggers 共同承担            |
-| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 51/51 | stage/workflow/standard/resource/meta · core/optional |
-| `triggers` 数组非空                                                                      | ✓ 51/51 | 每颗至少 4 个关键词                                   |
+| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 19/19 | core 由 root `skills/` 生成 |
+| `name` 使用裸 slug，扁平且不含连字符                                                       | ✓ 19/19 | LLM 原生 skill 入口保持简洁；CLI 选择层使用 `zsk:<slug>` |
+| `description` 简洁表达职责和使用时机                                                       | ✓ 19/19 | 面向索引阅读；triggers 留给机器使用 |
+| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 19/19 | stage/utility · core |
+| `triggers` 数组非空                                                                      | ✓ 19/19 | 至少含裸 slug |
 | 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）                                    | ✓       | harness-neutral                                       |
-| `related:` 相对路径合法（build 已重写）                                                  | ✓       | 无孤儿引用                                            |
-| 单文件 ≤ 300 行                                                                          | ✓ 51/51 | `lint-frontmatter` 作为 error 强制                    |
+| `related:` 相对路径合法                                                                  | ✓       | core 不依赖参考层生成物                               |
+| 单文件 ≤ 300 行                                                                          | ✓ 19/19 | core 由 `lint:harness` 强制                           |
 
 当前 `max-lines` 已由 `tools/lint-frontmatter.ts` 作为 error 强制；新增或修改 skill 不应超过 300 行。
 
 ## 使用方法通则
 
-zsk skill 是 LLM **按需自动触发**的资产：
+zsk skill 是 LLM **按需自动触发**的资产。用户通常只做两件事：先安装 skill，再在业务项目里用 `zsk init` 建知识工作区。
 
-1. **安装**：`npx @captain_z/zsk add` → 选 bundle（或 custom 多选）+ 目标路径（`~/.claude/skills/` / `~/.codex/skills/` / 自定义）→ 落盘
+1. **安装**：`npx @captain_z/zsk add` → 选 profile bundle（或 custom 多选）+ 目标路径（`~/.claude/skills/` / `~/.codex/skills/` / 自定义）→ 落盘
 2. **自动发现**：LLM（Claude Code / Codex / Gemini CLI）会话启动时扫描 skill 目录，读取每份 `SKILL.md` 的 frontmatter
 3. **自动触发**：遇到匹配 `description` 或 `triggers` 的任务时，LLM 载入对应 SKILL.md 的完整内容
-4. **手动触发**（可选）：会话中显式说 "用 `zsk:spec`"、"走 `zsk:feature` 工作流"，LLM 直接载入指定 skill
+4. **手动触发**（可选）：会话中显式说 "用 `zsk:dispatch` 调度"、"用 `zsk:spec` 写规格"，LLM 直接载入指定 skill
+
+## Profile 选择
+
+Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺在 `skills/`，profile 只决定默认安装集合、阶段顺序、可选节点和严格度。
+
+| profile | skills | 适用场景 |
+| --- | ---: | --- |
+| `zsk-lite` | 7 | 小修、小项目、脚本、低风险任务 |
+| `zsk-sdlc` | 16 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
+| `zsk-frontend` | 17 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
+| `zsk-enterprise` | 17 | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only` | 19 | 旧入口兼容；安装全部 core skills |
+
+## Skill 搭配流程图
+
+`dispatch` 是 ZSK 给 OMX 的调度适配入口；`flow` 是恢复下一合法阶段的状态机入口；profile 决定主线顺序、可选节点和严格度，其他 skill 按阶段负责一段明确产物。遇到缺资料、缺证据、缺 owner 或发现缺陷时，阶段不会静默跳过，而是写 issue 或回到前置阶段补齐。
+
+```mermaid
+flowchart TD
+  Start([开始或恢复工作]) --> Dispatch[zsk:dispatch<br/>让 OMX 按 ZSK workflow 调度]
+  Dispatch --> Flow[zsk:flow<br/>读取状态与资源]
+  Flow --> Prepare[zsk:prepare<br/>收集 SRS/PRD/API/设计/测试来源]
+  Prepare --> Proposal[zsk:proposal<br/>定义 why / scope / non-goals]
+  Proposal --> Spec[zsk:spec<br/>写 FR/NFR/AC/场景]
+  Spec --> Design[zsk:design<br/>映射接口/数据流/风险]
+  Design --> Task[zsk:task<br/>拆任务与证据钩子]
+  Task --> Coding[zsk:coding<br/>小步实现]
+  Coding --> Smoke[zsk:smoke<br/>本地证明变更可运行]
+  Smoke --> Review[zsk:review<br/>阻塞式实现审查]
+  Review --> Commit[zsk:commit<br/>review 后 scoped commit]
+  Commit --> Ready[zsk:ready<br/>整理待验收证据]
+  Ready --> Verify[zsk:verify<br/>独立验证 claim]
+  Verify --> Acceptance[zsk:acceptance<br/>业务接受或拒绝]
+  Acceptance --> Archive[zsk:archive<br/>归档产物与学习反馈]
+
+  Coding -.发现问题.-> Issue[zsk:issue<br/>缺陷/阻塞/风险/问题]
+  Smoke -.失败.-> Issue
+  Review -.拒绝.-> Issue
+  Verify -.不通过.-> Issue
+  Issue --> Coding
+  Commit -.需要环境.-> Deploy[zsk:deploy<br/>部署到非生产/演示环境]
+  Deploy -.进入验证.-> Ready
+  Demo[zsk:demo<br/>正式测试前演示] --> Defect[zsk:defect<br/>QA 缺陷归类与复现]
+  Defect --> Coding
+  Commit -.需要演示.-> Demo
+```
+
+## 常见用法
+
+| 目标 | 推荐说法或命令 | 结果 |
+| --- | --- | --- |
+| 安装默认 core skills | `npx @captain_z/zsk add` | 交互选择 target 和 bundle |
+| CI 安装轻量 profile | `npx @captain_z/zsk add zsk-lite --target=~/.claude/skills --yes` | 非交互安装 7 颗常用 skills |
+| CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 16 颗标准 workflow skills |
+| Claude plugin 安装 | `/plugin marketplace add codeshareman/zsk` 后 `/plugin install zsk@zsk` | 使用 `/zsk:<slug>` 命令面 |
+| GitHub skills 管理器安装 | `npx skills add codeshareman/zsk` | 从仓库根 `skills/` 安装；不要加 `@` |
+| 不确定该用哪个 skill | "用 `zsk:dispatch` 调度" | 让 OMX 围绕 ZSK skills 分配 subagents |
+| 恢复一个项目的下一步 | "用 `zsk:flow` 继续" | 读取配置、阶段文档和 blocker，选择合法下一阶段 |
+| 明确进入某阶段 | "用 `zsk:spec` 写模块规格" | 只载入对应 stage contract |
 
 **典型消费路径**（production，安装后）：
 
-- `~/.claude/skills/<domain>/<slug>/SKILL.md` — Claude Code
-- `~/.codex/skills/<domain>/<slug>/SKILL.md` — Codex
-- `@captain_z/zsk-skills/<domain>/<slug>/SKILL.md` — 通过 npm 读
+- `~/.claude/skills/zsk-<slug>/SKILL.md` — Claude Code / flat target
+- `~/.codex/skills/zsk-<slug>/SKILL.md` — Codex / flat target
+- `./.claude-plugin/skills/<slug>/SKILL.md` + `commands/<slug>.md` — Claude plugin local target
+- `@captain_z/zsk-skills/<slug>/SKILL.md` — 通过 npm 读
+
+仓库根还发布 `.claude-plugin/plugin.json` 和 `.claude-plugin/marketplace.json`，用于 Claude Code `/plugin marketplace add codeshareman/zsk` + `/plugin install zsk@zsk`；根级 `skills/` 同时兼容 `npx skills add codeshareman/zsk`。
 
 ## 和项目知识工作区的关系
 
 `zsk init` 生成的 `.zsk/config.yaml`、`docs/SYSTEM-SPEC.md`、`.raws/`、`docs/` 和 `.issues/` 是默认项目上下文。CLI 负责创建最小骨架、使用 package-owned schema 校验、刷新 `{paths.raws}/manifest.json`，并通过 `zsk config check` / `zsk check` 做确定性校验。
 
-Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，使用 Computer Use / Browser Use 验证运行时行为，并把问题写入配置的 issue 根。Skills 必须通过 `.zsk/config.yaml` 和 `docs/{module}/module.yaml` 解析路径，不能硬编码 `.raws`、`docs` 或 `.issues`。
+Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，并把问题写入配置的 issue 根。运行时验证默认用 Playwright 产生可复现 evidence；Browser Use 用于复用已登录浏览器/profile/SSO 状态；Computer Use 只用于结构化 Web 自动化不可达或需要视觉/系统级判断的场景。Skills 必须通过 `.zsk/config.yaml` 和 `docs/{module}/module.yaml` 解析路径，不能硬编码 `.raws`、`docs` 或 `.issues`。
 
-每个阶段都要把确认过的决策、约束、例外和验证结果写回持久文件。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
+每个 skill/stage 的输入、输出、工具/能力、脚本策略和 Browser Use 策略由 harness 的 `skill-io-contract.yaml` 约束；完成后的产物路径、issue 索引同步和确认后的文档反哺由 `completion-contract.yaml` 约束。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
 
 ## 领域总览
 
+包内只保留默认可安装的 core 领域。Frontend、quality、design-handoff 等内容仍在 `.best-practices/`，按需读取，不进入默认安装面。
+
 | 领域              | skill 数 | 职责                                       |
 | ----------------- | -------- | ------------------------------------------ |
-| `sdlc/`           | 18       | 7 阶段 SDLC + 3 变更工作流 + task 执行框架 |
-| `frontend/`       | 16       | React + Web 层实现规范                     |
-| `quality/`        | 5        | 跨栈质量原则                               |
-| `design-handoff/` | 5        | 设计交付方法论                             |
-| `system/`         | 6        | 工程宪法级资源                             |
-| `meta/`           | 1        | 元信息                                     |
-| **总计**          | **51**   |                                            |
+| `skills/`         | 19       | harness-first 默认工作流入口               |
+| **总计**          | **19**   |                                            |
 
 ## 安装套件（bundles.yaml）
 
 | name                           | skills | 场景                                          |
 | ------------------------------ | ------ | --------------------------------------------- |
-| `sdlc-only`                    | 11     | 纯流程骨架（7 阶段 + 3 工作流 + Agent 编排），不涉及技术栈 |
-| `frontend-project`（推荐）     | 30     | SDLC 10 + Agent 编排 + Frontend 16 + Quality 3 |
-| `frontend-with-design-handoff` | 35     | frontend-project + 设计交付 5                  |
+| `zsk-lite`                     | 7      | 小型低风险任务；coding → smoke → review → commit |
+| `zsk-sdlc`（推荐）             | 16     | 标准工程交付；完整需求、实现、审查、验证、验收、归档链路 |
+| `zsk-frontend`                 | 17     | 前端/视觉/browser-facing 任务；强化 demo 和前端质量门禁 |
+| `zsk-enterprise`               | 17     | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only`                    | 19     | 旧入口兼容；安装全部 core skills |
+| `frontend-project`             | 19     | 旧入口兼容；推荐改用 `zsk-frontend` |
+| `frontend-with-design-handoff` | 19     | 旧入口兼容；推荐改用 `zsk-frontend` |
 | `custom`                       | 交互   | 通过 `zsk add` 任意多选                       |
 
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 51 skills -->
-
-## Skill 清单（按领域）
-
-> 内容由 `tools/catalog.ts` 从各 SKILL.md frontmatter 生成。重生成：`pnpm catalog`。
-
-### `sdlc/` — SDLC · 7 阶段 + 3 变更工作流 + task 框架 (18)
-
-- **`zsk:proposal`** *[stage 1 · stage · core]*
-  New-change framing (feature / bugfix / refactor) before spec work — why, success criteria, out-of-scope boundary, alternatives considered, and risks. Always the first stage of the 7-stage SDLC.
-  触发：`new feature proposal` · `bug report` · `refactor trigger` · `SMART goals`
-
-- **`zsk:spec`** *[stage 2 · stage · core]*
-  Behavioral contract writing after proposal approval — scope, numbered functional and non-functional requirements, scenarios, acceptance criteria, edge cases, and impact boundaries. Stage 2 of the 7-stage SDLC.
-  触发：`writing spec` · `behavior contract` · `acceptance criteria` · `numbered requirements`
-
-- **`zsk:design`** *[stage 3 · stage · core]*
-  Solution design after spec freeze — current-state scan, architectural decisions, implementation mapping, delivery slices, risks, rollback, and observability. Stage 3 of the 7-stage SDLC.
-  触发：`technical design` · `solution design` · `architecture decision` · `current state scan`
-
-- **`zsk:coding`** *[stage 4 · stage · core]*
-  Implementation execution after design freeze — smallest viable change, auditable delivery batches, explicit TDD rules by change type, continuous evidence capture, and local quality gates before review. Stage 4 of the 7-stage SDLC.
-  触发：`implementing design` · `auditable delivery batches` · `local quality gates` · `smallest viable change`
-
-- **`zsk:reviewing`** *[stage 5 · stage · core]*
-  PR 代码审查与 AI 多维审查核心规范。包含 Scope 偏移检测、多视角 Sub-Agent 审查、测试执行流分析、代码整洁/重构纪律、置信度校准以及按严重性排序的判定协议。
-  触发：`code review` · `PR review` · `审查合并请求` · `review this PR`
-
-- **`zsk:verify`** *[stage 6 · stage · core]*
-  Acceptance verification before merge — independent contract check, FR/NFR coverage, AC evidence, gate records, and verdict with reproducible proof. Stage 6 of the 7-stage SDLC.
-  触发：`acceptance verification` · `evidence before assertion` · `FR coverage matrix` · `AC evidence`
-
-- **`zsk:archive`** *[stage 7 · stage · core]*
-  Iteration closing / archive — move historical snapshots to docs/{module}/archive/, write postmortem (P0/P1 mandatory), update changelog (SemVer + Keep a Changelog), flush ADRs, update SYSTEM-SPEC if cross-module constraints emerged, feed back to standards/system docs. Stage 7 of the 7-stage SDLC.
-  触发：`archive iteration` · `postmortem` · `changelog` · `ADR flush`
-
-- **`zsk:bugfix-tasks`** *[core]*
-  Bugfix task template with TDD enforcement — Step 1 Red (write failing reproduction test), Step 2 Green (minimal fix, no opportunistic refactor), Step 3 Regression (adjacent scenarios), Step 4 Evidence (before/after reproduction). Requires Superpowers' 3 confidence questions before starting.
-  触发：`bugfix task template` · `TDD bug fix` · `red green regression` · `bug confidence questions`
-
-- **`zsk:dor-dod`** *[core]*
-  DoR/DoD gates between SDLC stages — generic DoR/DoD for all change types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are in zsk:dor-dod-frontend.
-  触发：`definition of ready` · `definition of done` · `DoR DoD` · `task gate`
-
-- **`zsk:refactor-tasks`** *[core]*
-  Refactor task template (characterization + small-step atomic) — Step 1 capture behavior baseline, Step 2 apply one Fowler technique per atomic commit (revert on red), Step 3 Parallel Change for large refactors (Expand → Migrate → Contract), Step 4 prepare behavior-unchanged evidence.
-  触发：`refactor task template` · `characterization baseline` · `Fowler techniques` · `Parallel Change tasks`
-
-- **`zsk:task`** *[core]*
-  Cross-stage task execution mindset — what a task is, how it threads spec → verify, which template to pick by change type, cross-stage hard principles. Not for writing a specific task; use zsk:task-structure for that.
-  触发：`task framework` · `task execution overview` · `cross-stage tasks` · `which task template`
-
-- **`zsk:task-evidence`** *[core]*
-  Task verification evidence discipline — FR coverage matrix (every FR/NFR from spec has coverage task + acceptance evidence), AC checklist with reproducible links, validation records per gate (lint/type-check/test/security/etc.). Enforces "evidence before assertion" — links must be clickable and reproducible.
-  触发：`FR coverage matrix` · `AC verification` · `validation record` · `evidence links`
-
-- **`zsk:task-structure`** *[core]*
-  tasks.md authoring discipline — task granularity (0.5-2 person-days), two-level structure (parent/child, no deeper), estimation unit (T-shirt or Fibonacci), required fields per task (status/owner/covers-FR/deliverable/verification), FR coverage numbering rules.
-  触发：`task granularity` · `task estimation` · `T-shirt sizing` · `story points`
-
-- **`zsk:task-tracking`** *[core]*
-  Task execution tracking — dependencies (Mermaid graph), blockers (dated log with severity H/M/L and escalation rules), milestones, auditable LLM execution batches, and task state transitions (TODO → DOING → DONE, with BLOCKED requiring log entry).
-  触发：`task dependency graph` · `blocker log` · `milestones` · `task state flow`
-
-- **`zsk:bugfix`** *[workflow · core]*
-  Bugfix end-to-end orchestration — triage → reproduce → RCA (5 Whys with confidence questions) → TDD fix (red first) → regression coverage → postmortem (P0/P1 mandatory). Enforces Superpowers' bug confidence questioning discipline.
-  触发：`bug fix workflow` · `fix defect` · `RCA` · `5 whys`
-
-- **`zsk:feature`** *[workflow · core]*
-  Feature end-to-end orchestration across 7 SDLC stages — brainstorming → writing-plans → plan-eng-review → executing-plans+TDD → requesting/receiving-code-review → verification-before-completion → finishing-a-development-branch.
-  触发：`new feature workflow` · `feature end to end` · `start feature` · `feature stages`
-
-- **`zsk:refactor`** *[workflow · core]*
-  Behavior-preserving refactor discipline — Fowler catalog, characterization tests as baseline, small atomic commits, Parallel Change / Strangler Fig for large refactors. Enforces "behavior preserved" as a hard contract (any behavior change means it is not a refactor).
-  触发：`refactor workflow` · `Fowler refactoring` · `characterization test` · `Parallel Change`
-
-- **`zsk:standard-dev-flow`** *[workflow · core]*
-  交互式标准开发工作流，包含 Prepare 预检 + 7 阶段 SDLC（Proposal, Spec, Design, Coding, Reviewing, Verify, Archive）。通过强门禁、可审计批次和多视角审查，保障高质量开发落地。
-  触发：`standard dev flow` · `start a new feature workflow` · `execute enterprise workflow` · `7 stage development`
-
-### `frontend/` — Frontend · React + Web 层实现规范 (16)
-
-- **`zsk:spec-frontend`** *[stage 2 · stage · optional]*
-  Frontend component/page spec.md authoring — adds Component Public Contract (Props / Events / TS types), UE state matrix with a11y attributes, UE/MCP reference, and the 6-category Frontend NFR (performance / a11y / security / i18n / compat / observability). Extends the generic zsk:spec framework.
-  触发：`frontend spec` · `Component Public Contract` · `Props Event Contract` · `UE state matrix`
-
-- **`zsk:design-frontend`** *[stage 3 · stage · optional]*
-  Frontend module design.md authoring — adds Props/state/event implementation mapping, UE-state-to-structure mapping, Figma-to-implementation mapping, performance budget (Core Web Vitals), ErrorBoundary placement. Extends the generic zsk:design framework.
-  触发：`frontend design` · `Props implementation mapping` · `UE state to structure` · `Figma to implementation`
-
-- **`zsk:review-frontend`** *[stage 5 · stage · optional]*
-  Frontend PR code review — frontend-specific self-checklist and reviewer checklist covering TypeScript red lines (no any / @ts-ignore), React hooks rules, dangerouslySetInnerHTML, large-list performance hazards, visual regression, i18n three-language sync, jsx-a11y. Extends zsk:reviewing generic checklist.
-  触发：`frontend code review` · `React review checklist` · `TypeScript red lines` · `hooks review`
-
-- **`zsk:dor-dod-frontend`** *[optional]*
-  Frontend-specific DoR/DoD for SDLC stage transitions — frontend-specific rows on top of the generic checklist. Covers UE state matrix completeness, ue-mcp.md registration, visual regression, three-language i18n sync, a11y (keyboard/aria/focus), frontend NFR (CWV) evidence.
-  触发：`frontend DoR DoD` · `frontend definition of ready done` · `UE matrix gate` · `visual regression gate`
-
-- **`zsk:feature-tasks-frontend`** *[optional]*
-  Frontend component/page feature task template — 7-category mandatory (事实源对齐 / Props 契约 / UE-MCP 刷新 / UE 状态 / 测试 / 视觉回归 / 质量门禁). Enforces TDD-first, contract-driven, evidence-before-assertion.
-  触发：`frontend feature tasks` · `component tasks template` · `7 category tasks` · `Props UE state visual regression`
-
-- **`zsk:nfr-web`** *[optional]*
-  Web-side NFR thresholds for the 7-category framework — Core Web Vitals (LCP/INP/CLS/TTFB/TTI targets), WCAG 2.1 AA itemized rules, Web security NFR items, i18n language list + baseline + entry + RTL, browser/OS/device compatibility matrix, responsive breakpoints, observability (web-vitals + error reporting), reliability (ErrorBoundary + timeout + retry). Inherits system/nfr-baseline; modules declare deviations only.
-  触发：`Web NFR` · `CWV thresholds` · `WCAG AA rules` · `browser matrix`
-
-- **`zsk:a11y-web`** *[standard · optional]*
-  React/JSX accessibility implementation — label association (htmlFor/wrap), aria props usage, Modal focus trap (inert + initialFocus + restoreFocus), dialog role, live regions for async, skip link, axe-core + jsx-a11y toolchain, keyboard event handlers, prefers-reduced-motion. Implementation layer; principles (WCAG, POUR, contrast) live in quality/a11y-principles.
-  触发：`jsx a11y` · `focus trap` · `Modal accessibility` · `axe-core`
-
-- **`zsk:api-contract-ts`** *[standard · optional]*
-  TypeScript frontend × backend API contract — never hand-write API types, always consume from the shared types package or generated codegen. Covers source-of-truth pattern (backend-owned types), codegen workflows (OpenAPI / GraphQL / tRPC / Protobuf), breaking-change handling, version discipline, runtime validation (Zod at boundary), and service-layer shape. Pairs with typescript.md red lines.
-  触发：`API type sync` · `do not hand-write API types` · `OpenAPI codegen` · `GraphQL codegen`
-
-- **`zsk:i18n`** *[standard · optional]*
-  Frontend module i18n implementation — unified entry (i18n.t with mandatory fallback), key namespace structure (namespace.module.leaf_key), three-language sync rule (commit-atomic), ICU MessageFormat for plural/select, Intl.* for date/number/currency, RTL declaration, React Trans component for JSX interpolation. Replaces standards/i18n for frontend scope.
-  触发：`i18n implementation` · `key namespace` · `fallback baseline` · `ICU plural`
-
-- **`zsk:performance-web`** *[standard · optional]*
-  React / Web frontend performance for Core Web Vitals — CWV thresholds (LCP/INP/CLS/TTFB/TTI), React memoization discipline (when to memo vs not), virtualization for lists ≥ 200, lazy loading via React.lazy + Suspense + IntersectionObserver, bundle splitting + tree-shaking, image srcset + loading="lazy", debounce/throttle, re-render diagnosis with React DevTools Profiler. Implementation layer; budget framework in system/nfr-baseline + frontend/nfr-web.
-  触发：`Core Web Vitals` · `LCP INP CLS` · `React memo` · `virtual scrolling`
-
-- **`zsk:react-components`** *[standard · optional]*
-  React component API design — layering (UI/logic separation via hooks), composition vs configuration (compound components over flat-prop explosion), granularity (5-question checklist), controlled vs uncontrolled boundary, Props API design. React-specific implementation of generic component discipline.
-  触发：`React component design` · `compound components` · `component granularity` · `controlled uncontrolled`
-
-- **`zsk:react-naming`** *[standard · optional]*
-  React + TypeScript naming conventions — components, files, folders, variables, booleans, event handlers, event props, hooks, TS types/interfaces, constants, and i18n keys. Principles transfer to Vue/Svelte with syntax adjustments.
-  触发：`React naming` · `component file naming` · `event handler naming` · `boolean naming`
-
-- **`zsk:security-web`** *[standard · optional]*
-  Web frontend security — XSS (React default escape + dangerouslySetInnerHTML red line + DOMPurify exception), URL protocol whitelist, Storage red lines (no sensitive data in Local/SessionStorage), CSRF token integration, console log scrubbing for production, CSP meta/header consumption, SRI for third-party scripts, clickjacking (frame-ancestors awareness), postMessage origin checks. Frontend UI is the convenience defense; backend is final.
-  触发：`dangerouslySetInnerHTML` · `XSS React` · `DOMPurify` · `LocalStorage sensitive`
-
-- **`zsk:styling-system`** *[standard · optional]*
-  Frontend styling system discipline — scheme detection, naming conventions, nesting depth (≤3 layers), token usage rules (no hardcoded color/spacing), scope isolation, responsive breakpoints, and !important prohibition across Less / Sass / CSS Modules / Tailwind / CSS-in-JS.
-  触发：`CSS scheme detection` · `BEM naming` · `Less nesting` · `design token`
-
-- **`zsk:testing-web`** *[standard · optional]*
-  Frontend tests for React codebases — full toolchain (Jest/Vitest + React Testing Library + renderHook + user-event + MSW + Playwright + Chromatic + jest-axe), test structure (AAA/GWT), mock strategy (MSW for HTTP, manual for modules), coverage thresholds (new code / global), and the component test template. Implementation layer; cross-stack principles live in quality/testing-pyramid.
-  触发：`Jest Vitest` · `React Testing Library` · `MSW mock service worker` · `Playwright`
+<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 19 skills -->
 
-- **`zsk:typescript`** *[standard · optional]*
-  TypeScript in frontend codebases — red lines (no any / as any / @ts-ignore / empty interface / Object type), must-do (explicit types for public boundaries, union literals, strict + noUncheckedIndexedAccess), API types from backend (not hand-written), type vs interface, generics discipline, unknown over any. Complements quality/code-hygiene for cross-language hygiene.
-  触发：`TypeScript red lines` · `no any` · `strict mode` · `noUncheckedIndexedAccess`
+## Skill 清单（core skills）
 
-### `quality/` — Quality · 跨栈质量原则 (5)
+> 内容由 `tools/catalog.ts` 从 `packages/skills/*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
 
-- **`zsk:a11y-principles`** *[standard · optional]*
-  Accessibility principles at the concept level — WCAG 2.1 AA baseline, POUR principles, keyboard operation matrix, focus management, aria semantics, contrast ratios, don't-rely-on-color, reduced motion. For Web/JSX implementation (axe-core, jsx-a11y, focus traps in Modal, etc.) see frontend/a11y-web.md.
-  触发：`accessibility principles` · `WCAG AA` · `POUR` · `keyboard matrix`
+### `<slug>/` — Core · harness-first 默认工作流入口 (19)
 
-- **`zsk:code-hygiene`** *[standard · optional]*
-  Code hygiene for any language — comment policy (WHY not WHAT), import ordering principle, formatter discipline, generic forbidden patterns (TODO comments, commented-out code, signature-like comments). Stack-specific rules (TypeScript red lines, React naming) are in frontend/*.
-  触发：`code hygiene` · `comment policy` · `import order` · `WHY not WHAT`
+- **`dispatch`**
+  At task intake, asks OMX to assign subagents to the right zsk skill from request, state, evidence, and blockers.
 
-- **`zsk:release`** *[standard · optional]*
-  Version release discipline — SemVer numbering, Keep a Changelog, Conventional Changelog auto-generation, environment promotion (dev→test→pre→prod), feature flag lifecycle, rollback strategy, hotfix process, canary monitoring. Works across language stacks; tool names are stack-specific examples.
-  触发：`SemVer` · `changelog` · `conventional changelog` · `hotfix`
+- **`flow`**
+  Starts or resumes delivery by reading state, resources, and blockers, then selecting the next legal stage.
 
-- **`zsk:security-owasp`** *[standard · optional]*
-  Cross-stack security discipline — OWASP Top 10 overview, CVE response SLAs, dependency license whitelist, supply chain hygiene, common lint red lines (eval/dynamic execution), and the "frontend UI is not the final defense" principle. Web-specific XSS/CSRF/Storage red lines are in frontend/security-web.md.
-  触发：`OWASP Top 10` · `CVE response` · `license whitelist` · `supply chain security`
+- **`prepare`**
+  After project init, collects resource origins, snapshots evidence, and updates config/manifests before proposal/spec.
 
-- **`zsk:testing-pyramid`** *[standard · optional]*
-  Cross-language test strategy & discipline — test pyramid ratio (unit 70 / integration 20 / e2e 10), AAA/GWT structure, coverage targets, and the three hard principles (evidence before assertion, Red-Green-Refactor, bug confidence questioning). Stack-specific tooling (Jest/RTL/MSW/Playwright) is in frontend/testing-web.md.
-  触发：`test pyramid` · `TDD discipline` · `test coverage target` · `AAA GWT structure`
+- **`proposal`**
+  Before spec, frames the problem, scope, non-goals, success criteria, stakeholders, risks, and resource gaps.
 
-### `design-handoff/` — Design Handoff · 设计交付方法论 (5)
+- **`spec`**
+  After proposal, defines sourced FR/NFR, acceptance criteria, scenarios, edge cases, and open gaps.
 
-- **`zsk:figma-to-code`** *[optional]*
-  Figma design node → production code via MCP — 7-step workflow (locate → extract structure → extract annotations → naming conversion → layout decoding → states → tokens), plus the 4-dimension "100% fidelity" verification (visual / interaction / semantic / responsive). Styling specifics live in zsk:styling-system.
-  触发：`figma to code` · `100 percent fidelity` · `node naming conversion` · `design annotations`
+- **`design`**
+  After spec freeze, maps behavior to interfaces, data flow, rollout plan, risks, and implementation surfaces.
 
-- **`zsk:ue-mcp`** *[optional]*
-  Design Source capture & MCP readout for modules with Figma/design input — Design Source (URL/node-id), MCP readout status, module-specific UE deviations from system baselines, and implementation mapping. Produces docs/{module}/ue-mcp.md + structured description.md snapshot in design-assets. Only records deviations, not duplicated baseline rules.
-  触发：`UE MCP context` · `figma snapshot` · `design source reference` · `module UE deviation`
+- **`task`**
+  After design approval, creates executable tasks with dependencies, FR/AC coverage, owners, and evidence hooks.
 
-- **`zsk:ux-wireframe`** *[optional]*
-  UX wireframe workflow before high-fidelity design — turns spec scenarios into task flows, information architecture, low-fidelity layouts, and state coverage. Supports Pencil, Excalidraw, Mermaid, or text wireframes when Figma is not ready.
-  触发：`wireframe` · `low fidelity design` · `Pencil design` · `UX flow`
+- **`coding`**
+  For approved tasks, implements small scoped diffs with tests, evidence, and blocker reporting.
 
-- **`zsk:design-system`** *[standard · optional]*
-  Design system governance for Figma and frontend alignment — records tokens, component states, naming, responsive rules, accessibility baselines, and anti-generic visual constraints before high-fidelity generation or implementation.
-  触发：`design system` · `design tokens` · `Figma variables` · `component variants`
+- **`smoke`**
+  After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.
 
-- **`zsk:figma-generate-hifi`** *[workflow · optional]*
-  Figma high-fidelity generation workflow from spec, UX wireframes, and design-system rules — creates or updates production-oriented Figma pages with state matrices, responsive variants, annotations, and anti-generic visual checks.
-  触发：`generate Figma` · `high fidelity design` · `figma generate design` · `hifi UI`
+- **`review`**
+  After smoke, reviews implementation against scope, specs, tasks, tests, security, maintainability, and evidence.
 
-### `system/` — System · 工程宪法级资源 (6)
+- **`commit`**
+  After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.
 
-- **`zsk:adr`** *[optional]*
-  Cross-module long-lived architectural decision record — context, decision, rationale, alternatives considered, and consequences. Produces docs/system/adrs/ADR-NNNN-{slug}.md. Not for single-module implementation choices.
-  触发：`architecture decision record` · `ADR template` · `MADR` · `cross-module decision`
+- **`demo`**
+  Before formal testing, runs planned demos and captures evidence without making acceptance claims.
 
-- **`zsk:agent-orchestration`** *[core]*
-  Agent orchestration protocol for all zsk skills — assigns independent work to specialized Sub-Agents, defines main-agent ownership, role boundaries, review integration, and fallback behavior when delegation is unavailable.
-  触发：`sub agent orchestration` · `parallel agents` · `multi agent workflow` · `agent responsibilities`
+- **`defect`**
+  After formal QA reports findings, normalizes defects with repro, evidence, FR/AC links, and fix routing.
 
-- **`zsk:architecture`** *[optional]*
-  Project system architecture documentation — C4 context diagram, tech stack baseline, module boundaries, routing, auth flow, data flow (request/state/contract), deployment topology, related ADRs. Frontend micro-frontend topology is an optional add-on section.
-  触发：`system architecture` · `C4 model` · `tech stack baseline` · `module boundaries`
+- **`ready`**
+  Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.
 
-- **`zsk:glossary`** *[optional]*
-  Project Ubiquitous Language maintenance — single source for business terms, domain entities, state names, technical terms, and acronyms. Eliminates same-concept-different-names confusion across modules and backend contracts.
-  触发：`glossary` · `ubiquitous language` · `DDD terms` · `business term`
+- **`verify`**
+  Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.
 
-- **`zsk:nfr-baseline`** *[optional]*
-  Project NFR baseline (inherited or established) — 7-category framework (performance / a11y / security / i18n / compatibility / observability / reliability) and the deviation-declaration discipline. Web-specific values (CWV thresholds, WCAG AA, browser matrix, 三语) live in frontend/nfr-web.md.
-  触发：`NFR baseline` · `non functional requirements` · `quality attributes` · `ISO 25010`
+- **`acceptance`**
+  After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
 
-- **`zsk:project-constraints-template`** *[optional]*
-  Project constraints template for new-project bootstrap — captures import origins, forbidden libraries/patterns, required wrappers, naming conventions, quality gates, branch/release conventions in one SYSTEM-SPEC chapter. The project-side constitutional constraint table, complementary to project-config.md (mechanical values).
-  触发：`project constraints` · `SYSTEM-SPEC` · `import origins` · `forbidden packages`
+- **`deploy`**
+  After review, deploys to non-production or demo targets with version, smoke evidence, and rollback owner.
 
-### `meta/` — Meta · 元信息 (1)
+- **`archive`**
+  After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
 
-- **`zsk:philosophy`** *[meta · optional]*
-  Design rationale of the zsk skill set — LLM Wiki × Superpowers × GSD × project-adaptation synthesis. For contributors needing to understand why zsk is organized the way it is.
-  触发：`zsk philosophy` · `why is zsk organized this way` · `design rationale` · `LLM wiki vs superpowers`
+- **`issue`**
+  Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 

package/acceptance/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: acceptance
+description: After independent verify passes, records accept/reject decision,
+  linked evidence, and residual-risk owner.
+kind: workflow-node
+pack: core
+stage: acceptance
+requires:
+  - constraints.evidence-rules
+  - constraints.stage-gates
+domain: core
+category: stage
+tier: core
+triggers:
+  - acceptance
+---
+
+# Acceptance
+
+Use this stage after independent `verify` has passed and the product/business owner needs an acceptance decision. Acceptance is not another implementation review; it decides whether the delivered change is fit to close, reject, or archive with explicit residual risk.
+
+## Inputs
+
+- `verify-report` with linked evidence and unresolved findings.
+- `demo-report` when the change has user-visible behavior.
+- Linked issue records, waivers, and regression notes.
+- Proposal/spec/design/task artifacts for the accepted scope.
+
+## Procedure
+
+1. Re-check the accepted scope against proposal and spec, not against late wish-list items.
+2. Confirm P0/P1 acceptance criteria are verified or explicitly waived.
+3. Summarize residual risks, owners, and follow-up issues.
+4. Record one decision: `ACCEPT`, `ACCEPT_WITH_RISK`, `REJECT`, or `BLOCKED`.
+5. For `ACCEPT*`, apply documentation feedback from linked issues: update module spec/design/task docs and project specs for behavior that was missing, ambiguous, or under-described.
+6. Route `ACCEPT*` to `archive`; route rejection to the earliest invalidated stage.
+
+## Constraints
+
+- Do not accept work with missing verify evidence.
+- Do not hide product disagreement as a minor issue.
+- Do not mutate implementation or test files from this stage.
+- Do not leave confirmed issue learning only in `.issues`; accepted fixes must feed back into the relevant spec/design/task docs unless there is an explicit no-update rationale.
+- Keep the decision short, dated, and evidence-linked.
+
+## Outputs
+
+- `acceptance` decision artifact.
+- Residual-risk list with owner and due date.
+- Updated spec/design/task documentation feedback or explicit no-update rationale.
+- Archive readiness or rejection route.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/acceptance/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, smoke, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+
+When a `harness/` directory is installed beside this file, treat it as the local contract source:
+
+- Read `harness/workflow/skill-io-contract.yaml` for this skill's required inputs, outputs, tools, and capabilities.
+- Read `harness/workflow/state-machine.yaml` and `harness/constraints/stage-gates.md` before moving between stages.
+- Read `harness/constraints/evidence-rules.md` and `harness/workflow/completion-contract.yaml` before claiming READY / PASS / DONE.
+- Read `harness/constraints/issue-taxonomy.md` before creating or updating blockers, risks, defects, or questions.
+- Read the relevant file under `harness/best-practices/` when the task touches SDLC, quality, frontend, design handoff, system constraints, or agent orchestration.
+

package/acceptance/harness/README.md

@@ -0,0 +1,104 @@
+# Installed ZSK Harness Contract
+
+This harness bundle was embedded for `acceptance` so external installers such as `npx skills add codeshareman/zsk` install more than a bare `SKILL.md`.
+
+The local `SKILL.md` is the execution entrypoint. These files are the supporting contract for stage gates, evidence, issue taxonomy, workflow transitions, and compact best-practice references.
+
+---
+# zsk Harness
+
+`harness/` is the source of truth for workflow governance. Skills are execution surfaces, but the harness owns constraints, resources, templates, state transitions, evidence, issue taxonomy, completion outputs, and learning promotion rules.
+
+The harness should adapt best practices, not accumulate them. Prefer the smallest sufficient local design: no speculative abstractions, scripts, files, or workflow gates unless the current project need proves they are necessary.
+
+The harness-first build path is now wired: root `skills/` generates `capabilities/skills/`, then `packages/skills/`. `.best-practices/` is only a slim reference layer and is not part of default installation.
+
+## Authority
+
+Merge order:
+
+```text
+root harness
+-> selected pack overlays
+-> skill-local harness contract
+-> project .zsk/config.yaml bindings
+```
+
+Root constraints can only be extended or tightened. Packs and skill-local contracts cannot weaken anti-patterns, stage gates, evidence rules, issue taxonomy, or filesystem boundaries.
+
+## Learning Loop
+
+The harness owns self-learning. Skills and stage templates may surface `Documentation Feedback`, but they must not directly mutate core constraints, templates, packs, or root skills.
+
+Flow:
+
+1. Stage work records reusable failures, template gaps, or skill gaps as documentation feedback.
+2. `archive` converts durable findings into learning proposals under `.zsk/learning/proposals`.
+3. Promotion follows `harness/learning/promotion-rules.yaml`.
+4. Accepted proposals patch the smallest target: constraint, template, resource map, root skill, optional pack, or project-only docs.
+5. Core promotion requires review plus regression evidence.
+
+Project-specific experience stays in module archives or `docs/SYSTEM-SPEC.md`. General zsk changes must be proposed, reviewed, and verified before becoming default behavior.
+
+## Skill Completion Contract
+
+`workflow/skill-io-contract.yaml` defines each skill's expected inputs, outputs, tools, capabilities, script policy, and Browser Use policy.
+
+`workflow/completion-contract.yaml` defines what each skill/stage must leave behind after execution:
+
+- produced artifacts and their project-template paths;
+- evidence required for completion claims;
+- issue persistence and module/global index refreshes;
+- documentation feedback targets after verified and confirmed fixes;
+- learning proposal handoff for reusable process improvements.
+
+This contract is harness-owned. Individual skills may name their outputs, but they should not redefine where persistent project artifacts, issue indexes, or confirmed documentation feedback are managed.
+
+File updates can be implemented in two ways:
+
+- repeatable mechanical updates should use CLI commands or skill-local scripts declared by the skill;
+- context-sensitive docs feedback can be written by the agent with normal file-editing tools.
+
+Both paths must satisfy the same harness completion contract before the skill is considered done.
+
+## Runtime Flow
+
+The harness treats skills as stage contracts, not free-form prompts. Profiles under `profiles/*.yaml` choose the stage sequence and strictness before optional gates are enforced:
+
+```text
+zsk-lite       small, low-risk changes
+zsk-sdlc       standard engineering delivery
+zsk-frontend   UI/UX/browser-facing delivery with demo and visual evidence
+zsk-enterprise governed delivery with deploy, acceptance, and archive evidence
+```
+
+The standard profile follows:
+
+```text
+dispatch
+  -> flow
+  -> prepare -> proposal -> spec -> design -> task
+  -> coding -> smoke -> review -> commit
+  -> ready -> verify -> acceptance -> archive
+```
+
+Supporting stages can branch from the main flow:
+
+- `issue` records blockers, risks, questions, and defects without bypassing gates.
+- `dispatch` tells OMX to schedule subagents around the active ZSK skill and harness gate.
+- `demo` proves a changed flow before formal QA.
+- `defect` turns QA findings into reproducible, FR/AC-linked work.
+- `commit` is allowed only after smoke and review pass.
+- `deploy` is optional in `zsk-sdlc`, required in `zsk-enterprise`, and usually sits between `commit` and `ready`.
+
+Every branch must return with evidence, status, and index updates required by `workflow/completion-contract.yaml`.
+
+## Quality Bar
+
+High-quality skill output means:
+
+- source-linked: important claims trace to PRD/SRS, spec/design, task, issue, code/runtime evidence, or user clarification;
+- accurate: tests and scenarios prove the intended behavior, not convenient implementation details;
+- complete enough: missing resources, uncertainty, and conflicts are named with impact;
+- concise: no generic filler, speculative abstraction, or extra structure beyond the smallest sufficient design;
+- reviewed: review/verify/acceptance check traceability, test adequacy, scope creep, and unresolved uncertainty before pass.