@codihaus/claude-skills 1.6.28 → 1.7.0

package/package.json

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

package/skills/_registry.md

@@ -10,9 +10,7 @@ Central registry of all available skills. Reference this to suggest relevant ski
 | `/dev-arch` | Architecture decisions | New features, major changes, technical design |
 | `/dev-scout` | Explore codebase, detect patterns | Before implementation, understanding existing code |
 | `/dev-specs` | Create implementation plans | After debrief, before coding |
-| `/dev-coding` | Implement features | When specs are ready |
-| `/dev-coding-backend` | Backend patterns | API, schema, database work |
-| `/dev-coding-frontend` | Frontend patterns | UI, components, pages |
+| `/dev-coding` | Implement features (three-layer: universal + framework + project) | When specs are ready |
 | `/dev-test` | Automated testing | After implementation, before review |
 | `/dev-review` | Code review | After testing passes, before merge |
 | `/dev-changelog` | Implementation summary | After review passes |
@@ -48,9 +46,7 @@ Ready to plan implementation?
     Calls /dev-arch → "What patterns to use?"
 
 Ready to code?
-    → /dev-coding
-        ├── Backend work → loads /dev-coding-backend
-        └── Frontend work → loads /dev-coding-frontend
+    → /dev-coding (three-layer: universal + framework + project)
 
 Code done, need testing?
     → /dev-test (auto-triggered by /dev-coding)
@@ -82,6 +78,7 @@ When user says... → Suggest skill
 | "build this", "implement", "code this" | `/dev-coding` |
 | "test this", "verify it works", "run tests" | `/dev-test` |
 | "review my code", "check this PR" | `/dev-review` |
+| "check BRD coverage", "are all use cases implemented" | `/dev-review --brd` |
 | "what was built", "summarize changes", "document implementation" | `/dev-changelog` |
 | "create diagram", "architecture diagram", "flow chart" | `/utils/diagram` |
 
@@ -131,6 +128,7 @@ During each skill, consider suggesting:
 
 ### /dev-review
 - Reads: `_quality-attributes.md` for ALL level checklists (verification)
+- `--brd` flag: Macro-level BRD use case coverage verification (Code vs BRD)
 - If issues found: Offers to call `/dev-coding` for automatic fix
 - After fix: Re-runs review automatically
 - If pass: Suggests `/dev-changelog` to document implementation
@@ -138,9 +136,9 @@ During each skill, consider suggesting:
 
 ### /dev-changelog
 - Before: `/dev-review` must pass
-- Reads: Git changes, specs, use cases
-- Outputs: summary.md, implementation.md, tech-debt.md, docs-updates.md
-- Purpose: Document what was built, track progress, identify doc updates
+- Reads: Git changes, specs, BRD use cases
+- Outputs: summary.md, user-impact.md, implementation.md, tech-debt.md, docs-updates.md
+- Purpose: Document what was built, track user impact, identify doc updates
 
 ### /utils/diagram
 - Utility skill for diagram validation

package/skills/debrief/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: debrief
-description: Customer requirements → questionnaire (default) or BRD (with --answers flag)
-version: 5.3.1
+description: Customer requirements discovery, market research, and BRD creation. Use when: (1) Starting new project or feature, (2) Customer provides requirements or requests, (3) Processing customer questionnaire answers (--answers flag), (4) Generating BRD from research (--generate-brd flag)
+version: 5.4.0
 ---
 
 # /debrief - Business Requirements Document
@@ -92,10 +92,14 @@ version: 5.3.1
 ### 4. Questionnaire = Decision Tool
 
 **How to generate**:
+1. Write JSON to temp file: `/tmp/debrief-questions-{timestamp}.json`
+2. Call Python script with file path:
 ```bash
-python .claude/skills/debrief/scripts/generate_questionnaire.py questionnaire-{YYYY-MM-DD}.xlsx -
+python .claude/skills/debrief/scripts/generate_questionnaire.py \
+  plans/brd/use-cases/{feature-name}/questionnaire-{YYYY-MM-DD}.xlsx \
+  /tmp/debrief-questions-{timestamp}.json
 ```
