@codihaus/claude-skills 1.6.14 → 1.6.16

package/package.json

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

package/skills/_registry.md

@@ -115,7 +115,10 @@ During each skill, consider suggesting:
 
 ### /dev-coding
 - Before: Ensure `/dev-specs` completed
-- During: Auto-loads `/dev-coding-backend` or `/dev-coding-frontend`
+- Reads (Three Layers):
+  1. Universal principles: `references/backend-principles.md`, `frontend-principles.md`
+  2. Framework patterns: `knowledge/stacks/{stack}/_index.md` (detected from tech-context.md)
+  3. Project specifics: `tech-context.md`, `codebase-context.md`
 - Reads: `_quality-attributes.md` for implementation-level checklists
 - After: Auto-triggers `/dev-test` to verify implementation
 - After test: "Use `/dev-review` to review changes"
@@ -190,10 +193,11 @@ stacks/{name}/
 ```
 
 **How it works:**
-1. `/dev-scout` detects stack → writes `stack.md`
-2. `/dev-specs` reads `stack.md` → loads `stacks/{name}/_index.md`
-3. Uses "For /dev-specs" section for correct patterns
-4. Deep patterns in `references/`, templates in `assets/`
+1. `/dev-scout` detects stack → writes `tech-context.md` with stack info
+2. `/dev-specs` reads tech-context.md → loads `stacks/{name}/_index.md` → uses "For /dev-specs" section
+3. `/dev-coding` reads tech-context.md → loads `stacks/{name}/_index.md` → uses "For /dev-coding" section
+4. `/dev-review` reads tech-context.md → loads `stacks/{name}/_index.md` → uses "For /dev-review" section
+5. Deep patterns in `references/`, templates in `assets/`
 
 ### Domain Knowledge (`knowledge/domains/`)
 

package/skills/dev-coding/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: dev-coding
 description: Implement features as a Principal Engineering Developer
-version: 2.0.0
+version: 2.1.1
 ---
 
 # /dev-coding - Implementation Skill
 
 > **Skill Awareness**: See `skills/_registry.md` for all available skills.
 > - **Before**: Ensure `/dev-specs` completed
-> - **Reads**: Principles (references/), project specifics (tech-context.md), requirements (specs)
+> - **Reads**: Universal principles (references/), framework patterns (knowledge/stacks/), project specifics (tech-context.md), requirements (specs)
 > - **After**: Auto-triggers `/dev-test` to verify implementation
 > - **Review**: Suggest `/dev-review` for code review
 
-Work as a **Principal Engineering Developer**: apply universal principles with project-specific implementation.
+Work as a **Principal Engineering Developer**: apply three-layer knowledge (universal + framework + project-specific).
 
 ## When to Use
 
@@ -29,25 +29,50 @@ Work as a **Principal Engineering Developer**: apply universal principles with p
 
 ## Role: Principal Engineering Developer
 
-You have universal engineering principles and apply them to this specific project.
+You have three layers of knowledge to apply:
+
+**1. Universal Principles** (references/)
+- General software engineering wisdom
+- `backend-principles.md` - API, data, security
+- `frontend-principles.md` - UI, component, state
+
+**2. Framework-Specific Patterns** (knowledge/stacks/)
+- Best practices for detected stack (Next.js, Nuxt, Directus, etc.)
+- Framework conventions and patterns
+- Anti-patterns to avoid
+
+**3. Project-Specific Implementation** (tech-context.md)
+- How THIS project implements the patterns
+- Project conventions and standards
+- Existing code patterns
 
 **Workflow:**
-1. Load principles (references/) + project specifics (tech-context.md)
+1. Load three layers of knowledge
 2. Discover details just-in-time (Glob/Grep/Read as needed)
-3. Apply principles based on what requirement needs
+3. Apply all layers based on what requirement needs
 4. Validate against acceptance criteria
 
-**Principles:**
-- See `references/backend-principles.md` for API, data, security principles
-- See `references/frontend-principles.md` for UI, component, state principles
-- See `tech-context.md` for how THIS project implements them
-
 ## Prerequisites
 
 1. `/dev-specs {feature}` completed → specs exist
 2. `plans/brd/tech-context.md` exists → patterns known
 3. `plans/features/{feature}/codebase-context.md` exists (optional, helpful)
 
+## CRITICAL: Always Load Stack Knowledge
+
+**BEFORE implementing any feature:**
+
+1. **Read `plans/brd/tech-context.md`** → Identify stack(s)
+2. **Read `knowledge/stacks/{stack}/_index.md`** → Load framework patterns
+3. **Focus on "For /dev-coding" section** → Note best practices
+
+**Stack file mapping:**
+- "Next.js" → `knowledge/stacks/nextjs/_index.md`
+- "Nuxt" → `knowledge/stacks/nuxt/_index.md`
+- "Directus" → `knowledge/stacks/directus/_index.md`
+
+**If you skip this step**, you'll implement using generic patterns instead of framework-specific best practices (e.g., using fetch instead of Server Actions in Next.js).
+
 ## Expected Outcome
 
 Implemented feature that meets all acceptance criteria from spec.
@@ -55,36 +80,34 @@ Implemented feature that meets all acceptance criteria from spec.
 **What "done" looks like:**
 - All requirements from spec completed
 - All acceptance criteria pass
-- Patterns from tech-context.md followed
-- Files from spec checklist created/modified
+- Framework patterns (from knowledge/stacks/) followed
+- Project patterns (from tech-context.md) followed
+- Universal principles (from references/) applied
 - No security vulnerabilities
 - Tests passing (if applicable)
 - Code quality maintained
 
-## Role: Principal Engineering Developer
+## Implementation Approach
 
-You have universal engineering knowledge and apply it to this specific project.
+**1. Load Context (once):**
 
-**You know:**
-- Universal principles (references/backend-principles.md, frontend-principles.md)
-- Project-specific patterns (tech-context.md)
-- Business requirements (specs/*.md)
-- How to verify success (acceptance criteria)
+**Step 1: Read spec**
+- Get requirements, acceptance criteria, work area
 
-**You can:**
-- Discover details just-in-time (Glob/Grep/Read as needed)
-- Apply principles based on what requirement needs
-- Validate against acceptance criteria
-- Fix and iterate until passing
+**Step 2: Detect and load stack knowledge**
+- Read `plans/brd/tech-context.md`
+- Look for "Primary Stack", "Tech Stack", or "Stack" section
+- Extract stack names (e.g., "Next.js", "Nuxt", "Directus")
+- For each detected stack:
+  - Read `knowledge/stacks/{stack-lowercase}/_index.md` (e.g., `nextjs`, `nuxt`, `directus`)
+  - Focus on "For /dev-coding" section
+  - Note best practices, patterns, anti-patterns
+- If stack knowledge file doesn't exist, note it and continue
 
-## Implementation Approach
-
-**1. Load Context (once):**
-- Read spec → Get requirements, acceptance criteria, files to modify
-- Read tech-context.md → Get project patterns (API, data, UI, validation, etc.)
-- Read codebase-context.md → Get feature-specific implementation
-- Read architecture.md (if exists) → Get architecture decisions
-- Load universal principles (references/) as needed
+**Step 3: Load universal and project specifics**
+- Read `plans/features/{feature}/codebase-context.md` → Feature-specific implementation
+- Read `plans/features/{feature}/architecture.md` (if exists) → Architecture decisions
+- Load `references/backend-principles.md` and/or `frontend-principles.md` as needed
 
 **2. Plan Work:**
 - If feature name given (not specific UC): Ask implementation mode
@@ -95,13 +118,13 @@ You have universal engineering knowledge and apply it to this specific project.
 
 **3. Implement (for each requirement):**
 - **Understand:** What to build, where to build it, success criteria
-- **Apply:** Use principles + project patterns based on what requirement needs
-  - API work? → Apply API principles + project's API pattern
-  - UI work? → Apply component principles + project's UI pattern
-  - Data work? → Apply data access principles + project's data pattern
-  - Full-stack? → Apply multiple principles as needed
+- **Apply three layers:** Universal → Framework → Project-specific
+  - API work? → Universal API principles + Framework API patterns (e.g., Server Actions for Next.js) + Project's API pattern
+  - UI work? → Universal component principles + Framework UI patterns (e.g., Server Components) + Project's UI pattern
+  - Data work? → Universal data principles + Framework data patterns (e.g., Prisma, Directus) + Project's data pattern
+  - Full-stack? → Apply all three layers across multiple concerns
 - **Discover:** Find details just-in-time (Glob/Grep/Read)
-- **Build:** Create/modify files following patterns and conventions
+- **Build:** Create/modify files following all three layers
 - **Validate:** Check acceptance criteria, fix if needed
 - **Test:** Write/run tests if applicable
 
@@ -127,21 +150,47 @@ Don't pre-load everything. Discover when needed:
 - ❌ List all components upfront
 - ❌ Memorize function names (look up when needed)
 
-## How Principles Work
+## Three-Layer Knowledge System
 
 ```
