@pigcloud/skills 1.0.0

package/install.ps1

@@ -0,0 +1,74 @@
+param(
+    [switch]$SkipRuntimeBootstrap,
+    [switch]$SkipPostInstallSync
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Write-Info([string]$Message) {
+    Write-Host $Message
+}
+
+function Write-Warn([string]$Message) {
+    Write-Warning $Message
+}
+
+function Test-Command([string]$Name) {
+    return [bool](Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Ensure-NodeRuntime {
+    if (Test-Command npm) {
+        return
+    }
+
+    if ($SkipRuntimeBootstrap -or $env:PIG_SKILLS_SKIP_RUNTIME_BOOTSTRAP -match '^(1|true|yes)$') {
+        throw 'npm is not available and runtime bootstrap is disabled. Install Node.js LTS first, then rerun.'
+    }
+
+    if (-not (Test-Command winget)) {
+        throw 'npm is not available and winget is missing. Install Node.js LTS manually, then rerun.'
+    }
+
+    Write-Info 'npm is missing. Installing Node.js LTS via winget...'
+    & winget install --id OpenJS.NodeJS.LTS -e --source winget --accept-package-agreements --accept-source-agreements --silent --disable-interactivity | Out-Null
+    if ($LASTEXITCODE -ne 0) {
+        throw "winget install failed with exit code $LASTEXITCODE"
+    }
+
+    $programFilesX86 = [Environment]::GetEnvironmentVariable('ProgramFiles(x86)')
+    $nodeDirCandidates = @(
+        Join-Path $env:ProgramFiles 'nodejs',
+        if ($programFilesX86) { Join-Path $programFilesX86 'nodejs' },
+        Join-Path $env:LocalAppData 'Programs\nodejs',
+        Join-Path $env:LocalAppData 'Microsoft\WinGet\Links'
+    ) | Where-Object { $_ -and (Test-Path $_) }
+
+    foreach ($candidate in $nodeDirCandidates) {
+        if (-not (($env:PATH -split ';') -contains $candidate)) {
+            $env:PATH = "$candidate;$env:PATH"
+        }
+    }
+
+    if (-not (Test-Command npm)) {
+        throw 'Node.js was installed, but npm is still not visible in this shell. Restart the shell and rerun.'
+    }
+}
+
+function Install-Package {
+    $repoRoot = (Resolve-Path -LiteralPath $PSScriptRoot).Path
+    $npmArgs = @('install', '-g', $repoRoot)
+    if ($SkipPostInstallSync) {
+        $env:PIG_SKILLS_SKIP_AUTO_SYNC = '1'
+    }
+
+    Write-Info "Installing Pig Skills from $repoRoot ..."
+    & npm @npmArgs
+    if ($LASTEXITCODE -ne 0) {
+        throw "npm install failed with exit code $LASTEXITCODE"
+    }
+}
+
+Ensure-NodeRuntime
+Install-Package
+Write-Info 'Pig Skills installation complete.'

package/install.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$SCRIPT_DIR"
+SKIP_RUNTIME_BOOTSTRAP="${PIG_SKILLS_SKIP_RUNTIME_BOOTSTRAP:-0}"
+SKIP_POSTINSTALL_SYNC="${PIG_SKILLS_SKIP_AUTO_SYNC:-0}"
+
+for arg in "$@"; do
+  case "$arg" in
+    --skip-runtime-bootstrap)
+      SKIP_RUNTIME_BOOTSTRAP=1
+      ;;
+    --skip-postinstall-sync)
+      SKIP_POSTINSTALL_SYNC=1
+      ;;
+  esac
+done
+
+log() {
+  printf '%s\n' "$1"
+}
+
+warn() {
+  printf '%s\n' "$1" >&2
+}
+
+has_command() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+is_true() {
+  case "${1:-}" in
+    1|true|TRUE|yes|YES) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+run_privileged() {
+  if [ "$(id -u)" -eq 0 ]; then
+    "$@"
+    return
+  fi
+
+  if has_command sudo; then
+    sudo "$@"
+    return
+  fi
+
+  die "Command requires elevated privileges: $*"
+}
+
+die() {
+  warn "$1"
+  exit 1
+}
+
+bootstrap_with_nvm() {
+  if ! has_command curl; then
+    die "curl is required to bootstrap Node.js via nvm."
+  fi
+  if ! has_command git; then
+    die "git is required to bootstrap Node.js via nvm."
+  fi
+
+  export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+  if [ ! -s "$NVM_DIR/nvm.sh" ]; then
+    log "npm is missing. Installing nvm and Node.js LTS..."
+    mkdir -p "$NVM_DIR"
+    tmp_install_script="$(mktemp "${TMPDIR:-/tmp}/pig-skills-nvm.XXXXXX")"
+    curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh -o "$tmp_install_script"
+    bash "$tmp_install_script"
+    rm -f "$tmp_install_script"
+  fi
+
+  # shellcheck disable=SC1090
+  [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+  # shellcheck disable=SC1091
+  [ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
+  nvm install --lts
+  nvm use --lts
+}
+
+bootstrap_on_macos() {
+  if has_command brew; then
+    log "npm is missing. Installing Node.js via Homebrew..."
+    brew install node
+    return
+  fi
+
+  bootstrap_with_nvm
+}
+
+bootstrap_on_linux() {
+  if has_command apt-get; then
+    log "npm is missing. Installing Node.js via apt..."
+    run_privileged apt-get update
+    run_privileged apt-get install -y nodejs npm
+    return
+  fi
+
+  if has_command dnf; then
+    log "npm is missing. Installing Node.js via dnf..."
+    run_privileged dnf install -y nodejs npm
+    return
+  fi
+
+  if has_command yum; then
+    log "npm is missing. Installing Node.js via yum..."
+    run_privileged yum install -y nodejs npm
+    return
+  fi
+
+  if has_command pacman; then
+    log "npm is missing. Installing Node.js via pacman..."
+    run_privileged pacman -Sy --noconfirm nodejs npm
+    return
+  fi
+
+  if has_command zypper; then
+    log "npm is missing. Installing Node.js via zypper..."
+    run_privileged zypper --non-interactive install nodejs npm
+    return
+  fi
+
+  if has_command apk; then
+    log "npm is missing. Installing Node.js via apk..."
+    run_privileged apk add nodejs npm
+    return
+  fi
+
+  bootstrap_with_nvm
+}
+
+ensure_node_runtime() {
+  if has_command npm; then
+    return
+  fi
+
+  if is_true "$SKIP_RUNTIME_BOOTSTRAP"; then
+    die "npm is not available and runtime bootstrap is disabled. Install Node.js LTS first, then rerun."
+  fi
+
+  case "$(uname -s)" in
+    Darwin) bootstrap_on_macos ;;
+    Linux) bootstrap_on_linux ;;
+    *)
+      die "Unsupported platform for automatic bootstrap. Install Node.js LTS manually, then rerun."
+      ;;
+  esac
+
+  if ! has_command npm; then
+    die "Node.js was installed, but npm is still not visible in this shell. Restart the shell and rerun."
+  fi
+}
+
+install_package() {
+  log "Installing Pig Skills from $REPO_ROOT ..."
+  if is_true "$SKIP_POSTINSTALL_SYNC"; then
+    PIG_SKILLS_SKIP_AUTO_SYNC=1 npm install -g "$REPO_ROOT"
+  else
+    npm install -g "$REPO_ROOT"
+  fi
+}
+
+ensure_node_runtime
+install_package
+log "Pig Skills installation complete."

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@pigcloud/skills",
+  "version": "1.0.0",
+  "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",
+  "keywords": [
+    "ai",
+    "skills",
+    "openspec",
+    "pig-cloud",
+    "coding",
+    "distillation",
+    "agent",
+    "claude",
+    "cursor",
+    "copilot",
+    "trae"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/rebys/pig-skills.git"
+  },
+  "bugs": {
+    "url": "https://gitee.com/rebys/pig-skills/issues"
+  },
+  "homepage": "https://gitee.com/rebys/pig-skills",
+  "bin": {
+    "pig-skills": "./bin/cli.js"
+  },
+  "main": "./index.js",
+  "files": [
+    "bin/",
+    "install.cmd",
+    "install.ps1",
+    "install.sh",
+    "pig-cloud-skills-commands/",
+    "rules/",
+    "skills/",
+    "scripts/",
+    "templates/",
+    "index.js",
+    "README.md",
+    "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: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",
+    "postinstall": "node bin/postinstall.js",
+    "validate:skills": "node validate-skills.js",
+    "validate:shapes": "node scripts/validate-skill-shapes.js",
+    "validate:rules": "node scripts/validate-rules.js",
+    "validate:stop-rules": "node scripts/validate-skill-stop-rules.js",
+    "validate:replay-signals": "node scripts/validate-skill-replay-signals.js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "fs-extra": "^11.0.0",
+    "chalk": "^4.1.0",
+    "inquirer": "^8.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0"
+  }
+}

