@cleocode/skills 2.0.0

package/index.js

@@ -0,0 +1,405 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const LIBRARY_ROOT = __dirname;
+const SKILLS_ROOT = path.join(LIBRARY_ROOT, 'skills');
+const PROFILES_ROOT = path.join(LIBRARY_ROOT, 'profiles');
+const PROTOCOLS_ROOT = path.join(LIBRARY_ROOT, '..', '..', 'src', 'protocols');
+const SHARED_ROOT = path.join(SKILLS_ROOT, '_shared');
+
+// --- Package metadata ---
+
+/** Package version from package.json */
+const version = require('./package.json').version;
+
+/** Absolute path to the package root directory */
+const libraryRoot = LIBRARY_ROOT;
+
+// --- Core data ---
+
+/** Parsed skills.json index */
+const skillsIndex = JSON.parse(
+  fs.readFileSync(path.join(LIBRARY_ROOT, 'skills.json'), 'utf8')
+);
+
+/** Parsed manifest.json dispatch registry */
+const manifest = JSON.parse(
+  fs.readFileSync(path.join(SKILLS_ROOT, 'manifest.json'), 'utf8')
+);
+
+/** Parsed _shared/placeholders.json */
+const shared = JSON.parse(
+  fs.readFileSync(path.join(SHARED_ROOT, 'placeholders.json'), 'utf8')
+);
+
+/** All skill entries from skills.json */
+const skills = skillsIndex.skills;
+
+// --- Existing API (preserved) ---
+
+/**
+ * List all skill names.
+ * @returns {string[]}
+ */
+function listSkills() {
+  return skills.map(s => s.name);
+}
+
+/**
+ * Get skill metadata from skills.json by name.
+ * @param {string} name - Skill name (e.g. "ct-research-agent")
+ * @returns {object|undefined}
+ */
+function getSkill(name) {
+  return skills.find(s => s.name === name);
+}
+
+/**
+ * Resolve absolute path to a skill's SKILL.md file.
+ * @param {string} name - Skill name
+ * @returns {string}
+ */
+function getSkillPath(name) {
+  return path.join(SKILLS_ROOT, name, 'SKILL.md');
+}
+
+/**
+ * Resolve absolute path to a skill's directory.
+ * @param {string} name - Skill name
+ * @returns {string}
+ */
+function getSkillDir(name) {
+  return path.join(SKILLS_ROOT, name);
+}
+
+/**
+ * Get the dispatch matrix from manifest.json.
+ * @returns {object}
+ */
+function getDispatchMatrix() {
+  return manifest.dispatch_matrix;
+}
+
+/**
+ * Read a skill's SKILL.md content as a string.
+ * @param {string} name - Skill name
+ * @returns {string}
+ */
+function readSkillContent(name) {
+  return fs.readFileSync(getSkillPath(name), 'utf8');
+}
+
+// --- New: Core & Dependency awareness ---
+
+/**
+ * Get all skills marked as core.
+ * @returns {object[]} SkillEntry[] where core === true
+ */
+function getCoreSkills() {
+  return skills.filter(s => s.core === true);
+}
+
+/**
+ * Get skills filtered by category.
+ * @param {string} category - One of: core, recommended, specialist, composition, meta
+ * @returns {object[]}
+ */
+function getSkillsByCategory(category) {
+  return skills.filter(s => s.category === category);
+}
+
+/**
+ * Get direct dependency names for a skill.
+ * @param {string} name - Skill name
+ * @returns {string[]}
+ */
+function getSkillDependencies(name) {
+  const skill = getSkill(name);
+  if (!skill) return [];
+  return skill.dependencies || [];
+}
+
+/**
+ * Resolve the full dependency tree for a set of skill names.
+ * Returns deduplicated list with transitive deps. _shared is always included conceptually.
+ * @param {string[]} names - Initial skill names
+ * @returns {string[]} Full list of skills including transitive dependencies
+ */
+function resolveDependencyTree(names) {
+  const resolved = new Set();
+  const queue = [...names];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (resolved.has(current)) continue;
+    resolved.add(current);
+
+    const deps = getSkillDependencies(current);
+    for (const dep of deps) {
+      if (!resolved.has(dep)) {
+        queue.push(dep);
+      }
+    }
+  }
+
+  return Array.from(resolved);
+}
+
+// --- New: Profile-based selection ---
+
+/** Cache for loaded profile definitions */
+const _profileCache = new Map();
+
+/**
+ * List available profile names.
+ * @returns {string[]}
+ */
+function listProfiles() {
+  if (!fs.existsSync(PROFILES_ROOT)) return [];
+  return fs.readdirSync(PROFILES_ROOT)
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace('.json', ''));
+}
+
+/**
+ * Get a profile definition by name.
+ * @param {string} name - Profile name (e.g. "minimal", "core", "recommended", "full")
+ * @returns {object|undefined}
+ */
+function getProfile(name) {
+  if (_profileCache.has(name)) return _profileCache.get(name);
+
+  const filePath = path.join(PROFILES_ROOT, `${name}.json`);
+  if (!fs.existsSync(filePath)) return undefined;
+
+  const profile = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  _profileCache.set(name, profile);
+  return profile;
+}
+
+/**
+ * Resolve a profile to its full skill list, following extends chains
+ * and resolving transitive skill dependencies.
+ * @param {string} name - Profile name
+ * @returns {string[]} Full deduplicated skill list
+ */
+function resolveProfile(name) {
+  const allSkills = new Set();
+  const visited = new Set();
+
+  // Walk the extends chain
+  let current = name;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const profile = getProfile(current);
+    if (!profile) break;
+
+    for (const skill of profile.skills) {
+      allSkills.add(skill);
+    }
+    current = profile.extends || null;
+  }
+
+  // Resolve transitive dependencies
+  return resolveDependencyTree(Array.from(allSkills));
+}
+
+// --- New: Shared resources ---
+
+/**
+ * List available shared resource names (files in _shared/).
+ * @returns {string[]}
+ */
+function listSharedResources() {
+  if (!fs.existsSync(SHARED_ROOT)) return [];
+  return fs.readdirSync(SHARED_ROOT)
+    .filter(f => !f.startsWith('.'))
+    .map(f => f.replace(/\.[^.]+$/, ''));
+}
+
+/**
+ * Get absolute path to a shared resource file.
+ * @param {string} name - Resource name (without extension, e.g. "subagent-protocol-base")
+ * @returns {string|undefined}
+ */
+function getSharedResourcePath(name) {
+  if (!fs.existsSync(SHARED_ROOT)) return undefined;
+  const files = fs.readdirSync(SHARED_ROOT);
+  const match = files.find(f => f.replace(/\.[^.]+$/, '') === name);
+  return match ? path.join(SHARED_ROOT, match) : undefined;
+}
+
+/**
+ * Read a shared resource file content.
+ * @param {string} name - Resource name (without extension)
+ * @returns {string|undefined}
+ */
+function readSharedResource(name) {
+  const filePath = getSharedResourcePath(name);
+  if (!filePath || !fs.existsSync(filePath)) return undefined;
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+// --- New: Protocols ---
+
+/**
+ * List available protocol names.
+ * @returns {string[]}
+ */
+function listProtocols() {
+  if (!fs.existsSync(PROTOCOLS_ROOT)) return [];
+  return fs.readdirSync(PROTOCOLS_ROOT)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace('.md', ''));
+}
+
+/**
+ * Get absolute path to a protocol file.
+ * @param {string} name - Protocol name (e.g. "research", "implementation")
+ * @returns {string|undefined}
+ */
+function getProtocolPath(name) {
+  const filePath = path.join(PROTOCOLS_ROOT, `${name}.md`);
+  return fs.existsSync(filePath) ? filePath : undefined;
+}
+
+/**
+ * Read a protocol file content.
+ * @param {string} name - Protocol name
+ * @returns {string|undefined}
+ */
+function readProtocol(name) {
+  const filePath = getProtocolPath(name);
+  if (!filePath) return undefined;
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+// --- New: Validation ---
+
+const VALID_CATEGORIES = ['core', 'recommended', 'specialist', 'composition', 'meta'];
+
+/**
+ * Validate a skill's frontmatter fields.
+ * @param {string} name - Skill name
+ * @returns {{ valid: boolean, issues: { level: string, field: string, message: string }[] }}
+ */
+function validateSkillFrontmatter(name) {
+  const skill = getSkill(name);
+  const issues = [];
+
+  if (!skill) {
+    return { valid: false, issues: [{ level: 'error', field: 'name', message: `Skill '${name}' not found` }] };
+  }
+
+  // Required fields
+  if (!skill.name) issues.push({ level: 'error', field: 'name', message: 'Missing name' });
+  if (!skill.description) issues.push({ level: 'error', field: 'description', message: 'Missing description' });
+
+  // Version format
+  if (!skill.version) {
+    issues.push({ level: 'warn', field: 'version', message: 'Missing version' });
+  } else if (!/^\d+\.\d+\.\d+$/.test(skill.version)) {
+    issues.push({ level: 'warn', field: 'version', message: `Invalid semver: ${skill.version}` });
+  }
+
+  // Category validation
+  if (skill.category && !VALID_CATEGORIES.includes(skill.category)) {
+    issues.push({ level: 'error', field: 'category', message: `Invalid category '${skill.category}', must be one of: ${VALID_CATEGORIES.join(', ')}` });
+  }
+
+  // Core must be boolean
+  if (skill.core !== undefined && typeof skill.core !== 'boolean') {
+    issues.push({ level: 'error', field: 'core', message: `core must be boolean, got ${typeof skill.core}` });
+  }
+
+  // Tier must be 0-3
+  if (skill.tier !== undefined && (typeof skill.tier !== 'number' || skill.tier < 0 || skill.tier > 3)) {
+    issues.push({ level: 'warn', field: 'tier', message: `Tier should be 0-3, got ${skill.tier}` });
+  }
+
+  // Dependencies must reference valid skills
+  if (Array.isArray(skill.dependencies)) {
+    const allNames = listSkills();
+    for (const dep of skill.dependencies) {
+      if (!allNames.includes(dep)) {
+        issues.push({ level: 'error', field: 'dependencies', message: `Unknown dependency: ${dep}` });
+      }
+    }
+  }
+
+  // Protocol should reference an existing protocol file
+  if (skill.protocol && skill.protocol !== 'null') {
+    const protoPath = getProtocolPath(skill.protocol);
+    if (!protoPath) {
+      issues.push({ level: 'warn', field: 'protocol', message: `Protocol file not found: ${skill.protocol}.md` });
+    }
+  }
+
+  // Description length
+  if (skill.description && skill.description.length > 1024) {
+    issues.push({ level: 'error', field: 'description', message: `Description too long: ${skill.description.length} chars (max 1024)` });
+  }
+
+  return {
+    valid: issues.filter(i => i.level === 'error').length === 0,
+    issues
+  };
+}
+
+/**
+ * Validate all skills.
+ * @returns {Map<string, { valid: boolean, issues: { level: string, field: string, message: string }[] }>}
+ */
+function validateAll() {
+  const results = new Map();
+  for (const name of listSkills()) {
+    results.set(name, validateSkillFrontmatter(name));
+  }
+  return results;
+}
+
+// --- Exports ---
+
+module.exports = {
+  // Existing (preserved)
+  skills,
+  manifest,
+  shared,
+  listSkills,
+  getSkill,
+  getSkillPath,
+  getSkillDir,
+  getDispatchMatrix,
+  readSkillContent,
+
+  // New: Core & Dependency awareness
+  getCoreSkills,
+  getSkillsByCategory,
+  getSkillDependencies,
+  resolveDependencyTree,
+
+  // New: Profile-based selection
+  listProfiles,
+  getProfile,
+  resolveProfile,
+
+  // New: Shared resources
+  listSharedResources,
+  getSharedResourcePath,
+  readSharedResource,
+
+  // New: Protocols
+  listProtocols,
+  getProtocolPath,
+  readProtocol,
+
+  // New: Validation
+  validateSkillFrontmatter,
+  validateAll,
+
+  // New: Package metadata
+  version,
+  libraryRoot,
+};

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@cleocode/skills",
+  "version": "2.0.0",
+  "description": "CLEO skill definitions - bundled with CLEO monorepo",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "skills",
+    "profiles",
+    "*.json",
+    "*.js",
+    "*.d.ts"
+  ]
+}

