@pigcloud/skills 1.0.11 → 1.1.2

package/codex-commands/commands/workflow.md

@@ -1,20 +1,21 @@
-# /workflow
-
-按阶段路由到正确的 skill，并控制阶段切换。
-
-## Route
-
-- 适用：多阶段任务、跨 skill 协作、门禁控制、阶段切换
-- 不适用：单一步骤的小任务
-
-## Workflow
-
-1. 判断当前处于哪个生命周期阶段。
-2. 选择当前 skill 或下一步 skill。
-3. 如果门禁失败，暂停下游并说明原因。
-4. 记录下一步应该走哪个 skill。
-
-## Guardrails
-
-- 不替用户决定跳过阶段。
-- 不让下游覆盖上游未确认结果。
+# /workflow
+
+当任务还不能直接归类时，先判断下一步应该去哪个 skill。
+
+## Route
+
+- 对应 skill: `ambiguity-detection`
+- 适用: 多阶段任务、阶段切换、需要先定下一步
+- 不适用: 已经是明确单步任务
+
+## Workflow
+
+1. 判断当前卡在哪个阶段。
+2. 选出最合适的下一步 skill。
+3. 如果信息不足，先说明原因再继续。
+4. 记录下一步应该去哪个 skill。
+
+## Guardrails
+
+- 不要替用户跳过阶段。
+- 不要把未确认的结论写成定论。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pigcloud/skills",
-  "version": "1.0.11",
+  "version": "1.1.2",
   "description": "面向 Codex、Trae 和 Claude Code 的 AI 技能包，提供共享技能、规则约束、工作流路由和 Pig Cloud 专属覆盖层。",
   "author": "Pig Skills Maintainers",
   "license": "MIT",
@@ -44,10 +44,13 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "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",
+    "test": "node validate-skills.js && node scripts/validate-skill-shapes.js && node scripts/validate-rules.js && node self-test-skills.js",
     "test:self": "node self-test-skills.js",
     "replay:golden": "node scripts/run-golden-replays.js",
     "replay:golden:mock": "node scripts/run-golden-replays.js --provider mock",
+    "generate:skill-specs": "node scripts/bootstrap-skill-specs.js",
+    "generate:skill-prompts": "node scripts/generate-skill-prompt-library.js",
+    "generate:skills": "node scripts/bootstrap-skill-specs.js && node scripts/migrate-skill-packages.js",
     "postinstall": "node bin/postinstall.js",
     "validate:skills": "node validate-skills.js",
     "validate:shapes": "node scripts/validate-skill-shapes.js",

package/rules/core/index.md

@@ -1,41 +1,26 @@
-# Core Rules
-
-`core/` contains the baseline rules that apply to every AI-assisted task in this repository.
-
-## 默认做法
-
-- Use the smallest rule set that can answer the task.
-- Clarify task boundary, expected output, and stop condition before doing deeper work.
-- Prefer verifiable facts over guesses.
-- Load a more specific bundle only when the task clearly needs it.
-- Keep rule text short and move examples or edge cases into references.
-
-## 禁区
-
-- Do not mix domain-specific details into core rules.
-- Do not repeat long project explanations in every skill.
-- Do not let unclear inputs expand into open-ended work.
-- Do not treat `core` as a dumping ground for repo-specific conventions.
-
-## 检查
-
-- Can the task be solved without a more specific bundle?
-- Is the boundary of the task explicit?
-- Is the output shape clear?
-- Is the rule file short enough to load quickly?
-
-## 回放信号
-
-- Any prompt that only needs general collaboration or quality constraints should start here.
-- If the task needs product, workflow, coding, docs, or review specifics, hand off to the matching bundle.
-
-## References
-
-- `core/task-boundary.md`
-- `core/evidence.md`
-- `core/iteration.md`
-- `core/interface.md`
-- `core/layer-boundary.md`
-- `core/code-quality.md`
-- `core/logging.md`
-- `core/security.md`
+# Core Rules
+
+`core/` contains the baseline rules that apply to every AI-assisted task in this repository.
+
+## Purpose
+
+- Keep the request bounded before deeper work starts.
+- Favor evidence over guesswork.
+- Keep the file short and push details into stage-specific guidance only when needed.
+
+## Do Not
+
+- Do not mix stage-specific policy into core rules.
+- Do not turn core into a repository encyclopedia.
+- Do not let unclear inputs expand into open-ended work.
+
+## Check
+
+- Can the task be solved with only baseline rules?
+- Is the task boundary explicit?
+- Is the output shape clear?
+
+## Use When
+
+- Start here for any prompt that only needs general collaboration or quality constraints.
+- Hand off to the matching stage when the task needs discovery, design, implementation, validation, delivery, or shared guidance.

