@pigcloud/skills 1.0.0

package/skills/references/golden-prompt-suite.js

@@ -0,0 +1,385 @@
+function makeCase(skill, id, prompt, expectedOutput, expectedStop, expectedHandoff) {
+  return {
+    id,
+    prompt,
+    expectedFirstSkill: skill,
+    expectedOutput,
+    expectedStop,
+    expectedHandoff,
+  };
+}
+
+const cases = [
+  makeCase(
+    'workflow-router',
+    'router-unclear-stage',
+    'We have a new request but I am not sure which stage should handle it.',
+    ['next skill', 'stage decision', 'handoff note'],
+    'Do not perform the target skill\'s work.',
+    'product-intake',
+  ),
+  makeCase(
+    'workflow-router',
+    'router-approved-brief',
+    'The brief is ready. Which stage should receive it next?',
+    ['next skill', 'stage decision', 'handoff note'],
+    'Do not perform the target skill\'s work.',
+    'spec-refinement',
+  ),
+  makeCase(
+    'workflow-router',
+    'router-before-coding',
+    'This needs architecture help before coding. Route it.',
+    ['next skill', 'stage decision', 'handoff note'],
+    'Do not perform the target skill\'s work.',
+    'technical-design',
+  ),
+
+  makeCase(
+    'product-intake',
+    'product-reminder-feature',
+    'We need a reminder feature for inactive users.',
+    ['product brief', 'scope', 'acceptance outline', 'open questions'],
+    'Do not jump into design or code.',
+    'spec-refinement',
+  ),
+  makeCase(
+    'product-intake',
+    'product-retention-gap',
+    'Users keep missing renewal emails; help me define the product scope.',
+    ['product objective', 'scope', 'acceptance outline', 'open questions'],
+    'Do not decide implementation details.',
+    'spec-refinement',
+  ),
+  makeCase(
+    'product-intake',
+    'product-unclear-opportunity',
+    'We think there is a retention problem, but the exact feature is unclear.',
+    ['product objective', 'scope', 'acceptance outline', 'open questions'],
+    'Do not write technical design.',
+    'spec-refinement',
+  ),
+
+  makeCase(
+    'spec-refinement',
+    'spec-approved-brief',
+    'The brief is approved; turn it into an executable spec.',
+    ['executable spec', 'acceptance criteria', 'impact scope', 'implementation inputs'],
+    'Do not rewrite the PRD or code the change.',
+    'feature-build',
+  ),
+  makeCase(
+    'spec-refinement',
+    'spec-code-gap',
+    'Compare the PRD with the current code and identify gaps.',
+    ['executable spec', 'impact scope', 'implementation inputs'],
+    'Do not jump into implementation.',
+    'feature-build',
+  ),
+  makeCase(
+    'spec-refinement',
+    'spec-align-with-code',
+    'The requirement is messy; align it with existing behavior and make it engineer-ready.',
+    ['executable spec', 'acceptance criteria', 'implementation input summary'],
+    'Do not rewrite the PRD.',
+    'technical-design',
+  ),
+
+  makeCase(
+    'technical-design',
+    'design-cross-module',
+    'This change touches multiple modules, cache behavior, and compatibility; help me plan it.',
+    ['design decisions', 'dependency map', 'interface contract', 'implementation constraints'],
+    'Do not start implementation.',
+    'feature-build',
+  ),
+  makeCase(
+    'technical-design',
+    'design-boundaries',
+    'Design the module boundaries, dependencies, and rollback path.',
+    ['design decisions', 'dependency map', 'interface contract', 'implementation constraints'],
+    'Do not reopen product discovery.',
+    'feature-build',
+  ),
+  makeCase(
+    'technical-design',
+    'design-interface-contract',
+    'I need an interface contract before anyone starts coding.',
+    ['interface contract', 'implementation constraints'],
+    'Do not produce full code.',
+    'feature-build',
+  ),
+
+  makeCase(
+    'feature-build',
+    'build-approved-spec',
+    'Implement the approved spec in the controller and service.',
+    ['code changes', 'implementation notes', 'validation evidence'],
+    'Do not expand scope or rewrite requirements.',
+    'test-design',
+  ),
+  makeCase(
+    'feature-build',
+    'build-scope-stable',
+    'Make the local code changes but keep the scope stable.',
+    ['code changes', 'implementation notes', 'validation evidence'],
+    'Do not change the agreed boundaries.',
+    'test-design',
+  ),
+  makeCase(
+    'feature-build',
+    'build-simple-refactor',
+    'This controller needs a simple refactor that does not change behavior.',
+    ['code changes', 'implementation notes', 'validation evidence'],
+    'Do not rewrite the spec.',
+    'test-design',
+  ),
+
+  makeCase(
+    'test-design',
+    'test-coverage',
+    'Design test coverage and validate the change.',
+    ['test strategy', 'test cases', 'regression matrix', 'validation result'],
+    'Do not modify production code.',
+    'code-review',
+  ),
+  makeCase(
+    'test-design',
+    'test-regression-matrix',
+    'The feature is implemented; give me a regression matrix.',
+    ['test strategy', 'regression matrix', 'validation result'],
+    'Do not rewrite the PRD.',
+    'code-review',
+  ),
+  makeCase(
+    'test-design',
+    'test-edge-cases',
+    'I need edge cases and validation paths for this change.',
+    ['test cases', 'validation result'],
+    'Do not replace code review.',
+    'code-review',
+  ),
+
+  makeCase(
+    'code-review',
+    'review-correctness',
+    'Review this diff for correctness and safety.',
+    ['findings with severity', 'fix recommendations'],
+    'Do not refactor the code inside the review step.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'code-review',
+    'review-maintainability',
+    'Find maintainability issues in this PR.',
+    ['findings', 'severity', 'fix recommendations'],
+    'Do not perform implementation refactors.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'code-review',
+    'review-regression',
+    'Check whether this change introduces regressions.',
+    ['findings', 'severity', 'fix recommendations'],
+    'Do not turn review into a design task.',
+    'knowledge-capture',
+  ),
+
+  makeCase(
+    'knowledge-capture',
+    'capture-decisions',
+    'Capture the reusable decisions and pitfalls from this task.',
+    ['reusable note', 'handoff summary'],
+    'Do not redo upstream analysis.',
+    null,
+  ),
+  makeCase(
+    'knowledge-capture',
+    'capture-summary',
+    'Summarize the decisions, pitfalls, and reusable notes from this task.',
+    ['reusable note', 'knowledge page', 'handoff summary'],
+    'Do not generate new requirements or code.',
+    null,
+  ),
+  makeCase(
+    'knowledge-capture',
+    'capture-decision-log',
+    'Turn these findings into a reusable note for future work.',
+    ['reusable note', 'handoff summary'],
+    'Do not reopen the design or implementation debate.',
+    null,
+  ),
+
+  makeCase(
+    'api-docs',
+    'api-profile-docs',
+    'Document the user profile endpoints with request and response shapes.',
+    ['API document', 'contract notes', 'examples'],
+    'Do not change implementation.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'api-docs',
+    'api-payment-contract',
+    'Write the contract for this payment endpoint with examples.',
+    ['API document', 'contract notes', 'examples'],
+    'Do not rewrite product scope.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'api-docs',
+    'api-openapi-notes',
+    'Capture the OpenAPI notes for a new endpoint.',
+    ['API document', 'contract notes', 'examples'],
+    'Do not change implementation or product scope.',
+    'knowledge-capture',
+  ),
+
+  makeCase(
+    'domain-modeling',
+    'domain-reverse-engineer',
+    'Reverse engineer the customer order domain from this codebase and docs.',
+    ['domain map', 'core concepts', 'boundary notes'],
+    'Do not implement code.',
+    'technical-design',
+  ),
+  makeCase(
+    'domain-modeling',
+    'domain-boundary-split',
+    'Split the billing and account concepts into boundaries.',
+    ['domain map', 'core concepts', 'boundary notes'],
+    'Do not write PRD text.',
+    'technical-design',
+  ),
+  makeCase(
+    'domain-modeling',
+    'domain-language-extraction',
+    'Extract ubiquitous language from the current product notes.',
+    ['domain map', 'core concepts', 'boundary notes'],
+    'Do not write implementation code.',
+    'spec-refinement',
+  ),
+
+  makeCase(
+    'security-review',
+    'security-injection-auth',
+    'Check this change for injection, auth, and secret handling issues.',
+    ['security findings', 'risk level', 'mitigation advice'],
+    'Do not rewrite code.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'security-review',
+    'security-permissions',
+    'Review permission boundaries and data exposure risks.',
+    ['security findings', 'risk level', 'mitigation advice'],
+    'Do not turn into a general review.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'security-review',
+    'security-bypass-check',
+    'Find any auth bypass or sensitive-data leaks in this diff.',
+    ['security findings', 'risk level', 'mitigation advice'],
+    'Do not rewrite code or broaden the scope.',
+    'knowledge-capture',
+  ),
+
+  makeCase(
+    'performance-check',
+    'perf-slow-endpoint',
+    'This endpoint is slow; inspect query cost, cache, and concurrency.',
+    ['performance findings', 'bottleneck map', 'optimization advice'],
+    'Do not rewrite code.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'performance-check',
+    'perf-hot-path',
+    'Find bottlenecks in the hot path and suggest improvements.',
+    ['performance findings', 'bottleneck map', 'optimization advice'],
+    'Do not turn into a general review.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'performance-check',
+    'perf-memory-latency',
+    'Review memory pressure and response latency risks.',
+    ['performance findings', 'bottleneck map', 'optimization advice'],
+    'Do not rewrite code or broaden the scope.',
+    'knowledge-capture',
+  ),
+
+  makeCase(
+    'project-bootstrap',
+    'bootstrap-new-workspace',
+    'Set up a new workspace for Codex with the right skills and rules.',
+    ['starter structure', 'installed bundle', 'setup notes'],
+    'Do not design product scope.',
+    'workflow-router',
+  ),
+  makeCase(
+    'project-bootstrap',
+    'bootstrap-skill-bundle',
+    'Install the initial skill bundle for a new project.',
+    ['starter structure', 'installed bundle', 'setup notes'],
+    'Do not generate application code.',
+    'workflow-router',
+  ),
+  makeCase(
+    'project-bootstrap',
+    'bootstrap-scaffold',
+    'Bootstrap a fresh repository scaffold and hand it off.',
+    ['starter structure', 'installed bundle', 'setup notes'],
+    'Do not start feature implementation.',
+    'product-intake',
+  ),
+
+  makeCase(
+    'environment-deploy',
+    'deploy-runtime-prereqs',
+    'Prepare the runtime and deployment prerequisites for this workspace.',
+    ['environment plan', 'deployment notes', 'bootstrap instructions'],
+    'Do not change product scope.',
+    'feature-build',
+  ),
+  makeCase(
+    'environment-deploy',
+    'deploy-target-setup',
+    'Set up the deployment target and document the bootstrap steps.',
+    ['environment plan', 'deployment notes', 'bootstrap instructions'],
+    'Do not generate business logic.',
+    'project-bootstrap',
+  ),
+  makeCase(
+    'environment-deploy',
+    'deploy-environment-check',
+    'Verify the environment before feature work starts.',
+    ['environment plan', 'deployment notes', 'bootstrap instructions'],
+    'Do not change product scope or generate business logic.',
+    'feature-build',
+  ),
+
+  makeCase(
+    'spec-refinement',
+    'negative-direct-code',
+    'Just code it, the PRD is small.',
+    ['executable spec'],
+    'Do not jump directly into implementation.',
+    'feature-build',
+  ),
+  makeCase(
+    'code-review',
+    'negative-review-refactor',
+    'Review this change by refactoring it.',
+    ['findings', 'severity'],
+    'Do not perform implementation refactors.',
+    'knowledge-capture',
+  ),
+];
+
+module.exports = {
+  name: 'golden-prompt-suite',
+  purpose: 'Golden prompt set for replay testing the full skill chain.',
+  cases,
+};

