@codihaus/claude-skills 1.6.20 → 1.6.21

package/bin/cli.js

@@ -23,6 +23,7 @@ program
   .option('--all', 'Install all skills (default)', true)
   .option('--no-deps', 'Skip dependency checking')
   .option('--no-hooks', 'Skip hooks setup')
+  .option('-k, --knowledge <path>', 'Path to custom knowledge base to install')
   .option('-y, --yes', 'Skip confirmation prompts')
   .action(init);
 

package/knowledge/stacks/_index.md

@@ -28,7 +28,7 @@ Each stack follows this structure:
 
 ```
 stacks/{stack-name}/
-├── _index.md           # Main knowledge file
+├── _index.md           # Main knowledge file (always read first)
 │   ├── Overview        # What it is, when to use
 │   ├── Best Practices  # Patterns to follow
 │   ├── Anti-Patterns   # What to avoid
@@ -37,17 +37,43 @@ stacks/{stack-name}/
 │   ├── For /dev-review # Review checklists
 │   └── Integration     # How it works with other stacks
 │
-├── references/         # Detailed documentation
+├── references/         # Detailed documentation (load as needed)
 │   ├── api.md          # API reference
 │   ├── patterns.md     # Common patterns
 │   └── performance.md  # Performance optimization
 │
-└── assets/             # Code templates
+└── assets/             # Code templates (load as needed)
     ├── composable.ts   # Example composable
     ├── component.vue   # Example component
     └── config.ts       # Example config
 ```
 
+## Loading Knowledge
+
+Skills can load knowledge in two ways:
+
+### 1. Quick Reference (Default)
+Load only `_index.md` for overview and skill-specific guidance:
+```
+Read knowledge/stacks/{stack}/_index.md
+```
+
+### 2. Deep Dive (When Needed)
+Use `_knowledge.json` to discover and load additional files:
+```
+1. Read knowledge/_knowledge.json → Get file list for {stack}
+2. Read knowledge/stacks/{stack}/_index.md → Main guidance
+3. Read knowledge/stacks/{stack}/references/patterns.md → Detailed patterns
+4. Read knowledge/stacks/{stack}/references/performance.md → Performance tips
+```
+
+### When to Load More Than _index.md
+
+- **Specs**: Usually `_index.md` is enough (high-level patterns)
+- **Coding**: Load `references/` when implementing complex features
+- **Review**: Load `references/performance.md` for performance reviews
+- **Architecture**: Load `references/` for deep architectural decisions
+
 ## How Skills Use Stack Knowledge
 
 ### /dev-scout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.20",
+  "version": "1.6.21",
   "description": "Claude Code skills for software development workflow",
   "main": "src/index.js",
   "bin": {

package/skills/_registry.md

@@ -227,6 +227,29 @@ Domain knowledge captures:
 
 See `knowledge/stacks/_index.md` and `knowledge/domains/_index.md` for details.
 
+### Knowledge Loading Patterns
+
+Skills can load knowledge at two depths:
+
+**Quick Reference (Default):**
+- Load `knowledge/stacks/{stack}/_index.md` for overview and skill-specific sections
+- Use for most tasks where general guidance is enough
+- Examples: Specs, basic reviews, standard implementations
+
+**Deep Dive (When Needed):**
+1. Read `knowledge/_knowledge.json` to discover available files
+2. Load `_index.md` for overview
+3. Load additional reference files based on needs:
+   - `references/patterns.md` - Detailed implementation patterns
+   - `references/performance.md` - Performance optimization
+   - `references/api.md` - API reference
+
+**When to go deep:**
+- Complex or performance-critical implementations
+- Architecture decisions requiring deep framework knowledge
+- Comprehensive code reviews
+- Learning new patterns for unfamiliar stacks
+
 ## Skill Awareness Protocol
 
 Every skill should:

package/skills/debrief/SKILL.md

@@ -28,6 +28,7 @@ Create and maintain the unified BRD for a project. Handles initial requirements
 /debrief requirements.pdf                      # From document
 /debrief                                       # Interactive
 /debrief --answers questionnaire.xlsx         # Process customer answers
+/debrief --questionnaire-only                 # Generate questionnaire only (no BRD)
 ```
 
 ## Output Structure
@@ -89,6 +90,11 @@ Depending on mode:
 - Open questions resolved
 - Status updated to "Confirmed" if complete
 
+**Questionnaire Only:**
+- Excel questionnaire file generated
+- No BRD or feature folders created
+- Ready to send to customer for answers
+
 ## Success Criteria
 
 - Use cases are testable (clear acceptance criteria)
@@ -108,6 +114,7 @@ Detect automatically on start:
 | `plans/brd/` exists, adding features | **Add Feature** | Add to existing BRD, check for duplicates |
 | Modifying confirmed use cases | **Change Request** | Create CR first, then update |
 | `--answers` flag provided | **Process Answers** | Update use cases with customer responses |
+| `--questionnaire-only` flag provided | **Questionnaire Only** | Generate questionnaire Excel file only, no BRD |
 
 ## Context Gathering
 
@@ -345,6 +352,43 @@ Provide summary with:
 
 ---
 
+## Questionnaire-Only Mode
+
+When `--questionnaire-only` flag is provided, skip BRD generation and only create questionnaire file.
+
+### Use Cases
+- Quick requirements gathering without full debrief
+- Ad-hoc customer clarifications
+- Focused question sets for specific topics
+
+### Workflow
+
+1. **Ask Context Questions**
+   - Project name (or use current folder name)
+   - Topic/Feature being questioned
+   - Custom questions (user provides as text/list)
+
+2. **Generate Questionnaire**
+   - Create Excel file at `questionnaire-{YYYY-MM-DD}.xlsx` in current directory
+   - Include only the questions provided by user
+   - Use standard questionnaire format (Summary + Questions sheets)
+
+3. **Output Summary**
+   - File location
+   - Question count
+   - Next steps (send to customer, process with --answers)
+
+### Example
+
+```
+/debrief --questionnaire-only "I need to ask customer about payment methods, billing cycle, and refund policy"
+
+# Creates: questionnaire-2024-01-20.xlsx with 3 questions
+# Ready to send to customer
+```
+
+---
+
 ## Process Answers Workflow
 
 When customer returns filled questionnaire, run:

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
  */