-Universal Principles (references/)
+Layer 1: Universal Principles (references/)
+    +
+Layer 2: Framework Patterns (knowledge/stacks/{stack}/)
     +
-Project Specifics (tech-context.md)
+Layer 3: Project Specifics (tech-context.md)
     =
 Implementation
 ```
 
-**Apply what the requirement needs:**
-- API endpoint? → backend-principles.md + tech-context.md (API patterns)
-- UI component? → frontend-principles.md + tech-context.md (component patterns)
-- Form validation? → Both + tech-context.md (validation pattern)
-- Full-stack feature? → Use all as needed
+**How to detect and load stack knowledge:**
+
+1. **Read tech-context.md** and look for stack indicators:
+   ```markdown
+   **Primary Stack**: Next.js + Directus
+   ```
+   or
+   ```markdown
+   ## Tech Stack
+   - Frontend: Nuxt.js 3
+   - Backend: Directus
+   ```
+
+2. **Load stack knowledge files:**
+   - If "Next.js" detected → Read `knowledge/stacks/nextjs/_index.md`
+   - If "Nuxt" detected → Read `knowledge/stacks/nuxt/_index.md`
+   - If "Directus" detected → Read `knowledge/stacks/directus/_index.md`
+
+3. **Focus on "For /dev-coding" section** in each stack file for:
+   - Framework-specific patterns
+   - Best practices
+   - Anti-patterns to avoid
+   - Common gotchas
+
+**Apply all three layers based on requirement:**
+- API endpoint? → Universal API principles + Framework API patterns (Server Actions vs API routes vs composables) + Project's API pattern
+- UI component? → Universal component principles + Framework UI patterns (Server vs Client Components, SFC, etc.) + Project's UI pattern
+- Data access? → Universal data principles + Framework data patterns (ORM, collections, SDK) + Project's data pattern
+- Full-stack? → Apply all three layers across concerns
 
 ## After Implementation
 
@@ -155,29 +204,68 @@ Implementation
 - Commit if requested (follow git conventions from tech-context.md)
 - Continue to next UC (based on implementation mode)
 
-## How Principles Work
+## Example Flow
+
+**Requirement:** "Add password reset endpoint" (Next.js project)
+
+**1. Load Knowledge:**
 
 ```
