@codihaus/claude-skills 1.6.19 → 1.6.21

package/skills/dev-coding/SKILL.md

@@ -73,6 +73,12 @@ You have three layers of knowledge to apply:
 - "Nuxt" → `knowledge/stacks/nuxt/_index.md`
 - "Directus" → `knowledge/stacks/directus/_index.md`
 
+**Deep knowledge loading (for complex features):**
+- First read `knowledge/_knowledge.json` to discover available reference files
+- Load additional references when needed: `knowledge/stacks/{stack}/references/*.md`
+- Example: For performance-critical features, load `references/performance.md`
+- Example: For complex patterns, load `references/patterns.md`
+
 **If you skip this step**, you'll implement using generic patterns instead of framework-specific best practices (e.g., using fetch instead of Server Actions in Next.js).
 
 ## Expected Outcome

package/src/commands/init.js

@@ -186,17 +186,22 @@ export async function init(options) {
   const knowledgeSpinner = ora('Installing knowledge base...').start();
 
   try {
-    const { copied: knowledgeCopied, errors: knowledgeErrors } = await copyKnowledgeToProject(projectPath);
+    const { copied: knowledgeCopied, errors: knowledgeErrors } = await copyKnowledgeToProject(
+      projectPath,
+      options.knowledge  // Custom knowledge path if provided
+    );
 
     if (knowledgeErrors.length > 0) {
       knowledgeSpinner.warn(`Installed ${knowledgeCopied.length} knowledge folders with ${knowledgeErrors.length} errors`);
     } else if (knowledgeCopied.length > 0) {
-      knowledgeSpinner.succeed(`Installed knowledge: ${knowledgeCopied.join(', ')}`);
+      const source = options.knowledge ? ` from ${options.knowledge}` : '';
+      knowledgeSpinner.succeed(`Installed knowledge${source}: ${knowledgeCopied.join(', ')}`);
     } else {
       knowledgeSpinner.info('No knowledge to install');
     }
   } catch (e) {
     knowledgeSpinner.warn('Failed to install knowledge');
+    console.error(chalk.gray(`  ${e.message}`));
   }
 
   // Step 6: Copy scripts (graph.py, etc.)

package/src/utils/skills.js

@@ -272,13 +272,24 @@ export async function checkForUpdates(projectPath) {
 
 /**
  * Copy knowledge (stacks, domains) to project
+ * @param {string} projectPath - Target project path
+ * @param {string} customSource - Optional custom knowledge source path
  */
-export async function copyKnowledgeToProject(projectPath) {
+export async function copyKnowledgeToProject(projectPath, customSource = null) {
   const targetPath = path.join(projectPath, '.claude', 'knowledge');
+  const sourcePath = customSource
+    ? path.resolve(customSource)
+    : KNOWLEDGE_SOURCE;
 
   // Check if source exists
-  if (!await fs.pathExists(KNOWLEDGE_SOURCE)) {
-    return { copied: [], errors: [{ name: 'knowledge', error: 'Source not found' }] };
+  if (!await fs.pathExists(sourcePath)) {
+    return {
+      copied: [],
+      errors: [{
+        name: 'knowledge',
+        error: `Source not found: ${sourcePath}`
+      }]
+    };
   }
 
   // Remove existing and copy fresh
@@ -289,22 +300,27 @@ export async function copyKnowledgeToProject(projectPath) {
   const errors = [];
 
   try {
-    const items = await fs.readdir(KNOWLEDGE_SOURCE);
+    const items = await fs.readdir(sourcePath);
 
     for (const item of items) {
       // Skip hidden files
       if (item.startsWith('.')) continue;
 
-      const sourcePath = path.join(KNOWLEDGE_SOURCE, item);
+      const itemSourcePath = path.join(sourcePath, item);
       const targetItemPath = path.join(targetPath, item);
 
       try {
-        await fs.copy(sourcePath, targetItemPath);
+        await fs.copy(itemSourcePath, targetItemPath);
         copied.push(item);
       } catch (e) {
         errors.push({ name: item, error: e.message });
       }
     }
+
+    // Generate knowledge declaration file
+    if (copied.length > 0) {
+      await generateKnowledgeDeclare(targetPath);
+    }
   } catch (e) {
     errors.push({ name: 'knowledge', error: e.message });
   }
@@ -312,6 +328,137 @@ export async function copyKnowledgeToProject(projectPath) {
   return { copied, errors };
 }
 
+/**
+ * Generate knowledge declaration file
+ * Creates _knowledge.json that maps stacks/domains to their available files
+ */
+async function generateKnowledgeDeclare(knowledgePath) {
+  const declaration = {
+    stacks: {},
+    domains: {},
+    generated: new Date().toISOString()
+  };
+
+  // Scan stacks
+  const stacksPath = path.join(knowledgePath, 'stacks');
+  if (await fs.pathExists(stacksPath)) {
+    const stacks = await fs.readdir(stacksPath);
+
+    for (const stack of stacks) {
+      if (stack.startsWith('.') || stack === '_index.md') continue;
+
+      const stackPath = path.join(stacksPath, stack);
+      const stat = await fs.stat(stackPath);
+
+      if (stat.isDirectory()) {
+        // Scan files in stack folder
+        const files = await scanKnowledgeFiles(stackPath);
+        if (files.length > 0) {
+          declaration.stacks[stack] = files;
+        }
+      }
+    }
+  }
+
+  // Scan domains
+  const domainsPath = path.join(knowledgePath, 'domains');
+  if (await fs.pathExists(domainsPath)) {
+    const domains = await fs.readdir(domainsPath);
+
+    for (const domain of domains) {
+      if (domain.startsWith('.') || domain === '_index.md') continue;
+
+      const domainPath = path.join(domainsPath, domain);
+      const stat = await fs.stat(domainPath);
+
+      if (stat.isDirectory()) {
+        // Scan files in domain folder
+        const files = await scanKnowledgeFiles(domainPath);
+        if (files.length > 0) {
+          declaration.domains[domain] = files;
+        }
+      }
+    }
+  }
+
+  // Write declaration file
+  const declarePath = path.join(knowledgePath, '_knowledge.json');
+  await fs.writeJson(declarePath, declaration, { spaces: 2 });
+
+  // Also create a markdown version for easy reading
+  await generateKnowledgeDeclareMd(knowledgePath, declaration);
+
+  return declaration;
+}
+
+/**
+ * Scan knowledge folder and return list of files with metadata
+ */
+async function scanKnowledgeFiles(folderPath) {
+  const files = [];
+
+  async function scan(dir, relativePath = '') {
+    const items = await fs.readdir(dir);
+
+    for (const item of items) {
+      if (item.startsWith('.')) continue;
+
+      const itemPath = path.join(dir, item);
+      const stat = await fs.stat(itemPath);
+      const relPath = relativePath ? `${relativePath}/${item}` : item;
+
+      if (stat.isFile() && item.endsWith('.md')) {
+        files.push({
+          path: relPath,
+          name: item,
+          size: stat.size
+        });
+      } else if (stat.isDirectory()) {
+        await scan(itemPath, relPath);
+      }
+    }
+  }
+
+  await scan(folderPath);
+  return files;
+}
+
+/**
+ * Generate markdown version of knowledge declaration
+ */
+async function generateKnowledgeDeclareMd(knowledgePath, declaration) {
+  let content = '# Knowledge Base Index\n\n';
+  content += `Generated: ${new Date().toLocaleString()}\n\n`;
+  content += 'This file is auto-generated. It lists all available knowledge files in this project.\n\n';
+
+  // Stacks
+  if (Object.keys(declaration.stacks).length > 0) {
+    content += '## Stacks\n\n';
+    for (const [stack, files] of Object.entries(declaration.stacks)) {
+      content += `### ${stack}\n\n`;
+      for (const file of files) {
+        content += `- \`${file.path}\`\n`;
+      }
+      content += '\n';
+    }
+  }
+
+  // Domains
+  if (Object.keys(declaration.domains).length > 0) {
+    content += '## Domains\n\n';
+    for (const [domain, files] of Object.entries(declaration.domains)) {
+      content += `### ${domain}\n\n`;
+      for (const file of files) {
+        content += `- \`${file.path}\`\n`;
+      }
+      content += '\n';
+    }
+  }
+
+  const declarePath = path.join(knowledgePath, '_knowledge.md');
+  await fs.writeFile(declarePath, content);
+}
+
 /**
  * Copy scripts (graph.py, etc.) to project
  */