@codihaus/claude-skills 1.6.24 → 1.6.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.24",
+  "version": "1.6.26",
   "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: 4.2.0
+description: Customer requirements → questionnaire (default) or BRD (with --answers flag)
+version: 5.2.0
 ---
 
 # /debrief - Business Requirements Document
@@ -24,43 +24,42 @@ version: 4.2.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,22 +77,28 @@ version: 4.2.0
 
 **If you mention files, code, APIs, or tech → YOU ARE DOING IT WRONG.**
 
-### 3. Comparison-First Research
+### 3. Deep Research + Revalidation (ALWAYS)
 
-Use comparison pages first (5-10 competitors in one page):
-- `"{category} comparison"`
-- `"best {category} alternatives"`
+**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)
 
-Then validate per feature (Quick or Deep).
+**No shortcuts**: MVP/Standard/Full all get same deep research + revalidation.
 
-### 4. Questionnaire = Research Output
+### 4. Questionnaire = Decision Tool
 
-**3 sheets**:
-- Summary (stats, tiers)
+**3 sheets with evidence**:
+- Summary (features count, tier breakdown, research stats)
 - Questions (validation + open)
-- References (URLs)
+- References (URLs, evidence per feature)
+
+**Purpose**: User reviews evidence, makes decisions, validates with customer.
 
-Customer reviews, answers, returns file. Then create BRD via `--answers`.
+Then create BRD via `--answers` or `--generate-brd`.
 
 ---
 
@@ -102,19 +107,20 @@ Customer reviews, answers, returns file. Then create BRD via `--answers`.
 **See** `references/workflow.md` for detailed steps.
 
 **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: Research + questionnaire (no BRD)
+- Add Feature: Research + questionnaire (no BRD)
+- Process Answers (`--answers`): Create BRD from filled questionnaire
+- Generate BRD (`--generate-brd`): Create BRD from research
+
+**Default**: Questionnaire only. BRD requires explicit flag.
 
 ---
 
-## Market Research
+## Market Research (Always Deep)
 
-**See** `references/market-research-methodology.md`.
+**See** `references/research.md`.
 
-**Sources**: Competitors, ecosystems (Chrome, WordPress, GitHub, etc.), user signals (Reddit, reviews).
+**Always deep**: Comparison + ecosystems + user signals + full evidence.
 
 **Tiers**:
 - **MVP**: 80%+ competitors, free tier, high demand

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

@@ -2,23 +2,21 @@
 
 **Mindset**: Business analyst. Focus on WHAT and WHY, defer HOW to /dev-specs.
 
-**Methodology**: Mode detection → Context gathering → Research → Document → Questionnaire
+**Methodology**: Mode detection → Context gathering → Research (deep) → Questionnaire
 
-**Expected Outcome**: Market-validated BRD with tiered features, lean use cases, customer questionnaire.
+**Expected Outcome**: Questionnaire with deep research evidence (Summary + Questions + References).
 
 ---
 
 ## 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.
 
@@ -37,90 +35,33 @@
   - Reuse → Switch to Generate BRD mode
   - Fresh → Continue with new research
 
-**Ask 6 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)
-6. Research depth (Quick 5min / Deep 15-20min)
-
-**If existing codebase**: Scan for docs + features (Glob, Read)
+**Ask 4 questions** (AskUserQuestion):
+1. Industry (SaaS/E-commerce/Marketplace/etc.)
+2. Target users (B2B/B2C/Internal)
+3. Constraints (timeline/budget/compliance/integrations)
+4. **Scope tier** (Core/Standard/Full) - determines WHICH features to include
 
 **Output**: Context understanding, scope alignment
 
 ---
 
-### Market Research
-
-**Methodology**: See `research.md` for full process.
-
-**Quick** (5 min):
-- Find 2-3 comparison/alternative pages
-- Extract feature matrix
-- Initial tier hypothesis
-
-**Deep** (15-20 min):
-- Comparison pages (initial)
-- Cross-validate with ecosystem + user signals
-- Full tier classification with 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
+### Market Research (ALWAYS Deep + Revalidation)
 
-**Template**: `templates/use-case.md`
-
-**Output**: Lean use cases in `brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md`
+**CRITICAL**: After scope tier chosen, ALWAYS do deep research + multi-source revalidation.
 
----
-
-### BRD Structure
-
-**Project-wide** (`brd/`):
-- README.md (all features index)
-- context.md (stakeholders, users, constraints)
-- references.md (industry, compliance, competitor overview)
-- changelog.md
+**Methodology**: See `research.md` for full process.
 
-**Feature-specific** (`features/{feature}/`):
-- README.md (feature overview)
-- references.md (market research, tier evidence)
-- questionnaire-{date}.xlsx
+**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
 
-**Templates**: `templates/brd-references.md`, `templates/feature-references.md`
+**No shortcuts**: Core/Standard/Full scope all get identical deep research + revalidation process.
 
-**Output**: Organized BRD structure with scope separation
+**Output**: Features with tier classification and multi-source evidence
 
 ---
 
@@ -150,8 +91,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
 
 ---
 