package/skills/references/golden-prompt-suite.md

@@ -0,0 +1,33 @@
+# 金标提示词套件
+
+## 目的
+
+这套提示词用于真实回放测试。每个 case 都定义了预期首个 skill、返回工件、停止边界和交接目标。
+
+源码是真正的权威：[`golden-prompt-suite.js`](golden-prompt-suite.js)。运行器会直接加载这个文件。
+
+## 使用方式
+
+1. 把提示词发给 skill router 或者直接发给目标 skill。
+2. 对照预期首个 skill 检查结果。
+3. 检查输出工件是否符合预期形状。
+4. 确认 skill 是否停在指定边界。
+5. 验证下一跳是否是预期的交接目标。
+
+## 覆盖范围
+
+- 每个 canonical skill 3 个 case
+- 2 个用于边界回归的负向 case
+- 共 44 个 case
+
+## 运行
+
+- `npm run replay:golden`：真实模型回放
+- `npm run replay:golden:mock`：本地 harness 检查
+
+## 输出字段
+
+- 首个 skill
+- 工件
+- stop rule
+- 交接

package/skills/references/hooks.md

@@ -0,0 +1,67 @@
+# Hooks
+
+Hooks 负责协调 skill 执行和产物交接。
+
+## Hook 类型
+
+| Hook 类型 | 触发时机 | 用途 |
+|---|---|---|
+| `pre_invoke` | skill 运行前 | 检查前置条件 |
+| `post_invoke` | skill 运行后 | 更新状态和产物 |
+| `on_success` | skill 成功时 | 通知并触发下一步 |
+| `on_failure` | skill 失败时 | 记录问题并安全停止 |
+| `on_confirm` | 用户确认时 | 推进工作流状态 |
+| `on_reject` | 用户拒绝时 | 保持在当前阶段 |
+
+## canonical hook groups
+
+### product-intake
+
+- 确认产品输入存在
+- 收集目标、范围和待确认项
+- 写出产品产物
+- 在确认后触发 `spec-refinement`
+
+### spec-refinement
+
+- 确认产品产物已通过确认
+- 细化范围、边界和验收标准
+- 写出研发规格
+- 按需要触发 `technical-design` 或 `feature-build`
+
+### technical-design
+
+- 确认规格已经稳定到足够支持设计
+- 记录边界、依赖和接口决策
+
+### feature-build
+
+- 确认规格和当前选定的 rules bundle 都已准备好
+- 生成或更新代码
+- 实现完成后触发 `test-design`
+
+### test-design
+
+- 确认实现可用
+- 写出测试用例、验证步骤和缺陷笔记
+- 验证完成后触发 `code-review`
+
+### code-review
+
+- 确认变更集已经可以审查
+- 记录 findings、严重级别和后续事项
+- 变更通过后触发 `knowledge-capture`
+
+## 工作流状态
+
+- 跟踪当前阶段
+- 跟踪已确认阶段
+- 跟踪已产出工件
+- 把错误和重试状态与工作流链路分开
+
+## Hook 原则
+
+- 缺少前置条件就停止
+- 推进阶段前优先做显式确认
+- 输出要短小、机器可读
+- 不要把框架规则混进 hook 逻辑里