package/profiles/core.json

@@ -0,0 +1,7 @@
+{
+  "name": "core",
+  "description": "Orchestration and LOOM (RCASD-IVTR+C) pipeline awareness",
+  "extends": "minimal",
+  "skills": ["ct-orchestrator", "loom"],
+  "includeProtocols": ["agent-protocol"]
+}

package/profiles/full.json

@@ -0,0 +1,10 @@
+{
+  "name": "full",
+  "description": "All skills including execution, documentation, quality, and meta",
+  "extends": "recommended",
+  "skills": [
+    "ct-dev-workflow", "ct-documentor", "ct-docs-lookup", "ct-docs-write", "ct-docs-review",
+    "ct-contribution", "ct-grade", "ct-skill-creator"
+  ],
+  "includeProtocols": ["implementation", "contribution", "release", "testing", "artifact-publish", "provenance"]
+}

package/profiles/minimal.json

@@ -0,0 +1,7 @@
+{
+  "name": "minimal",
+  "description": "Solo task execution with core CLEO protocol — no orchestration needed",
+  "skills": ["ct-cleo", "ct-task-executor"],
+  "includeShared": true,
+  "includeProtocols": []
+}

package/profiles/recommended.json

@@ -0,0 +1,7 @@
+{
+  "name": "recommended",
+  "description": "Full LOOM (RCASD-IVTR+C pipeline) skills for epic-driven development",
+  "extends": "core",
+  "skills": ["ct-epic-architect", "ct-research-agent", "ct-spec-writer", "ct-validator", "loom"],
+  "includeProtocols": ["research", "consensus", "specification", "decomposition", "validation", "adr"]
+}

