@codihaus/claude-skills 1.6.5 → 1.6.7

package/skills/dev-specs/references/spec-template.md

@@ -0,0 +1,146 @@
+# UC Spec Template
+
+## Principle
+
+**Include:** Requirements (testable), technical constraints, acceptance criteria, file checklist
+**Exclude:** Pseudocode, detailed HOW, code examples (reference patterns instead)
+**Length:** ~150 lines max per UC
+
+---
+
+## Structure
+
+```markdown
+# UC-{GROUP}-{NNN}: {Title}
+
+> **Feature**: [[feature-{feature}]]
+> **BRD**: [[uc-{group}-{nnn}]]
+> **Status**: Draft
+> **Spec Type**: Lean (Requirements-focused)
+
+## Context
+
+{2-3 sentences on what this UC implements and why}
+
+**Links:**
+- Use Case: [UC-{GROUP}-{NNN}](../../brd/use-cases/{feature}/UC-{GROUP}-{NNN}-{slug}.md)
+- Codebase Context: [codebase-context.md](../codebase-context.md)
+
+## Requirements
+
+**Must Have:**
+- [ ] {testable requirement}
+- [ ] {testable requirement}
+
+**Should Have:**
+- [ ] {nice-to-have}
+
+**Must Not:**
+- [ ] {what should NOT happen}
+
+## Technical Constraints
+
+**Stack & Patterns** (from tech-context.md):
+- API Layer: {use X pattern}
+- Data Access: {use Y method}
+- Client Pattern: {use Z}
+- Validation: {where schemas go}
+- Forms: {which library}
+
+**Code Location:**
+- Primary location: `{path}`
+- Related files: `{paths}`
+- Follow pattern: `{reference file}`
+
+**External Dependencies:**
+{if applicable}
+
+**Constraints:**
+{performance/security/business rules}
+
+## Acceptance Criteria
+
+**Happy Path:**
+- [ ] Given {condition}, When {action}, Then {outcome}
+
+**Error Cases:**
+- [ ] Given {invalid}, When {action}, Then {error shown}
+
+**Edge Cases:**
+- [ ] Given {edge}, When {action}, Then {behavior}
+
+## Files to Modify
+
+**New Files:**
+- [ ] `{path}` - {purpose}
+
+**Modified Files:**
+- [ ] `{path}` - {what changes}
+
+**Reference Pattern:**
+- See `{existing file}` for similar implementation
+
+## API Contract (if applicable)
+
+**Endpoint:** `{METHOD} {path}`
+
+**Request:**
+```json
+{
+  "field": "type"
+}
+```
+
+**Response (Success):**
+```json
+{
+  "field": "type"
+}
+```
+
+**Response (Error):**
+| Status | Reason | Body |
+|--------|--------|------|
+| 400 | | |
+| 401 | | |
+
+## Test Checklist
+
+**Unit Tests:**
+- [ ] {what to test} in `{file}.test.ts`
+
+**Integration Tests:**
+- [ ] {scenario} - {expected outcome}
+
+**E2E Tests** (if applicable):
+- [ ] {user flow} - {expected result}
+
+## Dependencies
+
+**Must Exist Before Implementation:**
+- [ ] {dependency}
+
+**Blocks:**
+- [ ] [[uc-{group}-{nnn}]] - {why}
+
+## Implementation Notes
+
+**DO:**
+- {guidance}
+
+**DON'T:**
+- {anti-pattern}
+
+**Watch Out For:**
+- {gotcha}
+```
+
+---
+
+## Key Rules
+
+1. **No pseudocode** - requirements and constraints only
+2. **Reference patterns** - don't rewrite them
+3. **Testable criteria** - every requirement maps to a test
+4. **Stack-aware** - uses tech-context.md for correct approach
+5. **Scannable** - read in 2-3 minutes

package/src/utils/config.js

@@ -49,7 +49,7 @@ const DEFAULT_SETTINGS = {
         hooks: [
           {
             type: "command",
-            command: "jq -r '.tool_input.file_path // empty' | { read file_path; if [ -n \"$file_path\" ] && echo \"$file_path\" | grep -q 'plans/.*\\.md$'; then bash .claude/scripts/safe-graph-update.sh \"$file_path\" 2>/dev/null || true; fi; }"
+            command: "jq -r '.tool_input.file_path // empty' | { read file_path; if [ -n \"$file_path\" ] && echo \"$file_path\" | grep -q 'plans/.*\\.md$'; then python3 .claude/scripts/graph.py --check-path \"$file_path\" 2>/dev/null || true; fi; }"
           }
         ]
       }
