@codihaus/claude-skills 1.0.0

package/skills/dev-specs/SKILL.md

@@ -0,0 +1,577 @@
+---
+name: dev-specs
+description: Generate implementation specifications from BRD use cases
+version: 1.4.0
+---
+
+# /dev-specs - 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
+> - **Reads**: `_quality-attributes.md` (Specification Level)
+> - **After**: Use `/dev-coding` for implementation
+
+Generate precise implementation plans from BRD use cases. Creates per-UC specs with shared components.
+
+## When to Use
+
+- After `/debrief` created BRD use cases
+- After `/dev-scout {feature}` analyzed codebase
+- Before starting implementation
+- When onboarding engineers to a feature
+
+## Usage
+
+```
+/dev-specs auth                              # Generate specs for auth feature
+/dev-specs auth UC-AUTH-001                  # Single use case only
+/dev-specs billing --api=swagger.json        # With API spec file
+/dev-specs payments --schema=schema.prisma   # With DB schema
+```
+
+## Prerequisites
+
+Before running, ensure:
+1. `plans/brd/` exists with use cases
+2. `plans/features/{feature}/` exists
+
+**Note**: Scout is auto-triggered if missing (see Phase 0).
+
+## Input Files
+
+The skill can accept additional context files:
+
+| 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 |
+
+## Output Structure
+
+```
+plans/features/{feature}/
+├── README.md              # Feature overview
+├── scout.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}/
+        └── ...
+```
+
+## 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. Notify user: "No scout found for {feature}, running analysis..."
+2. Execute scout workflow (medium mode) for the feature
+3. Save to `plans/features/{feature}/scout.md`
+4. Continue to Phase 1
+
+**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 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)
+
+### 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 |
+```
+
+### Phase 3: Generate Shared Specs
+
+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`:
+
+```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]
+```
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Use Cases | {n} |
+| New Files | {n} |
+| Modified Files | {n} |
+| Tests | {n} |
+
+## Notes
+{Any implementation notes, risks, considerations}
+```
+
+### Phase 6: Summary
+
+Output:
+- Specs created
+- Use cases covered
+- Files that will change
+- Dependencies identified
+- Next steps
+
+## Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| `Read` | BRD, scout, input files |
+| `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 (input) |
+| `/dev-arch` | Provides architecture patterns (input) |
+| `/utils/diagram` | Validates mermaid in specs |
+
+## Tips
+
+- 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
+
+## References
+
+- `references/spec-templates.md` - Template structures
+- `references/checklist.md` - Spec completeness checklist