@pigcloud/skills 1.0.2 → 1.0.3

package/README.en.md

@@ -1,84 +1,83 @@
 # @pigcloud/skills
 
-> An AI skills pack for product, engineering, and QA workflows. `@pigcloud/skills` is the npm package name; `Pig Cloud` is the dedicated rules / scaffold context, while shared skills and specialized rule overlays stay separated.
-
-## What it is
-
-- Pick the right skill before acting
-- Skills own task boundaries and handoff
-- `rules/` owns framework constraints and coding conventions
-- Loading and validation are handled by the loader / CLI
-
-## Common entry points
-
-- Product intake: `product-intake`
-- Requirement refinement: `spec-refinement`
-- Stage routing: `workflow-router`
-- Design and implementation: `technical-design` / `feature-build`
-- Review: `code-review` / `security-review` / `performance-check`
-- Knowledge capture: `knowledge-capture`
-
-## Install
-
-### Without npm
-
-Run the matching script from the repo root:
-
-- Windows: `install.cmd`
-- macOS / Linux: `bash install.sh`
-
-### Auto-detect the current project
-
+> An AI skills pack for product, engineering, and QA collaboration. `@pigcloud/skills` is the npm package name; `skills/` carries reusable capabilities, `rules/` carries constraints and validation, `workflow-router` handles stage routing, and `CI / Test / Evidence` completes the delivery loop.
+
+## What this system does
+
+- Route first, then execute
+- Constrain first, then generate
+- Reuse first, then rewrite
+- Verify first, then conclude
+
+## Core Layers
+
+1. `workflow-router`: identifies the task type and chooses the next stage
+2. `skills/`: reusable capability modules
+3. `rules/`: project constraints, boundaries, and hard checks
+4. `CI / Test / Evidence`: verifiable delivery gates
+
+## Common Entry Points
+
+- Product intake: `product-intake`
+- Requirement refinement: `spec-refinement`
+- Stage routing: `workflow-router`
+- Design and implementation: `technical-design` / `feature-build`
+- Review and validation: `code-review` / `security-review` / `performance-check`
+- Knowledge capture: `knowledge-capture`
+
+## Install
+
 ```bash
 npm install -g @pigcloud/skills
 ```
 