package/provider-skills-map.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://lafs.dev/schemas/v1/provider-skills-map.schema.json",
+  "version": "1.0.0",
+  "description": "Provider skill path discovery and precedence rules for CLEO skill deployment",
+  "providers": {
+    "claude-code": {
+      "globalSkills": "$HOME/.claude/skills",
+      "projectSkills": ".claude/skills",
+      "agentsGlobal": null,
+      "agentsProject": null,
+      "readsFromDotAgents": false,
+      "precedence": "vendor-only",
+      "symlinkSupported": true,
+      "notes": "Created Agent Skills standard but uses vendor path exclusively"
+    },
+    "codex-cli": {
+      "globalSkills": "$HOME/.agents/skills",
+      "projectSkills": ".agents/skills",
+      "agentsGlobal": "$HOME/.agents/skills",
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": true,
+      "precedence": "agents-canonical",
+      "symlinkSupported": true,
+      "notes": "Uses .agents/skills as canonical location"
+    },
+    "gemini-cli": {
+      "globalSkills": "$HOME/.gemini/skills",
+      "projectSkills": ".gemini/skills",
+      "agentsGlobal": "$HOME/.agents/skills",
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": true,
+      "precedence": "agents-first",
+      "symlinkSupported": true,
+      "notes": ".agents/skills takes precedence over .gemini/skills within same tier"
+    },
+    "cursor": {
+      "globalSkills": "$HOME/.cursor/skills",
+      "projectSkills": ".cursor/skills",
+      "agentsGlobal": null,
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": "project-only",
+      "precedence": "vendor-global-agents-project",
+      "symlinkSupported": true,
+      "notes": "Global uses vendor path; project supports .agents/skills"
+    },
+    "github-copilot": {
+      "globalSkills": "$HOME/.copilot/skills",
+      "projectSkills": ".github/skills",
+      "agentsGlobal": "$HOME/.agents/skills",
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": true,
+      "precedence": "agents-supported",
+      "symlinkSupported": true,
+      "notes": "Supports both vendor and .agents paths at all levels"
+    },
+    "windsurf": {
+      "globalSkills": "$HOME/.codeium/windsurf/skills",
+      "projectSkills": ".windsurf/skills",
+      "agentsGlobal": null,
+      "agentsProject": null,
+      "readsFromDotAgents": false,
+      "precedence": "vendor-only",
+      "symlinkSupported": false,
+      "notes": "Vendor-specific paths only, no .agents support"
+    },
+    "opencode": {
+      "globalSkills": "$HOME/.config/opencode/skills",
+      "projectSkills": ".opencode/skills",
+      "agentsGlobal": "$HOME/.agents/skills",
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": true,
+      "precedence": "agents-supported",
+      "symlinkSupported": true,
+      "notes": "User confirms .agents/ support; verify via opencode docs"
+    },
+    "kimi-coding": {
+      "globalSkills": "$HOME/.kimi/skills",
+      "projectSkills": ".kimi/skills",
+      "agentsGlobal": null,
+      "agentsProject": null,
+      "readsFromDotAgents": false,
+      "precedence": "vendor-only",
+      "symlinkSupported": false,
+      "notes": "Model-based provider; skill path support uncertain"
+    },
+    "antigravity": {
+      "globalSkills": "$HOME/.antigravity/skills",
+      "projectSkills": ".agent/skills",
+      "agentsGlobal": null,
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": "project-only",
+      "precedence": "vendor-global-agents-project",
+      "symlinkSupported": true,
+      "notes": "Project-level .agents/skills confirmed in Google codelabs"
+    }
+  }
+}