package/pig-cloud-skills-commands/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "pig-cloud-skills-commands",
+  "version": "1.1.0",
+  "description": "Codex command pack for Pig Cloud skills. Exposes direct command-style entrypoints such as /prd and /analyze so the skill pack can be invoked without memorizing raw skill names.",
+  "author": {
+    "name": "pig-cloud-framework",
+    "url": "https://gitee.com/rebys/pig-skills"
+  },
+  "homepage": "https://gitee.com/rebys/pig-skills",
+  "repository": "https://gitee.com/rebys/pig-skills.git",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "commands",
+    "skills",
+    "prd",
+    "analysis"
+  ],
+  "interface": {
+    "displayName": "Pig Cloud Skills Commands",
+    "shortDescription": "Command-style entrypoints for the Pig Cloud skill pack",
+    "longDescription": "Provides Codex command files like /prd, /analyze, /design, /build, and /kb that route into the Pig Cloud skills pack with stable, low-token prompts and clear execution gates.",
+    "developerName": "pig-cloud-framework",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Read"
+    ],
+    "websiteURL": "https://gitee.com/rebys/pig-skills",
+    "defaultPrompt": [
+      "Use /prd, /analyze, /design, /build, /review, or /kb to route work into the correct Pig Cloud skill"
+    ],
+    "brandColor": "#2563EB"
+  }
+}

