@codihaus/claude-skills 1.6.6 → 1.6.8

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/skills/dev-test/SKILL.md

@@ -38,166 +38,88 @@ Automated testing using Playwright to verify implementation works correctly.
 | Visual State | `browser_snapshot` | Render errors, missing elements |
 | Interactions | `browser_click`, `browser_type` | Form failures, broken buttons |
 
-## Workflow
+## Expected Outcome
+
+Test report showing whether implementation works correctly.
+
+**Report includes:**
+- Overall status (Pass/Fail + issue count)
+- Issues found (critical/warning with location + suggested fix)
+- Test steps executed (which passed/failed)
+- Suggested fixes or next actions
+
+## Success Criteria
+
+- No console errors during user flows
+- No network failures (API 4xx/5xx)
+- Expected elements render correctly
+- User interactions work as expected
+- Happy path completes successfully
+- All acceptance criteria from spec verified
+
+## What to Test
+
+**From UC spec:**
+- Expected user flows (happy path)
+- Required inputs and outputs
+- Acceptance criteria
+- Error scenarios (if specified)
+
+**From recent changes:**
+- Modified components/endpoints
+- New functionality added
+
+## Error Detection
+
+| Check | What It Catches |
+|-------|----------------|
+| Console Errors | JS errors, React errors, warnings, unhandled promises |
+| Network Failures | API 4xx/5xx, failed fetches, timeouts |
+| Visual State | Render errors, missing elements, wrong state |
+| Interactions | Form failures, broken buttons, navigation issues |
+
+**Error categories:**
+- 🔴 **Critical:** Breaks functionality, must fix
+- 🟡 **Warning:** Should fix, not blocking
+
+## Test Approach
+
+**1. Prepare:**
+- Identify what to test (from spec + recent changes)
+- Determine test URL (from spec or default: http://localhost:3000)
+- Verify dev server running (prompt if not)
+
+**2. Execute User Flows:**
+- Navigate to page
+- Capture initial state (check page loads, no immediate errors)
+- Execute happy path (fill forms, click buttons, navigate)
+- Wait for expected results
+- Capture final state
+
+**3. Collect Errors:**
+- Console messages (errors, warnings)
+- Network requests (find failures)
+- Visual issues (missing elements)
+
+**4. Report:**
+- Status (pass/fail + count)
+- Issues with severity, location, suggested fix
+- Test steps executed (which passed/failed)
+
+**5. Fix Loop (if --fix):**
+- For each issue: read file, identify fix, apply fix, re-test
+- Continue until fixed or max iterations (3) or needs user input
+- Re-run full test to verify
 
-### Phase 1: Prepare Test Context
-
-```
-1. Identify what to test
-   → From UC spec: expected flows, inputs, outputs
-   → From recent changes: modified components/endpoints
-
-2. Determine test URL
-   → From spec or project config
-   → Default: http://localhost:3000
-
-3. Check if dev server running
-   → Look for existing process on port
-   → If not, prompt user to start it
-```
-
-### Phase 2: Navigate and Capture Initial State
-
-```typescript
-// Navigate to the page
-await mcp__playwright__browser_navigate({
-  url: 'http://localhost:3000/login'
-});
-
-// Wait for page to stabilize
-await mcp__playwright__browser_wait_for({ time: 2 });
-
-// Capture accessibility snapshot (better than screenshot for analysis)
-await mcp__playwright__browser_snapshot({});
-```
-
-**Check for immediate errors:**
-- Page loads without errors
-- Expected elements present
-- No console errors on load
-
-### Phase 3: Test User Flows
-
-From the UC spec, execute the happy path:
-
-```typescript
-// Example: Login flow
-// Step 1: Fill form
-await mcp__playwright__browser_type({
-  element: 'email input',
-  ref: 'input-email',  // From snapshot
-  text: 'test@example.com'
-});
-
-await mcp__playwright__browser_type({
-  element: 'password input',
-  ref: 'input-password',
-  text: 'password123'
-});
-
-// Step 2: Submit
-await mcp__playwright__browser_click({
-  element: 'login button',
-  ref: 'btn-login'
-});
-
-// Step 3: Wait for response
-await mcp__playwright__browser_wait_for({
-  text: 'Dashboard'  // Expected after login
-});
-
-// Step 4: Verify result
-await mcp__playwright__browser_snapshot({});
-```
-
-### Phase 4: Collect Errors
-
-```typescript
-// Get console messages (errors, warnings)
-const console = await mcp__playwright__browser_console_messages({
-  level: 'error'
-});
-
-// Get network requests (find failures)
-const network = await mcp__playwright__browser_network_requests({});
-
-// Filter for issues:
-// - Console: Any error level messages
-// - Network: Status >= 400, or failed requests
-```
-
-**Error Categories:**
-
-| Category | Source | Examples |
-|----------|--------|----------|
-| JS Errors | Console | TypeError, ReferenceError, unhandled promise |
-| React Errors | Console | Component errors, hooks violations |
-| API Errors | Network | 400 Bad Request, 401 Unauthorized, 500 Server Error |
-| Network Errors | Network | Failed to fetch, CORS, timeout |
-| Render Errors | Snapshot | Missing elements, wrong state |
-
-### Phase 5: Generate Report
-
-```markdown
-## Test Report
-
-**Target**: UC-AUTH-001 Login
-**URL**: http://localhost:3000/login
-**Status**: ❌ Failed (3 issues)
-
-### Issues Found
-
-#### 🔴 Critical
-
-1. **API Error**: POST /api/auth/login returned 500
-   - Response: `{"error":"Internal server error"}`
-   - Likely cause: Database connection or missing env var
-   - File: Check `src/app/api/auth/login/route.ts`
-
-2. **Console Error**: Unhandled promise rejection
-   - Message: `Cannot read property 'id' of undefined`
-   - Stack: `LoginForm.tsx:45`
-   - Cause: API response handling when login fails
-
-#### 🟡 Warning
-
-3. **Console Warning**: Missing key prop in list
-   - Component: `ErrorMessages.tsx`
-   - Not critical but should fix
-
-### Test Steps Executed
-
-| Step | Action | Result |
-|------|--------|--------|
-| 1 | Navigate to /login | ✓ Page loaded |
-| 2 | Fill email | ✓ Input accepted |
-| 3 | Fill password | ✓ Input accepted |
-| 4 | Click login | ✗ Error occurred |
-| 5 | Verify dashboard | ⏭ Skipped |
-
-### Suggested Fixes
-
-1. Check database connection in backend
-2. Add error handling in LoginForm.tsx:45
-3. Add key prop to ErrorMessages.tsx list items
-```
+## Test Patterns
 
-### Phase 6: Fix Loop (if --fix)
+Available as reference in original SKILL.md:
+- Form submission
+- Navigation flow
+- API response validation
+- Error state testing
 
-```
-1. For each issue:
-   a. Read the problematic file
-   b. Identify the fix
-   c. Apply the fix
-   d. Re-run failed test step
-
-2. Continue until:
-   - All issues fixed, OR
-   - Max iterations reached (3), OR
-   - Issue requires user input
-
-3. Re-run full test to verify
-```
+Use Playwright MCP tools to interact with browser.
 
 ## Test Patterns
 

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; }"
           }
         ]
       }

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
-```