@@ -163,10 +103,9 @@
 
 ### Context Gathering
 
-**Ask 3 questions**:
+**Ask 2 questions**:
 1. Feature name
 2. Scope tier (Core/Standard/Full)
-3. Research depth (Quick / Deep)
 
 **Duplicate check**: Read `docs-graph.json` if exists, warn if similar feature found
 
@@ -188,97 +127,102 @@
 
 ## Process Answers Mode
 
+**Trigger**: `/debrief --answers questionnaire.xlsx`
+
 **Goal**: Create BRD from customer-answered questionnaire.
 
 **Mindset**: BRD creation mode. Customer validated research, now create structure.
 
-### Process
+### Read Questionnaire
 
 **Read questionnaire** (Excel file):
 - Summary sheet (features, tiers, research)
 - Questions sheet (customer answers)
 - References sheet (source URLs)
 
-**Create BRD structure**:
-- `brd/` files (README, context, references, changelog)
-- `features/{feature}/` folders
-- Use cases (lean format, sequenced)
-
-**Incorporate answers**:
-- Update use cases with customer answers
-- Remove questions that were answered
-- Keep unanswered questions in "Open Questions"
+---
 
-**Check completeness**:
-- If gaps remain → note in use cases
-- If complete → mark UC status "Confirmed"
+### Feature Sequencing
 
-**Output**: Full BRD structure + use cases
+**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)
 
-## Change Request Mode
+**Validation**: No forward dependencies (UC-001 doesn't depend on UC-002)
 
-**Goal**: Track modifications to confirmed BRD.
+**Output**: Sequenced feature list (UC-001, UC-002, UC-003...)
 
-**Mindset**: Traceability mode. Document change rationale and impact.
+---
 
-### Process
+### Use Case Generation
 
-**Create CR** (`brd/changes/CR-{NNN}-{slug}.md`):
-- Change description
-- Reason for change
-- Impact analysis (affected UCs)
+**Principle**: Lean 80/20 format (~30 lines).
 
-**If gaps introduced**: Generate questionnaire at `brd/changes/CR-{NNN}-questionnaire-{date}.xlsx`
+**Include (20%)**:
+- Story (1 line)
+- Critical acceptance criteria (3-5 bullets)
+- Key business rules (constraints, limits)
+- Open questions (blockers)
 
-**Update**: Affected use cases, references, changelog
+**Defer to /dev-specs (80%)**:
+- Detailed flows, integrations, edge cases, UI/UX
 
-**Output**: CR document with impact analysis
+**Template**: `templates/use-case.md`
 
----
+**Incorporate customer answers**:
+- Update use cases with answers from questionnaire
+- Remove answered questions from "Open Questions"
+- Keep unanswered questions
 
-## Generate BRD Mode
+**Output**: Lean use cases in `brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md`
 
-**Goal**: Generate full BRD from existing questionnaire research.
+---
 
-**Mindset**: Resumption mode. User reviewed Summary + Questionnaire, ready for full BRD.
+### BRD Structure Creation
 
-### Process
+**Create project-wide** (`brd/`):
+- README.md (all features index)
+- context.md (stakeholders, users, constraints)
+- references.md (industry, compliance, competitor overview)
+- changelog.md
 
-**Check questionnaire validity**:
-- Ask: "Found existing research in questionnaire. Use it or start fresh?"
-  - Reuse (generate from questionnaire)
-  - Fresh (ignore questionnaire, do new research)
+**Create feature-specific** (`features/{feature}/`):
+- README.md (feature overview)
+- references.md (market research, tier evidence from questionnaire)
+- Move questionnaire here if not already
 
-**If reuse**:
-- Read Summary sheet (features, tiers, research stats)
-- Read References sheet (source URLs)
-- Generate BRD structure (no re-research)
+**Templates**: `templates/brd-references.md`, `templates/feature-references.md`
 
-**If fresh**:
-- Ignore questionnaire
-- Run full research flow (New Project or Add Feature mode)
+**Check completeness**:
+- If gaps remain → note in use cases
+- If complete → mark UC status "Confirmed"
 
-**Output**: BRD files + feature folders
+**Output**: Full BRD structure + use cases
 
 ---
 
-## Questionnaire Only Mode
+## Generate BRD Mode
 
-**Goal**: Generate questions without creating BRD.
+**Trigger**: `/debrief --generate-brd questionnaire.xlsx`
 
-**Mindset**: Quick mode. Capture questions for customer.
+**Goal**: Generate full BRD from existing questionnaire research.
 
-### Process
+**Mindset**: Resumption mode. User reviewed Summary + Questionnaire, ready for full BRD.
 
-**Ask**:
-- Topic/feature name
-- Custom questions (user provides)
+### Process
 
-**Generate**: `questionnaire-{date}.xlsx` in current directory
+**Execute same process as Process Answers mode**:
+- Read questionnaire sheets
+- Sequence features
+- Generate use cases
+- Create BRD structure
 
-**Output**: Excel file ready to send
+**Output**: BRD files + feature folders
 
 ---
 
@@ -331,17 +275,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
  */