🔗 Workflow Provenance

Source: This skill augments the baseline workflow located at ./workflows/spec-kitty.tasks-outline.md. It acts as an intelligent wrapper that is continuously improved with each execution.

<!-- spec-kitty-command-version: 3.0.3 -->

/spec-kitty.tasks-outline - Create Task Breakdown Document

Version: 0.12.0+

Purpose

Create tasks.md — the task breakdown document that defines work packages, subtask lists, dependency descriptions, and sizing estimates. This step produces the outline only; individual WP prompt files are generated in the next step.

⚠️ CRITICAL: THIS IS THE MOST IMPORTANT PLANNING WORK

You are creating the blueprint for implementation. The quality of work packages determines:

• How easily agents can implement the feature
• How parallelizable the work is
• How reviewable the code will be
• Whether the feature succeeds or fails

QUALITY OVER SPEED: Take your time to understand the full scope deeply, break work into clear pieces, and write detailed guidance.

📍 WORKING DIRECTORY: Stay in the project root checkout

IMPORTANT: This step works in the project root checkout. NO worktrees created.

Do NOT cd anywhere. Stay in the project root checkout root.

In repos with multiple features, always pass `--feature <slug>` to every spec-kitty command.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Context Resolution

Before proceeding, resolve canonical command context:

spec-kitty agent context resolve --action tasks_outline --json

Treat that JSON as canonical for feature slug, feature directory, and target branch. Do not probe git branch state manually inside the prompt.

Steps

1. Setup

Run the exact check_prerequisites command returned by the resolver. Capture feature_dir plus available_docs. All paths must be absolute.

CRITICAL: The command returns JSON with feature_dir as an ABSOLUTE path. YOU MUST USE THIS PATH for ALL subsequent file operations.

2. Load Design Documents

Read from feature_dir (only those present):

• Required: plan.md (tech architecture, stack), spec.md (user stories & priorities)
• Optional: data-model.md (entities), contracts/ (API schemas), research.md (decisions), quickstart.md (validation scenarios)

Scale your effort to the feature: simple UI tweaks deserve lighter coverage, multi-system releases require deeper decomposition.

3. Derive Fine-Grained Subtasks

Create complete list of subtasks with IDs T001, T002, etc.:

• Parse plan/spec to enumerate concrete implementation steps, tests (only if explicitly requested), migrations, and operational work.
• Capture prerequisites, dependencies, and parallelizability markers ([P] means safe to parallelize per file/concern).
• Assign IDs sequentially in execution order.
• Ideal granularity: One clear action (e.g., "Create user model", "Add login endpoint")

4. Roll Subtasks into Work Packages

Group subtasks into work packages (IDs WP01, WP02, ...):

TARGET SIZE: 3-7 subtasks per WP (200-500 line prompts) MAXIMUM: 10 subtasks per WP (700 line prompts) If more than 10 subtasks needed: Create additional WPs, don't pack them in

GROUPING PRINCIPLES:

• Each WP should be independently implementable
• Root in a single user story or cohesive subsystem
• Ensure every subtask appears in exactly one work package
• Name with succinct goal (e.g., "User Story 1 – Real-time chat happy path")
• Record metadata: priority, success criteria, risks, dependencies, included subtasks, and requirement references
• Every WP must include a Requirement Refs line listing IDs from spec.md (FR/NFR/C)

5. Write tasks.md

Write to feature_dir/tasks.md following the tasks template structure below (do NOT write instructions to read a template file from `.kittify/`):

• Populate Work Package sections (setup, foundational, per-story, polish) with WPxx entries
• Under each work package include:
• Summary (goal, priority, independent test)
• Requirement references (Requirement Refs: FR-001, NFR-001, C-001)
• Included subtasks (checkbox list referencing Txxx)
• Implementation sketch (high-level sequence)
• Parallel opportunities, dependencies, and risks
• Estimated prompt size (e.g., "~400 lines")
• Add a Requirements Coverage Summary section mapping every requirement ID in spec.md to one or more WPs
• Preserve the checklist style so implementers can mark progress

DO NOT generate WP prompt files in this step. That happens in the next step.

Output

After completing this step:

• feature_dir/tasks.md exists with full work package definitions
• Each WP has clear subtask lists, dependencies, and sizing estimates
• No WP prompt files have been created yet

Next step: spec-kitty next --agent <name> will advance to work package generation.

Work Package Sizing Guidelines

Target: 3-7 subtasks per WP → 200-500 line prompts Maximum: 10 subtasks → ~700 line prompts No arbitrary limit on WP count — let complexity dictate

Split if ANY of these are true:

• More than 10 subtasks
• Prompt would exceed 700 lines
• Multiple independent concerns mixed together
• Different phases or priorities mixed

Merge if ALL of these are true:

• Each WP has <3 subtasks
• Combined would be <7 subtasks
• Both address the same concern/component
• No natural parallelization opportunity

Dependency Detection

Analyze tasks.md for dependency relationships:

• Explicit phrases: "Depends on WP##", "Dependencies: WP##"
• Phase grouping: Phase 2 WPs typically depend on Phase 1
• Default to empty if unclear

Document dependencies clearly in each WP's section.

Context for work-package planning: $ARGUMENTS