name: create-task-spec description: Create hyper-detailed task specifications with embedded context, eliminating implementation lookups. This skill should be used for breaking features into implementable tasks with complete architecture references. acceptance:

task_file_created: "Task specification file created in configured location"
context_embedded: "All technical context embedded with source references"
tasks_defined: "3-15 sequential tasks with validation checkpoints"
user_approved: "User reviewed and approved specification" inputs: requirement: type: string required: true description: "Feature or requirement to implement" priority: type: string required: false description: "Priority level (P0/P1/P2/P3)" default: "P2" outputs: task_file: type: string description: "Path to created task specification file" task_id: type: string description: "Generated task ID (e.g., task-006)" task_count: type: number description: "Number of tasks in breakdown" status: type: string description: "Task status (Draft or Approved)" telemetry: emit: "skill.create-task-spec.completed" track:
- task_id
- task_count
- subtask_count
- priority
- status
- duration_ms

Create Task Specification Skill

Purpose

Create hyper-detailed task specifications that embed ALL context needed for implementation, eliminating the need for developers to search for information during coding.

Core Capabilities:

Requirement gathering and clarification
Architecture context extraction with source references
Component analysis (data models, APIs, UI)
Sequential task breakdown with validation checkpoints
Self-contained specifications

BMAD Pattern (Key Innovation):

SM reads PRD + Architecture + Previous task notes
Creates detailed task spec with embedded context
Dev reads ONLY task spec (no architecture lookup)
Result: Context never lost, implementation never blocked

Prerequisites

Configuration file (.claude/config.yaml) with task settings
Task template (.claude/templates/task-spec.md)
Architecture documentation (optional but recommended)
Project coding standards

Workflow

Step 0: Load Configuration and Validate Prerequisites

Action: Load configuration and verify prerequisites.

Execute:

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path .claude/config.yaml \
  --output json

Extract: documentation.architecture, development.alwaysLoadFiles, development.taskLocation, templates.taskSpec

Verify: Task location exists, template exists, determine next task ID

Halt if: Config missing, template missing, cannot determine task ID

See: references/templates.md for configuration format and references/requirements-gathering-guide.md for requirement clarification

Step 1: Gather Requirements from User

Action: Clarify requirement, acceptance criteria, and priority.

Ask user:

What needs to be implemented?
- Feature description
- Problem it solves
- Primary user/beneficiary
What defines "done"?
- Testable outcomes
- Acceptance criteria (2-5 specific criteria)
- Edge cases to consider
Priority and complexity?
- Priority: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
- Complexity: Simple | Medium | Complex
- Related epic/feature

Confirm understanding:

Restate as user story: As a [role], I want [action], so that [benefit]
Verify acceptance criteria
Get approval to proceed

Halt if:

User cannot articulate requirement clearly
Acceptance criteria are ambiguous
User does not approve proceeding

See: references/requirements-gathering-guide.md for detailed gathering techniques

Step 2: Load Architecture Context

Action: Load architecture documentation and previous task learnings.

Load files:

Always-required files (coding standards):

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path {always_load_file} \
  --output json

Architecture documentation:
- Read documentation.architecture files
- Extract: System design, patterns, conventions
Previous task insights:
- Read most recent task file from taskLocation
- Extract: Completion notes, lessons learned, patterns

Context categories: Tech stack, project structure, coding standards, testing strategy, data models, API specs, component specs, patterns

CRITICAL RULES: ONLY use information from source documents, NEVER invent details, ALWAYS cite sources, note when info missing

See: references/context-extraction-guide.md for detailed extraction strategies and references/templates.md for context format examples

Step 3: Analyze Relevant Components

Action: Identify affected components and extract specific technical details.

Identify components:

What data models are involved?
What API endpoints need creation/modification?
What UI components are affected?
What external services are used?

Extract details: Data models (schemas, validation, relationships), API specs (endpoints, request/response, auth, errors), component specs (location, props, state, styling), file locations (exact paths), constraints (performance, security, reliability, testing)

