@codihaus/claude-skills 1.6.25 → 1.6.27

package/package.json

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

package/skills/debrief/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: debrief
-description: Customer requirements → market-validated BRD with tiered features
-version: 5.0.0
+description: Customer requirements → questionnaire (default) or BRD (with --answers flag)
+version: 5.3.0
 ---
 
 # /debrief - Business Requirements Document
@@ -24,43 +24,42 @@ version: 5.0.0
 ## Usage
 
 ```bash
-/debrief "Customer wants..."                # New project
-/debrief "Add {feature}"                    # Add feature
-/debrief --answers questionnaire.xlsx       # Process answers
-/debrief --generate-brd questionnaire.xlsx  # Generate BRD from existing research
-/debrief --questionnaire-only               # Questions only
+/debrief "Customer wants..."                # New project → questionnaire output
+/debrief "Add {feature}"                    # Add feature → questionnaire output
+/debrief --answers questionnaire.xlsx       # Process answers → CREATE BRD
+/debrief --generate-brd questionnaire.xlsx  # Generate BRD from research
 ```
 
+**Key principle**:
+- **Without flags**: ONLY outputs questionnaire (no BRD)
+- **With --answers or --generate-brd**: Creates BRD files
+
 ---
 
-## Output Structure
+## Output
 
-**Project-wide** → `plans/brd/`:
-- README.md (all features index)
-- context.md (stakeholders, users, constraints)
-- references.md (industry, compliance, competitor overview)
-- use-cases/{feature}/ (all use cases, grouped)
-- changelog.md
+**Default (no flags)**: `questionnaire-{date}.xlsx` only (3 sheets: Summary, Questions, References)
 
-**Feature-specific** → `plans/features/{feature}/`:
-- README.md (feature overview)
-- references.md (market research, evidence, tier validation)
-- questionnaire-{date}.xlsx (feature questions)
+**With --answers or --generate-brd**:
+- `plans/brd/` - Project-wide BRD files
+- `plans/brd/use-cases/` - Use cases by feature
+- `plans/features/{feature}/` - Feature-specific files
 
 ---
 
 ## Key Principles
 
-### 1. Default Output: Questionnaire Only
+### 1. Questionnaire First (Default)
 
-**ALWAYS output**: Summary + Questionnaire (3 sheets Excel)
-**NEVER auto-create**: BRD files, use cases, feature folders
+**Default behavior (no flags)**:
+- ALWAYS output: Summary + Questionnaire (3 sheets Excel)
+- NEVER auto-create: BRD files, use cases, feature folders
 
-**BRD creation only via**:
-- `--answers questionnaire.xlsx` (after customer fills it)
-- `--generate-brd questionnaire.xlsx` (from existing research)
+**BRD creation (explicit flags)**:
+- `--answers questionnaire.xlsx` → Creates BRD after customer fills it
+- `--generate-brd questionnaire.xlsx` → Creates BRD from existing research
 
-**Why**: User reviews research first, validates with customer, then creates BRD.
+**Why**: User reviews research first, validates with customer, THEN creates BRD.
 
 ### 2. Business Focus ONLY
 
@@ -78,19 +77,27 @@ version: 5.0.0
 
 **If you mention files, code, APIs, or tech → YOU ARE DOING IT WRONG.**
 
-### 3. Deep Research (Always)
+### 3. Deep Research + Revalidation (ALWAYS)
 
-**Always thorough**:
-- Comparison pages (feature matrix)
-- Ecosystems (Chrome, WordPress, GitHub)
-- User signals (Reddit, reviews, forums)
-- Full evidence per feature
+**Always thorough** (regardless of scope tier):
+1. Comparison pages (feature matrix)
+2. **Multi-source revalidation** (MANDATORY):
+   - Ecosystems (Chrome, WordPress, GitHub, NPM)
+   - User signals (Reddit, reviews, forums)
+   - Competitor direct (pricing, features)
+3. Full evidence per feature (3+ source types)
 
-No quick mode. Always deep.
+**No shortcuts**: MVP/Standard/Full all get same deep research + revalidation.
 
 ### 4. Questionnaire = Decision Tool
 