-Pipe JSON to stdin with research data (see `references/workflow.md` for full JSON format).
+(See `references/workflow.md` for full JSON format)
 
 **CRITICAL: Populate with real data**:
 - **questions array**: 2-5 questions per feature (validation + open questions)
@@ -168,6 +172,11 @@ AskUserQuestion, WebSearch, Glob, Read, Write, Bash
 
 ## Scripts
 
+**Generate questionnaire from JSON file**:
 ```bash
-python .claude/skills/debrief/scripts/generate_questionnaire.py output.xlsx questions.json
+python .claude/skills/debrief/scripts/generate_questionnaire.py \
+  plans/brd/use-cases/{feature}/questionnaire-{date}.xlsx \
+  /tmp/debrief-questions.json
 ```
+
+**JSON file should be written to `/tmp/` first**, then passed to script.

package/skills/debrief/references/workflow.md

@@ -82,8 +82,14 @@
 
 **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
+2. **Write JSON to temp file**: `/tmp/debrief-questions-{timestamp}.json`
+3. **Call Python script with file path**:
+   ```bash
+   python .claude/skills/debrief/scripts/generate_questionnaire.py \
+     plans/brd/use-cases/{feature-name}/questionnaire-{YYYY-MM-DD}.xlsx \
+     /tmp/debrief-questions-{timestamp}.json
+   ```
+4. Python reads JSON from temp file and creates Excel in correct BRD location
 
 **CRITICAL: Populate questions array with TWO types:**
 

package/skills/dev-arch/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-arch
-description: Architecture decisions and technical design for features
-version: 1.1.0
+description: Architecture decisions and technical design for features. Use when: (1) New feature requires structural decisions, (2) Validating if current architecture supports requirements, (3) Choosing technology for new capability (payments, real-time, etc.), (4) Greenfield project architecture
+version: 1.2.0
 ---
 
 # /dev-arch - Architecture Design
@@ -234,49 +234,9 @@ Create `plans/features/{feature}/adrs/ADR-{NNN}-{slug}.md` with:
 
 ## Decision Categories
 
-### API Design
+See `references/decision-categories.md` for option tables (API, Database, Frontend State, Auth, Infrastructure) and Context7 usage for architecture research.
 
-| Question | Options |
-|----------|---------|
-| Style | REST, GraphQL, tRPC, gRPC |
-| Versioning | URL path, header, none |
-| Auth header | Bearer token, cookie, API key |
-| Response format | JSON:API, custom, none |
-
-### Database
-
-| Question | Options |
-|----------|---------|
-| Type | PostgreSQL, MySQL, MongoDB, SQLite |
-| ORM | Prisma, TypeORM, Drizzle, raw SQL |
-| Migrations | ORM-managed, manual, none |
-| Soft deletes | Yes (deletedAt), no |
-
-### Frontend State
-
-| Question | Options |
-|----------|---------|
-| Global state | Redux, Zustand, Jotai, Context |
-| Server state | React Query, SWR, manual |
-| Forms | React Hook Form, Formik, native |
-
-### Authentication
-
-| Question | Options |
-|----------|---------|
-| Strategy | JWT, session, OAuth only |
-| Token storage | httpOnly cookie, localStorage, memory |
-| Refresh | Sliding window, explicit refresh |
-| Permissions | RBAC, ABAC, simple roles |
-
-### Infrastructure
-
-| Question | Options |
-|----------|---------|
-| Caching | Redis, in-memory, CDN |
-| Queue | Redis/BullMQ, SQS, RabbitMQ |
-| File storage | S3, local, Cloudinary |
-| Email | SendGrid, SES, SMTP |
+**Categories**: API Design, Database, Frontend State, Authentication, Infrastructure.
 
 ## Tools Used
 
