@codihaus/claude-skills 1.6.28 → 1.7.0

package/skills/dev-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-review
-description: Code review with focus on quality, security, and best practices
-version: 1.4.1
+description: Code review comparing implementation against specs, BRD, and quality standards. Use when: (1) After implementation and testing, (2) Before merging a PR, (3) Verifying BRD use case coverage (--brd flag), (4) Checking code quality, security, and pattern compliance
+version: 1.5.0
 ---
 
 # /dev-review - Code Review
@@ -28,6 +28,7 @@ Review code changes for quality, security, and adherence to standards.
 /dev-review --staged             # Review staged changes only
 /dev-review src/auth/            # Review specific directory
 /dev-review UC-AUTH-001          # Review changes for specific UC
+/dev-review billing --brd        # Verify all BRD use cases covered
 ```
 
 ## Input
@@ -150,46 +151,7 @@ Review report with verdict and categorized issues.
 
 ### Stack-Specific
 
-**CRITICAL: Load framework-specific review checklists**
-
-After loading stack knowledge (from Context Sources → Step 1), apply framework-specific checks from the "For /dev-review" section:
-
-**React projects:**
-- Hooks follow Rules of Hooks (no conditional calls, correct order)
-- All dependencies included in useEffect/useCallback/useMemo
-- No infinite loops, no stale closures
-- State updates are immutable
-- Performance optimizations appropriate (memo, lazy)
-- Lists have stable keys
-
-**Vue 3 projects:**
-- Uses `<script setup>` (not Options API)
-- Composables follow naming convention (use*)
-- No destructuring reactive without toRefs
-- ref() accessed with .value in script (not in template)
-- v-for has unique :key
-- No v-for + v-if on same element
-- Props not mutated directly
-
-**Next.js projects:**
-- Server vs Client Components used correctly
-- Server Actions have "use server" directive
-- Data fetching uses proper Next.js patterns
-- No client-side code in Server Components
-
-**Nuxt projects:**
-- Composables follow naming convention (useX)
-- Server routes in correct location
-- Auto-imports used correctly
-- SSR-safe code (no window access in setup)
-
-**Directus projects:**
-- Collections accessed properly
-- Permissions configured
-- Field types match requirements
-- Flows and hooks follow patterns
-
-**If stack knowledge file doesn't exist**, apply general best practices only.
+**CRITICAL**: Load framework-specific review checklists from `references/stack-checks.md`. Also load `knowledge/stacks/{stack}/_index.md` "For /dev-review" section for deeper patterns.
 
 ## Context Sources
 
@@ -235,234 +197,81 @@ After loading stack knowledge (from Context Sources → Step 1), apply framework
 
 ## Review Best Practices
 
-### Be Constructive
+See `references/review-examples.md` for constructive feedback patterns, example reviews, and fix loop details.
 
-```markdown
-// BAD
-"This code is bad"
-
-// GOOD
-"This could cause a SQL injection. Consider using parameterized queries:
-```sql
-SELECT * FROM users WHERE id = $1
-```"
-```
-
-### Explain Why
-
-```markdown
-// BAD
-"Don't use var"
-
-// GOOD
-"Use const/let instead of var - var has function scope which can lead to
-unexpected behavior. const also signals intent that the value won't change."
-```
-
-### Suggest Alternatives
-
-```markdown
-// Issue + Solution
-"The N+1 query here will cause performance issues with many posts.
-
-Consider using an include/join:
-```typescript
-const posts = await db.posts.findMany({
-  include: { author: true }
-});
-```"
-```
-
-### Acknowledge Good Work
-
-```markdown
-### Positives
-- Clean separation of API and business logic
-- Good error messages for users
-- Comprehensive input validation
-```
+**Key principles**: Be constructive (suggest fix, not just flag), explain why, suggest alternatives, acknowledge good work.
 
 ## Tools Used
 
 | Tool | Purpose |
 |------|---------|
 | `Bash` | git diff, git log |
-| `Read` | Read changed files |
+| `Read` | Read changed files, specs, BRD use cases |
 | `Grep` | Search for patterns |
 | `Glob` | Find related files |
 
-## Integration
-
-| Skill | Relationship |
-|-------|--------------|
-| `/dev-coding` | Review after implementation |
-| `/dev-scout` | Get project conventions |
-| `/dev-specs` | Check spec compliance |
-
-## Example Review
-
-```
-User: /dev-review UC-AUTH-001
-
-Step 1: Load Context
-- Read tech-context.md → Stack: Next.js 14 + TypeScript
-- Read knowledge/stacks/nextjs/_index.md → "For /dev-review" section
-  → Check Server Actions, App Router, Server Components
-- Read knowledge/stacks/react/_index.md → "For /dev-review" section
-  → Check Hooks, state management, performance
-- Read _quality-attributes.md → All level checklists
-- Read UC-AUTH-001 spec → Requirements
-- Get git diff → Changed files
-
-Step 2: Analyze
-- src/api/auth/login.ts: Clean ✓
-- src/components/LoginForm.tsx: 1 issue (React hooks deps missing)
-- src/lib/api.ts: 1 suggestion (naming)
-
-Step 3: Generate Report
-
-## Review Summary
-
-**Verdict**: ⚠️ Request Changes
+## BRD Coverage Verification (--brd flag)
 