package/pig-cloud-skills-commands/README.md

@@ -0,0 +1,24 @@
+# Pig Cloud Skills Commands
+
+本插件提供 Pig Cloud skill pack 的命令式入口。
+
+先安装 skill pack，再重启 Codex，命令才会生效。
+
+## Commands
+
+- `/prd` -> `product-intake`
+- `/analyze` -> `spec-refinement`
+- `/design` -> `technical-design`
+- `/build` -> `feature-build`
+- `/review` -> `code-review`
+- `/security` -> `security-review`
+- `/perf` -> `performance-check`
+- `/test` -> `test-design`
+- `/doc` -> `api-docs`
+- `/distill` -> `domain-modeling`
+- `/workflow` -> `workflow-router`
+- `/kb` -> `knowledge-capture`
+- `/init` -> `project-bootstrap`
+- `/infra` -> `environment-deploy`
+
+这些命令页保持短小，是为了让 Codex 更快定位到正确的 skill。

package/pig-cloud-skills-commands/commands/analyze.md

@@ -0,0 +1,21 @@
+# /analyze
+
+把已经确认的需求收敛成研发可执行的规格。
+
+## Route
+
+- 对应 skill：`spec-refinement`
+- 适用：需求拆解、边界梳理、依赖确认、验收标准补全
+- 不适用：还没收口的产品讨论
+
+## Workflow
+
+1. 先确认输入来自 `product-intake` 的收口结果，或至少已经完成初步收敛。
+2. 把目标、边界、依赖、约束和验收条件整理成可执行规格。
+3. 输出研发分析结果，明确后续实现所需输入。
+4. 必要时交给 `technical-design` 或 `knowledge-capture`。
+
+## Guardrails
+
+- 不直接写实现代码。
+- 不把未确认假设当结论。

package/pig-cloud-skills-commands/commands/build.md

@@ -0,0 +1,21 @@
+# /build
+
+按方案规范实现已经收口的需求。
+
+## Route
+
+- 对应 skill：`feature-build`
+- 适用：开发实现、增量改造、接口联动、落地代码
+- 不适用：需求还没收口，或者设计还没稳定
+
+## Workflow
+
+1. 先确认输入来自 `spec-refinement` 或 `technical-design`。
+2. 按分层、事务和返回值规范实现。
+3. 保持改动最小，优先可验证。
+4. 交给 `test-design` 和 `code-review` 收口。
+
+## Guardrails
+
+- 不绕过架构约束。
+- 不把临时修补当作最终实现。