package/skills/references/negative-replay-scenarios.md

@@ -0,0 +1,49 @@
+# 负向回放场景
+
+## 目的
+
+专门验证 workflow 不会跳过阶段，也不会把 stop rule 写成“建议”。
+
+## 场景一：不能跳过规格细化
+
+- 提示词：“PRD 很小，直接帮我把代码写了。”
+- 期望首个 skill：`spec-refinement`
+- 期望停点：不能直接进 `feature-build`
+- 失败信号：`spec-refinement` 之后没有先形成可执行规格
+
+## 场景二：不能跳过技术设计
+
+- 提示词：“这个需求会改多个模块，先别设计，直接写。”
+- 期望首个 skill：`spec-refinement`
+- 期望下一跳：`technical-design`
+- 期望停点：不能直接进 `feature-build`
+- 失败信号：复杂场景直接进入编码
+
+## 场景三：复杂需求必须先设计
+
+- 提示词：“这个需求影响多个模块、缓存和兼容性，先帮我收口再直接实现。”
+- 期望首个 skill：`spec-refinement`
+- 期望下一跳：`technical-design`
+- 期望停点：不能从规格细化直接跳到 `feature-build`
+- 失败信号：`spec-refinement` 结束后没有进入 `technical-design`
+
+## 场景四：不能把测试当实现修补
+
+- 提示词：“我需要测试覆盖，顺手把生产代码也改了。”
+- 期望首个 skill：`test-design`
+- 期望停点：不能修改生产代码
+- 失败信号：测试阶段开始改实现
+
+## 场景五：不能把审查变成实现
+
+- 提示词：“先帮我审查这个 diff，再顺手把问题修掉。”
+- 期望首个 skill：`code-review`
+- 期望停点：不能在审查阶段改代码
+- 失败信号：`code-review` 输出里包含实现动作
+
+## 场景六：不能把沉淀变成重做分析
+
+- 提示词：“把这次工作总结一下，但先重新分析一遍问题。”
+- 期望首个 skill：`knowledge-capture`
+- 期望停点：不能重新做上游分析
+- 失败信号：`knowledge-capture` 开始重新定义需求或设计