-**Stats**: 3 files, +245 additions, -12 deletions
-
-### Issues Found
+When `--brd` flag provided, perform macro-level verification: Code vs BRD use cases.
 
-#### 🔴 Critical
-None
+**1. Load BRD use cases:**
+- Read all `plans/brd/use-cases/{feature}/UC-*.md`
+- Extract requirements and acceptance criteria per UC
 
-#### 🟡 Important
-- [error-handling] `src/components/LoginForm.tsx:34`
-  Promise rejection not handled. If API fails, user sees nothing.
-  ```tsx
-  // Add error state
-  .catch(err => setError(err.message))
-  ```
+**2. Load code changes:**
+- `git log --oneline` for feature branch/period
+- `git diff --stat` for files changed
 
-#### 🔵 Suggestions
-- [naming] `src/lib/api.ts:12`
-  `data` is generic. Consider `credentials` for clarity.
+**3. Map changes to UCs:**
 
-### Spec Compliance
-- [x] POST /api/auth/login works
-- [x] Returns token
-- [x] Validates input
-- [ ] Missing: Rate limiting (spec requirement)
+For each UC, determine:
+- ✅ **Covered**: Code changes address requirements
+- ⚠️ **Partial**: Some requirements met, some missing
+- ❌ **Not covered**: No code changes for this UC
 
-### Positives
-- Good validation on both client and server
-- Clean component structure
-- Proper TypeScript types
-```
-
-## Fix Loop
-
-When issues are found, `/dev-review` can trigger `/dev-coding` to fix them:
-
-```
-/dev-review
-    ↓
-Issues found?
-├── No → Pass ✅ → Suggest /dev-changelog
-└── Yes → Offer to fix
-        ↓
-    "1 important issue found. Fix now?"
-    ├── Yes → Load /dev-coding with fix context
-    │         ↓
-    │         Fix applied
-    │         ↓
-    │         Re-run /dev-review (auto)
-    └── No → Output review, user fixes manually
-```
-
-### Fix Flow
+**4. Report:**
 
 ```markdown
-**Review found issues:**
-
-| # | Severity | File | Issue |
-|---|----------|------|-------|
-| 1 | 🟡 Important | LoginForm.tsx:34 | Promise rejection not handled |
-| 2 | 🔵 Suggestion | api.ts:12 | Generic variable name |
-
-**Options:**
-- A: Fix important issues automatically (1 issue)
-- B: Fix all issues automatically (2 issues)
-- C: I'll fix manually
+## BRD Coverage Report: {feature}
+
+| UC | Title | Status | Evidence |
+|----|-------|--------|----------|
+| UC-PAY-001 | Checkout | ✅ Covered | src/api/checkout.ts, src/components/Checkout.tsx |
+| UC-PAY-002 | Refund | ⚠️ Partial | API done, UI missing |
+| UC-PAY-004 | Invoice | ❌ Not covered | No related changes |
+
+### Summary
+- **Covered**: 3/5 UCs
+- **Partial**: 1/5 UCs
+- **Not covered**: 1/5 UCs
 ```
 
-**If user chooses A or B:**
-
-```
-1. Load /dev-coding skill
-   → Pass: files to fix, issues to address
+**5. Recommendation:**
+- All covered → "BRD requirements fully addressed"
+- Gaps exist → "X UCs not covered. Run `/dev-specs` + `/dev-coding` for missing UCs"
 
-2. /dev-coding applies fixes
-   → Uses existing patterns from scout
-   → Follows spec requirements
+## Fix Loop
 
-3. Auto re-run /dev-review
-   → Verify fixes applied correctly
-   → Check for new issues introduced
+When issues found, offer to fix via `/dev-coding`. See `references/review-examples.md` for detailed fix loop flow.
 
-4. If pass → Suggest /dev-changelog
+```
+Issues found? → Offer fix → /dev-coding (fix) → /dev-review (re-run) → Pass → /dev-changelog
 ```
 
