@codihaus/claude-skills 1.6.20 → 1.6.22

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.22",
   "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

@@ -1,469 +1,145 @@
 ---
 name: debrief
-description: Analyze customer requirements and deliver market research, tiered proposals, and recommendations
-version: 3.9.0
+description: Customer requirements → market-validated BRD with tiered features
+version: 4.0.0
 ---
 
-# /debrief - Business Requirements Document (BRD)
+# /debrief - Business Requirements Document
 
-> **Skill Awareness**: See `skills/_registry.md` for all available skills.
-> - **Before**: Use `/dev-scout` if existing codebase
-> - **During**: Calls `/dev-arch` to validate architecture feasibility
-> - **After**: Use `/dev-specs` for implementation plans
-> - **Auto**: `docs-graph.json` updated by hook for relationships
+**Role**: Business analyst creating market-validated BRDs.
 
-Create and maintain the unified BRD for a project. Handles initial requirements and feature additions.
+**Focus**: WHAT features + WHY (business), not HOW (technical).
 
-## When to Use
+---
 
-- Start a new project (creates initial BRD)
-- Add new feature to existing project (updates BRD)
-- Process change requests (tracked separately)
+## When to Use
 
-## Usage
+- New project → Create BRD
+- Add features → Extend BRD
+- Process customer answers → Update BRD
+- Questionnaire only → Generate questions
 
-```
-/debrief "Customer wants a SaaS platform"     # New project
-/debrief "Add billing and subscriptions"      # Add feature
-/debrief requirements.pdf                      # From document
-/debrief                                       # Interactive
-/debrief --answers questionnaire.xlsx         # Process customer answers
-```
-
-## Output Structure
+---
 
-All output goes to unified `plans/` structure:
+## Usage
 
+```bash
+/debrief "Customer wants..."           # New project
+/debrief "Add {feature}"               # Add feature
+/debrief --answers questionnaire.xlsx  # Process answers
+/debrief --questionnaire-only          # Questions only
 ```
-plans/
-├── brd/                         # This skill manages this folder
-│   ├── README.md                # Project overview, feature index
-│   ├── context.md               # Stakeholders, constraints
-│   ├── use-cases/               # ALL use cases, grouped by feature
-│   │   ├── auth/                # Auth feature UCs
-│   │   │   ├── UC-AUTH-001-login.md
-│   │   │   ├── UC-AUTH-002-signup.md
-│   │   │   └── UC-AUTH-003-forgot.md
-│   │   ├── billing/             # Billing feature UCs
-│   │   │   ├── UC-PAY-001-checkout.md
-│   │   │   └── UC-PAY-002-refund.md
-│   │   └── ...
-│   ├── changes/                 # Change requests
-│   │   └── CR-001-add-sso.md
-│   ├── references.md
-│   └── changelog.md
-│
-├── features/                    # Created per feature
-│   ├── auth/                    # /dev-scout and /dev-specs work here
-│   ├── billing/
-│   └── ...
-│
-└── scout/                       # /dev-scout project level
-```
-
-## Expected Outcome
-
-Depending on mode:
-
-**New Project:**
-- BRD with use cases grouped by feature
-- Context document (stakeholders, constraints, users)
-- Market research (MVP/Standard/Advanced feature tiers)
-- Feature folders created
-- Architecture feasibility validated
-- Questionnaire for customer gaps
-
-**Add Feature:**
-- New use cases added to BRD
-- Feature folder created
-- Links to existing features
-- Change request (if BRD confirmed)
-
-**Change Request:**
-- CR document tracking the change
-- Affected use cases updated
-- Impact analysis
-
-**Process Answers:**
-- Use cases updated with answers
-- Open questions resolved
-- Status updated to "Confirmed" if complete
-
-## Success Criteria
-
-- Use cases are testable (clear acceptance criteria)
-- No duplicate features (checked via docs-graph if exists)
-- Open questions captured for customer
-- Architecture can support requirements (validated by /dev-arch)
-- Proper mode detected and handled
-- Naming conventions followed (UC-{GROUP}-{NNN}-{slug})
-
-## Modes
-
-Detect automatically on start:
-
-| Condition | Mode | Behavior |
-|-----------|------|----------|
-| `plans/brd/` doesn't exist | **New Project** | Create full BRD structure |
-| `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 |
-
-## Context Gathering
 
-Use `AskUserQuestion` to understand project context and scope preferences.
-
-### For New Project
-
-Ask 5 key questions using `AskUserQuestion`:
+---
 
