---

name: spec-flow:spec-task description: Break down a spec section or milestone into actionable, session-sized tasks. Use when a milestone is too large, when starting implementation, when the user asks to break down work, or when refining task granularity. allowed-tools: Read, Write, Edit, Glob

Task Breakdown

Convert high-level spec sections into atomic, implementable tasks.

When Claude Should Use This Skill

• User says "break this down" or "what are the tasks"
• User says "how should I implement this"
• A milestone has no task file yet
• Existing tasks are too large (> 1 session of work)
• User asks to "refine" or "expand" tasks

Arguments

Parse from conversation:

• Milestone name or spec section reference
• Granularity preference: fine (< 30 min), medium (30-60 min), coarse (1-2 hours)

Workflow

1. Understand the Scope

Read the relevant context:

Copy- .claude/spec/SPEC.md (requirements for this milestone)
- .claude/spec/tasks/{milestone}.md (existing tasks if any)
- .claude/steering/tech.md (technology constraints)

Extract:

• Requirements this milestone implements (REQ-xxx references)
• Technical stack (for realistic file paths)
• Existing task structure (if refining)

2. Decomposition Principles

Size Tasks Appropriately:

• Each task should be completable in one session (< 1 hour)
• A task should touch 1-3 files typically
• If task needs more than 5 acceptance criteria, split it

Make Tasks Independent:

• Each task should be implementable without others (when possible)
• Explicit dependencies where order matters
• Avoid circular dependencies

Include Context:

• Full file paths (not just filenames)
• Which requirements this satisfies
• Key technical decisions

3. Task Structure

For each task, define:

Copy### N. Task Title (Action-Oriented)

**Status**: Pending
**Files**: `path/to/file.go`, `path/to/test.go`
**Depends**: Task M (if applicable)
**Acceptance**:
- [ ] Specific, verifiable criterion
- [ ] Another criterion
- [ ] Tests pass (if applicable)

4. Common Decomposition Patterns

For a new feature:

1. Data model / types
2. Storage / persistence
3. Core logic
4. API / CLI interface
5. Tests

For a refactoring:

1. Add new implementation alongside old
2. Update callers to use new
3. Remove old implementation
4. Update tests

For a bug fix:

1. Add failing test
2. Implement fix
3. Verify fix doesn't break other tests

For an integration:

1. Define interface / types
2. Implement adapter
3. Wire into application
4. Integration test

5. Generate Output

Write to .claude/spec/tasks/{milestone}.md:

Copy# Tasks: {Milestone Name}

> Implements {REQ-xxx, REQ-yyy} from SPEC.md

## Status: Pending (0%)

## Dependencies

- {Other milestone if blocked}

---

## Tasks

{Generated tasks}

---

## Notes

{Technical notes, open questions}

6. Update SPEC.md

If this is a new task file:

• Add reference under milestone in SPEC.md
• Format: - [ ] @tasks/{milestone}.md - {Description}

Example Decomposition

Input: "Break down the authentication milestone"

SPEC.md excerpt:

Copy### MVP
- [ ] @tasks/auth.md - Authentication system

Requirements:

• [REQ-001] User can sign up with email/password
• [REQ-002] User can log in
• [REQ-003] Sessions persist across browser restarts

Generated tasks/auth.md:

Copy# Tasks: Authentication System

> Implements [REQ-001], [REQ-002], [REQ-003] from SPEC.md

## Status: Pending (0%)

## Dependencies

- None

---

## Tasks

### 1. User Model

**Status**: Pending
**Files**: `internal/user/user.go`, `internal/user/user_test.go`
**Acceptance**:
- [ ] User struct with ID, email, password hash
- [ ] Password hashing with bcrypt
- [ ] Validation for email format
- [ ] Unit tests for validation

### 2. User Repository

**Status**: Pending
**Files**: `internal/user/repository.go`, `internal/user/repository_test.go`
**Depends**: Task 1
**Acceptance**:
- [ ] Create user
- [ ] Find user by email
- [ ] SQL migrations for users table
- [ ] Integration tests with test DB

### 3. Signup Handler

**Status**: Pending
**Files**: `internal/api/signup.go`, `internal/api/signup_test.go`
**Depends**: Task 2
**Acceptance**:
- [ ] POST /signup endpoint
- [ ] Validates email not already taken
- [ ] Returns user ID on success
- [ ] Returns 400 on validation error

### 4. Session Management

**Status**: Pending
**Files**: `internal/session/session.go`, `internal/session/store.go`
**Acceptance**:
- [ ] Session struct with user ID, expiry
- [ ] Create session on login
- [ ] Persist to database
- [ ] Cookie configuration

### 5. Login Handler

**Status**: Pending
**Files**: `internal/api/login.go`, `internal/api/login_test.go`
**Depends**: Task 2, Task 4
**Acceptance**:
- [ ] POST /login endpoint
- [ ] Validates credentials
- [ ] Creates session
- [ ] Sets session cookie

### 6. Auth Middleware

**Status**: Pending
**Files**: `internal/api/middleware/auth.go`
**Depends**: Task 4
**Acceptance**:
- [ ] Validates session cookie
- [ ] Adds user to request context
- [ ] Returns 401 on invalid session

---

## Notes

- Using bcrypt for passwords (not argon2 for simplicity)
- Sessions stored in DB, not Redis (MVP simplicity)
- Cookie httpOnly, secure, sameSite=lax

Tips

• If unsure about granularity, ask the user
• Default to medium granularity (30-60 min tasks)
• Include test tasks alongside implementation
• Note technical decisions in Notes section