-Universal Principles (references/)
-    +
-Project Specifics (tech-context.md)
-    =
-Implementation
+Step 1: Read plans/brd/tech-context.md
+→ Found: "Primary Stack: Next.js 14 (App Router)"
+
+Step 2: Read knowledge/stacks/nextjs/_index.md
+→ Section "For /dev-coding":
+  - Use Server Actions for mutations (not Route Handlers)
+  - Server Actions = "use server" directive
+  - Place in lib/actions/
+  - Return structured response {success, error, data}
+
+Step 3: Read references/backend-principles.md
+→ API security: validate input, rate limit, secure tokens
+
+Step 4: Read tech-context.md patterns
+→ Project uses Zod for validation
+→ Project uses nodemailer for emails
+→ Auth actions in lib/actions/auth.ts
 ```
 
-**Apply what the requirement needs:**
-- API work → backend-principles.md + tech-context.md
-- UI work → frontend-principles.md + tech-context.md
-- Both → use both references + tech-context.md
+**2. Discover:**
+```
+Glob: lib/actions/*.ts
+Read: lib/actions/auth.ts (see existing login pattern)
+```
 
-## Example Flow
+**3. Apply Three Layers:**
+- **Universal**: Input validation, secure token (crypto.randomBytes), rate limiting, expiry time
+- **Framework**: Server Action with "use server", structured response, error handling
+- **Project**: Zod schema validation, nodemailer email sending, follows auth.ts pattern
+
+**4. Implement:**
+```typescript
+// lib/actions/auth.ts
+"use server"
+
+export async function resetPassword(email: string) {
+  // Universal: Validation
+  const schema = z.string().email()
+  const validated = schema.parse(email)
 
-**Requirement:** "Add password reset endpoint"
+  // Universal: Generate secure token
+  const token = crypto.randomBytes(32).toString('hex')
 
-1. **Think:** API work → backend-principles.md (validation, security) + tech-context.md (how we do APIs)
-2. **Discover:** Where are endpoints? → Glob, Read similar endpoint
-3. **Implement:** Follow pattern + apply principles
-4. **Validate:** Check acceptance criteria
+  // Project: Store token in DB (project pattern)
+  await db.passwordReset.create({...})
+
+  // Project: Send email (project uses nodemailer)
+  await sendEmail({...})
+
+  // Framework: Server Action response pattern
+  return { success: true, data: { sent: true } }
+}
+```
+
+**5. Validate:** Check acceptance criteria
 
 ## Quality
 
@@ -198,9 +286,10 @@ Apply principles from references/ during implementation. See `_quality-attribute
 ## Anti-Patterns
 
 ❌ Reading every file upfront (discover as needed)
-❌ Categorizing work as "backend" or "frontend" (just apply what's needed)
+❌ Ignoring framework patterns (using fetch when should use Server Actions)
+❌ Skipping any knowledge layer (need all three: universal + framework + project)
+❌ Applying patterns from wrong framework (React patterns in Vue project)
 ❌ Memorizing function names (look them up when needed)
-❌ Ignoring principles (universal + project-specific)
 ❌ Not validating against acceptance criteria (that's success)
 ❌ Pre-loading all components (wasteful, discover when needed)
 
@@ -212,24 +301,49 @@ Apply principles from references/ during implementation. See `_quality-attribute
 **No spec:**
 - Error: "Run /dev-specs {feature} first to create implementation plan"
 
+**Stack not detected:**
+- Load only universal principles + project specifics
+- Note: "No framework-specific patterns loaded"
+
+**Stack knowledge not available:**
+- If `knowledge/stacks/{stack}/` doesn't exist
+- Load only universal principles + project specifics
+- Follow general best practices for that framework
+- Note: "Framework patterns applied from general knowledge"
+
 **Spec references non-existent pattern:**
 - Discover pattern via Grep/Glob
-- If truly doesn't exist, implement following best practices
+- If truly doesn't exist, implement following three-layer approach
 - Note deviation in implementation notes
 
 ## Success Criteria
 
 Implementation successful when:
 - ✅ All acceptance criteria met
-- ✅ All files from checklist created/modified
-- ✅ Patterns from tech-context.md followed
+- ✅ Universal principles applied (security, validation, performance)
+- ✅ Framework patterns followed (Server Actions, composables, etc.)
+- ✅ Project patterns followed (conventions from tech-context.md)
 - ✅ Tests passing (if applicable)
 - ✅ Code quality checks passed
 - ✅ No security vulnerabilities
 
 ## References
 
-- `references/backend-principles.md` - Universal API, data, security principles
-- `references/frontend-principles.md` - Universal UI, component, state principles
+**Layer 1 - Universal:**
+- `references/backend-principles.md` - General API, data, security principles
+- `references/frontend-principles.md` - General UI, component, state principles
+
+**Layer 2 - Framework:**
+- `knowledge/stacks/nextjs/_index.md` - Next.js patterns (Server Actions, App Router, RSC)
+- `knowledge/stacks/nuxt/_index.md` - Nuxt patterns (composables, Nuxt UI, SSR)
+- `knowledge/stacks/directus/_index.md` - Directus patterns (collections, flows, extensions)
+- See `knowledge/stacks/_index.md` for all available stacks
+
+**Layer 3 - Project:**
+- `tech-context.md` - How THIS project implements patterns
+- `codebase-context.md` - Feature-specific implementation details
 
-These provide general software engineering wisdom. Combine with tech-context.md for project-specific implementation.
+**Three-layer approach ensures:**
+- ✅ Solid engineering fundamentals (Layer 1)
+- ✅ Framework best practices (Layer 2)
+- ✅ Project consistency (Layer 3)