-**Q1: Project Type & Source Code**
-Options:
-- New project (no existing code)
-- Existing codebase (current folder)
-- Existing codebase (different folder)
+## Output Structure
 
-**Q2: Industry/Niche**
-Options:
-- SaaS B2B
-- SaaS B2C
-- E-commerce
-- Marketplace
-- Enterprise
-- Other
+**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
 
-**Q3: Target Users**
-Options:
-- Business users (B2B)
-- Consumers (B2C)
-- Internal users
-- Mixed
+**Feature-specific** → `plans/features/{feature}/`:
+- README.md (feature overview)
+- references.md (market research, evidence, tier validation)
+- questionnaire-{date}.xlsx (feature questions)
 
-**Q4: Known Constraints** (multi-select)
-Options:
-- Timeline constraint
-- Budget constraint
-- Compliance requirements
-- Integration requirements
-- None
+---
 
-**Q5: Scope Tier Preference**
-Options:
-- **Core (3-5 use cases)** - MVP, essential features only
-- **Standard (8-12 use cases)** - Competitive parity, market standard
-- **Full (15+ use cases)** - Advanced features, differentiation
+## Key Principles
 
-This helps align on MVP vs market standard vs advanced features upfront.
+### 1. Comparison-First Discovery
 
-### For Add Feature
+**Don't** scan competitors one-by-one.
+**Do** use comparison/alternative pages first:
+- `"{category} comparison"` → feature matrices from 10+ competitors
+- `"best {category} alternatives"` → what features matter
+- `"{competitor A} vs {competitor B}"` → deal-breaker features
 
-Ask 2 questions:
+Then deep revalidation per feature (ecosystem, user signals).
 
-**Q1: Feature Name**
-What to call this feature (e.g., "billing", "notifications", "analytics")
-
-**Q2: Scope for This Feature**
-Options:
-- **Core** - MVP/essential only
-- **Standard** - Competitive parity
-- **Full** - Advanced/differentiation features
-
-### For Existing Codebase
-
-**If user indicates existing codebase:**
-- Scan for docs (CLAUDE.md, README, CONTRIBUTING)
-- Scan frontend files (.vue, .tsx, .jsx) to infer existing features
-- Use `references/file-patterns.md` for scan patterns
-- Summarize findings in `context.md`
+### 2. Always Generate Questionnaire
 
-This codebase discovery informs which features already exist and what gaps remain.
+Include both:
+- **Validation questions**: "We found 9/10 competitors offer SSO. Confirm this is needed?"
+- **Open questions**: "What's max team size per account?"
 
-## Duplicate Prevention
+Customer validates assumptions + fills gaps.
 
-**Use docs-graph** (if exists) to check for duplicates:
-- List existing use cases and features
-- Check for potential overlaps
-- Identify related nodes for impact analysis
+### 3. Scope-Based Organization
 
-**Before creating use cases:**
-- Check if similar UC already exists
-- If modifying confirmed UC → Create CR instead
+**Project-wide** (brd/references.md):
+- Industry landscape
+- Compliance (GDPR, PCI)
+- Competitor company profiles
 
-## Use Case Generation
+**Feature-specific** (features/{name}/references.md):
+- Market research for THIS feature
+- Tier validation evidence (MVP/Standard/Advanced)
+- Sequenced features with dependencies
 
-**Output location:** `plans/brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md`
+### 4. Lean Use Cases (80/20)
 
-**Each use case includes:**
-- User story (As a X, I want Y, so that Z)
-- Acceptance criteria (testable)
-- Business rules
-- Integration notes
+**Include (20%)**:
+- Story (1 line)
+- Critical acceptance criteria (3-5 bullets)
+- Key business rules (constraints, limits)
 - Open questions
