@codihaus/claude-skills 1.6.5 → 1.6.7

package/skills/dev-specs/SKILL.md

@@ -1,25 +1,23 @@
 ---
 name: dev-specs
-description: Generate implementation specifications from BRD use cases
-version: 1.6.0
+description: Generate lean implementation specifications from BRD use cases
+version: 2.0.0
 ---
 
-# /dev-specs - Implementation Specifications
+# /dev-specs - Lean Implementation Specifications
 
 > **Skill Awareness**: See `skills/_registry.md` for all available skills.
 > - **Before**: Ensure `/debrief` completed (BRD exists)
-> - **Auto**: Runs `/dev-scout` if scout.md missing
-> - **During**: Calls `/dev-arch` for patterns and architecture decisions
+> - **Auto**: Runs `/dev-scout` if `tech-context.md` missing
+> - **During**: Calls `/dev-arch` for patterns
 > - **Reads**: `_quality-attributes.md` (Specification Level)
-> - **Critical**: Reads `stack.md` to use correct SDK, patterns, validation
 > - **After**: Use `/dev-coding` for implementation
 
-Generate precise implementation plans from BRD use cases. Creates per-UC specs with shared components.
+Generate **lean, requirements-focused** specs from BRD use cases. Focuses on WHAT to build, not HOW.
 
 ## When to Use
 
 - After `/debrief` created BRD use cases
-- After `/dev-scout {feature}` analyzed codebase
 - Before starting implementation
 - When onboarding engineers to a feature
 
@@ -32,637 +30,145 @@ Generate precise implementation plans from BRD use cases. Creates per-UC specs w
 /dev-specs payments --schema=schema.prisma   # With DB schema
 ```
 
-## Prerequisites
+## Core Rule: WHAT, Not HOW
 
-Before running, ensure:
-1. `plans/brd/` exists with use cases
-2. `plans/features/{feature}/` exists
+Specs define **requirements and constraints**, not implementation details.
 
-**Note**: Scout is auto-triggered if missing (see Phase 0).
+**Include:**
+- Requirements (testable, bulleted)
+- Technical constraints (stack, location, patterns)
+- Acceptance criteria (testable outcomes)
+- File checklist (where to work)
 
-## Input Files
+**Exclude:**
+- Pseudocode (gets stale)
+- Detailed implementation (discovered during coding)
+- Code examples (reference existing patterns instead)
 
-The skill can accept additional context files:
+## Prerequisites
 
-| Input | Flag | Purpose |
-|-------|------|---------|
-| API Spec | `--api=` | OpenAPI, Swagger, GraphQL schema |
-| DB Schema | `--schema=` | Prisma, SQL, TypeORM entities |
-| Design | `--design=` | Figma link, screenshots path |
-| Docs | `--docs=` | External docs, wikis, READMEs |
-| Env | `--env=` | Credentials for live API testing |
+1. `plans/brd/` exists with use cases
+2. `plans/features/{feature}/` exists
+3. `plans/brd/tech-context.md` exists (auto-runs scout if missing)
 
 ## Output Structure
 
 ```
 plans/features/{feature}/
-├── README.md              # Feature overview
-├── scout.md               # From /dev-scout
-│
+├── codebase-context.md          # From /dev-scout
 └── specs/