package/rules/delivery/index.md

@@ -0,0 +1,25 @@
+# Delivery Rules
+
+`delivery/` contains rules for release readiness, handoff, changelog, and deployment guidance.
+
+## Purpose
+
+- Confirm the change is ready to ship.
+- Record what changed and how to verify it.
+- Keep deployment and recovery steps explicit.
+
+## Do Not
+
+- Do not introduce new feature work here.
+- Do not reopen earlier stage decisions unless a release blocker appears.
+- Do not hide verification steps in prose.
+
+## Check
+
+- Is the release safe to proceed?
+- Are the verification and rollback steps explicit?
+- Is the next owner clear?
+
+## Use When
+
+- Use this stage when the work is complete and needs release packaging or operational guidance.

package/rules/design/index.md

@@ -0,0 +1,25 @@
+# Design Rules
+
+`design/` contains rules for architecture, API, schema, and task-split decisions.
+
+## Purpose
+
+- Define the smallest useful system boundary before implementation starts.
+- Keep contracts, dependencies, and tradeoffs explicit.
+- Split approved work into testable pieces when needed.
+
+## Do Not
+
+- Do not write production code here.
+- Do not mix discovery questions into design output.
+- Do not expand the design beyond the confirmed boundary.
+
+## Check
+
+- Is the boundary stable enough to implement?
+- Are the contracts or data shapes clear?
+- Is the next implementation step obvious?
+
+## Use When
+
+- Use this stage when the request needs a design decision before coding can begin.

package/rules/discovery/index.md

@@ -0,0 +1,25 @@
+# Discovery Rules
+
+`discovery/` contains rules for requirement framing, ambiguity removal, and impact analysis.
+
+## Purpose
+
+- Clarify the request before design or implementation starts.
+- Extract business terms, constraints, and risks from the request or repository facts.
+- Keep the work bounded and evidence driven.
+
+## Do Not
+
+- Do not jump into implementation details.
+- Do not treat assumptions as facts.
+- Do not turn discovery into design or review.
+
+## Check
+
+- Is the request clear enough to move forward?
+- Are the important constraints and risks explicit?
+- Is the next stage obvious?
+
+## Use When
+
+- Use this stage when the input is ambiguous, underspecified, or likely to change the downstream plan.

package/rules/implementation/index.md

@@ -0,0 +1,25 @@
+# Implementation Rules
+
+`implementation/` contains rules for code changes, refactoring, scaffolding, and data-flow work.
+
+## Purpose
+
+- Make the smallest correct change that satisfies the confirmed design.
+- Keep implementation within the approved scope.
+- Validate the change before handing it off.
+
+## Do Not
+
+- Do not reopen design unless a blocking fact appears.
+- Do not broaden scope because it is convenient.
+- Do not skip validation.
+
+## Check
+
+- Is the change still inside the approved boundary?
+- Is the implementation path minimal and reversible?
+- Is there a concrete validation step?
+
+## Use When
+
+- Use this stage when the task is ready to become code or migration work.

package/rules/index.md

@@ -1,46 +1,31 @@
-# 规则入口
+# Rules Entry
 
-`rules/` 是仓库内的共享规则体系。它只负责给 skill 提供行为约束和检查标准，不负责 skill 路由，也不负责目标身份识别。
+`rules/` is the AI-facing constraint layer for the repository.
+Primary audience: AI readers.
 
-## 规则层
+## Layers
 
-- `core`：任务边界、证据、迭代和通用质量规则。
-- `workflow`：协作、路由、收口和交接规则。
-- `product`：需求、范围和业务概念规则。
-- `coding`：编码、重构、测试和交付规则。
-- `docs`：文档、知识沉淀和接口说明规则。
-- `review`：审查与质量门禁规则。
-- `overlays`：仓库、团队或公司级专属覆盖规则。
-- `skill-profile-map.json`：canonical skill 到 bundle/profile 的回退映射。
+- `core`: universal baseline rules
+- `discovery`: requirement framing, ambiguity removal, and impact analysis
+- `design`: architecture, API, schema, and task-split decisions
+- `implementation`: code changes, refactoring, scaffolding, and data-flow work
+- `validation`: tests, review, regression, security, and performance checks
+- `delivery`: release readiness, handoff, changelog, and deployment guidance
+- `shared`: repository orientation, evidence packaging, and reusable framework conventions
+- `overlays`: repository-specific or stack-specific overrides
+- `skill-stage-map.json`: canonical skill to stage mapping
 