@@ -290,30 +250,6 @@ Create `plans/features/{feature}/adrs/ADR-{NNN}-{slug}.md` with:
 | `Context7` | Look up architecture best practices |
 | `WebSearch` | Find architecture patterns |
 
-### Context7 for Architecture Research
-
-When making architecture decisions, use Context7 to look up best practices:
-
-```
-1. Resolve library ID
-   → mcp__context7__resolve-library-id({
-       libraryName: "prisma",
-       query: "database schema design patterns"
-     })
-
-2. Query documentation
-   → mcp__context7__query-docs({
-       libraryId: "/prisma/prisma",
-       query: "relations and foreign keys best practices"
-     })
-```
-
-**Use for:**
-- ORM patterns (Prisma, TypeORM, Drizzle)
-- Framework architecture (Next.js, NestJS)
-- Auth library patterns (NextAuth, Lucia)
-- API design (REST, GraphQL, tRPC)
-
 ## Integration
 
 | Skill | Relationship |
@@ -339,121 +275,7 @@ Greenfield → Ask constraint questions
 
 ## Example Flows
 
-### Example 1: Follow Mode (Most Common)
-
-```
-User: /dev-arch notifications
-
-1. Mode detection
-   → Scout exists with established patterns
-   → Mode: FOLLOW
-
-2. Load context
-   → Project uses: Next.js, REST API, PostgreSQL, Prisma
-   → Feature needs: notification preferences, email sending
-
-3. Apply existing patterns (NO QUESTIONS)
-   → API: POST /api/notifications, GET /api/notifications
-   → Database: Notification model with Prisma
-   → Frontend: NotificationSettings component
-
-4. Check for gaps
-   → Email sending needed
-   → Project already has SendGrid configured ✓
-   → No gaps!
-
-5. Output (minimal)
-   "Using existing patterns. No architecture changes needed.
-    - New Notification model
-    - New API endpoints following REST convention
-    - Uses existing SendGrid for emails"
-
-No ADRs created. No questions asked.
-```
-
-### Example 2: Extend Mode (New Part Only)
-
-```
-User: /dev-arch billing
-
-1. Mode detection
-   → Scout exists with established patterns
-   → Mode: FOLLOW initially...
-
-2. Load context
-   → Project uses: Next.js, REST, PostgreSQL
-   → Feature needs: payment processing, subscriptions
-
-3. Check for gaps
-   → Payment processing needed
-   → Project has NO payment provider ← Gap found!
-   → Mode switches to: EXTEND
-
-4. Ask ONLY about the gap
-   "Feature needs payment processing. No provider configured.
-    Options:
-    A: Stripe (Recommended) - Popular, good docs
-    B: Paddle - Handles taxes
-    C: LemonSqueezy - Simpler
-
-    Which provider?"
-
-   → User: "Stripe"
-
-5. Everything else follows existing patterns
-   → API: REST endpoints for billing
-   → Database: Prisma models
-   → Frontend: Existing component patterns
-
-6. Output
-   → architecture.md (documents Stripe choice)
-   → ADR-001-payment-provider.md (only for the NEW decision)
-
-   "Stripe selected. All other patterns follow existing project architecture."
-```
-
-### Example 3: Design Mode (Greenfield)
-
-```
-User: /dev-arch auth --new
-
-1. Mode detection
-   → --new flag provided
-   → Mode: DESIGN
-
-2. Ask constraint questions
-   Q1: "Team size?"
-   → Small team (3 devs)
-
-   Q2: "Deployment target?"
-   → Vercel
-
-   Q3: "Constraints?"
-   → Tight timeline
-
-3. Present options based on constraints
-   "Based on: Small team, Vercel, tight timeline
-
-    Recommended:
-    - NextAuth.js (simple, works with Vercel)
-    - JWT in httpOnly cookies
-    - RBAC for permissions
-
-    Alternatives considered:
-    - Auth0: Good but adds external dependency
-    - Custom JWT: More work, tight timeline
-
-    Proceed with NextAuth.js?"
-
-   → User: "Yes"
-
-4. Generate full architecture
-   → architecture.md (complete auth design)
-   → ADR-001-auth-strategy.md
-   → ADR-002-permission-model.md
-```
-
-## Summary
+See `references/examples.md` for detailed Follow/Extend/Design mode examples.
 
 | Mode | Questions Asked | ADRs Created |
 |------|-----------------|--------------|