-**3 sheets with evidence**:
+**How to generate**:
+```bash
+python .claude/skills/debrief/scripts/generate_questionnaire.py questionnaire-{YYYY-MM-DD}.xlsx -
+```
+Pipe JSON to stdin with research data (see `references/workflow.md` for JSON format).
+
+**3 sheets generated**:
 - Summary (features count, tier breakdown, research stats)
 - Questions (validation + open)
 - References (URLs, evidence per feature)
@@ -105,12 +112,24 @@ Then create BRD via `--answers` or `--generate-brd`.
 
 **See** `references/workflow.md` for detailed steps.
 
+**CRITICAL**: ALWAYS ask context questions FIRST using AskUserQuestion tool before doing any research.
+
 **Modes**:
-- No `plans/brd/` → New Project
-- `plans/brd/` exists → Add Feature
-- `--answers {file}` → Process Answers
-- `--generate-brd {file}` → Generate BRD from research
-- `--questionnaire-only` → Questions Only
+- **New Project**:
+  1. Ask 4 questions (Industry, Users, Constraints, Scope mode: MVP/Market Standard/Full)
+  2. Research + questionnaire → `plans/brd/use-cases/{project}/questionnaire-{date}.xlsx`
+  3. NO BRD created
+- **Add Feature**:
+  1. Ask 2 questions (Feature name, Scope mode: MVP/Market Standard/Full)
+  2. Research + questionnaire → `plans/brd/use-cases/{feature}/questionnaire-{date}.xlsx`
+  3. NO BRD created
+- **Process Answers** (`--answers`):
+  1. Read filled questionnaire
+  2. **ASK what to do**: Continue research / Ask follow-ups / Create BRD
+  3. Execute based on choice
+- **Generate BRD** (`--generate-brd`): Create BRD from research
+
+**Default**: Questionnaire only. BRD requires explicit flag AND user confirmation.
 
 ---
 

package/skills/debrief/references/codes.md

@@ -1,6 +1,6 @@
 # Reference Codes
 
-Quick reference for use case naming and codebase discovery.
+Quick reference for use case naming.
 
 ---
 
@@ -32,104 +32,3 @@ Standard codes for `UC-{GROUP}-{NNN}-{slug}.md` naming.
 **Custom codes**: Define project-specific codes in BRD README (3-5 chars, obvious meaning).
 
 **Principle**: Group by user intent, not implementation (PAY not STRIPE, USER not DATABASE).
-
----
-
-## Codebase Discovery Patterns
-
-For existing codebase scanning (detect features and tech stack).
-
-### Frontend File Patterns
-
-**Include**:
-```
-**/*.vue              # Vue.js
-**/*.tsx, **/*.jsx    # React / Next.js
-**/pages/**/*         # Routes
-**/app/**/page.tsx    # Next.js App Router
-**/*.svelte           # Svelte
-**/*.component.ts     # Angular
-```
-
-**Exclude**:
-```
-node_modules/**, dist/**, build/**, .next/**, .nuxt/**
-*.min.js, *.bundle.js, *.chunk.js
-**/*.test.*, **/*.spec.*, __tests__/**
-```
-
----
-
-### Feature Inference from Files
-
-Map file/folder names to features:
-
-| Pattern | Feature |
-|---------|---------|
-| `auth/`, `login.*`, `signin.*` | Authentication |
-| `user/`, `profile.*`, `account.*` | User Management |
-| `dashboard.*` | Dashboard |
-| `payment/`, `checkout.*`, `billing.*` | Payments |
-| `subscription/`, `plans.*` | Subscriptions |
-| `admin/` | Admin Panel |
-| `notification/`, `alerts/` | Notifications |
-| `search.*` | Search |
-| `cart.*`, `basket.*` | Shopping Cart |
-| `order/`, `orders/` | Orders |
-| `product/`, `catalog/` | Products |
-| `message/`, `chat/`, `inbox/` | Messaging |
-| `report/`, `analytics/` | Reporting |
-| `upload/`, `files/`, `media/` | File Management |
-| `team/`, `organization/` | Team Management |
-| `onboarding/`, `wizard/`, `setup/` | Onboarding |
-| `help/`, `support/`, `faq/` | Help/Support |
-
----
-
-### Tech Stack Detection
-
-**Package files**:
-```
-package.json      → Node.js / JavaScript
-requirements.txt  → Python
-Gemfile           → Ruby
-go.mod            → Go
-Cargo.toml        → Rust
-composer.json     → PHP
-```
-
-**Framework detection** (from package.json dependencies):
-- `next` → Next.js
-- `nuxt` → Nuxt.js
-- `vue` → Vue.js
-- `react` → React
-- `@angular/core` → Angular
-- `svelte` → Svelte
-- `express` → Express.js
-- `nestjs` → NestJS
-
----
-
-### Documentation Patterns
-
-Look for existing docs:
-```
-README.md, CLAUDE.md, CONTRIBUTING.md
-docs/**/*.md
-plans/**/*.md
-specifications/**/*.md
-.github/**/*.md
-```
-
----
-
-## Discovery Strategy
-
-**For existing codebase**:
-1. Find package.json → Detect framework
-2. Glob frontend files → List pages/components
-3. Match patterns → Infer features
-4. Read docs (README, CLAUDE.md)
-5. Summarize in context.md
-
-**Output**: Features table with status (exists/missing), tech stack summary