@@ -57,13 +57,14 @@ const DEFAULT_SETTINGS = {
   }
 };
 
-// Hooks are now configured in settings.json (see DEFAULT_SETTINGS)
+// Hooks are configured in BOTH settings.json AND settings.local.json
+// settings.json = team-shared (checked in), settings.local.json = personal (gitignored)
+// Claude Code merges them, with settings.local.json taking precedence
 
 /**
  * Set up Claude Code settings
- * Creates TWO files:
- * - settings.json (with hooks, checked into git)
- * - settings.local.json (with permissions, gitignored)
+ * Creates BOTH settings.json (with hooks for team) AND settings.local.json (with hooks+permissions)
+ * This ensures hooks work regardless of which file Claude Code prioritizes
  */
 export async function setupSettings(projectPath, options = {}) {
   const claudePath = path.join(projectPath, '.claude');
@@ -72,23 +73,20 @@ export async function setupSettings(projectPath, options = {}) {
 
   await fs.ensureDir(claudePath);
 
-  // Create settings.json with hooks (for team, checked in)
-  const settingsJsonContent = {
+  // Create settings.json with hooks (for team, checked into git)
+  const settingsJson = {
     hooks: DEFAULT_SETTINGS.hooks
   };
+  await fs.writeJson(settingsPath, settingsJson, { spaces: 2 });
 
-  await fs.writeJson(settingsPath, settingsJsonContent, { spaces: 2 });
-
-  // Create/update settings.local.json with permissions (personal, gitignored)
-  let localSettings = {
-    permissions: DEFAULT_SETTINGS.permissions
-  };
+  // Create/merge settings.local.json with hooks + permissions (personal, gitignored)
+  let settingsLocal = DEFAULT_SETTINGS;
 
   // Merge with existing if present
   if (await fs.pathExists(settingsLocalPath)) {
     try {
       const existing = await fs.readJson(settingsLocalPath);
-      localSettings = {
+      settingsLocal = {
         permissions: {
           allow: [...new Set([
             ...(existing.permissions?.allow || []),
@@ -98,24 +96,25 @@ export async function setupSettings(projectPath, options = {}) {
             ...(existing.permissions?.deny || []),
             ...(DEFAULT_SETTINGS.permissions?.deny || [])
           ])]
-        }
+        },
+        hooks: DEFAULT_SETTINGS.hooks
       };
     } catch (e) {
       // Invalid JSON, use defaults
     }
   }
 
-  await fs.writeJson(settingsLocalPath, localSettings, { spaces: 2 });
+  await fs.writeJson(settingsLocalPath, settingsLocal, { spaces: 2 });
 
   return {
     settingsPath,
     settingsLocalPath,
-    settings: { ...settingsJsonContent, ...localSettings }
+    settings: settingsLocal
   };
 }
 
 /**
- * Set up hook scripts (hooks config is in settings.json)
+ * Set up hook scripts (hooks config is in both settings.json and settings.local.json)
  */
 export async function setupHooks(projectPath, options = {}) {
   if (options.noHooks) return null;

package/templates/HOOK_TRIGGER_TEST.md

@@ -124,11 +124,11 @@ After running `npx @codihaus/claude-skills init`, verify:
 
 ```bash
 # Check hook configuration
-cat .claude/hooks.json | jq '.postToolUse[0].matcher.path'
-# Should output: "plans/**/*.md"
+cat .claude/settings.json | jq '.hooks.PostToolUse[0].matcher'
+# Should output: "Write|Edit"
 
-cat .claude/hooks.json | jq '.postToolUse[0].command'
-# Should output: "bash .claude/scripts/safe-graph-update.sh $PATH"
+cat .claude/settings.json | jq '.hooks.PostToolUse[0].hooks[0].command'
+# Should contain: "bash .claude/scripts/safe-graph-update.sh"
 
 # Test the safe wrapper script
 bash .claude/scripts/safe-graph-update.sh plans/brd/README.md

package/templates/hooks-guide.md

@@ -17,34 +17,34 @@ Hooks allow you to run commands automatically in response to Claude Code events.
 
 ## Best Practices
 
-### 1. Always Add Retry Limits
+### 1. Correct Hook Structure
+
+Hooks go in `.claude/settings.json`:
 
 ```json
 {
-  "postToolUse": [{
-    "matcher": {
-      "toolName": "Write|Edit",
-      "path": "plans/**/*.md"
-    },
-    "command": "bash .claude/scripts/safe-graph-update.sh $PATH",
-    "retries": {
-      "maxAttempts": 3,
-      "backoff": "exponential",
-      "failureAction": "warn"
-    },
-    "timeout": 5000
-  }]
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path // empty' | { read file_path; if [ -n \"$file_path\" ] && echo \"$file_path\" | grep -q 'plans/.*\\.md$'; then bash .claude/scripts/safe-graph-update.sh \"$file_path\" 2>/dev/null || true; fi; }"
+          }
+        ]
+      }
+    ]
+  }
 }
 ```
 
-**Key Fields:**
-- `maxAttempts`: Stop after N failures (recommended: 2-3)
-- `backoff`: Wait strategy ("none", "linear", "exponential")
-- `failureAction`: What to do after max attempts
-  - `"warn"` - Show warning, continue (recommended)
-  - `"error"` - Stop and ask user for help
-  - `"ignore"` - Silent failure (not recommended)
-- `timeout`: Kill hook after N milliseconds (recommended: 5000-10000)
+**Key Points:**
+- Hooks are in `settings.json` (checked into git for team)
+- Command uses bash subshell with `read` to capture file path
+- Includes `|| true` for graceful failure (non-blocking)
+- Filters to only run on `plans/**/*.md` files
+- Redirects stderr with `2>/dev/null` to avoid noise
 
 ### 2. Make Commands Fail Gracefully
 
@@ -161,7 +161,7 @@ fi
 timeout 10s python3 .claude/scripts/graph.py --check-path "$1" || true
 ```
 