-- References from market research
-
-## Market Research
-
-**Why research:** Understand feature tiers and competitive landscape to inform scope decisions.
-
-**Combines with user's scope preference:**
-- User chose "Core" → Focus research on MVP features
-- User chose "Standard" → Research MVP + market standard features
-- User chose "Full" → Research all tiers including advanced/differentiation
-
-**What to research:**
-- Industry patterns (what similar products do)
-- User flows (standard UX patterns in this domain)
-- Compliance requirements (regulations, standards, must-haves)
-- Documentation links (references for engineers)
-
-**Expected insights organized by tier:**
-- **MVP Features (Must-Have):** Minimum to be viable product
-  - Example: Login, basic CRUD, core workflows
-- **Market Standard (Competitive Parity):** What competitors offer
-  - Example: SSO, notifications, exports
-- **Advanced Features (Differentiation):** What sets apart top products
-  - Example: AI suggestions, real-time collaboration, advanced analytics
-
-**Output:**
-- `references.md` - Organized by feature tier with links and notes
-- Use insights to:
-  - Validate user's scope choice (Core/Standard/Full)
-  - Prioritize use cases (Must/Should/Could)
-  - Guide customer conversations ("This is standard" vs "This is premium")
-
-**Format for references.md:**
-```markdown
-## {Feature} - Market Research
-
-### MVP (Must-Have)
-- Login/Signup - Industry standard: email + password + OAuth
-  - Reference: [Auth0 best practices](link)
-- Profile management - Every product has this
-
-### Market Standard (Competitive Parity)
-- SSO integration - 80% of competitors offer this
-  - Reference: [SAML guide](link)
-- Email notifications - User expectation
-
-### Advanced (Differentiation)
-- AI-powered recommendations - Only Competitor X has this
-  - Reference: [ML recommendation patterns](link)
-- Real-time collaboration - Top-tier feature
-```
-
-**How it guides use case creation:**
-- User chose "Core" → Create use cases for MVP tier only
-- User chose "Standard" → Create use cases for MVP + Market Standard tiers
-- User chose "Full" → Create use cases for all tiers
 
-This alignment ensures use cases match the agreed scope.
+**Defer to /dev-specs (80%)**:
+- Detailed flows
+- Integration points
+- Edge cases
+- UI/UX details
 
-## BRD Structure
-
-**Create/Update:**
-- `README.md` - Project overview, feature index, use case tables
-- `context.md` - Stakeholders, users, constraints, existing features
-- `references.md` - Market research links
-- `changelog.md` - Track all BRD updates
-- `changes/` - Change requests (if modifying confirmed BRD)
-
-**Feature folders:**
-- `plans/features/{feature}/README.md` - Feature overview, links to use cases
-
-## Architecture Validation
-
-**After creating use cases**, call `/dev-arch` to validate feasibility:
-
-**dev-arch checks:**
-- Can current architecture support this?
-- What new architecture decisions needed?
-- Any blockers or major concerns?
-
-**dev-arch returns:**
-- Feasible with existing patterns → Continue
-- Feasible with additions → Note what's needed
-- Requires architecture work → Create architecture.md first
-
-## Open Questions & Questionnaire
-
-**Collect open questions from:**
-- Use case "Open Questions" sections
-- Context gaps
-- Integration uncertainties
-- Business rules needing clarification
-
-**If gaps exist, generate questionnaire:**
-```bash
-python .claude/skills/debrief/scripts/generate_questionnaire.py {output_path} questions.json
-```
-
-**Output location:**
-- New feature: `plans/features/{feature}/questionnaire-{YYYY-MM-DD}.xlsx`
-- Change request: `plans/brd/changes/CR-{NNN}-questionnaire-{YYYY-MM-DD}.xlsx`
-
-**Categories:** Business, Requirements, Constraints, Integration, Technical
-**Priority:** Required (blocks UC), Optional (nice to clarify)
-
-## Change Requests
-
-**Create CR when:**
-- Modifying confirmed use cases
-- BRD status is "Confirmed" and adding features
-- Scope expansion discovered
-
-**CR includes:**
-- Request description
-- Reason for change
-- Impact analysis (new/modified UCs, affected features)
-- Questionnaire (if questions exist)
-
-## Process Answers Workflow
-
-**When customer returns questionnaire:**
-
-1. **Read questionnaire** - Extract answers from Excel
-2. **Update use cases** - Add answers to relevant sections, remove from open questions
-3. **Update feature README** - Note questionnaire processed
-4. **Check completeness** - If gaps remain, generate new questionnaire with new date
-5. **Update status** - Mark UCs as "Confirmed" if complete
-
-**Keep questionnaire files** for revision history with date stamps.
-
-## Summary Output
-
-Provide summary with:
-- Use cases created/updated (count)
-- Features created
-- Change requests (if any)
-- Open questions count
-- Questionnaire location (if generated)
-- Next steps:
-  - Send questionnaire to customer
-  - Review with stakeholders
-  - Run `/dev-specs {feature}` (auto-scouts if needed)
-  - OR run `/dev-scout` first for project overview
+Keep use cases ~30 lines max. Business stakeholders scan in 30 seconds.
 
 ---
 