package/skills/debrief/references/research.md

@@ -2,15 +2,17 @@
 
 **Mindset**: Evidence-based validation. Features classified by market standards, not personal judgment.
 
-**Methodology**: Comparison-first → Deep validation → Tier classification
+**Methodology**: Comparison-first → Multi-source revalidation (ALWAYS) → Tier classification
 
-**Expected Outcome**: Features with tier (MVP/Standard/Advanced) backed by evidence (competitor presence, user demand, ecosystem signals).
+**Expected Outcome**: Features with tier (MVP/Standard/Advanced) backed by evidence from multiple sources.
 
 ---
 
-## Quick Start (20%)
+## Research Flow (ALWAYS Deep)
 
-### Comparison-First Approach
+**No quick mode.** Always do full research with multi-source revalidation, regardless of scope tier.
+
+### Step 1: Comparison-First Approach
 
 **Start here** - one comparison page = 10 competitors analyzed:
 
@@ -30,7 +32,19 @@
 
 ---
 
-### Tier Classification
+### Step 2: Multi-Source Revalidation (MANDATORY)
+
+**Always revalidate** across multiple source types for every feature:
+- Comparison pages (initial)
+- Ecosystems (Chrome, WordPress, GitHub, NPM)
+- User signals (Reddit, G2 reviews, forums)
+- Competitor direct (pricing pages, feature pages)
+
+**No shortcuts.** All tiers (MVP/Standard/Full) require full revalidation.
+
+---
+
+### Step 3: Tier Classification
 
 **MVP** (80%+ competitors, high demand):
 - Present in 8+ out of 10 competitors
@@ -67,7 +81,7 @@ Per feature, collect:
 
 ---
 
-## Validation Sources (20%)
+## Revalidation Sources (ALWAYS Use Multiple)
 
 ### Comparison & Alternatives (Primary)
 
@@ -135,9 +149,11 @@ Per feature, collect:
 
 ---
 
-## Methodology
+## Methodology (ALWAYS Deep)
 
-### Phase 1: Comparison Scan (5 min)
+**Process**: Always execute both phases regardless of scope tier (MVP/Standard/Full).
+
+### Phase 1: Comparison Scan
 
 **Goal**: Extract feature matrix from comparison pages.
 
@@ -151,17 +167,19 @@ Per feature, collect:
 
 ---
 
-### Phase 2: Deep Validation (5-10 min per feature)
+### Phase 2: Multi-Source Revalidation (MANDATORY)
 
-**Goal**: Validate tier with evidence from multiple source types.
+**Goal**: Validate tier with evidence from MULTIPLE source types.
 
-**Approach**: Cross-validate across source categories:
+**ALWAYS cross-validate** across source categories:
 - Comparison pages (initial)
-- Ecosystem (Chrome, WordPress, GitHub)
-- User signals (Reddit, reviews)
+- Ecosystems (Chrome, WordPress, GitHub, NPM)
+- User signals (Reddit, reviews, forums)
 - Competitor direct (pricing, features)
 
-**Output**: Tier classification with evidence and sources
+**No shortcuts**: Every feature needs multi-source validation, even for MVP scope.
+
+**Output**: Tier classification with evidence from 3+ source types
 
 ---
 

package/skills/debrief/references/templates/brd-references.md

@@ -52,22 +52,6 @@
 
 ---
 