-## After Pass: Changelog
-
-When review passes (no critical/important issues):
-
-```markdown
-## Review Complete ✅
-
-**Verdict**: Approved
-
-No critical or important issues found.
+## After Pass
 
-**Next Steps:**
-1. Run `/dev-changelog` to document what was built
-2. Commit and push changes
-3. Create PR
-
-💡 Run `/dev-changelog {feature}` to create implementation summary.
-```
+When review passes: suggest `/dev-changelog {feature}` to document what was built.
 
 ## Integration
 
 | Skill | Relationship |
 |-------|--------------|
-| `/dev-coding` | Review after implementation |
-| `/dev-coding` | Call to fix issues (fix loop) |
+| `/dev-coding` | Review after implementation, call to fix issues |
 | `/dev-scout` | Get project conventions |
 | `/dev-specs` | Check spec compliance |
 | `/dev-changelog` | Document after pass |
 
-## Complete Flow
+## References
 
-```
-/dev-coding → /dev-test → /dev-review
-                              │
-                    ┌─────────┴─────────┐
-                    │   Issues found?   │
-                    └─────────┬─────────┘
-                              │
-              ┌───────────────┼───────────────┐
-              ↓               ↓               ↓
-         Critical        Important        None
-              │               │               │
-              ↓               ↓               ↓
-         Must fix        Offer fix       Pass ✅
-              │               │               │
-              └───────┬───────┘               │
-                      ↓                       │
-              /dev-coding (fix)               │
-                      ↓                       │
-              /dev-review (re-run)            │
-                      ↓                       │
-                    Pass ────────────────────→│
-                                              ↓
-                                    /dev-changelog
-                                              ↓
-                                    summary.md created
-```
+- `references/stack-checks.md` - Framework-specific review checklists
+- `references/review-examples.md` - Examples, fix loop, best practices

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

@@ -0,0 +1,160 @@
+# Review Examples & Patterns
+
+## Review Best Practices
+
+### Be Constructive
+
+```markdown
+// BAD
+"This code is bad"
+
+// GOOD
+"This could cause a SQL injection. Consider using parameterized queries:
+```sql
+SELECT * FROM users WHERE id = $1
+```"
+```
+
+### Explain Why
+
+```markdown
+// BAD
+"Don't use var"
+
+// GOOD
+"Use const/let instead of var - var has function scope which can lead to
+unexpected behavior. const also signals intent that the value won't change."
+```
+
+### Suggest Alternatives
+
+```markdown
+// Issue + Solution
+"The N+1 query here will cause performance issues with many posts.
+
+Consider using an include/join:
+```typescript
+const posts = await db.posts.findMany({
+  include: { author: true }
+});
+```"
+```
+
+### Acknowledge Good Work
+
+```markdown
+### Positives
+- Clean separation of API and business logic
+- Good error messages for users
+- Comprehensive input validation
+```
+
+## Example Review
+
+```
+User: /dev-review UC-AUTH-001
+
+Step 1: Load Context
+- Read tech-context.md → Stack: Next.js 14 + TypeScript
+- Read knowledge/stacks/nextjs/_index.md → "For /dev-review" section
+  → Check Server Actions, App Router, Server Components
+- Read knowledge/stacks/react/_index.md → "For /dev-review" section
+  → Check Hooks, state management, performance
+- Read _quality-attributes.md → All level checklists
+- Read UC-AUTH-001 spec → Requirements
+- Get git diff → Changed files
+
+Step 2: Analyze
+- src/api/auth/login.ts: Clean ✓
+- src/components/LoginForm.tsx: 1 issue (React hooks deps missing)
+- src/lib/api.ts: 1 suggestion (naming)
+
+Step 3: Generate Report
+
+## Review Summary
+
+**Verdict**: ⚠️ Request Changes
+
+**Stats**: 3 files, +245 additions, -12 deletions
+
+### Issues Found
+
+#### 🔴 Critical
+None
+
+#### 🟡 Important
+- [error-handling] `src/components/LoginForm.tsx:34`
+  Promise rejection not handled. If API fails, user sees nothing.
+  ```tsx
+  // Add error state
+  .catch(err => setError(err.message))
+  ```
+
+#### 🔵 Suggestions
+- [naming] `src/lib/api.ts:12`
+  `data` is generic. Consider `credentials` for clarity.
+
+### Spec Compliance
+- [x] POST /api/auth/login works
+- [x] Returns token
+- [x] Validates input
+- [ ] Missing: Rate limiting (spec requirement)
+
+### Positives
+- Good validation on both client and server
+- Clean component structure
+- Proper TypeScript types
+```
+
+## Fix Loop
+
+When issues are found, `/dev-review` can trigger `/dev-coding` to fix them:
+
+```
+/dev-review
+    ↓
+Issues found?
+├── No → Pass ✅ → Suggest /dev-changelog
+└── Yes → Offer to fix
+        ↓
+    "1 important issue found. Fix now?"
+    ├── Yes → Load /dev-coding with fix context
+    │         ↓
+    │         Fix applied
+    │         ↓
+    │         Re-run /dev-review (auto)
+    └── No → Output review, user fixes manually
+```
+
+### Fix Flow
+
+```markdown
+**Review found issues:**
+
+| # | Severity | File | Issue |
+|---|----------|------|-------|
+| 1 | 🟡 Important | LoginForm.tsx:34 | Promise rejection not handled |
+| 2 | 🔵 Suggestion | api.ts:12 | Generic variable name |
+
+**Options:**
+- A: Fix important issues automatically (1 issue)
+- B: Fix all issues automatically (2 issues)
+- C: I'll fix manually
+```
+
+**If user chooses A or B:**
+
+```
+1. Load /dev-coding skill
+   → Pass: files to fix, issues to address
+
+2. /dev-coding applies fixes
+   → Uses existing patterns from scout
+   → Follows spec requirements
+
+3. Auto re-run /dev-review
+   → Verify fixes applied correctly
+   → Check for new issues introduced
+
+4. If pass → Suggest /dev-changelog
+```