@@ -462,3 +284,8 @@ User: /dev-arch auth --new
 | Design | Full constraint gathering | For all decisions |
 
 **Default to Follow mode. Only escalate when necessary.**
+
+## References
+
+- `references/decision-categories.md` - Option tables, Context7 usage
+- `references/examples.md` - Follow/Extend/Design mode examples

package/skills/dev-arch/references/decision-categories.md

@@ -0,0 +1,73 @@
+# Decision Categories
+
+## Option Tables
+
+Only create ADRs for NEW decisions, not for following existing patterns.
+
+### API Design
+
+| Question | Options |
+|----------|---------|
+| Style | REST, GraphQL, tRPC, gRPC |
+| Versioning | URL path, header, none |
+| Auth header | Bearer token, cookie, API key |
+| Response format | JSON:API, custom, none |
+
+### Database
+
+| Question | Options |
+|----------|---------|
+| Type | PostgreSQL, MySQL, MongoDB, SQLite |
+| ORM | Prisma, TypeORM, Drizzle, raw SQL |
+| Migrations | ORM-managed, manual, none |
+| Soft deletes | Yes (deletedAt), no |
+
+### Frontend State
+
+| Question | Options |
+|----------|---------|
+| Global state | Redux, Zustand, Jotai, Context |
+| Server state | React Query, SWR, manual |
+| Forms | React Hook Form, Formik, native |
+
+### Authentication
+
+| Question | Options |
+|----------|---------|
+| Strategy | JWT, session, OAuth only |
+| Token storage | httpOnly cookie, localStorage, memory |
+| Refresh | Sliding window, explicit refresh |
+| Permissions | RBAC, ABAC, simple roles |
+
+### Infrastructure
+
+| Question | Options |
+|----------|---------|
+| Caching | Redis, in-memory, CDN |
+| Queue | Redis/BullMQ, SQS, RabbitMQ |
+| File storage | S3, local, Cloudinary |
+| Email | SendGrid, SES, SMTP |
+
+## Context7 for Architecture Research
+
+When making architecture decisions, use Context7 to look up best practices:
+
+```
+1. Resolve library ID
+   → mcp__context7__resolve-library-id({
+       libraryName: "prisma",
+       query: "database schema design patterns"
+     })
+
+2. Query documentation
+   → mcp__context7__query-docs({
+       libraryId: "/prisma/prisma",
+       query: "relations and foreign keys best practices"
+     })
+```
+
+**Use for:**
+- ORM patterns (Prisma, TypeORM, Drizzle)
+- Framework architecture (Next.js, NestJS)
+- Auth library patterns (NextAuth, Lucia)
+- API design (REST, GraphQL, tRPC)

package/skills/dev-arch/references/examples.md