-## Implementation Resources
-
-> **For Engineers**: General documentation (feature-specific docs in feature folders)
-
-### Platform Documentation
-| Technology | Link | Purpose |
-|------------|------|---------|
-| {Platform/Service} | [Docs](url) | {General purpose} |
-
-### Industry Examples
-| Company | Link | What to Learn |
-|---------|------|---------------|
-| {Company} | [Example](url) | {General pattern} |
-
----
-
 ## Notes
 
 **Project Goals**:

package/skills/debrief/references/templates/feature-references.md

@@ -80,16 +80,6 @@
 
 ---
 
-## Implementation Resources
-
-> **For Engineers**: Links specific to this feature
-
-| Topic | Link | Purpose |
-|-------|------|---------|
-| {Service} {Feature} API | [Docs](url) | {Implementation} |
-
----
-
 ## Open Questions
 
 - {Question requiring customer input}

package/skills/debrief/references/workflow.md

@@ -10,15 +10,13 @@
 
 ## Mode Detection
 
-**Principle**: Behavior changes based on context.
+**Principle**: Default outputs questionnaire only. BRD creation requires explicit flag.
 
 **Detection**:
-- `--answers {file}` → Process Answers mode
-- `--generate-brd {file}` → Generate BRD mode
-- `--questionnaire-only` → Questionnaire Only mode
-- No `plans/brd/` → New Project mode
-- `plans/brd/` exists → Add Feature mode
-- Modifying confirmed UC → Change Request mode
+- `--answers {file}` → Process Answers mode (CREATE BRD)
+- `--generate-brd {file}` → Generate BRD mode (CREATE BRD)
+- New customer request → New Project mode (questionnaire only)
+- Adding to existing research → Add Feature mode (questionnaire only)
 
 **Action**: Execute appropriate workflow for detected mode.
 
@@ -30,50 +28,93 @@
 
 **Mindset**: Discovery mode. Understand context, research market, validate with customer.
 
-### Context Gathering
+### STEP 1: Context Gathering (MANDATORY - DO THIS FIRST)
+
+**CRITICAL**: ALWAYS ask questions BEFORE doing any research. DO NOT skip this step.
 
 **Check for existing questionnaire**:
 - If found: Ask "Found existing research. Use it or start fresh?"
   - Reuse → Switch to Generate BRD mode
   - Fresh → Continue with new research
 
-**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)
+**ALWAYS ask 4 questions** using AskUserQuestion tool:
+1. **Industry**: SaaS / E-commerce / Marketplace / etc.
+2. **Target users**: B2B / B2C / Internal
+3. **Constraints**: Timeline / Budget / Compliance / Integrations
+4. **Scope mode**: MVP / Market Standard / Full (determines WHICH features to include)
 
-**If existing codebase**: Scan for docs + features (Glob, Read)
+**DO NOT proceed to research until user answers these questions.**
 
 **Output**: Context understanding, scope alignment
 
 ---
 
-### Market Research (Always Deep)
+### STEP 2: Market Research (ALWAYS Deep + Revalidation)
+
+**CRITICAL**: After user answers questions and scope tier is chosen, THEN do deep research + multi-source revalidation.
 
 **Methodology**: See `research.md` for full process.
 
-**Deep research** (always):
-1. Comparison pages (feature matrix extraction)
-2. Ecosystems (Chrome, WordPress, GitHub, etc.)
-3. User signals (Reddit, reviews, forums)
-4. Full tier classification with evidence
+**Always execute** (same process for ALL scope tiers):
+1. **Phase 1**: Comparison pages (feature matrix extraction)
+2. **Phase 2**: Multi-source revalidation (MANDATORY)
+   - Ecosystems (Chrome, WordPress, GitHub, NPM)
+   - User signals (Reddit, reviews, forums)
+   - Competitor direct (pricing, features)
+3. Full tier classification with evidence from 3+ source types
 
-**Output**: Features with tier classification and evidence
+**No shortcuts**: Core/Standard/Full scope all get identical deep research + revalidation process.
 
----
+**Output**: Features with tier classification and multi-source evidence
 
-### Generate Questionnaire (ALWAYS)
-
-**Principle**: Default output. No BRD files created yet.
+---
 