-Then in hooks.json:
+Then in settings.json:
 ```json
 {
   "command": "bash .claude/scripts/safe-graph-update.sh $PATH"
@@ -251,7 +251,7 @@ To temporarily disable a problematic hook:
 }
 ```
 
-Or delete `.claude/hooks.json` entirely (hooks are optional).
+Or delete `.claude/settings.json` entirely (hooks are optional).
 
 ## Example: Robust Hook Configuration
 

package/templates/scripts/safe-graph-update.sh

@@ -13,7 +13,9 @@ set -e
 
 # Configuration
 TIMEOUT_SECONDS=10
-GRAPH_SCRIPT=".claude/scripts/graph.py"
+# Get the directory where this script is located
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+GRAPH_SCRIPT="$SCRIPT_DIR/graph.py"
 MAX_RETRIES=0  # Let Claude Code handle retries
 
 # Colors for output (optional)

package/skills/dev-coding-backend/SKILL.md

@@ -1,240 +0,0 @@
----
-name: dev-coding-backend
-description: Backend implementation patterns and workflows
-version: 2.1.0
----
-
-# /dev-coding-backend - Backend Implementation
-
-> **Loaded by**: `/dev-coding` when API/schema work needed
-> **After**: Frontend uses API contract documented here
-
-Backend-specific workflow for API, schema, and data layer implementation.
-
-## Fundamentals (MUST READ FIRST)
-
-**Before implementing, understand the principles:**
-
-→ Read `references/fundamentals.md`
-
-This covers:
-- **Core Mindset**: "Guardian of truth, trust nothing, enforce rules"
-- **7 Principles**: Separation of Concerns, Single Source of Truth, Don't Repeat Work, Don't Make Users Wait, Don't Trust Anyone, Plan for Failure, Stateless Design
-- **Pattern Recognition**: When to use Service Layer, Repository, Queue, Cache, Circuit Breaker, etc.
-- **Architecture Layers**: Route → Service → Domain → Repository → Infrastructure
-
-**Key Decision**: For each piece of code, ask "which principle applies?" Then choose the pattern that principle suggests.
-
-## Knowledge Loading (CRITICAL)
-
-Before implementing, load relevant knowledge:
-
-```
-1. Read stack.md → plans/scout/stack.md
-   → Identify: API layer, SDK, data access method
-
-2. Load stack knowledge based on detected tech:
-   | If using...  | Read...                           | Section           |
-   |--------------|-----------------------------------|-------------------|
-   | Directus     | knowledge/stacks/directus/_index.md  | "For /dev-coding" |
-   | Nuxt server  | knowledge/stacks/nuxt/_index.md      | "Server Routes"   |
-   | Next.js API  | knowledge/stacks/nextjs/_index.md    | "API Routes"      |
-
-3. Load domain knowledge (if applicable):
-   | If domain... | Read...                            | Section           |
-   |--------------|-----------------------------------|-------------------|
-   | SaaS         | knowledge/domains/saas/_index.md      | Billing, Multi-tenant |
-   | E-commerce   | knowledge/domains/ecommerce/_index.md | Orders, Payments  |
-
-4. Use loaded knowledge for:
-   → Correct SDK usage (not raw fetch)
-   → Domain-specific validation rules
-   → Stack-specific error handling
-```
-
-## Workflow
-
-### Step 1: Extract Backend Requirements
-
-From UC spec, identify:
-
-```
-[ ] Schema changes?
-    → New collections/tables
-    → New fields
-    → Relations
-
-[ ] API endpoints?
-    → Method + Path
-    → Request/Response shape
-    → Auth required?
-
-[ ] Business logic?
-    → Validation rules
-    → Side effects (emails, webhooks)
-
-[ ] External integrations?
-    → Third-party APIs
-    → File storage
-```
-
-### Step 2: Schema First
-
-**Order:** Schema → API → Logic
-
-```
-1. Design schema based on spec
-2. Create/modify collections or tables
-3. Set up relations
-4. Configure permissions
-5. Verify schema works
-```
-
-### Step 3: API Implementation
-
-For each endpoint:
-
-```
-1. Create route/handler
-2. Parse request
-3. Validate input
-4. Implement logic
-5. Handle errors
-6. Return response
-```
-
-**Follow project patterns** from scout (file locations, naming, error format).
-
-### Step 4: Essential Patterns
-
-#### Request Validation (always do this)
-
-```typescript
-const schema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8),
-});
-
-const result = schema.safeParse(req.body);
-if (!result.success) {
-  return res.status(400).json({
-    error: 'Validation failed',
-    details: result.error.issues
-  });
-}
-```
-
-#### Error Response Format
-
-```typescript
-// Consistent format
-{ "error": "Message", "code": "ERROR_CODE" }
-
-// Status codes
-200 - Success       400 - Bad request
-201 - Created       401 - Unauthorized
-                    403 - Forbidden
-                    404 - Not found
-                    500 - Server error
-```
-
-#### Auth Check
-
-```typescript
-if (!req.user) {
-  return res.status(401).json({ error: 'Unauthorized' });
-}
-if (!hasPermission(req.user, 'create:posts')) {
-  return res.status(403).json({ error: 'Forbidden' });
-}
-```
-
-### Step 5: Verify
-
-```bash
-# Test endpoint
-curl -X POST http://localhost:3000/api/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"test@test.com","password":"password123"}'
-```
-
-Checklist:
-```
-[ ] Endpoint responds
-[ ] Correct status codes
-[ ] Validation rejects bad input
-[ ] Auth works correctly
-[ ] Response matches spec
-```
-
-### Step 6: Document for Frontend
-
-```markdown
-## API Ready
-
-### POST /api/auth/login
-- **Auth**: None
-- **Request**: `{ email, password }`
-- **Success (200)**: `{ token, user }`
-- **Errors**: 400 (invalid), 401 (wrong creds)
-```
-
-## Security Checklist
-
-```
-[ ] Input validated (Zod/Yup)
-[ ] Parameterized queries (no SQL injection)
-[ ] Auth on protected routes
-[ ] Permissions verified
-[ ] Passwords hashed
-[ ] Secrets in env vars
-[ ] No sensitive data in logs
-```
-
-## Quick Debugging
-
-```bash
-# Server running?
-curl http://localhost:3000/health
-
-# Database connected?
-npx prisma db pull  # or check logs
-
-# Token valid?
-curl http://localhost:3000/api/me -H "Authorization: Bearer $TOKEN"
-```
-
-## Stack-Specific Patterns
-
-**Do not implement generic patterns. Load from stacks/:**
-
-| Stack | What to load | Key patterns |
-|-------|--------------|--------------|
-| Directus | `stacks/directus/` | SDK queries, permissions, hooks |
-| Prisma | `stacks/prisma/` (future) | ORM patterns, migrations |
-| Supabase | `stacks/supabase/` (future) | RLS, auth, realtime |
-
-**Example - if using Directus:**
-```
-1. Read knowledge/stacks/directus/_index.md
-2. Use ItemsService (not raw SQL)
-3. Follow permission patterns
-4. Use SDK for queries
-```
-
-## Domain-Specific Logic
-
-**Load from domains/ when applicable:**
-
-| Domain | What to load | Key patterns |
-|--------|--------------|--------------|
-| SaaS | `domains/saas/_index.md` | Subscription states, billing |
-| E-commerce | `domains/ecommerce/_index.md` | Order lifecycle, inventory |
-
-**Example - SaaS billing endpoint:**
-```
-1. Read knowledge/domains/saas/_index.md
-2. Follow subscription state machine
-3. Handle trial → paid → cancelled states
-4. Validate against billing rules
-```