@@ -0,0 +1,125 @@
+# Architecture Examples
+
+## Example 1: Follow Mode (Most Common)
+
+```
+User: /dev-arch notifications
+
+1. Mode detection
+   → Scout exists with established patterns
+   → Mode: FOLLOW
+
+2. Load context
+   → Project uses: Next.js, REST API, PostgreSQL, Prisma
+   → Feature needs: notification preferences, email sending
+
+3. Apply existing patterns (NO QUESTIONS)
+   → API: POST /api/notifications, GET /api/notifications
+   → Database: Notification model with Prisma
+   → Frontend: NotificationSettings component
+
+4. Check for gaps
+   → Email sending needed
+   → Project already has SendGrid configured ✓
+   → No gaps!
+
+5. Output (minimal)
+   "Using existing patterns. No architecture changes needed.
+    - New Notification model
+    - New API endpoints following REST convention
+    - Uses existing SendGrid for emails"
+
+No ADRs created. No questions asked.
+```
+
+## Example 2: Extend Mode (New Part Only)
+
+```
+User: /dev-arch billing
+
+1. Mode detection
+   → Scout exists with established patterns
+   → Mode: FOLLOW initially...
+
+2. Load context
+   → Project uses: Next.js, REST, PostgreSQL
+   → Feature needs: payment processing, subscriptions
+
+3. Check for gaps
+   → Payment processing needed
+   → Project has NO payment provider ← Gap found!
+   → Mode switches to: EXTEND
+
+4. Ask ONLY about the gap
+   "Feature needs payment processing. No provider configured.
+    Options:
+    A: Stripe (Recommended) - Popular, good docs
+    B: Paddle - Handles taxes
+    C: LemonSqueezy - Simpler
+
+    Which provider?"
+
+   → User: "Stripe"
+
+5. Everything else follows existing patterns
+   → API: REST endpoints for billing
+   → Database: Prisma models
+   → Frontend: Existing component patterns
+
+6. Output
+   → architecture.md (documents Stripe choice)
+   → ADR-001-payment-provider.md (only for the NEW decision)
+
+   "Stripe selected. All other patterns follow existing project architecture."
+```
+
+## Example 3: Design Mode (Greenfield)
+
+```
+User: /dev-arch auth --new
+
+1. Mode detection
+   → --new flag provided
+   → Mode: DESIGN
+
+2. Ask constraint questions
+   Q1: "Team size?"
+   → Small team (3 devs)
+
+   Q2: "Deployment target?"
+   → Vercel
+
+   Q3: "Constraints?"
+   → Tight timeline
+
+3. Present options based on constraints
+   "Based on: Small team, Vercel, tight timeline
+
+    Recommended:
+    - NextAuth.js (simple, works with Vercel)
+    - JWT in httpOnly cookies
+    - RBAC for permissions
+
+    Alternatives considered:
+    - Auth0: Good but adds external dependency
+    - Custom JWT: More work, tight timeline
+
+    Proceed with NextAuth.js?"
+
+   → User: "Yes"
+
+4. Generate full architecture
+   → architecture.md (complete auth design)
+   → ADR-001-auth-strategy.md
+   → ADR-002-permission-model.md
+```
+
+## Mode Summary
+
+| Mode | Questions Asked | ADRs Created |
+|------|-----------------|--------------|
+| Follow | None | None |
+| Extend | Only for gaps | Only for new decisions |
+| Design | Full constraint gathering | For all decisions |
+
+**Default to Follow mode. Only escalate when necessary.**

package/skills/dev-changelog/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-changelog
-description: Capture implementation summary, track progress, identify docs updates
-version: 1.0.0
+description: Document implementation results with developer summary and user impact analysis. Use when: (1) After /dev-review passes, (2) End of sprint or milestone, (3) Before handoff to another developer, (4) Need to track what changed for users (release notes, user guides)
+version: 1.1.0
 ---
 
 # /dev-changelog - Implementation Summary
