dev-specs

• After /debrief created BRD use cases
• After /dev-scout {feature} analyzed codebase
• Before starting implementation
• When onboarding engineers to a feature

```

/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

```

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).

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 |

```

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}/

└── ...

```

Phase 0: Check Dependencies & Graph Context

Before generating specs, verify prerequisites and gather context:

```

1. Check: plans/brd/ exists?

→ No: Error "Run /debrief first"

1. Check: plans/features/{feature}/ exists?

→ No: Error "Feature not found in BRD"

1. Check: plans/features/{feature}/scout.md exists?

→ No: Auto-run scout (see below)

1. 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 1: Gather Context

1. Read BRD use cases for the feature

- plans/brd/use-cases/UC-{GROUP}-*.md

- Extract acceptance criteria, business rules

1. Read feature scout (if exists)

- plans/features/{feature}/scout.md

- Understand existing implementation

1. Read additional inputs (if provided)

- API specs → Extract endpoints, contracts

- DB schema → Understand data model

- Design docs → UI requirements

1. 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

| 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

User

| Field | Type | Notes |

|-------|------|-------|

| id | uuid | PK |

| email | string | Unique |

| passwordHash | string | bcrypt |

```sql

-- Migration: add_users_table

CREATE TABLE users (

id UUID PRIMARY KEY,

email VARCHAR(255) UNIQUE NOT NULL,

...

);

```

{Describe entity relationships}

```

patterns.md:

```markdown

# Implementation Patterns

• Follow existing patterns from scout
• {Specific conventions}

• {How to handle errors}
• {User feedback patterns}

• {Request/response format}
• {Authentication headers}

• {State patterns}
• {Data fetching}

```

security.md:

```markdown

# Security Considerations

• {How auth works}

• {Permission model}

• {Input validation rules}

• {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

{What this UC implements}

{From BRD - acceptance criteria}

{From scout - what exists}

1. {Step 1}

• {Detail}
• {Detail}

2. {Step 2}

• {Detail}

{Method} {Endpoint}

Request:

```json

{

"field": "type"

}

```

Response:

```json

{

"field": "type"

}

```

Errors:

| Code | Reason |

|------|--------|

| 400 | Invalid input |

| 401 | Unauthorized |

| Component | Purpose | Props |

|-----------|---------|-------|

| {Name} | {Purpose} | {Key props} |

• {Edge case 1}
• {Edge case 2}

• [ ] {What must exist first}

| BRD Criteria | Implementation |

|--------------|----------------|

| Given X, When Y, Then Z | {How implemented} |

```

changes.md:

```markdown

# File Changes

| File | Purpose |

|------|---------|

| src/api/auth/login.ts | Login endpoint |

| src/components/LoginForm.tsx | Login form UI |

| File | Change |

|------|--------|

| src/lib/auth.ts | Add login function |

| prisma/schema.prisma | Add User model |

```

src/

├── api/

│ └── auth/

│ └── login.ts # NEW

├── components/

│ └── auth/

│ └── LoginForm.tsx # NEW

└── lib/

└── auth.ts # MODIFIED

```

```

tests.md:

```markdown

# Test Plan

| Test | File | Description |

|------|------|-------------|

| Login validation | login.test.ts | Validate email/password |

| Token generation | auth.test.ts | JWT token creation |

| Test | Description |

|------|-------------|

| Login flow | POST /api/auth/login with valid creds |

| Invalid login | POST /api/auth/login with wrong password |

| Scenario | Steps |

|----------|-------|

| User login | Navigate to /login, enter creds, verify redirect |

```json

{

"validUser": {

"email": "test@example.com",

"password": "TestPass123!"

}

}

```

• 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}

{Brief description of the feature implementation}

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

• [Data Model](./shared/data-model.md)
• [Patterns](./shared/patterns.md)
• [Security](./shared/security.md)

```mermaid

flowchart TD

shared[shared/*] --> UC001[UC-AUTH-001]

UC001 --> UC002[UC-AUTH-002]

UC001 --> UC003[UC-AUTH-003]

```

| Metric | Count |

|--------|-------|

| Total Use Cases | {n} |

| New Files | {n} |

| Modified Files | {n} |

| Tests | {n} |

{Any implementation notes, risks, considerations}

```

Phase 6: Summary

Output:

• Specs created
• Use cases covered
• Files that will change
• Dependencies identified
• Next steps

| Tool | Purpose |

|------|---------|

| Read | BRD, scout, input files |

| Glob | Find related files |

| Write | Create spec files |

| AskUserQuestion | Clarify scope |

| WebFetch | Fetch external docs (if URL) |

| Skill | Relationship |

|-------|--------------|

| /debrief | Provides use cases (input) |

| /dev-scout | Provides codebase context (input) |

| /diagram | Can validate mermaid in specs |

• 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/spec-templates.md - Template structures
• references/checklist.md - Spec completeness checklist