-**3 sheets**:
+### STEP 3: Generate Questionnaire (ALWAYS)
+
+**Principle**: After research is complete, generate questionnaire. No BRD files created yet.
+
+**How to generate**:
+1. Create JSON with research data (see format below)
+2. Call Python script: `python .claude/skills/debrief/scripts/generate_questionnaire.py questionnaire-{YYYY-MM-DD}.xlsx -`
+3. Pipe JSON to stdin or save as file
+
+**JSON format**:
+```json
+{
+  "project_name": "Project Name",
+  "date": "2026-01-25",
+  "research": {
+    "depth": "Deep",
+    "features_count": 12,
+    "tiers": {"MVP": 5, "Standard": 4, "Advanced": 3},
+    "sources_count": 23
+  },
+  "references": {
+    "Feature Name": [
+      {"type": "Comparison", "url": "https://..."},
+      {"type": "G2 Reviews", "url": "https://..."}
+    ]
+  },
+  "questions": [
+    {
+      "category": "Requirements",
+      "question": "Question text?",
+      "priority": "Required",
+      "context": "Why we're asking",
+      "source": "UC-XXX-NNN"
+    }
+  ]
+}
+```
+
+**3 sheets generated**:
 - **Summary**: Feature count, tier distribution, research stats
 - **Questions**: Validation + open questions
 - **References**: URLs by feature (comparison pages, reviews, ecosystems)
 
-**Output**: `questionnaire-{date}.xlsx` in current directory
+**Output location**:
+- New Project: `plans/brd/use-cases/{project-name}/questionnaire-{YYYY-MM-DD}.xlsx`
+- Add Feature: `plans/brd/use-cases/{feature-name}/questionnaire-{YYYY-MM-DD}.xlsx`
 
 **NO BRD files created**. User reviews questionnaire first.
 
@@ -90,8 +131,7 @@
 **Next steps**:
 1. Review questionnaire
 2. Send to customer for answers
-3. After answers: `/debrief --answers questionnaire-{date}.xlsx`
-4. BRD will be created from answers
+3. After answers: `/debrief --answers questionnaire-{date}.xlsx` to create BRD
 
 ---
 
@@ -101,25 +141,29 @@
 
 **Mindset**: Continuity mode. Check duplicates, maintain consistency.
 
-### Context Gathering
+### STEP 1: Context Gathering (MANDATORY - DO THIS FIRST)
 
-**Ask 2 questions**:
-1. Feature name
-2. Scope tier (Core/Standard/Full)
+**CRITICAL**: ALWAYS ask questions BEFORE doing any research. DO NOT skip this step.
+
+**ALWAYS ask 2 questions** using AskUserQuestion tool:
+1. **Feature name**: What feature to add?
+2. **Scope mode**: MVP / Market Standard / Full (determines WHICH features to include)
 
 **Duplicate check**: Read `docs-graph.json` if exists, warn if similar feature found
 
+**DO NOT proceed to research until user answers these questions.**
+
 **Output**: Feature to add, scope confirmed
 
 ---
 
-### Research & Generate Questionnaire
+### STEP 2: Research & Generate Questionnaire
 
 **Same as New Project**:
 - Market research (comparison-first, see `research.md`)
 - Generate questionnaire (validation + open questions)
 
-**Output**: `features/{feature}/questionnaire-{date}.xlsx`
+**Output**: `plans/brd/use-cases/{feature}/questionnaire-{YYYY-MM-DD}.xlsx`
 
 **NO BRD files created**. User reviews questionnaire, gets answers, then runs `--answers`.
 
@@ -127,11 +171,13 @@
 
 ## Process Answers Mode
 
-**Goal**: Create BRD from customer-answered questionnaire.
+**Trigger**: `/debrief --answers questionnaire.xlsx`
+
+**Goal**: Process filled questionnaire and ask what user wants to do next.
 
-**Mindset**: BRD creation mode. Customer validated research, now create structure.
+**Mindset**: Interactive mode. User decides next action based on answers.
 
-### Read Questionnaire
+### STEP 1: Read Questionnaire
 
 **Read questionnaire** (Excel file):
 - Summary sheet (features, tiers, research)
@@ -140,7 +186,23 @@
 
 ---
 