-## 统一结构
+## Design Principles
 
-每份规则都保持同一套最小章节：
+- Keep the rules stage-oriented and lightweight.
+- Keep rules authoritative and reusable.
+- Keep overlays narrow and explicit.
+- Keep routing metadata out of skill files.
+- Load the smallest stage set that still covers the task.
+- Treat the stage map as the source of truth for skill-to-rule routing.
+- Use [docs/skill-layer-boundary-plan.md](../docs/skill-layer-boundary-plan.md) as the companion map for how `skills`, `references`, and `rules` fit together.
 
-- 默认做法
-- 禁区
-- 检查
-- 回放信号
-- References
+## Related Docs
 
-## 选择原则
-
-- 能用 `core` 解决的，不要加载更具体的 bundle。
-- 需要更具体约束时，先加载 `core`，再加载匹配的 bundle/profile。
-- `skill` frontmatter 里的 `rule_profile` 是声明源，映射文件只做校验和回退。
-- 不要把产品发现、技能路由或专属 overlay 的正文写回 `rules/index.md`。
-
-## 使用方式
-
-- skill 不要内嵌规则细节，统一指向这里。
-- loader 先识别 bundle，再按 profile 选最小文件集。
-- `PIG_SKILLS_RULE_BUNDLE` 负责强制 bundle。
-- `PIG_SKILLS_RULE_PROFILE` 负责强制 profile。
-- `PIG_SKILLS_RULE_SKILL` 负责按 skill 名自动推导。
-- `PIG_SKILLS_RULE_OVERLAY` 可用于附加本地覆盖层。
-
-## Review Stack Split
-
-- `review/code.md` 是通用审查边界。
-- `review/java.md`、`review/vue.md`、`review/ts.md` 是按栈叠加的审查覆盖层。
-- 混合栈仓库可以叠加多个 overlay。
+- [docs/skill-system-target.md](../docs/skill-system-target.md)
+- [docs/skill-layer-boundary-plan.md](../docs/skill-layer-boundary-plan.md)

package/rules/overlays/index.md

@@ -1,28 +1,28 @@
-# 覆盖规则
+# Overlays
 
-`overlays/` 用于仓库、团队或公司级的专属覆盖规则。它不是基础 bundle 的复制品，而是在共享规则之上增加更窄的本地约束。
+`overlays/` holds narrow repository-, team-, or stack-specific rules.
 
-## 默认做法
+## Purpose
 
-- 只放更高优先级的本地覆盖。
-- 每个 overlay 都应该比被覆盖的基础 bundle 更窄、更明确。
+- Add local conventions on top of shared stage rules.
+- Keep special cases out of the generic rule tree.
+- Avoid duplicating the same guidance across multiple places.
 
-## 禁区
+## Good Overlay Content
 
-- 不要把整个基础 bundle 复制进 `overlays/`。
-- 不要用 overlay 去补全缺失的基础规则。
-- 不要把专属覆盖层写成第二套通用规则体系。
+- Spring Boot conventions
+- MyBatis conventions
+- Redis conventions
+- project-specific layering rules
+- local naming and response-shape conventions
 
-## 检查
+## What Not to Put Here
 
-- 这是仓库、团队或公司层面的专属约束吗？
-- 这层覆盖是否比基础 bundle 更窄？
+- Generic engineering rules that belong in `core/`
+- Stage routing that belongs in `core/` plus the stage map
+- Discovery, design, implementation, validation, or delivery policy that belongs in the matching stage
 
-## 回放信号
+## Rule of Thumb
 
-- 当需要在基础 bundle 之后再叠加本地专属约束时触发。
-
-## References
-
-- `rules/index.md`
-- `rules/overlays/pig-cloud.md`
+- If the rule is true for most repositories, it should not be an overlay.
+- If the rule is only true for this repository or stack, overlay is the right place.

package/rules/overlays/pig-cloud.md

