@pigcloud/skills 1.0.10 → 1.1.2

package/scripts/validate-skill-shapes.js

@@ -3,133 +3,159 @@
 const fs = require('fs');
 const path = require('path');
 
-const repoRoot = path.join(__dirname, '..');
-const skillsRoot = path.join(repoRoot, 'skills');
-const enhancedTemplateSkills = new Set([
-  'spec-refinement',
-  'technical-design',
-  'feature-build',
-  'code-review',
-  'security-audit',
-  'performance-audit',
-  'business-fact-extraction',
-]);
-const enhancedSections = [
-  '## Quick Start',
-  '## Inputs / Outputs',
-  '## Gotchas',
-];
-const shortTemplateSections = [
-  '## Quick Start',
-  '## Inputs / Outputs',
-  '## Gotchas',
-];
-
-function readSkillDirectories() {
-  return fs.readdirSync(skillsRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && entry.name !== 'references')
-    .map((entry) => entry.name)
-    .sort();
-}
-
-function readSkillFile(skillName) {
-  return fs.readFileSync(path.join(skillsRoot, skillName, 'SKILL.md'), 'utf8');
-}
-
-function extractFrontmatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  return match ? match[1] : '';
-}
-
-function extractHeadings(content) {
-  return content
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter((line) => /^##\s+/.test(line))
-    .map((line) => line);
-}
-
-function assert(condition, message) {
-  if (!condition) {
-    throw new Error(message);
-  }
-}
-
-function ensureFrontmatterKeys(skillName, frontmatter) {
-  const requiredKeys = [
-    'name:',
-    'description:',
-    'lifecycle_stage:',
-    'dependencies:',
-    'triggers:',
-    'inputs:',
-    'outputs:',
-    'workflow:',
-    'gates:',
-    'refs:',
-    'rule_profile:',
-  ];
-
-  for (const key of requiredKeys) {
-    assert(frontmatter.includes(key), `${skillName}: missing frontmatter key ${key}`);
-  }
-}
-
-function ensureSectionOrder(skillName, headings, requiredOrder) {
-  let lastIndex = -1;
-  for (const section of requiredOrder) {
-    const index = headings.indexOf(section);
-    assert(index >= 0, `${skillName}: missing section ${section}`);
-    assert(index > lastIndex, `${skillName}: section order is invalid around ${section}`);
-    lastIndex = index;
-  }
-}
-
-function validateSkill(skillName) {
-  const content = readSkillFile(skillName);
-  const frontmatter = extractFrontmatter(content);
-  assert(frontmatter, `${skillName}: missing frontmatter`);
-  ensureFrontmatterKeys(skillName, frontmatter);
-
-  const headings = extractHeadings(content);
-  const requiredOrder = enhancedTemplateSkills.has(skillName)
-    ? [
-      '## Purpose',
-      '## Suitable / Unsuitable',
-      '## Quick Start',
-      '## Inputs / Outputs',
-      '## Workflow',
-      '## Replay Signals',
-      '## Gotchas',
-      '## Stop Rules',
-      '## References',
-    ]
-    : [
-      '## Purpose',
-      '## Suitable / Unsuitable',
-      '## Workflow',
-      '## Replay Signals',
-      '## Stop Rules',
-      '## References',
-    ];
-
-  ensureSectionOrder(skillName, headings, requiredOrder);
-
-  if (enhancedTemplateSkills.has(skillName)) {
-    for (const section of enhancedSections) {
-      assert(headings.includes(section), `${skillName}: missing enhanced section ${section}`);
-    }
-  } else {
-    for (const section of shortTemplateSections) {
-      assert(!headings.includes(section), `${skillName}: short template should not include ${section}`);
-    }
-  }
-}
-
-function main() {
-  for (const skillName of readSkillDirectories()) {
-    validateSkill(skillName);
-  }
+const repoRoot = path.join(__dirname, '..');
+const skillsRoot = path.join(repoRoot, 'skills');
+
+function readSkillDirectories() {
+  const results = [];
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'references') {
+        continue;
+      }
+
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const skillFile = path.join(fullPath, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+          results.push(fullPath);
+        }
+        walk(fullPath);
+      }
+    }
+  }
+
+  walk(skillsRoot);
+  return results.sort();
+}
+
+function readSkillFile(skillDir) {
+  return fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+}
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return match ? match[1] : '';
+}
+
+function extractHeadings(content) {
+  return content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^##\s+/.test(line));
+}
+
+function extractSectionItems(content, sectionName) {
+  const lines = content.split(/\r?\n/);
+  const items = [];
+  let inSection = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!inSection) {
+      if (line === `## ${sectionName}`) {
+        inSection = true;
+      }
+      continue;
+    }
+
+    if (line.startsWith('## ')) {
+      break;
+    }
+
+    if (line.startsWith('- ')) {
+      items.push(line.slice(2).trim());
+    }
+  }
+
+  return items;
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function parseFrontmatter(frontmatter) {
+  const entries = [];
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    const match = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) {
+      entries.push({ key: match[1], value: match[2] });
+    }
+  }
+
+  return entries;
+}
+
+function extractBody(content) {
+  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+  return match ? match[1] : '';
+}
+
+function validateSkill(skillDir) {
+  const skillName = path.basename(skillDir);
+  const specPath = path.join(skillDir, 'skill-spec.json');
+  const content = readSkillFile(skillDir);
+  assert(fs.existsSync(specPath), `${skillName}: missing skill-spec.json`);
+  const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+  const frontmatter = extractFrontmatter(content);
+  assert(frontmatter, `${skillName}: missing frontmatter`);
+  const entries = parseFrontmatter(frontmatter);
+  const keys = entries.map((entry) => entry.key);
+  assert(keys.includes('name'), `${skillName}: missing frontmatter key name`);
+  assert(keys.includes('description'), `${skillName}: missing frontmatter key description`);
+
+  const allowedKeys = new Set(['name', 'description']);
+  const extraKeys = entries.filter((entry) => !allowedKeys.has(entry.key));
+  assert(extraKeys.length === 0, `${skillName}: unexpected frontmatter keys: ${extraKeys.map((entry) => entry.key).join(', ')}`);
+
+  const body = extractBody(content).trim();
+  assert(body.length > 0, `${skillName}: skill body is missing`);
+  assert(spec.name === skillName, `${skillName}: skill-spec.json name mismatch`);
+  assert(spec.description === entries.find((entry) => entry.key === 'description')?.value, `${skillName}: skill-spec.json description mismatch`);
+  assert(Array.isArray(spec.whenToUse) && spec.whenToUse.length >= 2, `${skillName}: skill-spec.json whenToUse too short`);
+  assert(Array.isArray(spec.how) && spec.how.length >= 3, `${skillName}: skill-spec.json how too short`);
+  assert(Array.isArray(spec.whenToAvoid) && spec.whenToAvoid.length >= 2, `${skillName}: skill-spec.json whenToAvoid too short`);
+  assert(typeof spec.purpose === 'string' && spec.purpose.length > 0, `${skillName}: skill-spec.json purpose missing`);
+
+  const headings = extractHeadings(body);
+  const expectedOrder = ['## Purpose', '## When to Use', '## How', '## When to Avoid'];
+  let lastIndex = -1;
+  for (const section of expectedOrder) {
+    const index = headings.indexOf(section);
+    assert(index >= 0, `${skillName}: missing section ${section}`);
+    assert(index > lastIndex, `${skillName}: section order is invalid around ${section}`);
+    lastIndex = index;
+  }
+
+  for (const heading of headings) {
+    assert(expectedOrder.includes(heading), `${skillName}: unexpected section ${heading}`);
+  }
+
+  assert(extractSectionItems(body, 'When to Use').length >= 2, `${skillName}: When to Use needs at least 2 bullets`);
+  assert(extractSectionItems(body, 'How').length >= 3, `${skillName}: How needs at least 3 bullets`);
+  assert(extractSectionItems(body, 'When to Avoid').length >= 2, `${skillName}: When to Avoid needs at least 2 bullets`);
+  const referencesDir = path.join(skillDir, 'references');
+  const assetsDir = path.join(skillDir, 'assets');
+  assert(fs.existsSync(path.join(referencesDir, 'README.md')), `${skillName}: missing local references README file`);
+  assert(fs.existsSync(path.join(referencesDir, 'prompt-template.md')), `${skillName}: missing local prompt template file`);
+  assert(fs.existsSync(path.join(referencesDir, 'cases.md')), `${skillName}: missing local replay cases file`);
+  assert(fs.existsSync(path.join(assetsDir, 'golden-prompt-suite.current.js')), `${skillName}: missing local replay asset file`);
+}
+
+function main() {
+  assert(!fs.existsSync(path.join(skillsRoot, 'references')), 'legacy skills/references directory should not exist');
+  for (const skillDir of readSkillDirectories()) {
+    validateSkill(skillDir);
+  }
 
   console.log('=== Skill shape validation complete ===');
 }