package/pig-cloud-skills-commands/commands/design.md

@@ -0,0 +1,21 @@
+# /design
+
+把已经收口的需求补成可实现的技术方案。
+
+## Route
+
+- 对应 skill：`technical-design`
+- 适用：架构选型、模块拆分、接口设计、数据流设计、实现前补充设计
+- 不适用：尚未收口的需求讨论
+
+## Workflow
+
+1. 读取 `spec-refinement` 的结论。
+2. 拆分模块、接口、数据结构、事务边界和异常路径。
+3. 输出方案草图、关键决策和落地顺序。
+4. 给 `feature-build` 准备实现输入。
+
+## Guardrails
+
+- 不重新发散需求范围。
+- 不跳过架构约束直接写实现。

package/pig-cloud-skills-commands/commands/distill.md

@@ -0,0 +1,21 @@
+# /distill
+
+把业务事实提炼成可复用的领域知识。
+
+## Route
+
+- 对应 skill：`domain-modeling`
+- 适用：领域边界、实体关系、核心概念、规则沉淀
+- 不适用：纯接口变更说明
+
+## Workflow
+
+1. 识别业务对象、边界和核心规则。
+2. 抽取实体、关系、状态和约束。
+3. 输出可复用的领域索引和冲突点。
+4. 不把命名本身当作领域模型。
+
+## Guardrails
+
+- 不忽略规则冲突。
+- 不把实现细节冒充领域知识。

package/pig-cloud-skills-commands/commands/doc.md

@@ -0,0 +1,21 @@
+# /doc
+
+把接口和变更整理成可对接的文档。
+
+## Route
+
+- 对应 skill：`api-docs`
+- 适用：接口说明、变更说明、联调说明、同步文档
+- 不适用：纯代码审查
+
+## Workflow
+
+1. 先确认接口边界和输入输出。
+2. 提炼请求、响应、错误码和调用顺序。
+3. 输出可联调的文档草案。
+4. 变更后同步到知识沉淀。
+
+## Guardrails
+
+- 不遗漏错误返回和约束。
+- 不把空泛说明当成文档交付。

package/pig-cloud-skills-commands/commands/infra.md

@@ -0,0 +1,21 @@
+# /infra
+
+准备或管理开发依赖的基础设施。
+
+## Route
+
+- 对应 skill：`environment-deploy`
+- 适用：Docker Compose、依赖服务启动、开发联调环境准备
+- 不适用：业务需求分析
+
+## Workflow
+
+1. 识别需要启动的基础设施组件。
+2. 只拉起最小可用组合。
+3. 输出启动状态和常见失败点。
+4. 不把生产部署和本地开发混在一起。
+
+## Guardrails
+
+- 不默认启动多余服务。
+- 不混淆生产环境和本地环境。

package/pig-cloud-skills-commands/commands/init.md

@@ -0,0 +1,20 @@
+# /init
+
+初始化项目或模块脚手架。
+
+## Route
+
+- 对应 skill：`project-bootstrap`
+- 适用：新建项目、模块初始化、标准目录生成
+- 不适用：业务分析
+
+## Workflow
+
+1. 确认初始化对象是项目还是模块。
+2. 生成标准目录、基础配置和依赖边界。
+3. 输出后续应该进入的 skill。
+4. 不触碰具体业务逻辑。
+
+## Guardrails
+
+- 不跳过基础配置检查。

package/pig-cloud-skills-commands/commands/kb.md

@@ -0,0 +1,20 @@
+# /kb
+
+把项目事实整理成可检索、可复用、可过期治理的知识中心。
+
+## Route
+
+- 对应 skill：`knowledge-capture`
+- 适用：项目概览、模块索引、领域知识、方案沉淀、交接归档
+
+## Workflow
+
+1. 收集事实、来源、适用场景和限制条件。
+2. 分类沉淀到项目、模块、领域、方案或协作索引。
+3. 标明哪些内容可复用，哪些内容应过期清理。
+4. 让归档结果反哺后续分析和实现。
+
+## Guardrails
+
+- 不堆文档。
+- 不把未经验证的信息当知识沉淀。

package/pig-cloud-skills-commands/commands/perf.md