All extractions must cite: [Source: filename#section]

See: references/context-extraction-guide.md for analysis patterns and references/templates.md for extraction format examples

Step 4: Create Sequential Task Breakdown

Action: Break requirement into 3-15 sequential tasks with subtasks.

Task breakdown:

Break into 3-15 tasks:
- Each task implements specific functionality
- Tasks build on each other logically
- Each task maps to one or more acceptance criteria
Create subtasks for each task:
- Specific implementation steps
- Test writing requirements
- Validation checkpoints
Structure in implementation order:
- Data layer first (models, migrations)
- Business logic second (services, utilities)
- API layer third (routes, controllers)
- UI layer fourth (components, pages)
- Integration last (E2E tests, documentation)
Link to acceptance criteria: Example: "Task 1: Create user model (AC: 1, 2)"

Halt if: Cannot break down coherently, >15 tasks (too complex), <3 tasks (too simple)

See: references/task-breakdown-guide.md for detailed strategies and references/templates.md for task structure examples

Step 5: Populate Task Specification Template

Action: Generate task file from template with all context embedded.

Load template:

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path .claude/templates/task-spec.md \
  --output json

Replace placeholders: task_id, title, date, priority, status, user_story, acceptance_criteria, context, tasks, validation

Context must include: Previous insights, data models, API specs, component specs, file locations, testing requirements, constraints - ALL with [Source: filename#section] references

See: references/templates.md for placeholder examples and formats

Step 6: Validate Task Specification Completeness

Action: Verify all required elements are present and properly formatted.

Validation checklist:

Required Sections:

Status (Draft)
Objective (clear user story)
Acceptance Criteria (2-5 specific criteria)
Context section with embedded details
Tasks / Subtasks (3-15 tasks)
Implementation Record (empty placeholder)

Context Completeness:

Previous insights referenced
Data models included (if applicable)
API specs included (if applicable)
Component specs included (if applicable)
File locations specified
Testing requirements documented
All context has [Source: ...] references

Task Quality:

Tasks in logical implementation order
Each task linked to acceptance criteria
Subtasks include test writing steps
Validation checkpoints included
File paths are specific, not generic

Halt if:

Critical sections missing
Context lacks source references
Tasks are ambiguous or generic
No validation checkpoints

See: references/validation-approval-guide.md for validation details

Step 7: Save Task Specification and Get User Approval

Action: Save task file and present summary for approval.

Save file:

python .claude/skills/bmad-commands/scripts/write_file.py \
  --path {taskLocation}/{task_id}.md \
  --content "{task_spec}" \
  --output json

Present summary: Show task ID, objective, acceptance criteria, task breakdown, embedded context sources, and request approval.

Update status if approved: Change from "Draft" to "Approved"

See: references/templates.md for complete summary format and references/validation-approval-guide.md for approval workflow

Output

Return structured output with task file path, task ID, task count, status, and telemetry metrics.

See: references/templates.md for complete output format

Best Practices

Context Embedding is Critical - Implementation should never need architecture docs
Be Specific, Not Generic - Exact file paths, schemas, API specs
Source Everything - Cite [Source: filename#section] for all technical details
Task Granularity - 3-15 tasks (>15 too complex, <3 too simple)

See: references/task-breakdown-guide.md for detailed practices

Routing Guidance

Use this skill when:

Breaking features into implementable tasks
Creating detailed specifications for development
Embedding architectural context for implementation
Need clear, unambiguous work items

Always use before:

execute-task skill (implementation)
Task must be "Approved" status

Do not use for:

Quick bug fixes (too much overhead)
Urgent hotfixes (too structured)
Exploratory coding (too constrained)

Reference Files

references/requirements-gathering-guide.md - Clarifying requirements, acceptance criteria, user stories
references/context-extraction-guide.md - Loading architecture, extracting technical details, sourcing
references/task-breakdown-guide.md - Creating sequential tasks, granularity, validation checkpoints
references/validation-approval-guide.md - Completeness validation, saving, approval workflow
references/templates.md - Task spec template, output format, placeholder examples, configuration format

Using This Skill

Invoked with requirement input (feature description) and optional priority (P0-P3)

Part of BMAD Enhanced Planning Suite

create-task-spec

$ 설치