@pigcloud/skills 1.0.3 → 1.0.5

package/bin/postinstall.js

@@ -39,7 +39,7 @@ function syncCodexSkills() {
   };
 }
 
-print('Pig Cloud Skills installed.');
+print('Pig Skills installed.');
 
 if (autoSyncDisabled) {
   print('Auto-sync skipped because PIG_SKILLS_SKIP_AUTO_SYNC is set.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pigcloud/skills",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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/rules/skill-profile-map.json

@@ -3,11 +3,7 @@
     "bundle": "workflow",
     "profile": "router"
   },
-  "product-intake": {
-    "bundle": "product",
-    "profile": "intake"
-  },
-  "spec-refinement": {
+  "spec": {
     "bundle": "workflow",
     "profile": "refinement"
   },
@@ -31,6 +27,10 @@
     "bundle": "product",
     "profile": "modeling"
   },
+  "extract-business-facts": {
+    "bundle": "product",
+    "profile": "modeling"
+  },
   "api-docs": {
     "bundle": "docs",
     "profile": "api"

package/rules/skill-profile-map.md

@@ -7,13 +7,13 @@ This file explains which canonical skill loads which rules bundle and profile.
 | Skill | Bundle | Profile |
 |---|---|---|
 | `workflow-router` | `workflow` | `router` |
-| `product-intake` | `product` | `intake` |
-| `spec-refinement` | `workflow` | `refinement` |
+| `spec` | `workflow` | `refinement` |
 | `technical-design` | `coding` | `analysis` |
 | `feature-build` | `coding` | `implementation` |
 | `test-design` | `coding` | `testing` |
 | `code-review` | `review` | `code` |
 | `domain-modeling` | `product` | `modeling` |
+| `extract-business-facts` | `product` | `modeling` |
 | `api-docs` | `docs` | `api` |
 | `security-review` | `review` | `security` |
 | `performance-check` | `review` | `performance` |

package/scripts/validate-skill-shapes.js

@@ -6,12 +6,13 @@ const path = require('path');
 const repoRoot = path.join(__dirname, '..');
 const skillsRoot = path.join(repoRoot, 'skills');
 const enhancedTemplateSkills = new Set([
-  'spec-refinement',
+  'spec',
   'technical-design',
   'feature-build',
   'code-review',
   'security-review',
   'performance-check',
+  'extract-business-facts',
 ]);
 const enhancedSections = [
   '## Quick Start',

package/scripts/validate-skills.ps1

@@ -6,12 +6,12 @@ $ErrorActionPreference = 'Stop'
 $repoRoot = (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot '..')).Path
 $python = Join-Path $repoRoot '.tools\python.cmd'
 if (-not $SkillsRoot) {
-    if (Test-Path -LiteralPath (Join-Path $repoRoot 'skills')) {
-        $SkillsRoot = Join-Path $repoRoot 'skills'
-    } else {
-        $SkillsRoot = Join-Path $repoRoot '.agents\skills'
-    }
-}
+    if (Test-Path -LiteralPath (Join-Path $repoRoot 'skills')) {
+        $SkillsRoot = Join-Path $repoRoot 'skills'
+    } else {
+        $SkillsRoot = Join-Path $repoRoot '.codex\skills\pigcloud'
+    }
+}
 $codexHome = $env:CODEX_HOME
 if (-not $codexHome) {
     $codexHome = Join-Path $HOME '.codex'

package/scripts/validate-skills.sh

@@ -7,11 +7,11 @@ codex_home="${CODEX_HOME:-$HOME/.codex}"
 validator="$codex_home/skills/.system/skill-creator/scripts/quick_validate.py"
 if [ -n "${1:-}" ]; then
   skills_root="$1"
-elif [ -d "$repo_root/skills" ]; then
-  skills_root="$repo_root/skills"
-else
-  skills_root="$repo_root/.agents/skills"
-fi
+elif [ -d "$repo_root/skills" ]; then
+  skills_root="$repo_root/skills"
+else
+  skills_root="$repo_root/.codex/skills/pigcloud"
+fi
 
 if [ ! -f "$validator" ]; then
   echo "Validator not found: $validator" >&2

package/skills/api-docs/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: api-docs
-description: 当接口需要可复用参考文档时，记录稳定的 API 行为、请求/响应契约和示例
+description: 当接口需要可复用参考文档时，记录稳定的 API 行为、请求/响应契约和示例
 lifecycle_stage: capture
 rule_profile: api
 dependencies:
-  - spec-refinement
+  - spec
 triggers:
   - API docs
   - contract

package/skills/domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: domain-modeling
-description: 当领域模型不清晰时，从代码或业务语言中提炼领域边界和核心概念
+description: 当领域模型不清晰时，从代码或业务语言中提炼领域边界和核心概念
 lifecycle_stage: design
 rule_profile: modeling
 dependencies: []
@@ -23,7 +23,7 @@ workflow:
   - extract the core domain terms
   - group concepts by boundary
   - identify aggregates and dependencies
-  - hand off to technical-design or spec-refinement
+  - hand off to technical-design or spec
 gates:
   - stop at domain boundaries
   - do not implement code
@@ -51,14 +51,14 @@ Extract domain boundaries and core concepts from messy input.
 1. Extract the core domain terms.
 2. Group concepts by boundary.
 3. Identify aggregates and dependencies.
-4. Hand off to `technical-design` or `spec-refinement`.
+4. Hand off to `technical-design` or `spec`.
 
 ## Replay Signals
 
 - Input signal: existing business language, product context, code, or documents.
 - Output to verify: domain map, core concepts, boundary notes.
 - Stop signal: implementation code or PRD drafting.
-- Handoff signal: the boundary map is ready for `technical-design` or `spec-refinement`.
+- Handoff signal: the boundary map is ready for `technical-design` or `spec`.
 
 ## Examples
 

package/skills/extract-business-facts/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: extract-business-facts
+description: Extract business facts, current behaviors, invariants, and terminology from code, tests, logs, and docs when Codex needs to reverse-engineer what the system actually does or prepare evidence-backed input for domain modeling, spec refinement, or knowledge capture.
+lifecycle_stage: analysis
+rule_profile: modeling
+dependencies: []
+triggers:
+  - reverse engineer behavior
+  - business facts
+  - current behavior
+  - code facts
+  - extract facts from code
+  - behavior map
+inputs:
+  - code paths
+  - tests
+  - logs
+  - docs
+  - schemas
+  - runtime evidence
+outputs:
+  - code fact map
+  - business fact map
+  - codewiki delta
+  - handoff notes
+  - knowledge-base file targets
+workflow:
+  - collect code, test, doc, and runtime evidence for the requested area
+  - extract code facts first, then derive business meaning, then propose CodeWiki updates
+  - mark each fact as evidence-backed, inferred, or unknown
+  - summarize gaps, contradictions, and open questions
+  - choose the destination knowledge-base files before writing the final note
+  - hand off to domain-modeling, spec, or knowledge-capture
+gates:
+  - stop at fact extraction
+  - do not design a new solution
+  - do not rewrite the PRD
+  - do not generate code
+refs:
+  - skills/references/business-fact-extraction.md
+  - skills/references/skill-reference-matrix.md
+  - skills/references/rule-loading-map.md
+  - docs/codewiki-knowledge-base.md
+---
+
+# Extract Business Facts
+
+## Purpose
+
+Turn code-backed evidence into reusable business facts.
+
+## Suitable / Unsuitable
+
+- Suitable: reverse engineering, current behavior mapping, business rule extraction, terminology normalization, evidence-backed summaries
+- Unsuitable: PRD drafting, solution design, implementation, review, final knowledge capture
+
+## Quick Start
+
+- Start from code paths, tests, docs, runtime traces, and schemas.
+- Produce the output in three stages: code facts, business facts, and CodeWiki updates.
+- Keep evidence, inference, and unknowns distinct.
+- Hand off the result when the facts are stable enough for `domain-modeling`, `spec`, or `knowledge-capture`.
+
+## Write Back
+
+- When the user wants persistence, render the staged output into a JSON fact pack.
+- Use `skills/extract-business-facts/scripts/write-knowledge-base.js` to write the pack into the knowledge-base files.
+- Keep the pack keyed by target file path under `knowledge-base/`.
+- Write only the smallest matching file for each fact.
+- Treat the script as a writer, not as a second analysis pass.
+
+## Inputs / Outputs
+
+- Inputs:
+  - code paths
+  - tests
+  - logs
+  - docs
+  - schemas
+  - runtime evidence
+- Outputs:
+  - code fact map
+  - business fact map
+  - codewiki delta
+  - handoff notes
+  - knowledge-base file targets
+
+## Output Template
+
+### 1. Code Facts
+
+#### `knowledge-base/realtime-code/modules.md`
+
+- module:
+- current responsibility:
+- key entry points:
+- important constraints:
+- last verified:
+
+#### `knowledge-base/realtime-code/flows.md`
+
+- flow name:
+- trigger:
+- path:
+- output:
+- failure points:
+- notes:
+
+#### `knowledge-base/realtime-code/runtime-notes.md`
+
+- fact:
+- evidence:
+- affected area:
+- date:
+- notes:
+
+### 2. Business Facts
+
+#### `knowledge-base/requirements/decisions.md`
+
+- decision:
+- reason:
+- date or context:
+- affected artifact:
+- notes:
+
+#### `knowledge-base/requirements/acceptance.md`
+
+- requirement:
+- acceptance criteria:
+- out of scope:
+- open questions:
+- confirmed by:
+
+#### `knowledge-base/requirements/conflicts.md`
+
+- conflict:
+- source:
+- impact:
+- resolution:
+- status:
+
+### 3. CodeWiki Update
+
+#### `knowledge-base/codewiki/overview.md`
+
+- one-line summary:
+- what the system does:
+- what changed:
+- why it matters:
+
+#### `knowledge-base/codewiki/architecture.md`
+
+- layers:
+- boundaries:
+- dependencies:
+- major integration points:
+
+#### `knowledge-base/codewiki/modules.md`
+
+- module name:
+- responsibility:
+- main interfaces:
+- related runtime facts:
+
+#### `knowledge-base/codewiki/flows.md`
+
+- request flow:
+- data flow:
+- error flow:
+- handoff flow:
+
+#### `knowledge-base/codewiki/api.md`
+
+- endpoint or contract:
+- request shape:
+- response shape:
+- constraints:
+
+#### `knowledge-base/codewiki/runbook.md`
+
+- startup:
+- verify:
+- troubleshoot:
+- recover:
+
+#### `knowledge-base/codewiki/conventions.md`
+
+- naming:
+- layering:
+- error handling:
+- logging:
+- data handling:
+
+### 4. Enterprise Note
+
+#### `knowledge-base/enterprise/decisions.md`
+
+- decision:
+- reason:
+- scope:
+- date:
+- reusable lesson:
+
+#### `knowledge-base/enterprise/pitfalls.md`
+
+- pitfall:
+- context:
+- why it failed:
+- how to avoid it:
+
+#### `knowledge-base/enterprise/examples.md`
+
+- example:
+- context:
+- lesson:
+- reusable pattern:
+
+#### `knowledge-base/enterprise/ai-coding-rules.md`
+
+- rule:
+- when it applies:
+- why it matters:
+- examples:
+
+## Sample Output
+
+### Code Facts
+
+#### `knowledge-base/realtime-code/modules.md`
+
+- module: `order-service`
+- current responsibility: creates orders and reserves inventory
+- key entry points: `createOrder()`, `reserveInventory()`
+- important constraints: stock must be checked before commit
+- last verified: 2026-06-22
+
+#### `knowledge-base/realtime-code/flows.md`
+
+- flow name: checkout order placement
+- trigger: user confirms checkout
+- path: validate stock -> reserve inventory -> create order
+- output: confirmed order or shortage error
+- failure points: stock shortage, reservation failure
+- notes: reservation must happen before the order commit
+
+### Business Facts
+
+#### `knowledge-base/requirements/decisions.md`
+
+- decision: inventory must be reserved before order confirmation
+- reason: avoid overselling
+- date or context: 2026-06-22, order flow review
+- affected artifact: checkout spec
+- notes: failure should return a clear stock shortage message
+
+#### `knowledge-base/requirements/acceptance.md`
+
+- requirement: checkout must not confirm an order when stock is unavailable
+- acceptance criteria: shortage blocks confirmation and returns a clear message
+- out of scope: backorder design
+- open questions: whether to retry reservation automatically
+- confirmed by: order flow review
+
+### CodeWiki Update
+
+#### `knowledge-base/codewiki/flows.md`
+
+- request flow: checkout -> validate stock -> reserve inventory -> create order
+- data flow: cart snapshot -> reservation record -> order record
+- error flow: stock shortage -> stop checkout -> return shortage reason
+- handoff flow: checkout service hands off to inventory service and order repository
+
+#### `knowledge-base/codewiki/modules.md`
+
+- module name: `order-service`
+- responsibility: coordinates checkout and order creation
+- main interfaces: `createOrder()`, `reserveInventory()`
+- related runtime facts: inventory must be reserved before commit
+
+### Enterprise Note
+
+#### `knowledge-base/enterprise/pitfalls.md`
+
+- pitfall: reservation happens after order creation
+- context: checkout path
+- why it failed: allowed overselling under concurrent requests
+- how to avoid it: reserve before committing the order
+
+#### `knowledge-base/enterprise/ai-coding-rules.md`
+
+- rule: reserve inventory before committing the order
+- when it applies: any checkout flow that can oversell
+- why it matters: keeps business state consistent under concurrency
+- examples: validate stock, reserve, then create the order
+
+## Workflow
+
+1. Collect code, test, doc, and runtime evidence for the requested area.
+2. Write the code fact map with observed behavior, state changes, contracts, and evidence.
+3. Derive the business fact map from the code facts and separate inference from proof.
+4. Draft the CodeWiki delta with reusable architecture, flow, and convention updates.
+5. Map each section to the exact knowledge-base files it should update.
+6. Mark each fact as evidence-backed, inferred, or unknown.
+7. Summarize gaps, contradictions, and open questions.
+8. Hand off to `domain-modeling`, `spec`, or `knowledge-capture`.
+
+## Replay Signals
+
+- Input signal: codebase walkthrough, behavior reconstruction, business rule extraction, or current-state analysis.
+- Output to verify: code fact map, business fact map, codewiki delta, file targets, gap list.
+- Stop signal: solution design, PRD rewriting, or code generation.
+- Handoff signal: the extracted facts are stable enough for downstream modeling or capture.
+
+## Gotchas
+
+- Do not infer business intent from comments alone.
+- Do not merge evidence-backed facts and assumptions into one claim.
+- Do not skip contradictory evidence.
+- Do not turn extraction into design.
+- Do not write the CodeWiki delta before the code facts are stable.
+- Do not leave file targets implicit.
+
+## Stop Rules
+
+- Stop at fact extraction.
+- Do not design a new solution.
+- Do not rewrite the PRD.
+- Do not generate code.
+
+## References
+
+- `skills/references/business-fact-extraction.md`
+- `skills/references/skill-reference-matrix.md`
+- `skills/references/rule-loading-map.md`
+- `docs/codewiki-knowledge-base.md`