clearctx 3.0.0 → 3.1.0

package/src/mcp-server.js

@@ -48,6 +48,9 @@ const DiffEngine = require('./diff-engine');
 const BriefingGenerator = require('./briefing-generator');
 const DecisionJournal = require('./decision-journal');
 const PatternRegistry = require('./pattern-registry');
+
+// Skills system
+const skillRegistry = require('./skill-registry');
 const StaleDetector = require('./stale-detector');
 
 // Capture version at load time — used to detect stale server processes
@@ -518,6 +521,7 @@ const TOOLS = [
         permission_mode: { type: 'string', enum: ['default', 'acceptEdits', 'bypassPermissions', 'plan'], description: 'Permission mode. Use bypassPermissions to allow sessions to write files without approval (default: bypassPermissions)' },
         team:   { type: 'string', description: 'Team name (default: "default")' },
         work_dir: { type: 'string', description: 'Working directory for the session (default: current directory)' },
+        skills: { type: 'array', items: { type: 'string' }, description: 'Optional expertise skill IDs to inject into worker (e.g., ["postgresql", "nodejs-backend"]). Use skill_detect to auto-match.' }
       },
       required: ['name', 'prompt'],
     },
@@ -1265,6 +1269,45 @@ const TOOLS = [
       },
       required: ['projectPath', 'patternId']
     }
+  },
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // Skills System — expertise domain skills for workers
+  // ══════════════════════════════════════════════════════════════════════════
+
+  {
+    name: 'skill_list',
+    description: 'List all available expertise skills with descriptions, domains, and keywords.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        team: { type: 'string', description: 'Team name (default: "default")' }
+      }
+    }
+  },
+  {
+    name: 'skill_get',
+    description: 'Read a specific expertise skill\'s full content including Worker Context, Conventions, Patterns, and Anti-Patterns.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        skillId: { type: 'string', description: 'Skill ID (e.g., "postgresql", "nodejs-backend", "react-frontend")' },
+        section: { type: 'string', description: 'Optional: extract only a specific section ("worker-context", "conventions", "patterns", "anti-patterns", "integration"). Omit for full content.' }
+      },
+      required: ['skillId']
+    }
+  },
+  {
+    name: 'skill_detect',
+    description: 'Auto-detect which expertise skills are relevant for a given task description. Returns up to 3 matched skills ranked by relevance.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: { type: 'string', description: 'Task description to match skills against' },
+        role: { type: 'string', description: 'Optional worker role for role-based skill matching fallback' }
+      },
+      required: ['task']
+    }
   }
 ];
 
@@ -1539,6 +1582,63 @@ async function executeTool(toolName, args) {
         return textResult(JSON.stringify(result, null, 2));
       }
 
+      // ── Skills System handlers ──
+      case 'skill_list': {
+        const skills = skillRegistry.listSkills();
+        return textResult(JSON.stringify({
+          skills,
+          count: skills.length,
+          message: `${skills.length} expertise skills available. Use skill_get to read full content, or skill_detect to auto-match skills to a task.`
+        }, null, 2));
+      }
+
+      case 'skill_get': {
+        const { skillId, section } = args;
+        const content = skillRegistry.loadSkill(skillId);
+        if (!content) {
+          return errorResult(`Skill "${skillId}" not found. Use skill_list to see available skills.`);
+        }
+        if (section) {
+          // Extract specific section
+          const sectionMap = {
+            'worker-context': '## Worker Context',
+            'conventions': '## Conventions',
+            'patterns': '## Common Patterns',
+            'anti-patterns': '## Anti-Patterns',
+            'integration': '## Integration Notes'
+          };
+          const heading = sectionMap[section];
+          if (!heading) {
+            return errorResult(`Unknown section "${section}". Valid: worker-context, conventions, patterns, anti-patterns, integration`);
+          }
+          const regex = new RegExp(`${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n([\\s\\S]*?)(?=\\n## |$)`);
+          const match = content.match(regex);
+          return textResult(JSON.stringify({
+            skillId,
+            section,
+            content: match ? match[1].trim() : 'Section not found in skill.'
+          }, null, 2));
+        }
+        return textResult(JSON.stringify({ skillId, content }, null, 2));
+      }
+
+      case 'skill_detect': {
+        const { task, role } = args;
+        const detected = skillRegistry.detectSkills(task, role);
+        const skills = detected.map(id => {
+          const all = skillRegistry.listSkills();
+          const skill = all.find(s => s.id === id);
+          return skill || { id, description: 'Unknown skill' };
+        });
+        return textResult(JSON.stringify({
+          detected: skills,
+          count: skills.length,
+          message: skills.length > 0
+            ? `Detected ${skills.length} relevant skill(s): ${detected.join(', ')}. Use team_spawn with skills parameter to inject into workers.`
+            : 'No skills matched. Provide more detail or assign skills manually.'
+        }, null, 2));
+      }
+
       default:
         return errorResult(`Unknown tool: ${toolName}`);
     }