package/scripts/validate-skill-stop-rules.js

@@ -6,17 +6,34 @@ const path = require('path');
 const repoRoot = path.join(__dirname, '..');
 const skillsRoot = path.join(repoRoot, 'skills');
 
-function readSkillDirectories() {
-  return fs.readdirSync(skillsRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && entry.name !== 'references')
-    .map((entry) => entry.name)
-    .sort();
-}
-
-function readSkillFile(skillName) {
-  const skillFile = path.join(skillsRoot, skillName, 'SKILL.md');
-  return fs.readFileSync(skillFile, 'utf8');
-}
+function readSkillDirectories() {
+  const results = [];
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'references') {
+        continue;
+      }
+
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const skillFile = path.join(fullPath, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+          results.push(fullPath);
+        }
+        walk(fullPath);
+      }
+    }
+  }
+
+  walk(skillsRoot);
+  return results.sort();
+}
+
+function readSkillFile(skillDir) {
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  return fs.readFileSync(skillFile, 'utf8');
+}
 
 function extractFrontmatter(content) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -92,41 +109,32 @@ function hasMatchingRule(gate, stopRules) {
   });
 }
 
-function validateSkill(skillName) {
-  const content = readSkillFile(skillName);
-  const frontmatter = extractFrontmatter(content);
-  if (!frontmatter) {
-    throw new Error(`${skillName}: missing frontmatter`);
-  }
-
-  const gates = extractSectionList(frontmatter, 'gates');
-  const stopRules = extractStopRules(content);
-
-  if (!gates.length) {
-    throw new Error(`${skillName}: missing gates`);
-  }
-
-  if (!stopRules.length) {
-    throw new Error(`${skillName}: missing Stop Rules section`);
-  }
-
-  const missing = gates.filter((gate) => !hasMatchingRule(gate, stopRules));
-  if (missing.length > 0) {
-    throw new Error(`${skillName}: stop rules do not cover gates: ${missing.join(' | ')}`);
-  }
-
-  return {
-    skillName,
-    gates,
-    stopRules,
-  };
-}
-
-function main() {
-  const skills = readSkillDirectories();
-  for (const skillName of skills) {
-    validateSkill(skillName);
-  }
+function validateSkill(skillDir) {
+  const skillName = path.basename(skillDir);
+  const content = readSkillFile(skillDir);
+  const frontmatter = extractFrontmatter(content);
+  if (!frontmatter) {
+    throw new Error(`${skillName}: missing frontmatter`);
+  }
+
+  const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+  if (!/##\s+When to Avoid/.test(body)) {
+    throw new Error(`${skillName}: missing When to Avoid section`);
+  }
+
+  const stopRules = extractStopRules(content);
+  if (stopRules.length > 0) {
+    throw new Error(`${skillName}: Stop Rules section should be removed`);
+  }
+
+  return { skillName };
+}
+
+function main() {
+  const skills = readSkillDirectories();
+  for (const skillDir of skills) {
+    validateSkill(skillDir);
+  }
 
   console.log(`=== Stop rule validation complete for ${skills.length} skills ===`);
 }

package/skills/01-discovery/ambiguity-detection/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: ambiguity-detection
+description: Surface blockers, contradictions, and missing decisions before the work moves forward.
+---
+
+# Ambiguity Detection
+
+## Purpose
+
+Find blockers that prevent the next stage from being safe or deterministic.
+
+## When to Use
+
+- The input contains conflicting or underspecified statements.
+- You need to surface risks before committing to a plan.
+- The same phrase could reasonably mean more than one thing.
+
+## How
+
+- Separate facts, assumptions, conflicts, and missing decisions before the work moves forward.
+- Name each ambiguity, the decision it blocks, and the question that removes it.
+- Classify each item as blocker, risk, or open question.
+- Turn every assumption into an explicit decision or an explicit unknown.
+- Stop after the blocker list is complete; do not resolve conflicts without evidence.
+
+## When to Avoid
+
+- The request is already routeable and only needs design work.
+- The input is already clear enough for implementation.
+- You only need wording cleanup or formatting.

package/skills/01-discovery/ambiguity-detection/assets/golden-prompt-suite.current.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+module.exports = {
+  "name": "ambiguity-detection.golden-prompt-suite.current",
+  "skill": "ambiguity-detection",
+  "description": "Surface blockers, contradictions, and missing decisions before the work moves forward.",
+  "cases": [
+    {
+      "id": "ambiguity-conflict-scan",
+      "prompt": "This request may contain contradictions or hidden assumptions. Find them.",
+      "expectedFirstSkill": "ambiguity-detection",
+      "expectedOutput": [
+        "blockers",
+        "conflicts",
+        "missing decisions"
+      ],
+      "expectedStop": "Do not resolve conflicts without evidence.",
+      "expectedHandoff": "impact-analysis"
+    }
+  ]
+};
+

package/skills/01-discovery/ambiguity-detection/references/README.md

@@ -0,0 +1,17 @@
+# ambiguity-detection References
+
+This directory is local to the skill and is the only reference entry point for this skill.
+
+## Contents
+
+- `../skill-spec.json`: design source for regenerating this skill
+- `prompt-template.md`: reusable prompt wording for this skill
+- `cases.md`: human-readable replay case for this skill
+- `../assets/golden-prompt-suite.current.js`: machine-readable local case fixture
+
+## Guidance
+
+- Keep skill-specific explanation here instead of pushing it into a stage-level shared library.
+- Keep shared hard constraints in `../../../rules/index.md`.
+- Keep canonical names unchanged.
+- Skill summary: Surface blockers, contradictions, and missing decisions before the work moves forward.

package/skills/01-discovery/ambiguity-detection/references/cases.md

@@ -0,0 +1,26 @@
+# ambiguity-detection
+
+## Replay Case
+
+- Case: `ambiguity-conflict-scan`
+- First skill: `ambiguity-detection`
+
+### Prompt
+
+```text
+This request may contain contradictions or hidden assumptions. Find them.
+```
+
+### Expected Output
+
+- blockers
+- conflicts
+- missing decisions
+
+### Stop Rule
+
+- Do not resolve conflicts without evidence.
+
+### Handoff
+
+- impact-analysis

package/skills/01-discovery/ambiguity-detection/references/prompt-template.md

@@ -0,0 +1,18 @@
+# ambiguity-detection
+
+## Prompt Template
+
+```text
+You are handling the ambiguity-detection skill.
+Goal: Surface blockers, contradictions, and missing decisions before the work moves forward
+Inputs: the request, supporting evidence, constraints, and existing repository facts.
+Output contract: blockers, conflicts, missing decisions.
+Stop rule: Do not resolve conflicts without evidence.
+Handoff: impact-analysis.
+Keep the response scoped to this stage and do not absorb the work of the next stage.
+```
+
+## Notes
+
+- Keep the template aligned with the local replay case and local assets.
+- Read `cases.md` for the matching replay example.

package/skills/01-discovery/ambiguity-detection/skill-spec.json

@@ -0,0 +1,26 @@
+{
+  "group": "01-discovery",
+  "name": "ambiguity-detection",
+  "description": "Surface blockers, contradictions, and missing decisions before the work moves forward.",
+  "title": "Ambiguity Detection",
+  "purpose": "Find blockers that prevent the next stage from being safe or deterministic.",
+  "whenToUse": [
+    "The input contains conflicting or underspecified statements.",
+    "You need to surface risks before committing to a plan.",
+    "The same phrase could reasonably mean more than one thing."
+  ],
+  "how": [
+    "Separate facts, assumptions, conflicts, and missing decisions before the work moves forward.",
+    "Name each ambiguity, the decision it blocks, and the question that removes it.",
+    "Classify each item as blocker, risk, or open question.",
+    "Turn every assumption into an explicit decision or an explicit unknown.",
+    "Stop after the blocker list is complete; do not resolve conflicts without evidence."
+  ],
+  "whenToAvoid": [
+    "The request is already routeable and only needs design work.",
+    "The input is already clear enough for implementation.",
+    "You only need wording cleanup or formatting."
+  ],
+  "caseId": "ambiguity-conflict-scan",
+  "source": "bootstrap-from-skill-md"
+}

package/skills/01-discovery/business-analysis/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: business-analysis
+description: Normalize business terms, ownership, and rules into a reusable glossary.
+---
+
+# Business Analysis
+
+## Purpose
+
+Normalize business language into stable terms, ownership boundaries, and decision rules.
+
+## When to Use
+
+- The business logic is unclear.
+- You need to define terms, rules, workflows, or ownership boundaries.
+- Different stakeholders are using different words for the same thing.
+
+## How
+
+- Extract canonical terms, then define each term in one sentence.
+- Map each term to owner, scope, rule, exception, and evidence.
+- Separate user intent, business behavior, and implementation detail.
+- Capture success conditions, exclusions, and exceptions, not just the happy path.
+- Stop once later stages can reuse the glossary and business rules without re-interpretation.
+
+## When to Avoid
+
+- The glossary and business rules are already stable.
+- The request is already technical and needs impact or design work.
+- You only need wording cleanup or formatting.

package/skills/01-discovery/business-analysis/assets/golden-prompt-suite.current.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+module.exports = {
+  "name": "business-analysis.golden-prompt-suite.current",
+  "skill": "business-analysis",
+  "description": "Normalize business terms, ownership, and rules into a reusable glossary.",
+  "cases": [
+    {
+      "id": "analysis-business-terms",
+      "prompt": "This is a business description. Extract the business goal, terms, and boundaries.",
+      "expectedFirstSkill": "business-analysis",
+      "expectedOutput": [
+        "glossary",
+        "business rules",
+        "ownership boundaries"
+      ],
+      "expectedStop": "Do not decide design or implementation details.",
+      "expectedHandoff": "ambiguity-detection"
+    }
+  ]
+};
+

package/skills/01-discovery/business-analysis/references/README.md

@@ -0,0 +1,17 @@
+# business-analysis References
+
+This directory is local to the skill and is the only reference entry point for this skill.
+
+## Contents
+
+- `../skill-spec.json`: design source for regenerating this skill
+- `prompt-template.md`: reusable prompt wording for this skill
+- `cases.md`: human-readable replay case for this skill
+- `../assets/golden-prompt-suite.current.js`: machine-readable local case fixture
+
+## Guidance
+
+- Keep skill-specific explanation here instead of pushing it into a stage-level shared library.
+- Keep shared hard constraints in `../../../rules/index.md`.
+- Keep canonical names unchanged.
+- Skill summary: Normalize business terms, ownership, and rules into a reusable glossary.

package/skills/01-discovery/business-analysis/references/cases.md

@@ -0,0 +1,26 @@
+# business-analysis
+
+## Replay Case
+
+- Case: `analysis-business-terms`
+- First skill: `business-analysis`
+
+### Prompt
+
+```text
+This is a business description. Extract the business goal, terms, and boundaries.
+```
+
+### Expected Output
+
+- glossary
+- business rules
+- ownership boundaries
+
+### Stop Rule
+
+- Do not decide design or implementation details.
+
+### Handoff
+
+- ambiguity-detection