Task Planning

Task Planning

Overview

Transforms specifications and implementation plans into concrete, dependency-ordered tasks. Creates phased breakdowns that guide systematic implementation.

When To Use

• Converting specifications to implementation tasks
• Planning feature implementation order
• Identifying parallel execution opportunities
• Breaking down complex features into phases

When NOT To Use

• Writing specifications - use spec-writing

Task Phases

Tasks follow a 5-phase structure from setup through polish:

• Phase 0: Setup - Project initialization, dependencies, configuration
• Phase 1: Foundation - Data models, interfaces, test infrastructure
• Phase 2: Core Implementation - Business logic, APIs, services
• Phase 3: Integration - External services, middleware, logging
• Phase 4: Polish - Optimization, documentation, final testing

For detailed phase definitions, selection guidelines, and anti-patterns, see modules/phase-structure.md.

Task Format

Each task includes:

• ID: Unique identifier (TASK-001)
• Description: Clear action statement
• Phase: Which phase it belongs to
• Dependencies: Tasks that must complete first
• Parallel Marker: [P] if can run concurrently
• Files: Affected file paths
• Criteria: How to verify completion

Dependency Rules

Dependencies define execution order and identify parallelization opportunities:

• Sequential Tasks: Execute in strict order when dependencies exist
• Parallel Tasks [P]: Can run concurrently when ALL nonconflicting conditions are met
• File Coordination: Tasks affecting same files MUST run sequentially

Nonconflicting Criteria for Parallel Execution:

• ✅ Files: No file overlap between tasks
• ✅ State: No shared configuration or global state
• ✅ Dependencies: All prerequisites satisfied
• ✅ Code paths: No merge conflicts possible
• ✅ Outputs: Tasks don't need each other's results

Mark tasks with [P] ONLY if they pass ALL criteria above.

For fan-out/fan-in patterns, task ID conventions, and validation rules, see modules/dependency-patterns.md.

Example Task Entry

## Phase 2: Core Implementation

### TASK-007 - Implement user authentication service [P]
**Dependencies**: TASK-003, TASK-004
**Files**: src/services/auth.ts, src/types/user.ts
**Criteria**: All auth tests pass, tokens are valid JWT

Verification: Run pytest -v to verify tests pass.

Quality Checklist

• [ ] All requirements mapped to tasks
• [ ] Dependencies are explicit
• [ ] Parallel opportunities identified
• [ ] Tasks are right-sized (not too large/small)
• [ ] Each task has clear completion criteria

Related Skills

• spec-writing: Creating source specifications
• speckit-orchestrator: Workflow coordination

Task Dependency Patterns

Overview

Dependencies define task execution order and identify parallelization opportunities. Proper dependency modeling prevents race conditions and validates components exist before they're used.

Dependency Types

Sequential Dependencies

Definition: Task B cannot start until Task A completes

When to Use:

• Task B modifies output from Task A
• Task B requires interfaces/types defined in Task A
• Task B tests functionality implemented in Task A
• Tasks affect the same file(s)

Example:

### TASK-002 - Define Task data model
**Dependencies**: TASK-001
**Files**: src/models/task.py

### TASK-003 - Implement task validation
**Dependencies**: TASK-002
**Files**: src/models/task.py, src/validators/task.py

Reasoning: Task validation requires the Task model to exist first. Both affect task.py, requiring sequential execution.

Parallel Dependencies [P]

Definition: Tasks can execute concurrently with no conflicts

When to Use:

• No shared dependencies beyond a common foundation
• Operate on different files
• Independent feature implementations
• Separate test suites

Marker: Suffix task with [P]

Example:

### TASK-004 - Implement user authentication [P]
**Dependencies**: TASK-001
**Files**: src/services/auth.py, tests/test_auth.py

### TASK-005 - Implement task storage [P]
**Dependencies**: TASK-001
**Files**: src/services/storage.py, tests/test_storage.py

Reasoning: Both depend on TASK-001 setup but operate on different files and can run concurrently.

Fan-Out Pattern

Definition: Multiple tasks depend on single foundation task

Pattern:

TASK-001 (Foundation)
    ├─> TASK-002 [P]
    ├─> TASK-003 [P]
    └─> TASK-004 [P]

Use Case: After creating data models, implement multiple independent services

Example:

### TASK-001 - Define API schemas
**Dependencies**: None
**Files**: src/types/api.ts

### TASK-002 - Implement user endpoints [P]
**Dependencies**: TASK-001
**Files**: src/routes/users.ts

### TASK-003 - Implement task endpoints [P]
**Dependencies**: TASK-001
**Files**: src/routes/tasks.ts

### TASK-004 - Implement project endpoints [P]
**Dependencies**: TASK-001
**Files**: src/routes/projects.ts

Fan-In Pattern

Definition: Single task depends on multiple prerequisites

Pattern:

TASK-002 [P] ─┐
TASK-003 [P] ─┼─> TASK-005
TASK-004 [P] ─┘

Use Case: Integration task requiring multiple components

Example:

### TASK-002 - Implement auth service [P]
**Dependencies**: TASK-001
**Files**: src/services/auth.py