@@ -1935,7 +2035,27 @@ async function handleTeamSpawn(args) {
     const roster = teamHub.getRoster();
 
     // Build team system prompt (now includes role-specific guidance, examples, anti-patterns)
-    const teamSystemPrompt = buildTeamSystemPrompt(args.name, args.role, args.task, roster, teamName);
+    let teamSystemPrompt = buildTeamSystemPrompt(args.name, args.role, args.task, roster, teamName);
+
+    // Role-based skill fallback (only if skills param not provided at all)
+    // Explicitly passing skills: [] opts out of auto-injection
+    if (args.skills === undefined && args.role) {
+      const roleSkills = skillRegistry.getSkillsForRole(args.role);
+      if (roleSkills.length > 0) {
+        args.skills = roleSkills;
+        // Log that we auto-detected
+        log({ event: 'skill_auto_detect', worker: args.name, role: args.role, detected: roleSkills });
+      }
+    }
+
+    // Inject expertise skills if provided
+    if (args.skills && Array.isArray(args.skills) && args.skills.length > 0) {
+      const skillsContext = skillRegistry.getWorkerContext(args.skills);
+      if (skillsContext) {
+        teamSystemPrompt += '\n\n## EXPERTISE SKILLS\n\nThe following domain expertise has been assigned to you. Follow these patterns and conventions:\n\n' + skillsContext;
+        log({ event: 'skills_injected', worker: args.name, skills: args.skills });
+      }
+    }
 
     // Spawn the session with team system prompt appended
     // Default to bypassPermissions so team sessions can write files without manual approval
@@ -1969,6 +2089,11 @@ async function handleTeamSpawn(args) {
       result.turns = response.turns;
     }
 
+    // Add skill info if skills were injected
+    if (args.skills && args.skills.length > 0) {
+      result._skills_injected = args.skills;
+    }
+
     // Auto version check on first spawn
     const staleness = getCachedStalenessWarning();
     if (staleness) {

package/src/prompts.js

@@ -687,6 +687,10 @@ When all workers are done:
 | Quick one-off task | \`delegate_task\` | \`team_spawn\` |
 | Need safety limits (cost/turns) | \`delegate_task\` | \`team_spawn\` |
 | Verify phase completion | \`phase_gate\` |
+| Auto-detect skills for a task | \`skill_detect\` |
+| List available skills | \`skill_list\` |
+| Read a skill's content | \`skill_get\` |
+| Spawn worker with skills | \`team_spawn\` with \`skills\` parameter |
 | Clean up between runs | \`team_reset\` |
 
 ## WHAT GOES WRONG (And How to Avoid It)
@@ -786,6 +790,33 @@ When done:
 6. Publish your output as an artifact with artifact_publish
 7. Broadcast completion with team_broadcast
 8. Update your status to idle"
+
+### Rule 8: Use expertise skills for domain work
+
+When spawning workers, assign relevant expertise skills to improve output quality:
+
+1. Call \`skill_detect\` with the task description to auto-match skills
+2. Pass matched skills to \`team_spawn\` via the \`skills\` parameter:
+   \`\`\`
+   team_spawn({
+     name: "db-dev",
+     role: "database",
+     skills: ["postgresql"],
+     prompt: "Create the database schema..."
+   })
+   \`\`\`
+3. Override auto-detection with explicit skills when you know better
+4. Workers with skills produce higher-quality, convention-compliant output
+5. Available skills: postgresql, nodejs-backend, react-frontend, testing-qa, api-design, devops, security, typescript
+
+**Role-based fallback:** If you don't specify skills but provide a role, the system auto-detects relevant skills:
+- database → postgresql
+- backend → nodejs-backend, api-design
+- frontend → react-frontend
+- QA/testing → testing-qa
+- devops → devops
+- security → security
+- fullstack → nodejs-backend, react-frontend, typescript
 `;
 }
 
@@ -931,11 +962,25 @@ function getRolePrompt(role) {
  * @param {string} opts.teamName   — Team name
  * @returns {string} Complete system prompt
  */
-function buildFullTeamPrompt({ name, role, task, roster, teamName }) {
+function buildFullTeamPrompt({ name, role, task, roster, teamName, skills }) {
   const basePrompt = buildTeamWorkerPrompt(name, role, task, roster, teamName);
   const rolePrompt = getRolePrompt(role);
 
-  return basePrompt + rolePrompt;
+  // Inject expertise skills if provided
+  let skillsPrompt = '';
+  if (skills && skills.length > 0) {
+    try {
+      const skillRegistry = require('./skill-registry');
+      const context = skillRegistry.getWorkerContext(skills);
+      if (context) {
+        skillsPrompt = '\n\n## DOMAIN EXPERTISE\n\nYou have been assigned the following expertise skills. Follow these patterns, conventions, and anti-patterns strictly:\n\n' + context + '\n';
+      }
+    } catch (e) {
+      // Skills not available — degrade gracefully
+    }
+  }
+
+  return basePrompt + skillsPrompt + rolePrompt;
 }
 
 

package/src/skill-registry.js

@@ -0,0 +1,182 @@
+const fs = require('fs');
+const path = require('path');
+
+// Cache for manifest
+let manifestCache = null;
+
+// Skills directory path (relative to this module)
+const SKILLS_DIR = path.join(__dirname, '..', 'skills');
+
+// Keyword triggers for skill detection
+const SKILL_TRIGGERS = {
+  'postgresql': ['postgres', 'postgresql', 'pg', 'database', 'schema', 'migration', 'sql', 'db'],
+  'nodejs-backend': ['node', 'express', 'backend', 'server', 'api', 'rest', 'endpoint', 'middleware'],
+  'react-frontend': ['react', 'frontend', 'component', 'ui', 'jsx', 'tsx', 'hook', 'state'],
+  'testing-qa': ['test', 'testing', 'qa', 'jest', 'mocha', 'integration', 'unit test', 'e2e'],
+  'api-design': ['api', 'rest', 'endpoint', 'openapi', 'swagger', 'route', 'pagination'],
+  'devops': ['docker', 'ci/cd', 'deploy', 'pipeline', 'kubernetes', 'nginx', 'devops'],
+  'security': ['auth', 'security', 'jwt', 'oauth', 'encryption', 'owasp', 'xss', 'csrf'],
+  'typescript': ['typescript', 'ts', 'type', 'interface', 'generic', 'typed']
+};
+
+// Role-based skill mapping (keys should be lowercase for case-insensitive lookup)
+const ROLE_SKILLS = {
+  'database': ['postgresql'],
+  'backend': ['nodejs-backend', 'api-design'],
+  'frontend': ['react-frontend'],
+  'qa': ['testing-qa'],
+  'testing': ['testing-qa'],
+  'fullstack': ['nodejs-backend', 'react-frontend', 'typescript'],
+  'devops': ['devops'],
+  'security': ['security']
+};
+
+/**
+ * Load the skills manifest (cached)
+ * @returns {Object} The manifest object
+ */
+function loadManifest() {
+  if (manifestCache) {
+    return manifestCache;
+  }
+
+  const manifestPath = path.join(SKILLS_DIR, 'index.json');
+  const manifestData = fs.readFileSync(manifestPath, 'utf8');
+  manifestCache = JSON.parse(manifestData);
+  return manifestCache;
+}
+
+/**
+ * List all available skills
+ * @returns {Array} Array of skill objects from manifest
+ */
+function listSkills() {
+  const manifest = loadManifest();
+  return manifest.skills;
+}
+
+/**
+ * Load a specific skill's full content
+ * @param {string} skillId - The skill ID (e.g., 'postgresql')
+ * @returns {string|null} The full SKILL.md content, or null if not found
+ */
+function loadSkill(skillId) {
+  const manifest = loadManifest();
+  const skill = manifest.skills.find(s => s.id === skillId);
+
+  if (!skill) {
+    return null;
+  }
+
+  const skillPath = path.join(SKILLS_DIR, skillId, 'SKILL.md');
+
+  if (!fs.existsSync(skillPath)) {
+    return null;
+  }
+
+  return fs.readFileSync(skillPath, 'utf8');
+}
+
+/**
+ * Detect relevant skills from task description
+ * @param {string} taskDescription - The task text to analyze
+ * @returns {Array<string>} Up to 3 skill IDs ranked by relevance
+ */
+function detectSkills(taskDescription) {
+  const lowerTask = taskDescription.toLowerCase();
+  const skillScores = {};
+
+  // Initialize scores
+  Object.keys(SKILL_TRIGGERS).forEach(skillId => {
+    skillScores[skillId] = 0;
+  });
+
+  // Check keyword matches
+  Object.entries(SKILL_TRIGGERS).forEach(([skillId, keywords]) => {
+    keywords.forEach(keyword => {
+      if (lowerTask.includes(keyword.toLowerCase())) {
+        skillScores[skillId]++;
+      }
+    });
+  });
+
+  // Check role matches
+  Object.entries(ROLE_SKILLS).forEach(([role, skillIds]) => {
+    if (lowerTask.includes(role.toLowerCase())) {
+      skillIds.forEach(skillId => {
+        skillScores[skillId] += 2; // Role matches get higher weight
+      });
+    }
+  });
+
+  // Sort by score and return top 3
+  const rankedSkills = Object.entries(skillScores)
+    .filter(([_, score]) => score > 0)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([skillId, _]) => skillId);
+
+  return rankedSkills;
+}
+
+/**
+ * Extract Worker Context sections from multiple skills
+ * @param {Array<string>} skillIds - Array of skill IDs to load
+ * @returns {string} Concatenated worker context content with headers
+ */
+function getWorkerContext(skillIds) {
+  if (!Array.isArray(skillIds) || skillIds.length === 0) {
+    return '';
+  }
+
+  const manifest = loadManifest();
+  const contexts = [];
+
+  skillIds.forEach(skillId => {
+    const skill = manifest.skills.find(s => s.id === skillId);
+    if (!skill) {
+      return;
+    }
+
+    const skillContent = loadSkill(skillId);
+    if (!skillContent) {
+      return;
+    }
+
+    // Extract ONLY the "## Worker Context" section (not the full SKILL.md)
+    // This keeps injected content small enough for Windows CLI arg limits
+    const lines = skillContent.split(/\r?\n/);
+    const workerIdx = lines.findIndex(l => l.trim() === '## Worker Context');
+
+    if (workerIdx !== -1) {
+      const nextHeaderIdx = lines.slice(workerIdx + 1).findIndex(l => /^## /.test(l));
+      const endIdx = nextHeaderIdx !== -1 ? workerIdx + 1 + nextHeaderIdx : lines.length;
+      const contextContent = lines.slice(workerIdx + 1, endIdx).join('\n').trim();
+
+      if (contextContent) {
+        const skillName = skill.description.split(' — ')[0] || skill.description.split(',')[0];
+        contexts.push(`### ${skillName}\n${contextContent}`);
+      }
+    }
+  });
+
+  return contexts.join('\n\n');
+}
+
+/**
+ * Get skills for a given role using ROLE_SKILLS mapping
+ * @param {string} role - The worker role (case-insensitive)
+ * @returns {Array<string>} Skill IDs for the role, or empty array if no match
+ */
+function getSkillsForRole(role) {
+  if (!role) return [];
+  return ROLE_SKILLS[role.toLowerCase()] || [];
+}
+
+module.exports = {
+  listSkills,
+  loadSkill,
+  detectSkills,
+  getSkillsForRole,
+  getWorkerContext
+};

package/src/stream-session.js

@@ -30,6 +30,9 @@
 
 const { spawn } = require('child_process');
 const { EventEmitter } = require('events');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
 
 // How many milliseconds to wait for a response before timing out
 const DEFAULT_TIMEOUT = 600000; // 10 minutes
@@ -219,6 +222,7 @@ class StreamSession extends EventEmitter {
         this.process.stdin.end();
       }
     }
+    this._cleanupSystemPromptFile();
   }
 
   /**
@@ -229,6 +233,7 @@ class StreamSession extends EventEmitter {
       this.status = 'stopped';
       this.process.kill('SIGTERM');
     }
+    this._cleanupSystemPromptFile();
   }
 
   /**
@@ -272,6 +277,16 @@ class StreamSession extends EventEmitter {
   // Private methods
   // ===========================================================================
 
+  /**
+   * Clean up the temp system prompt file if one was created.
+   */
+  _cleanupSystemPromptFile() {
+    if (this._systemPromptFile) {
+      try { fs.unlinkSync(this._systemPromptFile); } catch (_) {}
+      this._systemPromptFile = null;
+    }
+  }
+
   /**
    * Build claude CLI arguments for stream-json mode.
    */
@@ -299,9 +314,14 @@ class StreamSession extends EventEmitter {
       args.push('--allowedTools', ...this.allowedTools);
     }
 
-    // System prompt
+    // System prompt — write to temp file to avoid Windows ENAMETOOLONG on long prompts
     if (this.systemPrompt) {
-      args.push('--append-system-prompt', this.systemPrompt);
+      const tmpDir = path.join(os.tmpdir(), 'clearctx');
+      fs.mkdirSync(tmpDir, { recursive: true });
+      const tmpFile = path.join(tmpDir, `sysprompt-${this.name}-${Date.now()}.md`);
+      fs.writeFileSync(tmpFile, this.systemPrompt, 'utf8');
+      this._systemPromptFile = tmpFile;
+      args.push('--append-system-prompt-file', tmpFile);
     }
 
     // Budget limit