@@ -0,0 +1,20 @@
+# /perf
+
+检查性能热点、瓶颈和回归风险。
+
+## Route
+
+- 对应 skill：`performance-check`
+- 适用：N+1、缓存、索引、批量操作、热点路径
+- 不适用：纯安全审查或纯需求讨论
+
+## Workflow
+
+1. 找出高频路径和大数据量路径。
+2. 检查数据库访问、缓存命中、循环调用和批处理。
+3. 输出可验证的性能风险和优化顺序。
+4. 必要时交给 `code-review` 或 `feature-build`。
+
+## Guardrails
+
+- 不用泛泛建议替代定位结论。

package/pig-cloud-skills-commands/commands/prd.md

@@ -0,0 +1,21 @@
+# /prd
+
+把产品意图收口成给研发分析使用的需求输入。
+
+## Route
+
+- 对应 skill：`product-intake`
+- 适用：产品目标、业务背景、范围裁剪、优先级、验收口径、需求初稿
+- 不适用：已经进入实现细节的研发分析
+
+## Workflow
+
+1. 先确认这是产品侧需求，不直接进入设计或编码。
+2. 收集目标、范围、约束、优先级和验收标准。
+3. 输出结构化的 PRD-ready brief。
+4. 交给 `spec-refinement`。
+
+## Guardrails
+
+- 不替代研发需求分析。
+- 不跳过需求收口直接写最终结论。

package/pig-cloud-skills-commands/commands/review.md

@@ -0,0 +1,21 @@
+# /review
+
+审查代码变更、质量风险和跨模块影响。
+
+## Route
+
+- 对应 skill：`code-review`
+- 适用：PR 审查、diff 审核、上线前检查、框架规范核对
+- 不适用：纯需求讨论
+
+## Workflow
+
+1. 先确认变更范围，不只看单文件。
+2. 核对架构、边界、回归风险和约束。
+3. 输出问题级别、风险和修复建议。
+4. 必要时补 `security-review` 或 `performance-check`。
+
+## Guardrails
+
+- 只审查已经发生的变更。
+- 不跳过证据直接下结论。

package/pig-cloud-skills-commands/commands/security.md

@@ -0,0 +1,21 @@
+# /security
+
+审查安全风险、权限边界和敏感数据暴露。
+
+## Route
+
+- 对应 skill：`security-review`
+- 适用：安全审查、权限检查、数据暴露检查、合规风险检查
+- 不适用：普通需求讨论
+
+## Workflow
+
+1. 先确认输入是已经发生的变更或可检查的方案。
+2. 拆分接口、权限、数据流向和敏感信息风险。
+3. 输出安全发现、优先级和修复建议。
+4. 必要时交给 `knowledge-capture` 或 `feature-build`。
+
+## Guardrails
+
+- 不直接修改生产代码。
+- 不把一般质量问题误判成安全结论。

package/pig-cloud-skills-commands/commands/test.md

@@ -0,0 +1,21 @@
+# /test
+
+把验收标准转成可执行的测试设计。
+
+## Route
+
+- 对应 skill：`test-design`
+- 适用：测试策略、用例设计、回归矩阵、验证路径
+- 不适用：需求还不明确，或者只是想“快速跑一下”
+
+## Workflow
+
+1. 先确认验收标准或实现结果。
+2. 转成测试策略、用例、回归和边界场景。
+3. 输出可执行的验证方案。
+4. 必要时交给 `code-review` 或 `feature-build`。
+
+## Guardrails
+
+- 不跳过前置条件。
+- 不把“跑过一次”当作完整验证。

package/pig-cloud-skills-commands/commands/workflow.md

@@ -0,0 +1,20 @@
+# /workflow
+
+按阶段路由到正确的 skill，并控制阶段切换。
+
+## Route
+
+- 适用：多阶段任务、跨 skill 协作、门禁控制、阶段切换
+- 不适用：单一步骤的小任务
+
+## Workflow
+
+1. 判断当前处于哪个生命周期阶段。
+2. 选择当前 skill 或下一步 skill。
+3. 如果门禁失败，暂停下游并说明原因。
+4. 记录下一步应该走哪个 skill。
+
+## Guardrails
+
+- 不替用户决定跳过阶段。
+- 不让下游覆盖上游未确认结果。