-### Migration note
-
-- `@pig/skills` was the intermediate package name during migration.
-- New installs should use `@pigcloud/skills`.
-- `rules/overlays/pig-cloud/` remains the Pig Cloud-specific rule layer and is not the npm package name.
-
-### Codex command entry
-
-```bash
-pig-skills codex
-```
-
-### Inspect rule loading
-
-```bash
-pig-skills rules
-```
-
-### Bootstrap runtime
-
-```bash
-pig-skills bootstrap
-```
-
-## Validation
-
-```bash
-node validate-skills.js
-node scripts/validate-skill-shapes.js
-node scripts/validate-rules.js
-```
-
-## Directory map
-
-- `skills/`: skill bodies
-- `skills/references/`: authoring standard, reference matrix, loading map
-- `rules/`: rule entry point and bundles
-- `docs/`: usage notes, workflow design, and reports
-- `bin/`: CLI, auto-install, postinstall
-
-## Entry docs
-
-- [AGENTS.md](AGENTS.md)
+## Migration Note
+
+- `@pig-cloud/skills` is the historical package name
+- `@pig/skills` was the intermediate migration name
+- New installs should use `@pigcloud/skills`
+- `Pig Cloud` is only the repository-specific rules/scaffold context, not the npm package name
+
+## Client Setup
+
+- Codex: see [docs/CODEX-APP-GUIDE.md](docs/CODEX-APP-GUIDE.md)
+- Trae: see [docs/TRAE-GUIDE.md](docs/TRAE-GUIDE.md)
+- Cloud Code / Claude Code: see [docs/CLAUDE-CODE-GUIDE.md](docs/CLAUDE-CODE-GUIDE.md)
+- Unified installation guide: see [docs/client-installation-guide.md](docs/client-installation-guide.md)
+
+## Governance Overview
+
+- System overview: [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
+- Skills extension guide: [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
+- Package migration note: [docs/package-name-migration.md](docs/package-name-migration.md)
+
+## Validation
+
+```bash
+node validate-skills.js
+node scripts/validate-skill-shapes.js
+node scripts/validate-rules.js
+node scripts/validate-skill-stop-rules.js
+node scripts/validate-skill-replay-signals.js
+node self-test-skills.js
+```
+
+## Directory Map
+
+- `skills/`: skill bodies
+- `skills/references/`: authoring standard, reference matrix, loading map
+- `rules/`: rule entry point and bundles
+- `docs/`: install, governance, migration, and workflow notes
+- `bin/`: CLI, auto-install, postinstall
+
+## Entry Docs
+
+- [AGENTS.md](AGENTS.md)
 - [docs/README.md](docs/README.md)
+- [docs/client-installation-guide.md](docs/client-installation-guide.md)
+- [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
+- [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
 - [docs/package-name-migration.md](docs/package-name-migration.md)
 - [skills/references/skill-authoring-standard.md](skills/references/skill-authoring-standard.md)
-- [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
-- [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)
-- [README.md](README.md)
+- [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
+- [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)

package/README.md

@@ -1,30 +1,33 @@
 # @pigcloud/skills
 
-> 面向产品、研发、测试协作的 AI skills pack。`@pigcloud/skills` 是 npm 包名；`Pig Cloud` 是专属规则/脚手架语境，通用 skills 与专属 rules overlay 分层并存。
+> 一个面向产品、研发、测试协作的 AI skills pack。`@pigcloud/skills` 是 npm 包名；`skills/` 负责能力执行，`rules/` 负责约束与校验，`workflow-router` 负责阶段编排，`CI / Test / Evidence` 负责交付闭环。
 
-## 它是什么
+## 这套体系做什么
 
-这套包的定位很简单：先选对 skill，再开始执行；skill 负责任务边界和交接；`rules/` 负责框架约束和编码规范；规则加载与校验由 `loader` / CLI 负责；面向 AI 的摘要和标签优先用英文，面向人的说明优先用中文。
+- 先路由，再执行
+- 先约束，再生成
+- 先复用，再重写
+- 先验证，再结论
 
-## 常用入口
+## 核心分层
 
-1. 产品收口：`product-intake`
-2. 需求细化：`spec-refinement`
-3. 阶段路由：`workflow-router`
-4. 设计与实现：`technical-design` / `feature-build`
-5. 审核：`code-review` / `security-review` / `performance-check`
-6. 沉淀：`knowledge-capture`
+1. `workflow-router`：识别任务类型并决定下一阶段
+2. `skills/`：承载可复用能力模块
+3. `rules/`：承载项目规范、边界和强约束
+4. `CI / Test / Evidence`：承载可验证交付
 
-## 安装
-
-### 没有 npm
+## 常见入口
 
-在仓库根目录执行对应脚本：
+- 产品收口：`product-intake`
+- 需求细化：`spec-refinement`
+- 阶段路由：`workflow-router`
+- 设计与实现：`technical-design` / `feature-build`
+- 审核与验证：`code-review` / `security-review` / `performance-check`
+- 知识沉淀：`knowledge-capture`
 
-1. Windows: `install.cmd`
-2. macOS / Linux: `bash install.sh`
+## 安装
 
-### 自动识别当前项目
+### 全局安装
 
 ```bash
 npm install -g @pigcloud/skills
@@ -32,25 +35,23 @@ npm install -g @pigcloud/skills
 
 ### 迁移说明
 
-迁移时请记住三件事：`@pig/skills` 是前一版尝试的名称；现在请使用 `@pigcloud/skills`；仓库内的 `rules/overlays/pig-cloud/` 仍保留为 Pig Cloud 专属规则层，不等同于 npm 包名。
+- `@pig-cloud/skills` 是历史包名
+- `@pig/skills` 是迁移中间名
+- 现在请使用 `@pigcloud/skills`
+- `Pig Cloud` 仅表示仓库里的专属规则/脚手架语境，不再表示 npm 包名
 
-### Codex 命令入口
+## 客户端接入
 
-```bash
-pig-skills codex
-```
+- Codex：见 [docs/CODEX-APP-GUIDE.md](docs/CODEX-APP-GUIDE.md)
+- Trae：见 [docs/TRAE-GUIDE.md](docs/TRAE-GUIDE.md)
+- Cloud Code / Claude Code：见 [docs/CLAUDE-CODE-GUIDE.md](docs/CLAUDE-CODE-GUIDE.md)
+- 统一安装说明：见 [docs/client-installation-guide.md](docs/client-installation-guide.md)
 
-### 查看规则加载
+## 治理总览
 
-```bash
-pig-skills rules
-```
-
-### 补齐运行时
-
-```bash
-pig-skills bootstrap
-```
+- 体系总览：见 [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
+- 技能扩展：见 [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
+- 包名迁移：见 [docs/package-name-migration.md](docs/package-name-migration.md)
 
 ## 验证
 
@@ -58,22 +59,27 @@ pig-skills bootstrap
 node validate-skills.js
 node scripts/validate-skill-shapes.js
 node scripts/validate-rules.js
+node scripts/validate-skill-stop-rules.js
+node scripts/validate-skill-replay-signals.js
+node self-test-skills.js
 ```
 
 ## 目录
 
-1. `skills/`: skill 本体
-2. `skills/references/`: 作者规范、参考矩阵、加载图
-3. `rules/`: 规则入口和 bundle
-4. `docs/`: 说明、链路设计和报告
-5. `bin/`: CLI、自动安装、postinstall
+- `skills/`：技能主体
+- `skills/references/`：作者规范、参考矩阵、规则加载地图
+- `rules/`：规则入口和 bundle
+- `docs/`：安装、治理、迁移、工作流说明
+- `bin/`：CLI、自动安装、postinstall
 
 ## 入口文档
 
 - [AGENTS.md](AGENTS.md)
 - [docs/README.md](docs/README.md)
+- [docs/client-installation-guide.md](docs/client-installation-guide.md)
+- [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
+- [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
 - [docs/package-name-migration.md](docs/package-name-migration.md)
 - [skills/references/skill-authoring-standard.md](skills/references/skill-authoring-standard.md)
 - [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
 - [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)
-- [README.en.md](README.en.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pigcloud/skills",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "AI skills pack with client-aware installation, shared skills and rules, Codex command entries, and Pig Cloud-specific overlays for requirements, implementation, and knowledge curation.",
   "author": "Pig Skills Maintainers",
   "license": "MIT",

package/skills/api-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-docs
-description: Document stable API behavior, request and response contracts, and examples when endpoints need reusable reference docs
+description: 当接口需要可复用参考文档时，记录稳定的 API 行为、请求/响应契约和示例
 lifecycle_stage: capture
 rule_profile: api
 dependencies:

package/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Review a diff or pull request for correctness, maintainability, and regression risk when a generic code review is needed
+description: 当需要通用代码审查时，对 diff 或 PR 进行正确性、可维护性和回归风险审查
 lifecycle_stage: review
 rule_profile: code
 dependencies:

package/skills/domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: domain-modeling
-description: Extract domain boundaries and core concepts from code or business language when the model is unclear
+description: 当领域模型不清晰时，从代码或业务语言中提炼领域边界和核心概念
 lifecycle_stage: design
 rule_profile: modeling
 dependencies: []

package/skills/environment-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: environment-deploy
-description: Prepare deployment and runtime prerequisites when a workspace or target environment needs setup
+description: 当工作区或目标环境需要配置时，准备部署和运行时前置条件
 lifecycle_stage: scaffold
 rule_profile: scaffold
 dependencies:

package/skills/feature-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-build
-description: Implement approved design changes when code, refactor, or integration work needs to stay within agreed boundaries
+description: 在代码、重构或集成工作需要保持在既定边界内时，实现已批准的设计变更
 lifecycle_stage: build
 rule_profile: implementation
 dependencies:

package/skills/knowledge-capture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-capture
-description: Capture reusable decisions, requirements knowledge, realtime code facts, codewiki facts, and handoff notes when downstream work needs a durable summary
+description: 当下游工作需要可持续沉淀时，捕捉可复用的决策、需求知识、实时代码事实、CodeWiki 事实和交接说明
 lifecycle_stage: capture
 rule_profile: capture
 dependencies: []

package/skills/performance-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: performance-check
-description: Review a change for latency, throughput, or resource bottlenecks when performance findings are needed
+description: 当需要性能结论时，对变更中的延迟、吞吐量或资源瓶颈进行审查
 lifecycle_stage: review
 rule_profile: performance
 dependencies:

package/skills/product-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: product-intake
-description: Capture product intent and separate it from project facts, prototypes, and current implementation facts into a PRD-ready brief when the goal, scope, or priority is still fuzzy
+description: 捕捉产品意图，并将其与项目事实、原型和当前实现事实分离，形成可进入 PRD 的简报，适用于目标、范围或优先级仍不清晰时
 lifecycle_stage: intake
 rule_profile: intake
 dependencies: []

package/skills/project-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-bootstrap
-description: Bootstrap a new workspace with the right skills and rules bundle when a project needs initial setup
+description: 当项目需要初始化时，为新工作区装载合适的技能和规则包
 lifecycle_stage: scaffold
 rule_profile: scaffold
 dependencies: []

package/skills/references/rule-loading-map.md

@@ -1,10 +1,18 @@
-# Rule Loading Map
-
-## Goal
-
-Keep rule loading separate from skill routing. Load the smallest rule set that matches the current task, then add the stack-specific overlay only when needed. When changed files are available, prefer them over workspace-wide heuristics.
-
-## Load Order
+# Rule Loading Map
+
+## Goal
+
+Keep rule loading separate from skill routing. Load the smallest rule set that matches the current task, then add the stack-specific overlay only when needed. When changed files are available, prefer them over workspace-wide heuristics.
+
+## Governance Context
+
+- `workflow-router` decides the next stage.
+- `skills/` decides the reusable execution pattern.
+- `rules/` decides the project constraints and must/never checks.
+- `CI / Test / Evidence` decides whether the result can be accepted.
+- For the higher-level explanation, see [docs/agent-governance-overview.md](../../docs/agent-governance-overview.md).
+
+## Load Order
 
 ### 1. Core Layer
 

package/skills/references/skill-reference-matrix.md

@@ -1,6 +1,13 @@
-# Skill Reference Matrix
-
-## Borrowed Patterns
+# Skill Reference Matrix
+
+## Governance Context
+
+- Skills are the execution layer.
+- Rules are the constraint layer.
+- Workflow decides routing before execution.
+- For a broader system view, see [docs/agent-governance-overview.md](../../docs/agent-governance-overview.md).
+
+## Borrowed Patterns
 
 | Source | Best Practice | Applies To |
 |---|---|---|

package/skills/security-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-review
-description: Review a diff, endpoint, or design note for auth, secret, or data exposure risks when security findings are needed
+description: 当需要安全结论时，对 diff、接口或设计说明中的认证、密钥或数据暴露风险进行审查
 lifecycle_stage: review
 rule_profile: security
 dependencies:

package/skills/spec-refinement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-refinement
-description: Refine approved demand into an executable spec by aligning product intent, project facts, prototypes, implementation facts, and knowledge-base evidence when acceptance gaps, constraints, or implementation inputs remain
+description: 通过对齐产品意图、项目事实、原型、实现事实和知识库证据，将已批准的需求细化为可执行规格，适用于仍存在验收缺口、约束或实现输入时
 lifecycle_stage: refinement
 rule_profile: refinement
 dependencies:

package/skills/technical-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-design
-description: Shape architecture and implementation boundaries from a stable spec when modules, interfaces, or dependencies still need decisions
+description: 当模块、接口或依赖仍需决策时，在稳定规格基础上梳理架构与实现边界
 lifecycle_stage: design
 rule_profile: analysis
 dependencies:

package/skills/test-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-design
-description: Design and validate test coverage for an implemented change when regression risk or edge cases need verification
+description: 当需要验证回归风险或边界场景时，为已实现的变更设计并验证测试覆盖
 lifecycle_stage: verify
 rule_profile: testing
 dependencies:

package/skills/workflow-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-router
-description: Route work into the next skill and stage when intent, ownership, or handoff is unclear
+description: 当意图、归属或交接不清楚时，将工作路由到下一技能和阶段
 lifecycle_stage: routing
 rule_profile: router
 dependencies: []