package/skills/dev-review/references/stack-checks.md

@@ -0,0 +1,45 @@
+# Stack-Specific Review Checklists
+
+Load the relevant checklist based on stack detected in `tech-context.md`. Also load `knowledge/stacks/{stack}/_index.md` "For /dev-review" section for deeper patterns.
+
+## React
+
+- Hooks follow Rules of Hooks (no conditional calls, correct order)
+- All dependencies included in useEffect/useCallback/useMemo
+- No infinite loops, no stale closures
+- State updates are immutable
+- Performance optimizations appropriate (memo, lazy)
+- Lists have stable keys
+
+## Vue 3
+
+- Uses `<script setup>` (not Options API)
+- Composables follow naming convention (use*)
+- No destructuring reactive without toRefs
+- ref() accessed with .value in script (not in template)
+- v-for has unique :key
+- No v-for + v-if on same element
+- Props not mutated directly
+
+## Next.js
+
+- Server vs Client Components used correctly
+- Server Actions have "use server" directive
+- Data fetching uses proper Next.js patterns
+- No client-side code in Server Components
+
+## Nuxt
+
+- Composables follow naming convention (useX)
+- Server routes in correct location
+- Auto-imports used correctly
+- SSR-safe code (no window access in setup)
+
+## Directus
+
+- Collections accessed properly
+- Permissions configured
+- Field types match requirements
+- Flows and hooks follow patterns
+
+**If stack knowledge file doesn't exist**, apply general best practices only.

package/skills/dev-scout/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-scout
-description: Discover and document how the codebase works - patterns, rules, and team conventions
-version: 3.0.0
+description: Discover and document how the codebase works - patterns, rules, and team conventions. Use when: (1) Before implementation to understand existing code, (2) Onboarding to a new codebase, (3) Documenting team patterns and architecture, (4) Understanding how a specific feature is implemented
+version: 3.1.0
 ---
 
 # /dev-scout - Codebase Pattern Discovery

package/skills/dev-specs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-specs
-description: Generate lean implementation specifications from BRD use cases
-version: 2.0.1
+description: Generate lean implementation specifications from BRD use cases. Use when: (1) BRD/use cases exist and implementation planning needed, (2) Before starting coding on a feature, (3) Onboarding engineers to a feature's technical scope
+version: 2.1.0
 ---
 
 # /dev-specs - Lean Implementation Specifications
@@ -51,20 +51,6 @@ Specs define **requirements and constraints**, not implementation details.
 2. `plans/features/{feature}/` exists
 3. `plans/brd/tech-context.md` exists (auto-runs scout if missing)
 
-## Output Structure
-
-```
-plans/features/{feature}/
-├── codebase-context.md          # From /dev-scout
-└── specs/
-    ├── README.md                # Index, implementation order
-    ├── shared/                  # Shared across UCs
-    │   ├── data-model.md
-    │   ├── patterns.md
-    │   └── security.md
-    └── UC-XXX-001-slug.md       # Lean spec per UC (~150 lines)
-```
-
 ## Expected Outcome
 
 **Lean specs** (~150 lines per UC) that define **WHAT to build**, not HOW.