@@ -1,45 +1,20 @@
-# Pig Cloud 专属索引
-
-`overlays/pig-cloud/` 只放 Pig Cloud 仓库的专属规则块。
-
-## 加载顺序
-
-1. 先看 `rules/index.md`
-2. 再看 `rules/overlays/index.md`
-3. 再按需加载下列专属子规则
-
-## 默认做法
-
-- 这里只做入口和索引，不承载具体规则语义。
-
-## 子规则
-
-- [controller.md](rules/overlays/pig-cloud/controller.md)
-- [service.md](rules/overlays/pig-cloud/service.md)
-- [mapper.md](rules/overlays/pig-cloud/mapper.md)
-- [dto-vo.md](rules/overlays/pig-cloud/dto-vo.md)
-- [exception.md](rules/overlays/pig-cloud/exception.md)
-- [layering.md](rules/overlays/pig-cloud/layering.md)
-- [rest-response.md](rules/overlays/pig-cloud/rest-response.md)
-- [entity.md](rules/overlays/pig-cloud/entity.md)
-- [validation.md](rules/overlays/pig-cloud/validation.md)
-- [query-style.md](rules/overlays/pig-cloud/query-style.md)
-- [transactions.md](rules/overlays/pig-cloud/transactions.md)
-
-## 禁区
-
-- 不要把具体规则再写回这个索引页。
-
-## 检查
-
-- 入口是否仍然足够短？
-- 具体约束是否都下沉到了子文件？
-
-## 回放信号
-
-- 当需要定位 Pig Cloud 专属规则时触发。
-
-## References
-
-- `rules/overlays/index.md`
-- `rules/index.md`
+# Pig Cloud Overlay
+
+`overlays/pig-cloud.md` is the explicit overlay for the Pig Cloud repository.
+
+## Loading Order
+
+1. Read `rules/index.md`
+2. Read `rules/overlays/index.md`
+3. Load this overlay only when Pig Cloud conventions are required
+
+## Default Behavior
+
+- Keep this file as an overlay entry point and index.
+- Do not duplicate generic stage rules here.
+- Keep stack-specific rules narrow and local.
+
+## References
+
+- `rules/overlays/index.md`
+- `rules/index.md`

package/rules/shared/index.md

@@ -0,0 +1,25 @@
+# Shared Rules
+
+`shared/` contains repository orientation, evidence packaging, and reusable framework conventions.
+
+## Purpose
+
+- Keep cross-stage guidance reusable.
+- Capture evidence and repo facts once.
+- Hold framework-level conventions that apply across stages.
+
+## Do Not
+
+- Do not put stage routing here.
+- Do not move task-specific policy into shared rules.
+- Do not duplicate detailed stage guidance.
+
+## Check
+
+- Is the content useful across more than one stage?
+- Does it stay narrow enough to load quickly?
+- Is it stable across tasks?
+
+## Use When
+
+- Use this stage for shared context, evidence, and framework conventions.

package/rules/skill-stage-map.json

@@ -0,0 +1,26 @@
+{
+  "requirement-discovery": { "stage": "discovery" },
+  "business-analysis": { "stage": "discovery" },
+  "ambiguity-detection": { "stage": "discovery" },
+  "impact-analysis": { "stage": "discovery" },
+  "architecture-design": { "stage": "design" },
+  "api-design": { "stage": "design" },
+  "database-design": { "stage": "design" },
+  "task-breakdown": { "stage": "design" },
+  "backend-development": { "stage": "implementation" },
+  "frontend-development": { "stage": "implementation" },
+  "database-change": { "stage": "implementation" },
+  "bug-fix": { "stage": "implementation" },
+  "unit-test": { "stage": "validation" },
+  "code-review": { "stage": "validation" },
+  "security-review": { "stage": "validation" },
+  "performance-review": { "stage": "validation" },
+  "regression-check": { "stage": "validation" },
+  "release-check": { "stage": "delivery" },
+  "release-validation": { "stage": "delivery" },
+  "change-log": { "stage": "delivery" },
+  "deployment-guide": { "stage": "delivery" },
+  "framework-guide": { "stage": "shared" },
+  "codebase-learning": { "stage": "shared" },
+  "evidence-collector": { "stage": "shared" }
+}

package/rules/stages.json

@@ -0,0 +1,48 @@
+{
+  "core": {
+    "description": "Universal baseline rules that apply to every AI-assisted task in this repository.",
+    "entry": "core/index.md",
+    "files": ["core/index.md"]
+  },
+  "discovery": {
+    "description": "Requirement framing, ambiguity removal, and impact analysis before design or implementation.",
+    "entry": "discovery/index.md",
+    "files": ["discovery/index.md"]
+  },
+  "design": {
+    "description": "Architecture, API, schema, and task-split decisions before implementation.",
+    "entry": "design/index.md",
+    "files": ["design/index.md"]
+  },
+  "implementation": {
+    "description": "Production code, refactoring, scaffolding, and data-flow change rules.",
+    "entry": "implementation/index.md",
+    "files": ["implementation/index.md"]
+  },
+  "validation": {
+    "description": "Testing, review, regression, security, and performance verification rules.",
+    "entry": "validation/index.md",
+    "files": ["validation/index.md"]
+  },
+  "delivery": {
+    "description": "Release readiness, handoff, change logging, and deployment guidance.",
+    "entry": "delivery/index.md",
+    "files": ["delivery/index.md"]
+  },
+  "shared": {
+    "description": "Repository orientation, evidence packaging, and reusable framework conventions.",
+    "entry": "shared/index.md",
+    "files": ["shared/index.md"]
+  },
+  "overlays": {
+    "description": "Repository- or stack-specific rules applied only when explicitly requested.",
+    "entry": "overlays/index.md",
+    "files": ["overlays/index.md", "overlays/pig-cloud.md"],
+    "variants": {
+      "pig-cloud": {
+        "entry": "overlays/pig-cloud.md",
+        "files": ["overlays/index.md", "overlays/pig-cloud.md"]
+      }
+    }
+  }
+}