-    ├── README.md          # Index, implementation order, dependencies
-    │
-    ├── shared/            # Shared across all UCs
-    │   ├── data-model.md  # Schema changes, entities
-    │   ├── patterns.md    # Code patterns, conventions
-    │   └── security.md    # Auth, validation, permissions
-    │
-    ├── UC-XXX-001-{slug}/ # Per use case
-    │   ├── README.md      # Implementation plan
-    │   ├── changes.md     # Files to create/modify
-    │   └── tests.md       # Test cases
-    │
-    └── UC-XXX-002-{slug}/
-        └── ...
+    ├── 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)
 ```
 
 ## Workflow
 
-### Phase 0: Check Dependencies & Graph Context
-
-Before generating specs, verify prerequisites and gather context:
-
-```
-1. Check: plans/brd/ exists?
-   → No: Error "Run /debrief first"
-
-2. Check: plans/features/{feature}/ exists?
-   → No: Error "Feature not found in BRD"
-
-3. Check: plans/features/{feature}/scout.md exists?
-   → No: Auto-run scout (see below)
-
-4. Read: plans/docs-graph.json
-   → Get related nodes and dependencies
-```
-
-**Auto-Scout Logic:**
-
-If scout.md doesn't exist:
-1. **First check if project-level scout exists:**
-   ```
-   Check: plans/scout/stack.md exists?
-   → No: Run project-level scout FIRST
-      - Notify: "No project scout found, analyzing entire codebase first..."
-      - Execute: /dev-scout (project-level, medium mode)
-      - Output: plans/scout/README.md, structure.md, features.md, stack.md
-      - This provides project-wide context and stack configuration
-   → Yes: Continue to feature scout
-   ```
-
-2. **Then run feature-level scout:**
-   - Notify user: "Running targeted analysis for {feature}..."
-   - Execute scout workflow (medium mode) for the feature
-   - Save to `plans/features/{feature}/scout.md`
-
-3. Continue to Phase 1
-
-**Why project scout first?**
-- `stack.md` tells us HOW to write specs (SDK, patterns, validation)
-- Prevents specs from suggesting wrong approaches (raw fetch vs. SDK)
-- Feature scout can reference project context for better targeting
-
-**Docs-Graph Integration:**
-
-Read `plans/docs-graph.json` to understand:
-
-| What to Find | How It Helps |
-|--------------|--------------|
-| Use cases for feature | Know exactly which UCs to spec (`[[uc-auth-001]]`) |
-| Existing specs | Avoid duplicates, find patterns |
-| Dependencies | UCs that link to each other need coordinated specs |
-| Related features | Cross-feature impacts (`[[feature-billing]]` links) |
-
-**Example graph query for `/dev-specs auth`:**
-```json
-{
-  "feature": "auth",
-  "use_cases": ["uc-auth-001", "uc-auth-002", "uc-auth-003"],
-  "existing_specs": [],
-  "dependencies": {
-    "uc-auth-002": ["uc-auth-001"],  // Signup depends on Login
-    "uc-auth-003": ["uc-auth-001"]   // Forgot depends on Login
-  },
-  "cross_feature": ["feature-billing"]  // Auth linked from billing
-}
-```
-
-This informs:
-- Implementation order (Login first, then Signup/Forgot)
-- Shared components (auth patterns used by billing)
-- What specs are already done vs. needed
-
-### Phase 0.5: Load Quality Attributes
-
-Read specification-level quality checklists:
-
-```
-1. Read skills/_quality-attributes.md
-2. Extract "Specification Level" sections for:
-   - Scalability (pagination, batch ops, indexes)
-   - Maintainability (API design, data model)
-   - Performance (eager/lazy loading, caching)
-   - Security (auth rules, validation)
-   - Reliability (error handling, timeouts)
-   - Testability (test cases, coverage)
-```
-
-These checklists inform spec generation.
-
-### Phase 0.6: Get Architecture Decisions
-
-Call `/dev-arch` for patterns to use:
-
-```
-1. Check: plans/features/{feature}/architecture.md exists?
-   → Yes: Read and use those decisions
-   → No: Call dev-arch to generate
-
-2. dev-arch provides:
-   → API patterns (REST conventions, response format)
-   → Data patterns (ORM, schema conventions)
-   → Component patterns (structure, state management)
-   → Auth patterns (how to secure endpoints)
-
-3. Use these patterns in spec generation
-```
-
-**Example from architecture.md:**
-
-```markdown
-## Patterns to Follow
-
-### API Patterns
-- RESTful: `/{resource}` and `/{resource}/:id`
-- Response: `{ data, error, meta }`
-- Auth: Bearer token in header
-
-### Data Patterns
-- ORM: Prisma
-- Soft deletes: deletedAt field
-- Timestamps: createdAt, updatedAt
-```
-
-Specs will use these patterns for consistency.
-
-### Phase 0.7: Read Stack Configuration (CRITICAL)
-
-Read `plans/scout/stack.md` to understand HOW to implement:
-
-```
-1. Check: plans/scout/stack.md exists?
-   → No: This should not happen (Phase 0 auto-scout ensures it exists)
-   → Yes: Continue
-
-2. Extract key information:
-   → API Layer: BaaS, REST, GraphQL, tRPC
-   → SDK to use: @directus/sdk, @supabase/supabase-js, etc.
-   → Data access: BaaS-managed, ORM, direct SQL
-   → API client pattern: hooks, composables, services
-   → Validation: Zod, Yup, native
-   → Forms: react-hook-form, vee-validate
-   → External services: What's already configured
-
-3. Load stack knowledge files (IMPORTANT):
-   → Check "Stack Knowledge References" section in stack.md
-   → Read each referenced knowledge/stacks/*.md file
-   → Use "For /dev-specs" sections for patterns
-
-   Examples:
-   - Directus project → Read knowledge/stacks/directus/_index.md
-   - Nuxt project → Read knowledge/stacks/nuxt/_index.md
-   - Next.js project → Read knowledge/stacks/nextjs/_index.md
-
-4. Use this to write specs that FIT the project
-```
-
-**Why this matters:**
-
-| Without stack.md | With stack.md |
-|------------------|---------------|
-| "Create REST endpoint" | "Use Directus collection via SDK" |
-| "Create fetch wrapper" | "Use existing `useApi()` composable" |
-| "Add validation" | "Add Zod schema to shared/schemas/" |
-| "Handle auth" | "Use Directus auth middleware" |
-
-**Stack-aware spec generation:**
-
-| Stack Aspect | Spec Impact |
-|--------------|-------------|
-| BaaS (Directus) | Don't create tables, use collections |
-| Composables pattern | New features use composables, not services |
-| Zod validation | Schema in shared/schemas/*.ts |
-| Server Actions (Next.js) | Use 'use server' not API routes |
-| React Query | Wrap in useQuery, not raw fetch |
-
-**Example: spec for "Add user profile"**
-
-Without stack.md:
-```markdown
-1. Create POST /api/users/profile endpoint
-2. Add Prisma User model
-3. Create ProfileForm with useState
-```
-
-With stack.md (Directus + Vue composables):
-```markdown
-1. Add profile fields to Directus users collection (via admin)
-2. Create useUserProfile composable using useDirectus()
-3. Create ProfileForm using VeeValidate + Zod schema
-```
+### Phase 0: Check & Prepare
+1. Verify BRD exists
+2. Verify feature folder exists
+3. Check `tech-context.md` exists (run scout if not)
+4. Check `codebase-context.md` exists (run feature scout if not)
+5. Read docs-graph.json for dependencies
 
 ### Phase 1: Gather Context
-
-1. **Read BRD use cases** for the feature
-   - `plans/brd/use-cases/UC-{GROUP}-*.md`
-   - Extract acceptance criteria, business rules
-
-2. **Read feature scout** (if exists)
-   - `plans/features/{feature}/scout.md`
-   - Understand existing implementation
-
-3. **Read architecture decisions** (from Phase 0.6)
-   - `plans/features/{feature}/architecture.md`
-   - Use established patterns
-
-4. **Read additional inputs** (if provided)
-   - API specs → Extract endpoints, contracts
-   - DB schema → Understand data model
-   - Design docs → UI requirements
-
-5. **Ask clarifying questions** using `AskUserQuestion`:
-
-**Q1: Implementation Scope**
-- Backend only
-- Frontend only
-- Full-stack
-- API/Service only
-- Mobile app
-
-**Q2: Additional Context** (multi-select)
-- Have API specs (Swagger/OpenAPI/GraphQL)
-- Have DB schema file
-- Have design files/links
-- Have existing documentation
-- None
-
-**Q3: Testing Approach**
-- Unit tests only
-- Unit + Integration
-- Unit + Integration + E2E
-- No tests (docs only)
+1. Read BRD use cases for feature
+2. Read `tech-context.md` (HOW to implement)
+3. Read `codebase-context.md` (existing implementation)
+4. Read architecture.md (patterns - call `/dev-arch` if missing)
+5. Read quality attributes (Specification Level)
+6. Ask user: scope, additional context, testing approach
 
 ### Phase 2: Analyze Impact
-
-For each use case:
-
-1. **What's new?** - Files/components to create
-2. **What changes?** - Existing files to modify
-3. **What's shared?** - Reusable across UCs
-4. **Dependencies?** - What must exist first
-
-Create impact summary:
-```markdown
-## Impact Analysis
-
-| UC | New Files | Modified | Dependencies |
-|----|-----------|----------|--------------|
-| UC-AUTH-001 | 5 | 2 | shared/data-model |
-| UC-AUTH-002 | 3 | 1 | UC-AUTH-001 |
-```
+For each UC:
+- What's new? (files to create)
+- What changes? (files to modify)
+- What's shared? (reusable across UCs)
+- Dependencies? (what must exist first)
 
 ### Phase 3: Generate Shared Specs
+Create `specs/shared/`:
+- `data-model.md` - Schema changes, entities
+- `patterns.md` - Pattern references (not pseudocode)
+- `security.md` - Auth, validation rules
+
+### Phase 4: Generate UC Specs (Lean Format)
+For each UC, create `specs/UC-XXX-NNN-slug.md` (~150 lines):
+- Context & links
+- Requirements (bulleted, testable)
+- Technical constraints (stack-aware from tech-context.md)
+- Acceptance criteria (testable)
+- Files to modify
+- API contract (if applicable)
+- Test checklist
+- Dependencies
+- Implementation notes (DO/DON'T)
+
+### Phase 5: Generate Index
+Create `specs/README.md` with implementation order and dependencies.
+
+## Stack Awareness
+
+Specs **must** read `tech-context.md` to know the right approach:
 
-Create `specs/shared/` files:
-
-**data-model.md:**
-```markdown
-# Data Model
-
-## New Entities
-
-### User
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| email | string | Unique |
-| passwordHash | string | bcrypt |
-
-## Schema Changes
-
-```sql
--- Migration: add_users_table
-CREATE TABLE users (
-    id UUID PRIMARY KEY,
-    email VARCHAR(255) UNIQUE NOT NULL,
-    ...
-);
-```
-
-## Relationships
-{Describe entity relationships}
-```
-
-**patterns.md:**
-```markdown
-# Implementation Patterns
-
-## Code Style
-- Follow existing patterns from scout
-- {Specific conventions}
-
-## Error Handling
-- {How to handle errors}
-- {User feedback patterns}
-
-## API Patterns (if applicable)
-- {Request/response format}
-- {Authentication headers}
-
-## State Management (if applicable)
-- {State patterns}
-- {Data fetching}
-```
-
-**security.md:**
-```markdown
-# Security Considerations
-
-## Authentication
-- {How auth works}
-
-## Authorization
-- {Permission model}
-
-## Data Validation
-- {Input validation rules}
-
-## Sensitive Data
-- {What to protect, how}
-```
-
-### Phase 4: Generate UC Specs
-
-For each use case, create folder with:
-
-**README.md** (Implementation Plan):
-```markdown
-# UC-{GROUP}-{NNN}: {Title}
-
-> **Feature**: [[feature-{feature}]]
-> **BRD**: [[uc-{group}-{nnn}]]
-> **Status**: Draft
-
-## Overview
-{What this UC implements}
-
-## Business Requirements
-{From BRD - acceptance criteria}
-
-## Current State
-{From scout - what exists}
-
-## Implementation Plan
-
-### 1. {Step 1}
-- {Detail}
-- {Detail}
-
-### 2. {Step 2}
-- {Detail}
-
-## API Contract (if applicable)
-
-### {Method} {Endpoint}
-
-**Request:**
-```json
-{
-    "field": "type"
-}
-```
-
-**Response:**
-```json
-{
-    "field": "type"
-}
-```
-
-**Errors:**
-| Code | Reason |
-|------|--------|
-| 400 | Invalid input |
-| 401 | Unauthorized |
-
-## UI Components (if applicable)
-
-| Component | Purpose | Props |
-|-----------|---------|-------|
-| {Name} | {Purpose} | {Key props} |
-
-## Edge Cases
-- {Edge case 1}
-- {Edge case 2}
-
-## Dependencies
-- [ ] {What must exist first}
-
-## Acceptance Mapping
-| BRD Criteria | Implementation |
-|--------------|----------------|
-| Given X, When Y, Then Z | {How implemented} |
-```
-
-**changes.md:**
-```markdown
-# File Changes
-
-## New Files
-
-| File | Purpose |
-|------|---------|
-| `src/api/auth/login.ts` | Login endpoint |
-| `src/components/LoginForm.tsx` | Login form UI |
-
-## Modified Files
-
-| File | Change |
-|------|--------|
-| `src/lib/auth.ts` | Add login function |
-| `prisma/schema.prisma` | Add User model |
-
-## File Tree Preview
-```
-src/
-├── api/
-│   └── auth/
-│       └── login.ts     # NEW
-├── components/
-│   └── auth/
-│       └── LoginForm.tsx # NEW
-└── lib/
-    └── auth.ts          # MODIFIED
-```
-```
-
-**tests.md:**
-```markdown
-# Test Plan
-
-## Unit Tests
-
-| Test | File | Description |
-|------|------|-------------|
-| Login validation | `login.test.ts` | Validate email/password |
-| Token generation | `auth.test.ts` | JWT token creation |
-
-## Integration Tests
-
-| Test | Description |
-|------|-------------|
-| Login flow | POST /api/auth/login with valid creds |
-| Invalid login | POST /api/auth/login with wrong password |
-
-## E2E Tests (if applicable)
-
-| Scenario | Steps |
-|----------|-------|
-| User login | Navigate to /login, enter creds, verify redirect |
-
-## Test Data
-
-```json
-{
-    "validUser": {
-        "email": "test@example.com",
-        "password": "TestPass123!"
-    }
-}
-```
-
-## Coverage Target
-- Unit: 80%+
-- Integration: Key paths
-- E2E: Happy path + critical errors
-```
-
-### Phase 5: Generate Specs Index
-
-Create `specs/README.md`:
+| Stack Aspect | Spec Impact |
+|--------------|-------------|
+| BaaS (Directus) | Use collections, not tables |
+| Composables | New API calls in composables/ |
+| Zod | Schemas in shared/schemas/ |
+| Server Actions | Use 'use server', not API routes |
 
+**Example:**
 ```markdown
-# {Feature} - Implementation Specs
-
-> **Feature**: [[feature-{feature}]]
-> **Generated**: {date}
-> **Use Cases**: {count}
-
-## Overview
-{Brief description of the feature implementation}
-
-## Implementation Order
-
-| Order | UC | Title | Depends On | Estimate |
-|-------|-----|-------|------------|----------|
-| 1 | [[uc-auth-001]] | Login | shared/* | - |
-| 2 | [[uc-auth-002]] | Signup | [[uc-auth-001]] | - |
-| 3 | [[uc-auth-003]] | Forgot Password | [[uc-auth-001]] | - |
-
-## Shared Specs
-- [Data Model](./shared/data-model.md)
-- [Patterns](./shared/patterns.md)
-- [Security](./shared/security.md)
-
-## Dependencies Graph
-
-```mermaid
-flowchart TD
-    shared[shared/*] --> UC001[UC-AUTH-001]
-    UC001 --> UC002[UC-AUTH-002]
-    UC001 --> UC003[UC-AUTH-003]
+## Technical Constraints
+- Use existing `useUserProfile` composable
+- Follow VeeValidate + Zod pattern from auth forms
+- Profile fields exist in Directus users collection
 ```
 
-## Summary
+## Spec Format
 
-| Metric | Count |
-|--------|-------|
-| Total Use Cases | {n} |
-| New Files | {n} |
-| Modified Files | {n} |
-| Tests | {n} |
+See `references/spec-template.md` for structure.
 
-## Notes
-{Any implementation notes, risks, considerations}
-```
+**Max:** ~150 lines per UC
+**Focus:** Requirements + acceptance criteria
+**No:** Pseudocode or detailed HOW
 
-### Phase 6: Summary
+## Quality Questions
 
-Output:
-- Specs created
-- Use cases covered
-- Files that will change
-- Dependencies identified
-- Next steps
+Ask user for:
+1. **Scope:** Backend only | Frontend only | Full-stack | API/Service | Mobile
+2. **Additional Context:** API specs | DB schema | Design files | Docs
+3. **Testing:** Unit only | Unit + Integration | Unit + Integration + E2E | No tests
 
-## Tools Used
+## Tools
 
 | Tool | Purpose |
 |------|---------|
-| `Read` | BRD, scout, input files |
+| `Read` | BRD, tech-context, codebase-context, architecture |
 | `Glob` | Find related files |
 | `Write` | Create spec files |
 | `AskUserQuestion` | Clarify scope |
-| `WebFetch` | Fetch external docs (if URL) |
 | `Context7` | Look up API/library patterns |
 
-### Context7 for Spec Accuracy
-
-When writing specs, use Context7 to verify API patterns:
-
-```
-1. Look up framework patterns
-   → mcp__context7__resolve-library-id({
-       libraryName: "next.js",
-       query: "API routes patterns"
-     })
-
-2. Get specific documentation
-   → mcp__context7__query-docs({
-       libraryId: "/vercel/next.js",
-       query: "server actions form handling"
-     })
-```
-
-**Use for:**
-- API route conventions (Next.js, Express, NestJS)
-- Form validation patterns (Zod, Yup)
-- Database query patterns (Prisma, Drizzle)
-- Authentication flows (NextAuth, Lucia)
-
-## Integration with Other Skills
-
-| Skill | Relationship |
-|-------|--------------|
-| `/debrief` | Provides use cases (input) |
-| `/dev-scout` | Provides codebase context + stack.md (input) |
-| `/dev-arch` | Provides architecture patterns (input) |
-| `/utils/diagram` | Validates mermaid in specs |
+## Philosophy
 
-**Key dependency**: `stack.md` from `/dev-scout` tells specs HOW to implement:
-- Which SDK to use (not raw fetch)
-- Which patterns to follow (hooks vs services vs composables)
-- Which validation library (Zod vs Yup)
-- Whether to use BaaS or direct DB
+Specs are **contracts**, not **pseudocode**.
+- Define WHAT (requirements)
+- Reference HOW (existing patterns)
+- Implementation discovers details fresh during `/dev-coding`
 
-## Tips
+## Anti-Patterns
 
-- Run `/dev-scout {feature}` first for better context
-- Provide API specs when available for accurate contracts
-- Keep each UC spec focused - one job per UC
-- Estimates are left blank for team to fill
+❌ Writing 500+ line implementation plans
+❌ Including pseudocode that gets stale
+❌ Rewriting existing patterns
+❌ Over-specifying implementation details
+❌ Ignoring tech-context.md (suggests wrong approach)
 
-## References
+## Reference
 
-- `references/spec-templates.md` - Template structures
-- `references/checklist.md` - Spec completeness checklist
+See `references/spec-template.md` for output structure (principle + empty template).