package/skills/_shared/cleo-style-guide.md

@@ -0,0 +1,84 @@
+# CLEO Writing Style Guide
+
+## Core Principles
+
+Write like you're talking to a colleague. Be conversational, not formal. Get people what they need quickly. Know your audience and match the complexity.
+
+## Tone and Voice
+
+**Do:**
+
+- Use contractions ("can't" not "cannot")
+- Say "people" or "companies" instead of "users"
+- Be friendly but not peppy
+- Acknowledge limitations honestly ("that's on us, not them")
+- Jokes and Easter eggs are okay (permit them, don't suggest them)
+
+**Don't:**
+
+- Use exclamation points excessively
+- Rely on tired tropes about nerdiness
+- Use corporate jargon ("utilize", "offerings", "actionable insights")
+- Tell people something is cool (show them instead)
+
+## Structure and Clarity
+
+**Lead with the important stuff:**
+
+- Most important information first
+- Lead with the ask, then provide context
+- Cut text that adds little value (when in doubt, cut it)
+- Each paragraph should have one clear purpose
+
+**Make headings do the work:**
+
+- Convey your actual point, not just the topic
+- "Use headings to highlight key points" not "How to write a good heading"
+- Use sentence case, no punctuation except question marks
+- No links in headings unless entire heading is a link
+
+## Instructions and Examples
+
+**Tell people what to do:**
+
+- Give the action before explaining why
+- Put commands in execution order
+- Provide context, steps, and reasoning
+- Don't describe tasks as "easy" or "simple"
+
+**Answer unasked questions:**
+
+- Include answers to "dumb" questions you had when learning
+- Don't literally include the question, just give the answer
+
+## Formatting
+
+**Code vs. UI elements:**
+
+- Backticks for code, variable names, parameters only
+- **Bold** for UI elements and labels (e.g., "Click the **Save** button")
+- Don't use backticks or quotes for UI elements
+
+## Writing Mechanics
+
+- Limit pronouns when introducing new terms (repeat the term to reinforce it)
+- Ampersands only in proper nouns, never as substitute for "and"
+
+## Terminology Preferences
+
+Use familiar terms from tools people already know:
+
+- "Summarize" (like Excel) instead of "aggregate"
+- "Take a look at" instead of "reference"
+- "Filter" instead of technical database terms when appropriate
+
+## Red Flags
+
+Avoid these patterns:
+
+- Multiple exclamation points
+- Linking "here"
+- Bullet lists to explain (use prose)
+- Numbers that will change (guard against change)
+- Describing things as "easy" or "simple"
+- Stock photography-worthy content