package/rules/validation/index.md

@@ -0,0 +1,25 @@
+# Validation Rules
+
+`validation/` contains rules for tests, review, regression, security, and performance checks.
+
+## Purpose
+
+- Prove the change is correct, safe, and ready for handoff.
+- Keep findings concrete and tied to evidence.
+- Avoid rewriting the change during validation.
+
+## Do Not
+
+- Do not use validation to redesign the implementation.
+- Do not report findings without proof.
+- Do not expand the scope beyond the submitted change.
+
+## Check
+
+- Is the evidence strong enough to support the conclusion?
+- Is the risk concrete and reproducible?
+- Is the next handoff step clear?
+
+## Use When
+
+- Use this stage after implementation or when a change must be inspected for risk.

package/scripts/add-skill-reference-nav.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('./migrate-skill-packages');

package/scripts/bootstrap-skill-specs.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.join(__dirname, '..');
+const skillsRoot = path.join(repoRoot, 'skills');
+const suite = require(path.join(repoRoot, 'scripts', 'golden-prompt-suite.current.js'));
+
+function readSkillDirectories() {
+  const results = [];
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'references' || entry.name === 'assets' || entry.name === 'scripts') {
+        continue;
+      }
+
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const skillFile = path.join(fullPath, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+          results.push(fullPath);
+        }
+        walk(fullPath);
+      }
+    }
+  }
+
+  walk(skillsRoot);
+  return results.sort();
+}
+
+function readSkillMd(skillFile) {
+  const content = fs.readFileSync(skillFile, 'utf8');
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const frontmatter = frontmatterMatch ? frontmatterMatch[1] : '';
+  const name = (frontmatter.match(/^name:\s*(.+)$/m) || [])[1]?.trim() || path.basename(path.dirname(skillFile));
+  const description = (frontmatter.match(/^description:\s*(.+)$/m) || [])[1]?.trim() || '';
+  const title = (content.match(/^#\s+(.+)$/m) || [])[1]?.trim() || name;
+
+  function extractSection(title) {
+    const match = content.match(new RegExp(`## ${title}\\s*\\n\\n([\\s\\S]*?)(?=\\n## |$)`));
+    if (!match) {
+      return [];
+    }
+    return match[1]
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.startsWith('- '))
+      .map((line) => line.slice(2).trim());
+  }
+
+  function extractSectionText(title) {
+    const match = content.match(new RegExp(`## ${title}\\s*\\n\\n([\\s\\S]*?)(?=\\n## |$)`));
+    return match ? match[1].trim().replace(/\r/g, '') : '';
+  }
+
+  return {
+    name,
+    description,
+    title,
+    purpose: extractSectionText('Purpose'),
+    whenToUse: extractSection('When to Use'),
+    how: extractSection('How'),
+    whenToAvoid: extractSection('When to Avoid'),
+  };
+}
+
+function findCaseId(skillName) {
+  const testCase = suite.cases.find((item) => item.expectedFirstSkill === skillName);
+  return testCase ? testCase.id : null;
+}
+
+function main() {
+  let count = 0;
+
+  for (const skillDir of readSkillDirectories()) {
+    const skillFile = path.join(skillDir, 'SKILL.md');
+    const specFile = path.join(skillDir, 'skill-spec.json');
+    const group = path.relative(skillsRoot, skillDir).split(path.sep)[0];
+    const spec = readSkillMd(skillFile);
+    const payload = {
+      group,
+      ...spec,
+      caseId: findCaseId(spec.name),
+      source: 'bootstrap-from-skill-md',
+    };
+    fs.writeFileSync(specFile, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    count += 1;
+  }
+
+  console.log(`Bootstrapped ${count} skill specs.`);
+}
+
+main();