-## Process Answers Workflow
-
-When customer returns filled questionnaire, run:
-```
-/debrief --answers plans/features/billing/questionnaire-2024-01-20.xlsx
-```
-
-### Step 1: Read Questionnaire
-
-Read the Excel file and extract answers:
-- Parse "Answer" column
-- Match to source use cases via "Context/Source" column
-- Flag unanswered required questions
-
-### Step 2: Update Related Files
+## Workflow
 
-For each answered question:
+**See** `references/workflow.md` for detailed steps.
 
-1. **Find source use case file**
-2. **Update use case**:
-   - Remove question from `## Open Questions`
-   - Add answer to relevant section (Acceptance Criteria, Business Rules, etc.)
-3. **Update feature README** with new information
-4. **Update CR file** if questionnaire is CR-related
+**Modes**:
+- No `plans/brd/` → New Project
+- `plans/brd/` exists → Add Feature
+- `--answers {file}` → Process Answers
+- `--questionnaire-only` → Questions Only
 
-### Step 3: Handle Questionnaire File
-
-**Keep the file** for revision history:
-- File stays at original location with date
-- Add "Processed: {date}" to Summary sheet
-- If follow-up needed → new questionnaire with new date
+---
 
-Example revision history:
-```
-plans/features/billing/
-├── questionnaire-2024-01-15.xlsx  # Initial, processed
-├── questionnaire-2024-01-22.xlsx  # Follow-up, processed
-└── questionnaire-2024-01-28.xlsx  # Final clarifications
-```
+## Market Research
 
-### Step 4: Check Completeness
+**See** `references/market-research-methodology.md`.
 
-After processing:
-- Count remaining open questions across related use cases
-- If still gaps → generate new questionnaire with new date
-- If complete → update use case status to "Confirmed"
+**Sources**: Competitors, ecosystems (Chrome, WordPress, GitHub, etc.), user signals (Reddit, reviews).
 
-### Step 5: Update References
+**Tiers**:
+- **MVP**: 80%+ competitors, free tier, high demand
+- **Standard**: 60-80% competitors, pro tier, expected
+- **Advanced**: <60% competitors, enterprise, differentiator
 
-Add questionnaire to relevant files for traceability:
+---
 
-**In feature README.md:**
-```markdown
-## Questionnaire History
-| Date | Status | Questions |
-|------|--------|-----------|
-| 2024-01-15 | Processed | 8 answered |
-| 2024-01-22 | Processed | 3 answered |
-```
+## Tools
 
-**In CR file (if applicable):**
-```markdown
-## Clarifications
-- [Questionnaire 2024-01-20](./CR-001-questionnaire-2024-01-20.xlsx)
-```
+AskUserQuestion, WebSearch, Glob, Read, Write, Bash
 
-### Step 6: Summary
+---
 
-Output:
-- Questions answered: X/Y
-- Use cases updated: [list]
-- Files modified: [list]
-- Remaining gaps: [if any]
-- Next questionnaire: [path if generated]
-- Status: Complete | Needs follow-up
+## References
 
-## Tools Used
+- `references/workflow.md` - Principles and methodology
+- `references/research.md` - Market research guide
+- `references/codes.md` - Group codes and file patterns
+- `references/templates/` - Output formats
 
-| Tool | Purpose |
-|------|---------|
-| `AskUserQuestion` | Context gathering |
-| `Glob` | Find existing files, codebase scan |
-| `Read` | Read existing BRD, docs |
-| `Write` | Create/update BRD files |
-| `WebSearch` | Market research |
+---
 
 ## Scripts
 
-### Customer Questionnaire
-
-Generate dynamic questionnaire based on open questions identified during debrief:
-
 ```bash
 python .claude/skills/debrief/scripts/generate_questionnaire.py output.xlsx questions.json
 ```
-
-**Input:** JSON file with collected open questions (see Phase 7)
-
-**Output:** Excel file with:
-- Summary sheet (project info, priority breakdown, category counts)
-- Questions sheet (categorized questions with context/source)
-- Answer column for customer to fill
-- Required vs Optional priority indicators
-
-**Example:**
-```bash
-# After debrief creates questions.json
-python .claude/skills/debrief/scripts/generate_questionnaire.py plans/features/{feature}/questionnaire-{date}.xlsx /tmp/questions.json
-```
-
-The questionnaire only contains questions we couldn't answer from:
-- Customer brief
-- Existing codebase (if any)
-- Market research
-
-## References
-
-- `references/research-queries.md` - Search templates
-- `references/use-case-template.md` - UC file template
-- `references/group-codes.md` - Standard group codes
-- `references/file-patterns.md` - Codebase scan patterns
-- `references/change-request-template.md` - CR template