@pigcloud/skills 1.0.3 → 1.0.5

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