-### Feature Sequencing
+### STEP 2: Ask What To Do (MANDATORY)
+
+**CRITICAL**: ALWAYS ask what user wants to do. DO NOT auto-create BRD.
+
+**Ask using AskUserQuestion tool** - What would you like to do?
+1. **Continue research and revise summary** (do more research based on answers)
+2. **Ask follow-up questions** (generate new questionnaire with deeper questions)
+3. **Create BRD** (generate use cases and BRD files)
+
+**Based on user choice**:
+- Choice 1 → Do additional research, update questionnaire
+- Choice 2 → Generate new questionnaire with follow-up questions
+- Choice 3 → Proceed to Feature Sequencing (below)
+
+---
+
+### STEP 3: Feature Sequencing (ONLY if user chose "Create BRD")
 
 **Principle**: Order by dependencies within each tier.
 
@@ -157,7 +219,7 @@
 
 ---
 
-### Use Case Generation
+### STEP 4: Use Case Generation (ONLY if user chose "Create BRD")
 
 **Principle**: Lean 80/20 format (~30 lines).
 
@@ -181,9 +243,9 @@
 
 ---
 
-### BRD Structure Creation
+### STEP 5: BRD Structure Creation (ONLY if user chose "Create BRD")
 
-**Create project-wide** (`brd/`):
+**Create project-wide** (`plans/brd/`):
 - README.md (all features index)
 - context.md (stakeholders, users, constraints)
 - references.md (industry, compliance, competitor overview)
@@ -204,73 +266,26 @@
 
 ---
 
-## 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
-
----
-
 ## Generate BRD Mode
 
+**Trigger**: `/debrief --generate-brd questionnaire.xlsx`
+
 **Goal**: Generate full BRD from existing questionnaire research.
 
 **Mindset**: Resumption mode. User reviewed Summary + Questionnaire, ready for full BRD.
 
 ### Process
 
-**Check questionnaire validity**:
-- Ask: "Found existing research in questionnaire. Use it or start fresh?"
-  - Reuse (generate from questionnaire)
-  - Fresh (ignore questionnaire, do new research)
-
-**If reuse**:
-- Execute same process as Process Answers mode
+**Execute same process as Process Answers mode**:
 - Read questionnaire sheets
 - Sequence features
 - Generate use cases
 - Create BRD structure
 
-**If fresh**:
-- Ignore questionnaire
-- Run full research flow (New Project or Add Feature mode)
-
 **Output**: BRD files + feature folders
 
 ---
 
-## 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**:
@@ -320,17 +335,17 @@
 
 ## Summary
 
-**Workflow adapts to mode**:
-- New Project: Full discovery and research
-- Add Feature: Focused research, duplicate check
-- Generate BRD: Reads existing questionnaire research
-- Process Answers: Integration and validation
-- Change Request: Impact tracking
-- Questionnaire Only: Quick question generation
+**Workflow modes**:
+- New Project: Full discovery and research → questionnaire (no BRD)
+- Add Feature: Focused research, duplicate check → questionnaire (no BRD)
+- Process Answers (`--answers`): Read filled questionnaire → CREATE BRD
+- Generate BRD (`--generate-brd`): Read research questionnaire → CREATE BRD
+
+**Default**: Questionnaire only. BRD creation requires explicit flag.
 
 **Consistent principles**:
-- Business focus (WHAT and WHY)
-- Evidence-based validation
-- Lean documentation (80/20)
-- Scope-based organization
-- Customer validation (questionnaire)
+- Business focus (WHAT and WHY, never HOW)
+- Evidence-based validation (multi-source)
+- Always deep research + revalidation
+- Customer validation via questionnaire
+- BRD creation ONLY when user provides filled questionnaire

package/skills/debrief/scripts/generate_questionnaire.py

@@ -36,6 +36,32 @@ questions.json format:
 
 import sys
 import json
+import subprocess
+import os
+
+# Check and install openpyxl if missing
+def check_dependencies():
+    """Check if openpyxl is installed, install if missing."""
+    try:
+        import openpyxl
+    except ImportError:
+        print("Installing required dependency: openpyxl")
+
+        # Detect pip command (pip3 or pip)
+        pip_cmd = 'pip3' if os.system('which pip3 > /dev/null 2>&1') == 0 else 'pip'
+
+        try:
+            subprocess.check_call([pip_cmd, 'install', 'openpyxl'],
+                                stdout=subprocess.DEVNULL,
+                                stderr=subprocess.DEVNULL)
+            print("✓ openpyxl installed successfully")
+        except subprocess.CalledProcessError:
+            print("✗ Failed to install openpyxl")
+            print(f"Please run: {pip_cmd} install openpyxl")
+            sys.exit(1)
+
+check_dependencies()
+
 from openpyxl import Workbook
 from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
 from openpyxl.utils import get_column_letter

