@pigcloud/skills 1.0.3 → 1.0.4

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`

package/skills/extract-business-facts/scripts/write-knowledge-base.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const REPO_ROOT = path.join(__dirname, '..', '..', '..');
+const START_MARKER = '<!-- extract-business-facts:start -->';
+const END_MARKER = '<!-- extract-business-facts:end -->';
+
+const FILE_FIELD_ORDER = {
+  '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'],
+  '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'],
+  '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'],
+  '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']
+};
+
+const SAMPLE_PACK = {
+  files: {
+    '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/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/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/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'
+      }
+    ]
+  }
+};
+
+function parseArgs(argv) {
+  const args = {
+    input: null,
+    root: REPO_ROOT,
+    dryRun: false,
+    sample: false
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--input' || token === '-i') {
+      args.input = argv[++index];
+      continue;
+    }
+    if (token.startsWith('--input=')) {
+      args.input = token.slice('--input='.length);
+      continue;
+    }
+    if (token === '--root' || token === '-r') {
+      args.root = path.resolve(argv[++index]);
+      continue;
+    }
+    if (token.startsWith('--root=')) {
+      args.root = path.resolve(token.slice('--root='.length));
+      continue;
+    }
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+    if (token === '--sample') {
+      args.sample = true;
+      continue;
+    }
+  }
+
+  return args;
+}
+
+function readInput(inputPath) {
+  if (!inputPath || inputPath === '-') {
+    return fs.readFileSync(0, 'utf8');
+  }
+  return fs.readFileSync(inputPath, 'utf8');
+}
+
+function loadPack(inputText) {
+  const parsed = JSON.parse(String(inputText).replace(/^\uFEFF/, ''));
+  if (parsed && typeof parsed === 'object' && parsed.files && typeof parsed.files === 'object') {
+    return parsed.files;
+  }
+  if (parsed && typeof parsed === 'object') {
+    return parsed;
+  }
+  throw new Error('Input must be a JSON object.');
+}
+
+function normalizeValue(value) {
+  if (value === null || value === undefined || value === '') return 'unknown';
+  if (Array.isArray(value)) return value.map(item => normalizeValue(item)).join(', ');
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value).trim() || 'unknown';
+}
+
+function renderEntry(fields, entry) {
+  return fields.map(field => `- ${field}: ${normalizeValue(entry[field])}`).join('\n');
+}
+
+function renderFileSection(relativePath, entries) {
+  const fieldOrder = FILE_FIELD_ORDER[relativePath];
+  if (!fieldOrder) {
+    throw new Error(`Unsupported target file: ${relativePath}`);
+  }
+  if (!Array.isArray(entries) || entries.length === 0) {
+    throw new Error(`No entries provided for ${relativePath}`);
+  }
+
+  const blocks = entries.map(entry => renderEntry(fieldOrder, entry));
+  return [
+    '## Generated Entries',
+    START_MARKER,
+    blocks.join('\n\n'),
+    END_MARKER
+  ].join('\n');
+}
+
+function upsertGeneratedSection(existingContent, generatedSection) {
+  const startIndex = existingContent.indexOf(START_MARKER);
+  const endIndex = existingContent.indexOf(END_MARKER);
+
+  if (startIndex >= 0 && endIndex >= 0 && endIndex > startIndex) {
+    const before = existingContent.slice(0, startIndex).trimEnd();
+    const after = existingContent.slice(endIndex + END_MARKER.length).trimStart();
+    const middle = generatedSection;
+    const parts = [before, middle];
+    if (after) {
+      parts.push(after);
+    }
+    return `${parts.filter(Boolean).join('\n\n').trimEnd()}\n`;
+  }
+
+  const base = existingContent.trimEnd();
+  if (!base) {
+    return `${generatedSection}\n`;
+  }
+
+  return `${base}\n\n${generatedSection}\n`;
+}
+
+function collectTargets(filePack) {
+  const targets = [];
+  for (const [relativePath, entries] of Object.entries(filePack)) {
+    if (!relativePath.startsWith('knowledge-base/')) {
+      throw new Error(`Refusing to write outside knowledge-base: ${relativePath}`);
+    }
+    targets.push({ relativePath, entries });
+  }
+  return targets;
+}
+
+function ensureParentDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.sample) {
+    process.stdout.write(`${JSON.stringify(SAMPLE_PACK, null, 2)}\n`);
+    return;
+  }
+
+  const inputText = readInput(args.input);
+  const filePack = loadPack(inputText);
+  const targets = collectTargets(filePack);
+
+  for (const { relativePath, entries } of targets) {
+    const absolutePath = path.join(args.root, relativePath);
+    const generatedSection = renderFileSection(relativePath, entries);
+    const existingContent = fs.existsSync(absolutePath) ? fs.readFileSync(absolutePath, 'utf8') : '';
+    const nextContent = upsertGeneratedSection(existingContent, generatedSection);
+
+    if (args.dryRun) {
+      process.stdout.write(`=== ${relativePath} ===\n${nextContent}\n`);
+      continue;
+    }
+
+    ensureParentDir(absolutePath);
+    fs.writeFileSync(absolutePath, nextContent, 'utf8');
+    process.stdout.write(`Wrote ${relativePath}\n`);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/skills/knowledge-capture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-capture
-description: 当下游工作需要可持续沉淀时，捕捉可复用的决策、需求知识、实时代码事实、CodeWiki 事实和交接说明
+description: Capture reusable decisions, requirement knowledge, realtime code facts, CodeWiki facts, and handoff notes; use when an upstream task already produced evidence and you need to normalize it, persist it, or hand it off without redoing analysis.
 lifecycle_stage: capture
 rule_profile: capture
 dependencies: []
@@ -15,21 +15,26 @@ inputs:
   - approved artifacts
   - findings
   - decisions
+  - staged fact packs
 outputs:
   - reusable note
   - knowledge page
   - handoff summary
+  - knowledge-base write pack
 workflow:
   - collect the produced artifact
   - normalize it into a reusable note
   - separate requirement knowledge, realtime code facts, CodeWiki facts, and decision-log content
   - link it to the originating skill
+  - when persistence is needed, convert the note into a knowledge-base fact pack and write it with the capture writer
   - publish the handoff summary for downstream reuse
 gates:
   - stop at capture and organization
   - do not redo upstream analysis
   - do not generate new requirements or code
+  - do not rewrite the fact pack into a new analysis
 refs:
+  - skills/references/business-fact-extraction.md
   - skills/references/skill-reference-matrix.md
   - skills/references/rule-loading-map.md
   - skills/references/flow-test-cases.md
@@ -46,7 +51,7 @@ Store decisions, artifacts, and handoff notes so other skills can reuse them lat
 
 ## Suitable / Unsuitable
 
-- Suitable: summaries, decision logs, reusable knowledge, artifact handoff, CodeWiki facts, requirements knowledge, realtime code facts
+- Suitable: summaries, decision logs, reusable knowledge, artifact handoff, CodeWiki facts, requirements knowledge, realtime code facts, staged fact packs
 - Unsuitable: requirement discovery, design, implementation, review, test authoring
 
 ## Workflow
@@ -55,12 +60,13 @@ Store decisions, artifacts, and handoff notes so other skills can reuse them lat
 2. Normalize it into a reusable note.
 3. Separate requirement knowledge, realtime code facts, CodeWiki facts, decision log entries, and pitfall notes.
 4. Link it back to the originating skill.
-5. Publish the handoff summary for downstream reuse.
+5. If the note should persist, map it to the knowledge-base file targets and write the fact pack.
+6. Publish the handoff summary for downstream reuse.
 
 ## Replay Signals
 
-- Input signal: approved artifacts, findings, or decisions.
-- Output to verify: reusable note, knowledge page, handoff summary, decision log entry, codewiki update, enterprise knowledge note.
+- Input signal: approved artifacts, findings, decisions, or staged fact packs.
+- Output to verify: reusable note, knowledge page, handoff summary, decision log entry, codewiki update, enterprise knowledge note, knowledge-base write pack.
 - Stop signal: redoing upstream analysis or generating new requirements/code.
 - Handoff signal: the reusable note is ready for later reuse by other skills.
 
@@ -70,15 +76,18 @@ Store decisions, artifacts, and handoff notes so other skills can reuse them lat
 - Do not redo upstream analysis.
 - Do not generate new requirements or code.
 - Do not merge requirement knowledge, code facts, and decisions into one blob.
+- Do not treat persistence as a new analysis pass.
+- Do not rewrite the fact pack into a new analysis.
 
 ## Examples
 
 - Input: "Capture the decisions and pitfalls from this task."
-- Output: reusable note, knowledge page, handoff summary
+- Output: reusable note, knowledge page, handoff summary, optional knowledge-base write pack
 - Stop: do not re-open the design or implementation debate
 
 ## References
 
+- `skills/references/business-fact-extraction.md`
 - `skills/references/skill-reference-matrix.md`
 - `skills/references/rule-loading-map.md`
-- `skills/references/flow-test-cases.md`
+- `docs/codewiki-knowledge-base.md`

package/skills/project-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-bootstrap
-description: 当项目需要初始化时，为新工作区装载合适的技能和规则包
+description: 当项目需要初始化时，为新工作区装载合适的技能和规则包
 lifecycle_stage: scaffold
 rule_profile: scaffold
 dependencies: []
@@ -58,7 +58,7 @@ Create a new workspace with the right skills and rules layout.
 - Input signal: client type, workspace markers, desired rules bundle.
 - Output to verify: starter structure, installed bundle, setup notes.
 - Stop signal: product scope design or application code generation.
-- Handoff signal: the workspace is ready for `workflow-router` or `product-intake`.
+- Handoff signal: the workspace is ready for `workflow-router` or `spec`.
 
 ## Examples