@@ -33,7 +33,8 @@ Capture what was implemented after review passes. Creates actionable documentati
 
 ```
 plans/features/{feature}/
-├── summary.md              # What was built (this session/PR)
+├── summary.md              # What was built (developer perspective)
+├── user-impact.md          # What changed for users (user perspective)
 ├── implementation.md       # Cumulative implementation status
 ├── tech-debt.md            # Known issues, TODOs
 └── docs-updates.md         # Documentation tasks
@@ -44,7 +45,8 @@ plans/features/{feature}/
 Documentation of what was implemented after `/dev-review` passes.
 
 **Outputs:**
-- `summary.md` - What was built this session/PR
+- `summary.md` - What was built this session/PR (developer perspective)
+- `user-impact.md` - What changed for users (user perspective)
 - `implementation.md` - Cumulative status (updated)
 - `tech-debt.md` - Known issues, TODOs (updated)
 - `docs-updates.md` - Documentation tasks
@@ -101,6 +103,43 @@ For each changed file:
 | Breaking change | Migration guide |
 | New component | Component docs |
 
+## User Impact Analysis
+
+**Purpose**: Describe changes from USER perspective. Input for user guides, release notes, training materials.
+
+**Source**: BRD use cases + git changes (what was intended vs what was built).
+
+**For each change, capture:**
+
+| Aspect | Question | Example |
+|--------|----------|---------|
+| **What changed** | What does user see/do differently? | "Login now requires 2FA verification step" |
+| **Where** | Which part of the app? | "Login page, after email/password" |
+| **Why** | Business reason (from BRD) | "UC-AUTH-003: Security compliance" |
+| **Impact level** | How disruptive? | Breaking / Visible / Behind-the-scenes |
+
+**Impact levels:**
+- **Breaking**: User workflow changes (new required steps, removed features)
+- **Visible**: User sees changes (new UI, new options, layout changes)
+- **Behind-the-scenes**: No visible change (performance, security, refactor)
+
+**Output** (`user-impact.md`):
+```markdown
+# User Impact: {Feature}
+
+## Breaking Changes
+- {description} ({UC reference})
+  - What users need to do differently
+
+## Visible Changes
+- {description} ({UC reference})
+  - What users will notice
+
+## Behind-the-scenes
+- {description}
+  - No user action needed
+```
+
 ## Output Files
 
 **summary.md** (per session/PR):
@@ -151,22 +190,6 @@ Then:
 ├── Generates summary.md, implementation.md, etc.
 ```
 
-## Resume Flow
-
-When returning to work later:
-
-```
-1. Read implementation.md
-   → See what's done, what's remaining
-
-2. Read tech-debt.md
-   → See known issues
-
-3. Read summary.md (latest)
-   → See where you left off
-
-4. Continue with /dev-specs or /dev-coding
-```
 
 ## Tools Used
 

package/skills/dev-coding/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-coding
-description: Implement features as a Principal Engineering Developer
-version: 2.1.3
+description: Implement features using three-layer knowledge (universal principles + framework patterns + project specifics). Use when: (1) Specs are ready and implementation should begin, (2) Building backend, frontend, or full-stack features, (3) Applying project patterns to new code
+version: 2.2.0
 ---
 
 # /dev-coding - Implementation Skill
@@ -158,6 +158,19 @@ Don't pre-load everything. Discover when needed:
 - ❌ List all components upfront
 - ❌ Memorize function names (look up when needed)
 
+## When to Escalate
+
+During implementation, if you discover issues that affect scope:
+
+| Situation | Action |
+|-----------|--------|
+| Missing detail in spec (e.g., field name unclear) | Decide based on patterns, note in commit |
+| Spec assumes non-existent pattern (e.g., "use existing payment service" but none exists) | STOP → Ask user: "Spec references X but it doesn't exist. Options: A) Build it, B) Use alternative, C) Skip UC" |
+| Requirement conflicts with existing code (e.g., schema mismatch) | STOP → Ask user with specific conflict details |
+| UC scope much larger than expected (e.g., requires full OAuth refactor) | STOP → Flag to user: "This UC requires [X] which is beyond spec scope. Proceed or re-scope?" |
+
+**Rule**: If you can resolve in <5 minutes with confidence → do it + note in commit. Otherwise → STOP and ask.
+
 ## Three-Layer Knowledge System
 
 ```
@@ -323,7 +336,7 @@ Apply principles from references/ during implementation. See `_quality-attribute
 
 **Spec references non-existent pattern:**
 - Discover pattern via Grep/Glob
-- If truly doesn't exist, implement following three-layer approach
+- If truly doesn't exist → See "When to Escalate" section
 - Note deviation in implementation notes
 
 ## Success Criteria