package/src/commands/update.js

@@ -6,14 +6,35 @@
 
 import chalk from 'chalk';
 import ora from 'ora';
+import { execSync } from 'child_process';
+import fs from 'fs-extra';
+import path from 'path';
 
-import { checkForUpdates, copySkillsToProject, getInstalledSkills } from '../utils/skills.js';
+import { checkForUpdates, copySkillsToProject, getInstalledSkills, cleanupOldSkills } from '../utils/skills.js';
 
 export async function update(options) {
   const projectPath = process.cwd();
 
   console.log(chalk.bold('\n📦 Claude Skills Update\n'));
 
+  // Check for npm package updates
+  const packageSpinner = ora('Checking npm for latest version...').start();
+  try {
+    const currentVersion = await getCurrentPackageVersion();
+    const latestVersion = await getLatestNpmVersion();
+
+    if (currentVersion !== latestVersion) {
+      packageSpinner.info(`Package update available: ${currentVersion} → ${latestVersion}`);
+      console.log(chalk.yellow(`\nTo update the CLI package, run:\n  npm install -g @codihaus/claude-skills@latest\n`));
+    } else {
+      packageSpinner.succeed(`CLI package is up to date (${currentVersion})`);
+    }
+  } catch (e) {
+    packageSpinner.warn('Could not check for CLI updates');
+  }
+
+  console.log('');
+
   // Check for installed skills
   const installed = await getInstalledSkills(projectPath);
 
@@ -25,7 +46,7 @@ export async function update(options) {
   console.log(chalk.gray(`Found ${installed.length} installed skills\n`));
 
   // Check for updates
-  const spinner = ora('Checking for updates...').start();
+  const spinner = ora('Checking for skill updates...').start();
   const updates = await checkForUpdates(projectPath);
   spinner.stop();
 
@@ -52,6 +73,13 @@ export async function update(options) {
 
   try {
     const skillNames = updates.map(u => u.name);
+
+    // Clean up old files first
+    updateSpinner.text = 'Cleaning up old skill files...';
+    await cleanupOldSkills(projectPath, skillNames);
+
+    // Copy new versions
+    updateSpinner.text = 'Installing updated skills...';
     const { copied, errors } = await copySkillsToProject(projectPath, skillNames);
 
     if (errors.length > 0) {
@@ -70,3 +98,30 @@ export async function update(options) {
 
   console.log(chalk.green('\n✅ Update complete!\n'));
 }
+
+/**
+ * Get current package version
+ */
+async function getCurrentPackageVersion() {
+  try {
+    const packageJson = await fs.readJson(path.join(import.meta.dirname, '../../package.json'));
+    return packageJson.version;
+  } catch (e) {
+    return 'unknown';
+  }
+}
+
+/**
+ * Get latest version from npm
+ */
+async function getLatestNpmVersion() {
+  try {
+    const result = execSync('npm view @codihaus/claude-skills version', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore']
+    });
+    return result.trim();
+  } catch (e) {
+    throw new Error('Could not fetch latest version from npm');
+  }
+}

package/src/utils/skills.js

@@ -243,6 +243,30 @@ export async function removeSkillFromProject(projectPath, skillName) {
   }
 }
 
+/**
+ * Clean up old skill files before updating
+ * Removes entire skill directory to ensure deleted files are removed
+ */
+export async function cleanupOldSkills(projectPath, skillNames) {
+  const skillsPath = path.join(projectPath, '.claude', 'skills');
+
+  if (!await fs.pathExists(skillsPath)) {
+    return;
+  }
+
+  for (const skillName of skillNames) {
+    const skillPath = path.join(skillsPath, skillName);
+
+    if (await fs.pathExists(skillPath)) {
+      try {
+        await fs.remove(skillPath);
+      } catch (e) {
+        // Ignore errors, will be logged during copy
+      }
+    }
+  }
+}
+
 /**
  * Check if skills need updating
  */