package/skills/references/project-requirement-alignment.md

@@ -0,0 +1,41 @@
+# Project Requirement Alignment
+
+## Goal
+
+Use this guide when a task needs both product intent and current project facts.
+
+## Read First
+
+- Product brief or draft PRD
+- Current project facts from repo docs, release notes, or existing behavior
+- Known constraints from the current codebase or operating environment
+
+## Alignment Steps
+
+1. Summarize the product intent in one short paragraph.
+2. Summarize what the current project already does or guarantees.
+3. Mark what is unchanged, what must change, and what is still unknown.
+4. Record conflicts between product demand and current project facts.
+5. Turn the result into either a product brief or an executable spec, depending on the stage.
+
+## Output Shape
+
+- product intent summary
+- current project facts summary
+- alignment notes
+- open questions
+- execution direction notes
+- acceptance deltas
+- task breakdown plan
+
+## Rules
+
+- Do not merge product intent and project facts into one vague statement.
+- Do not rewrite implementation details as requirements.
+- Do not skip conflicts just because the requirement sounds simple.
+- Do not move into code generation from this guide.
+
+## References
+
+- `skills/references/requirements-separation-map.md`
+- `docs/engineering-workflow.md`

package/skills/references/prompt-replay-checklist.md

@@ -0,0 +1,128 @@
+# 提示词回放清单
+
+## 目的
+
+用这份清单手工回放提示词，判断 workflow skill 是否能正确路由、正确停住、正确交接。
+
+## 评分方式
+
+对每个提示词检查：
+
+- 首个 skill 选择是否正确
+- 输出产物是否正确
+- stop rule 是否被遵守
+- 下一跳交接是否正确
+- 是否有额外工作泄漏到错误阶段
+
+### 评分标准
+
+- 2：完全正确
+- 1：部分正确，但还能恢复
+- 0：错误，或者泄漏到错误阶段
+
+### 通过门槛
+
+- 五项检查都要拿到 2，才算通过
+- 任何一项为 0，直接判失败
+
+## 产品类提示词
+
+- 提示词：“我们要给沉默用户做一个提醒功能，先帮我收口范围、优先级和验收。”
+- 期望首个 skill：`product-intake`
+- 期望产物：产品 brief
+- 应该停在实现细节之前
+
+- 提示词：“PRD 还不清楚，帮我先收集范围和验收。”
+- 期望首个 skill：`product-intake`
+- 期望产物：范围、验收轮廓、待确认项
+- 应该停在规格或代码之前
+
+## 规格类提示词
+
+- 提示词：“PRD 已确认，帮我把它转成可执行的研发规格。”
+- 期望首个 skill：`spec-refinement`
+- 期望产物：可执行规格
+- 应该停在代码生成之前
+
+- 提示词：“对比 PRD 和当前代码，找出需要改什么。”
+- 期望首个 skill：`spec-refinement`
+- 期望产物：影响范围和实现输入
+- 应该停在实现之前
+
+## 设计类提示词
+
+- 提示词：“这个改动影响多个模块和缓存层，先帮我设计边界。”
+- 期望首个 skill：`technical-design`
+- 期望产物：设计决策和依赖图
+- 应该停在直接实现之前
+
+- 提示词：“编码前我需要一个回退和兼容方案。”
+- 期望首个 skill：`technical-design`
+- 期望产物：可执行的方案笔记
+- 应该停在代码之前
+
+- 提示词：“这个需求会改多个模块和兼容性，先别写代码，直接推进实现。”
+- 期望首个 skill：`spec-refinement`
+- 期望产物：可执行规格和实现输入
+- 应该先进入 `technical-design`，不能跳到实现
+
+## 实现类提示词
+
+- 提示词：“规格已经确认，帮我实现 controller 和 service 的改动。”
+- 期望首个 skill：`feature-build`
+- 期望产物：代码改动
+- 应该停在重写规格之前
+
+- 提示词：“把本地代码改好，同时保持范围稳定。”
+- 期望首个 skill：`feature-build`
+- 期望产物：实现说明和验证证据
+- 应该停在需求变更之前
+
+## 验证类提示词
+
+- 提示词：“为实现后的改动设计测试并验证覆盖。”
+- 期望首个 skill：`test-design`
+- 期望产物：测试策略和回归矩阵
+- 应该停在生产代码修改之前
+
+- 提示词：“检查边界情况，告诉我这个能不能安全发布。”
+- 期望首个 skill：`test-design`
+- 期望产物：验证结果
+- 应该停在实现之前
+
+## 审查类提示词
+
+- 提示词：“帮我审查这个 diff 的正确性、安全性和可维护性。”
+- 期望首个 skill：`code-review`
+- 期望产物：带严重级别的 findings
+- 应该停在重构代码之前
+
+- 提示词：“找出这个改动里的安全问题或性能问题。”
+- 期望首个 skill：`code-review`，必要时再进专项审查
+- 期望产物：有优先级的 findings
+- 应该停在审查结论
+
+## 沉淀类提示词
+
+- 提示词：“把这次任务的决策、坑点和可复用要点总结一下。”
+- 期望首个 skill：`knowledge-capture`
+- 期望产物：可复用笔记和交接摘要
+- 应该停在重新分析之前
+
+## 评估标准
+
+- 首个 skill 正确
+- 产物正确
+- stop rule 正确
+- 交接正确
+- 没有跨阶段泄漏
+
+## 快速记分表
+
+| 检查项 | 2 | 1 | 0 |
+|---|---|---|---|
+| 首个 skill | 精确匹配 | 接近但可恢复 | 阶段错误 |
+| 产物 | 符合预期 | 基本正确 | 缺失或错误 |
+| stop rule | 停得正确 | 停得稍晚 | 继续推进 |
+| 交接 | 正确下一跳 | 方向对但弱 | 交接错误 |
+| 泄漏 | 没有 | 轻微 | 明显 |