### TASK-003 - Implement storage service [P]
**Dependencies**: TASK-001
**Files**: src/services/storage.py

### TASK-004 - Implement notification service [P]
**Dependencies**: TASK-001
**Files**: src/services/notifications.py

### TASK-005 - Integrate services in workflow
**Dependencies**: TASK-002, TASK-003, TASK-004
**Files**: src/workflow/coordinator.py

File Coordination Rules

Same-File Modification

Rule: Tasks modifying the same file must execute sequentially

Example:

### TASK-006 - Add base Task class
**Files**: src/models/task.py

### TASK-007 - Add Task validation methods
**Dependencies**: TASK-006
**Files**: src/models/task.py

Reasoning: Prevents merge conflicts and validates clean incremental changes.

Same-Directory Independence

Rule: Tasks creating different files in same directory can run in parallel

Example:

### TASK-008 - Create user model [P]
**Files**: src/models/user.py

### TASK-009 - Create task model [P]
**Files**: src/models/task.py

Reasoning: No file conflicts, different models, independent implementations.

Test-Implementation Pairing

Rule: Implementation and its tests are typically sequential

Example:

### TASK-010 - Implement resolver logic
**Files**: src/services/resolver.py

### TASK-011 - Add resolver integration tests
**Dependencies**: TASK-010
**Files**: tests/integration/test_resolver.py

Reasoning: Can't test what doesn't exist yet.

Exception: TDD approach might reverse this (write test first).

Task ID Conventions

Numbering Format

Pattern: TASK-NNN where NNN is zero-padded number

Examples:

• TASK-001 - First task
• TASK-023 - Twenty-third task
• TASK-100 - Hundredth task

Rules:

• Always zero-pad to 3 digits minimum
• Sequential numbering across phases
• No gaps in sequence
• Don't reuse IDs

Ordering Strategy

By Phase First:

TASK-001 through TASK-003: Phase 0
TASK-004 through TASK-010: Phase 1
TASK-011 through TASK-025: Phase 2
TASK-026 through TASK-030: Phase 3
TASK-031 through TASK-035: Phase 4

Benefit: Clear phase boundaries, easy to identify task phase

Dependency Declaration Format

Single Dependency

**Dependencies**: TASK-001

Multiple Dependencies

**Dependencies**: TASK-001, TASK-003, TASK-007

No Dependencies

**Dependencies**: None

Common Dependency Patterns

Linear Chain

TASK-001 -> TASK-002 -> TASK-003 -> TASK-004

Use when each task builds directly on previous task.

Independent Parallel

TASK-001
    ├─> TASK-002 [P]
    ├─> TASK-003 [P]
    └─> TASK-004 [P]

Use when multiple features share only initial setup.

Diamond Pattern

        TASK-001
       /          \
TASK-002 [P]    TASK-003 [P]
       \          /
        TASK-004

Use when parallel work converges for integration.

Layered Dependencies

Phase 1: TASK-001, TASK-002, TASK-003
           ↓         ↓         ↓
Phase 2: TASK-004 depends on all Phase 1

Use when foundation must be complete before next phase.

Validation Rules

• [ ] Every task has explicit dependency field
• [ ] No circular dependencies
• [ ] Parallel tasks [P] have no file conflicts
• [ ] Sequential tasks on same file are ordered
• [ ] All referenced task IDs exist
• [ ] Tasks reference dependencies from earlier phases

Task Phase Structure

Overview

Tasks are organized into five phases that follow natural implementation flow. Each phase builds on previous phases, creating a dependency foundation that validates components exist before they're used.

Phase Definitions

Phase 0: Setup

Purpose: Establish project foundation and development environment

Typical Tasks:

• Project initialization (package.json, pyproject.toml, etc.)
• Dependency installation and lock files
• Configuration files (linting, formatting, build tools)
• Development environment setup
• Git repository initialization
• CI/CD pipeline scaffolding

When to Use:

• Starting new projects from scratch
• Adding new build tools or development dependencies
• Setting up infrastructure before code implementation

Example:

### TASK-001 - Initialize Python project with uv
**Dependencies**: None
**Files**: pyproject.toml, uv.lock
**Criteria**: `uv sync` runs successfully

Phase 1: Foundation

Purpose: Create core data structures and testing infrastructure

Typical Tasks:

• Data models and type definitions
• Core interfaces and protocols
• Database schemas and migrations
• Test infrastructure and fixtures
• Base classes and abstract components
• Shared utilities

When to Use:

• Defining data contracts that other code depends on
• Creating type systems for type-safe implementations
• Establishing testing patterns before feature work

Example:

### TASK-002 - Define Task data model
**Dependencies**: TASK-001
**Files**: src/models/task.py, tests/test_models.py
**Criteria**: All model tests pass, types validate with mypy

Phase 2: Core Implementation

Purpose: Implement primary business logic and features

Typical Tasks:

• Service layer implementation
• Business logic and algorithms
• API endpoint implementations
• Core feature functionality
• Domain-specific operations
• State management

When to Use:

• Building main application features
• Implementing business requirements
• Creating user-facing functionality

Example:

### TASK-007 - Implement task dependency resolver [P]
**Dependencies**: TASK-002, TASK-003
**Files**: src/services/resolver.py, tests/test_resolver.py
**Criteria**: Resolves complex dependency graphs, handles cycles

Phase 3: Integration

Purpose: Connect components and integrate external systems

Typical Tasks:

• External API integrations
• Middleware implementation
• Error handling and recovery
• Logging and monitoring
• Database connection pooling
• Message queue integrations
• Authentication/authorization hooks

When to Use:

• Connecting to external services
• Adding cross-cutting concerns
• Implementing system-wide error handling

Example:

### TASK-012 - Add structured logging with context
**Dependencies**: TASK-007, TASK-009
**Files**: src/middleware/logging.py, src/utils/logger.py
**Criteria**: All operations logged with correlation IDs

Phase 4: Polish

Purpose: Optimize, document, and finalize for production

Typical Tasks:

• Performance optimization and profiling
• detailed documentation
• End-to-end testing
• Security hardening
• Code cleanup and refactoring
• Production readiness checks

When to Use:

• After core functionality is complete
• Preparing for production deployment
• Addressing technical debt before release

Example:

### TASK-015 - Add API documentation with examples
**Dependencies**: TASK-007, TASK-010
**Files**: docs/api.md, examples/quickstart.py
**Criteria**: All endpoints documented, examples run successfully

Phase Selection Guidelines

Moving Between Phases

• Complete phase foundations before advancing: Don't jump to Phase 3 if Phase 1 models are incomplete
• Parallel work within phases: Multiple Phase 2 tasks can run concurrently if dependencies allow
• Return to earlier phases sparingly: Indicates incomplete planning or new requirements

Common Patterns

Small Features (5-10 tasks):

• Phase 0: Usually skipped (project exists)
• Phase 1: 1-2 tasks (data models)
• Phase 2: 3-5 tasks (core logic)
• Phase 3: 1-2 tasks (integration)
• Phase 4: 1-2 tasks (docs, tests)

Medium Features (10-20 tasks):

• Phase 0: 1-2 tasks (new dependencies)
• Phase 1: 3-4 tasks (multiple models, test infrastructure)
• Phase 2: 6-10 tasks (multiple services)
• Phase 3: 2-4 tasks (several integrations)
• Phase 4: 2-3 tasks (optimization, detailed docs)

Large Features (20+ tasks):

• Consider breaking into multiple features
• Each phase may have 5+ tasks
• Requires careful dependency management
• May benefit from sub-phases

Anti-Patterns to Avoid

• Phase jumping: Implementing Phase 2 features before Phase 1 models exist
• Phase mixing: Putting setup tasks in Phase 2 or implementation tasks in Phase 1
• Skipping phases: Every feature needs at least Phase 1 (models) and Phase 2 (logic)
• Over-granular phases: Creating sub-phases or custom phase numbers

Technology Stack Patterns

Overview

Common patterns for ignore files, tool configurations, and technology-specific artifacts across different development stacks.

Universal Ignore Patterns

Patterns that apply to all projects regardless of stack:

# OS artifacts
.DS_Store
Thumbs.db
desktop.ini

# IDE/Editor
.vscode/
.idea/
*.swp
*.swo
*~
.project
.classpath
.settings/

# Logs
*.log
logs/

Language-Specific Patterns

Node.js / JavaScript / TypeScript

# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# Build outputs
dist/
build/
out/
.next/
.nuxt/

# Cache
.npm
.eslintcache
.cache/
.parcel-cache/

# Environment
.env
.env.local
.env.*.local

Python

# Virtual environments
venv/
env/
.venv/
ENV/
.Python

# Build outputs
__pycache__/
*.py[cod]
*$py.class
*.so
.eggs/
*.egg-info/
dist/
build/

# Testing
.pytest_cache/
.coverage
htmlcov/
.tox/

Rust

# Build outputs
target/
Cargo.lock  # (exclude for libraries, include for binaries)

# Debug symbols
*.pdb

Go

# Build outputs
*.exe
*.exe~
*.dll
*.so
*.dylib
*.test

# Binary
bin/
vendor/

Java / Kotlin

# Build outputs
*.class
*.jar
*.war
*.ear
target/
build/
out/

# IDE
.gradle/
.mvn/

C# / .NET

# Build outputs
bin/
obj/
*.dll
*.exe
*.pdb

# User-specific
*.user
*.suo
*.userprefs

Common Tool Configurations

Docker

# Docker
.dockerignore
docker-compose.override.yml

Git

# Git
.git/
.gitattributes

Terraform

# Terraform
*.tfstate
*.tfstate.*
.terraform/
.terraform.lock.hcl

Linting & Formatting

# ESLint
.eslintcache

# Prettier
.prettierignore

# Ruff (Python)
.ruff_cache/

Cloud Provider Artifacts

# AWS
.aws/
*.pem

# GCP
.gcloud/
*-key.json

# Azure
.azure/

Usage in Spec-Kit

When generating .gitignore recommendations in planning phase: 1. Start with universal patterns 2. Add language-specific patterns based on tech stack 3. Include tool-specific patterns from implementation plan 4. Add cloud provider patterns if applicable