@codihaus/claude-skills 1.6.20 → 1.6.22

package/skills/debrief/references/workflow.md

@@ -0,0 +1,315 @@
+# Workflow Principles
+
+**Mindset**: Business analyst. Focus on WHAT and WHY, defer HOW to /dev-specs.
+
+**Methodology**: Mode detection → Context gathering → Research → Document → Questionnaire
+
+**Expected Outcome**: Market-validated BRD with tiered features, lean use cases, customer questionnaire.
+
+---
+
+## Mode Detection
+
+**Principle**: Behavior changes based on context.
+
+**Detection**:
+- `--answers {file}` → Process Answers mode
+- `--questionnaire-only` → Questionnaire Only mode
+- No `plans/brd/` → New Project mode
+- `plans/brd/` exists → Add Feature mode
+- Modifying confirmed UC → Change Request mode
+
+**Action**: Execute appropriate workflow for detected mode.
+
+---
+
+## New Project Mode
+
+**Goal**: Create initial BRD with market-validated features.
+
+**Mindset**: Discovery mode. Understand context, research market, validate with customer.
+
+### Context Gathering
+
+**Ask 5 questions** (AskUserQuestion):
+1. Project type (new/existing codebase)
+2. Industry (SaaS/E-commerce/Marketplace/etc.)
+3. Target users (B2B/B2C/Internal)
+4. Constraints (timeline/budget/compliance/integrations)
+5. Scope tier (Core/Standard/Full)
+
+**If existing codebase**: Scan for docs + features (Glob, Read)
+
+**Output**: Context understanding, scope alignment
+
+---
+
+### Market Research
+
+**Methodology**: See `research.md` for full process.
+
+**Comparison-first**:
+- Find 2-3 comparison/alternative pages
+- Extract feature matrix
+- Initial tier hypothesis
+
+**Deep validation**:
+- Per feature: cross-validate with ecosystem + user signals
+- Classify tier (MVP/Standard/Advanced)
+- Collect evidence
+
+**Output**: Features with tier classification and evidence
+
+---
+
+### Feature Sequencing
+
+**Principle**: Order by dependencies within each tier.
+
+**Common patterns**:
+- Create before operate (signup before login)
+- Auth before features (login before projects)
+- Basic before advanced (CRUD before bulk operations)
+- Data before analytics (tracking before dashboards)
+- Core before extensions (email before templates)
+
+**Validation**: No forward dependencies (UC-001 doesn't depend on UC-002)
+
+**Output**: Sequenced feature list (UC-001, UC-002, UC-003...)
+
+---
+
+### Use Case Generation
+
+**Principle**: Lean 80/20 format (~30 lines).
+
+**Include (20%)**:
+- Story (1 line)
+- Critical acceptance criteria (3-5 bullets)
+- Key business rules (constraints, limits)
+- Open questions (blockers)
+
+**Defer to /dev-specs (80%)**:
+- Detailed flows, integrations, edge cases, UI/UX
+
+**Template**: `templates/use-case.md`
+
+**Output**: Lean use cases in `brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md`
+
+---
+
+### BRD Structure
+
+**Project-wide** (`brd/`):
+- README.md (all features index)
+- context.md (stakeholders, users, constraints)
+- references.md (industry, compliance, competitor overview)
+- changelog.md
+
+**Feature-specific** (`features/{feature}/`):
+- README.md (feature overview)
+- references.md (market research, tier evidence)
+- questionnaire-{date}.xlsx
+
+**Templates**: `templates/brd-references.md`, `templates/feature-references.md`
+
+**Output**: Organized BRD structure with scope separation
+
+---
+
+### Questionnaire
+
+**Principle**: Always generate. Validate assumptions + fill gaps.
+
+**Include**:
+- **Validation questions**: "We found 9/10 competitors offer SSO. Confirm?"
+- **Open questions**: "What's max team size per account?"
+
+**Categories**: Validation, Business, Requirements, Constraints, Integration
+
+**Output**: `features/{feature}/questionnaire-{date}.xlsx`
+
+---
+
+### Summary
+
+**Provide**:
+- Files created (brd/, features/)
+- Use case count (lean format)
+- Research summary (comparison pages, evidence sources)
+- Tier distribution (MVP: X, Standard: Y, Advanced: Z)
+- Questionnaire location and question count
+
+**Next steps**:
+- Review BRD with stakeholders
+- Send questionnaire to customer
+- Process with `/debrief --answers {path}`
+- Then `/dev-specs {feature}` for implementation
+
+---
+
+## Add Feature Mode
+
+**Goal**: Extend existing BRD with new feature.
+
+**Mindset**: Continuity mode. Check duplicates, maintain consistency.
+
+### Context Gathering
+
+**Ask 2 questions**:
+1. Feature name
+2. Scope tier (Core/Standard/Full)
+
+**Duplicate check**: Read `docs-graph.json` if exists, warn if similar feature found
+
+**Output**: Feature to add, scope confirmed
+
+---
+
+### Research & Document
+
+**Same as New Project**:
+- Market research (comparison-first, see `research.md`)
+- Feature sequencing (dependencies)
+- Lean use cases (templates/use-case.md)
+
+**Update**:
+- `brd/README.md` (add to index)
+- `brd/changelog.md` (log addition)
+- Create `features/{feature}/` folder
+
+**Questionnaire**: Always generate (validation + open questions)
+
+**Output**: Feature added to BRD with research and questionnaire
+
+---
+
+## Process Answers Mode
+
+**Goal**: Update BRD with customer responses.
+
+**Mindset**: Integration mode. Incorporate feedback, resolve gaps.
+
+### Process
+
+**Read questionnaire** (Excel file):
+- Extract answers from "Answer" column
+- Match to source use cases via "Context/Source"
+
+**Update use cases**:
+- Remove questions from "Open Questions" section
+- Add answers to relevant sections (Acceptance Criteria, Business Rules)
+
+**Update feature README**:
+- Log questionnaire as processed
+- Track history
+
+**Check completeness**:
+- If gaps remain → generate new questionnaire (new date)
+- If complete → update UC status to "Confirmed"
+
+**Output**: Updated use cases, questionnaire history, completion status
+
+---
+
+## Change Request Mode
+
+**Goal**: Track modifications to confirmed BRD.
+
+**Mindset**: Traceability mode. Document change rationale and impact.
+
+### Process
+
+**Create CR** (`brd/changes/CR-{NNN}-{slug}.md`):
+- Change description
+- Reason for change
+- Impact analysis (affected UCs)
+
+**If gaps introduced**: Generate questionnaire at `brd/changes/CR-{NNN}-questionnaire-{date}.xlsx`
+
+**Update**: Affected use cases, references, changelog
+
+**Output**: CR document with impact analysis
+
+---
+
+## Questionnaire Only Mode
+
+**Goal**: Generate questions without creating BRD.
+
+**Mindset**: Quick mode. Capture questions for customer.
+
+### Process
+
+**Ask**:
+- Topic/feature name
+- Custom questions (user provides)
+
+**Generate**: `questionnaire-{date}.xlsx` in current directory
+
+**Output**: Excel file ready to send
+
+---
+
+## File Organization Principles
+
+**Scope-based placement**:
+
+**Project-wide** (applies to entire product):
+- Industry landscape → `brd/references.md`
+- Compliance (GDPR, PCI) → `brd/references.md`
+- Competitor companies → `brd/references.md`
+- Use cases → `brd/use-cases/{feature}/`
+
+**Feature-specific** (applies to one feature):
+- Market research → `features/{feature}/references.md`
+- Tier evidence → `features/{feature}/references.md`
+- Questionnaire → `features/{feature}/questionnaire-{date}.xlsx`
+
+**Cross-reference**: Files can link to each other
+
+---
+
+## Use Case Principles
+
+**Lean format** (80/20 rule):
+- ~30 lines max
+- Scannable in 30 seconds
+- Business focus only (no technical details)
+
+**Sequencing**:
+- Dependencies first (create before validate)
+- Logical user journey
+- No forward references
+
+**Wikilinks**: Use [[node-id]] for docs-graph traceability
+
+---
+
+## Research Principles
+
+**See**: `research.md` for full methodology.
+
+**Key principles**:
+- Comparison-first (fast feature extraction)
+- Evidence-based (multiple source types)
+- Tier validation (MVP/Standard/Advanced rules)
+- Always questionnaire (validation + open questions)
+
+---
+
+## Summary
+
+**Workflow adapts to mode**:
+- New Project: Full discovery and research
+- Add Feature: Focused research, duplicate check
+- Process Answers: Integration and validation
+- Change Request: Impact tracking
+- Questionnaire Only: Quick question generation
+
+**Consistent principles**:
+- Business focus (WHAT and WHY)
+- Evidence-based validation
+- Lean documentation (80/20)
+- Scope-based organization
+- Customer validation (questionnaire)

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