spec-kitty-tasks

name	spec-kitty-tasks
description	Generate grouped work packages with actionable subtasks and matching

/spec-kitty.tasks - Generate Work Packages

Version: 0.11.0+

⚠️ 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: This is NOT the time to save tokens or rush. Take your time to:

• Understand the full scope deeply
• Break work into clear, manageable pieces
• Write detailed, actionable guidance
• Think through risks and edge cases

Token usage is EXPECTED and GOOD here. A thorough task breakdown saves 10x the effort during implementation. Do not cut corners.

---

📍 WORKING DIRECTORY: Stay in planning repository

IMPORTANT: Tasks works in the planning repository. NO worktrees created.

# Run from project root (same directory as /spec-kitty.plan):
# You should already be here if you just ran /spec-kitty.plan

# Creates:
# - kitty-specs/###-feature/tasks/WP01-*.md → In planning repository
# - kitty-specs/###-feature/tasks/WP02-*.md → In planning repository
# - Commits ALL to target branch
# - NO worktrees created

Do NOT cd anywhere. Stay in the planning repository root.

Worktrees created later: After tasks are generated, use spec-kitty implement WP## to create workspace for each WP.

User Input

$ARGUMENTS

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

Location Check (0.11.0+)

Before proceeding, verify you are in the planning repository:

1. Run spec-kitty agent feature check-prerequisites --json --paths-only --include-tasks from the repository root and capture:

   • target_branch / base_branch
   • TARGET_BRANCH / BASE_BRANCH (uppercase aliases)
   • feature_dir, artifact_files, artifact_dirs

   Treat this JSON as canonical branch context for this command. Do not read meta.json to infer branch expectations.

Check your current branch:

git branch --show-current

Expected output: the value from TARGET_BRANCH (typically main or 2.x) If you see a feature branch: You're in the wrong place. Return to the target branch:

cd $(git rev-parse --show-toplevel)
git checkout "$TARGET_BRANCH"

Work packages are generated directly in kitty-specs/###-feature/ and committed to the target branch. Worktrees are created later when implementing each work package.

Outline

1. Setup: Use the previously captured check-prerequisites JSON. Capture:

   • feature_dir
   • artifact_files / artifact_dirs (if present)
   • available_docs
   • target_branch / base_branch All paths must be absolute.

   CRITICAL: The command returns JSON with feature_dir as an ABSOLUTE path (e.g., /Users/robert/Code/new_specify/kitty-specs/001-feature-name). It also returns runtime_vars.now_utc_iso (NOW_UTC_ISO) for deterministic timestamp fields.

   YOU MUST USE THIS PATH for ALL subsequent file operations. Example:

   feature_dir = "/Users/robert/Code/new_specify/kitty-specs/001-a-simple-hello"
   tasks.md location: feature_dir + "/tasks.md"
   prompt location: feature_dir + "/tasks/WP01-slug.md"
   

   DO NOT CREATE paths like:

   • ❌ tasks/WP01-slug.md (missing feature_dir prefix)
   • ❌ /tasks/WP01-slug.md (wrong root)
   • ❌ feature_dir/tasks/planned/WP01-slug.md (WRONG - no subdirectories!)
   • ❌ WP01-slug.md (wrong directory)

2. Load design documents 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 (IDs T001, T002, ...):

   • 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).
   • Maintain the subtask list internally; it feeds the work-package roll-up and the prompts.

4. Roll subtasks into work packages (IDs , , ...):

Context for work-package planning: $ARGUMENTS

The combination of tasks.md and the bundled prompt files must enable a new engineer to pick up any work package and deliver it end-to-end without further specification spelunking.

Dependency Detection (0.11.0+)

Parse dependencies from tasks.md structure:

The LLM should 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

Generate dependencies in WP frontmatter:

Each WP prompt file MUST include a dependencies field:

---
work_package_id: "WP02"
title: "Build API"
lane: "planned"
dependencies: ["WP01"]  # Generated from tasks.md
subtasks: ["T001", "T002"]
---

Include the correct implementation command:

• No dependencies: spec-kitty implement WP01
• With dependencies: spec-kitty implement WP02 --base WP01

The WP prompt must show the correct command so agents don't branch from the wrong base.

Requirement Reference Mapping (MANDATORY)

finalize-tasks validates requirement coverage from tasks.md. Each WP section must include a requirement mapping line in this format:

### Requirement Refs
- FR-001, FR-007

or

**Requirements Refs**: FR-001, FR-007

Do not rely on WP frontmatter alone for requirement mapping; keep the canonical mapping in tasks.md.

Work Package Sizing Guidelines (CRITICAL)

Ideal WP Size

Target: 3-7 subtasks per WP

• Results in 200-500 line prompt files
• Agent can hold entire context in working memory
• Clear scope - easy to review
• Parallelizable - multiple agents can work simultaneously

Examples of well-sized WPs:

• WP01: Foundation Setup (5 subtasks, ~300 lines)

  • T001: Create database schema
  • T002: Set up migration system
  • T003: Create base models
  • T004: Add validation layer
  • T005: Write foundation tests

• WP02: User Authentication (6 subtasks, ~400 lines)

  • T006: Implement login endpoint
  • T007: Implement logout endpoint
  • T008: Add session management
  • T009: Add password reset flow
  • T010: Write auth tests
  • T011: Add rate limiting

Maximum WP Size

Hard limit: 10 subtasks, ~700 lines

• Beyond this, agents start making mistakes
• Prompts become overwhelming
• Reviews take too long
• Integration risk increases

If you need more than 10 subtasks: SPLIT into multiple WPs.

Number of WPs: No Arbitrary Limit

DO NOT limit based on WP count. Limit based on SIZE.

• ✅ 20 WPs of 5 subtasks each = 100 subtasks, manageable prompts
• ❌ 5 WPs of 20 subtasks each = 100 subtasks, overwhelming 1400-line prompts

Feature complexity scales with subtask count, not WP count:

• Simple feature: 10-15 subtasks → 2-4 WPs
• Medium feature: 30-50 subtasks → 6-10 WPs
• Complex feature: 80-120 subtasks → 15-20 WPs ← Totally fine!
• Very complex: 150+ subtasks → 25-30 WPs ← Also fine!

The goal is manageable WP size, not minimizing WP count.

When to Split a WP

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
• Agent would need to switch contexts multiple times

How to split:

• By phase: Foundation WP01, Implementation WP02, Testing WP03
• By component: Database WP01, API WP02, UI WP03
• By user story: Story 1 WP01, Story 2 WP02, Story 3 WP03
• By type of work: Code WP01, Tests WP02, Migration WP03, Docs WP04

When to Merge WPs

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
• Implementation is highly coupled

Don't merge just to hit a WP count target!

Task Generation Rules

Tests remain optional. Only include testing tasks/steps if the feature spec or user explicitly demands them.

1. Subtask derivation:

   • Assign IDs Txxx sequentially in execution order.
   • Use [P] for parallel-safe items (different files/components).
   • Include migrations, data seeding, observability, and operational chores.
   • Ideal subtask granularity: One clear action (e.g., "Create user model", "Add login endpoint")
   • Too granular: "Add import statement", "Fix typo" (bundle these)
   • Too coarse: "Build entire API" (split into endpoints)

2. Work package grouping:

   • Focus on SIZE first, count second
   • Target 3-7 subtasks per WP (200-500 line prompts)
   • Maximum 10 subtasks per WP (700 line prompts)
   • Keep each work package laser-focused on a single goal
   • Avoid mixing unrelated concerns
   • Let complexity dictate WP count: 20+ WPs is fine for complex features

3. Prioritisation & dependencies:

   • Sequence work packages: setup → foundational → story phases (priority order) → polish.
   • Call out inter-package dependencies explicitly in both tasks.md and the prompts.
   • Front-load infrastructure/foundation WPs (enable parallelization)

4. Prompt composition:

   • Mirror subtask order inside the prompt.
   • Provide actionable implementation and test guidance per subtask—short for trivial work, exhaustive for complex flows.
   • Aim for 30-70 lines per subtask in the prompt (includes purpose, steps, files, validation)
   • Surface risks, integration points, and acceptance gates clearly so reviewers know what to verify.
   • Include examples where helpful (API request/response shapes, config file structures, test cases)

5. Quality checkpoints:

   • After drafting WPs, review each prompt size estimate
   • If any WP >700 lines: STOP and split it
   • If most WPs <200 lines: Consider merging related ones
   • Aim for consistency: Most WPs should be similar size (within 200-line range)
   • Think like an implementer: Can I complete this WP in one focused session? If not, it's too big.

6. Think like a reviewer: Any vague requirement should be tightened until a reviewer can objectively mark it done or not done.

Step-by-Step Process

Step 1: Setup

Run spec-kitty agent feature check-prerequisites --json --paths-only --include-tasks and capture feature_dir.

Step 2: Load Design Documents

Read from feature_dir:

• spec.md (required)
• plan.md (required)
• data-model.md (optional)
• research.md (optional)
• contracts/ (optional)

Step 3: Derive ALL Subtasks

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

Don't worry about count yet - capture EVERYTHING needed.

Step 4: Group into Work Packages

SIZING ALGORITHM:

For each cohesive unit of work:
  1. List related subtasks
  2. Count subtasks
  3. Estimate prompt lines (subtasks × 50 lines avg)

  If subtasks <= 7 AND estimated lines <= 500:
    ✓ Good WP size - create it

  Else if subtasks > 10 OR estimated lines > 700:
    ✗ Too large - split into 2+ WPs

  Else if subtasks < 3 AND can merge with related WP:
    → Consider merging (but don't force it)

Examples:

Good sizing:

• WP01: Database Foundation (5 subtasks, ~300 lines) ✓
• WP02: User Authentication (7 subtasks, ~450 lines) ✓
• WP03: Admin Dashboard (6 subtasks, ~400 lines) ✓

Too large - MUST SPLIT:

• ❌ WP01: Entire Backend (25 subtasks, ~1500 lines)
  • ✓ Split into: DB Layer (5), Business Logic (6), API Layer (7), Auth (7)

Too small - CONSIDER MERGING:

• WP01: Add config file (2 subtasks, ~100 lines)
• WP02: Add logging (2 subtasks, ~120 lines)
  • ✓ Merge into: WP01: Infrastructure Setup (4 subtasks, ~220 lines)

Step 5: Write tasks.md

Create work package sections with:

• Summary (goal, priority, test criteria)
• Included subtasks (checkbox list)
• Implementation notes
• Parallel opportunities
• Dependencies
• Estimated prompt size (e.g., "~400 lines")

Step 6: Generate WP Prompt Files

For each WP, generate feature_dir/tasks/WPxx-slug.md using the template.

CRITICAL VALIDATION: After generating each prompt:

1. Count lines in the prompt
2. If >700 lines: GO BACK and split the WP
3. If >1000 lines: STOP - this will fail - you MUST split it

Self-check:

• Subtask count: 3-7? ✓ | 8-10? ⚠️ | 11+? ❌ SPLIT
• Estimated lines: 200-500? ✓ | 500-700? ⚠️ | 700+? ❌ SPLIT
• Can implement in one session? ✓ | Multiple sessions needed? ❌ SPLIT

Step 7: Finalize Tasks

Run spec-kitty agent feature finalize-tasks --json to:

• Parse dependencies
• Update frontmatter
• Validate (cycles, invalid refs)
• Commit to target branch

DO NOT run git commit after this - finalize-tasks commits automatically. Check JSON output for "commit_created": true and "commit_hash" to verify.

Step 8: Report

Provide summary with:

• WP count and subtask tallies
• Size distribution (e.g., "6 WPs ranging from 250-480 lines")
• Size validation (e.g., "✓ All WPs within ideal range" OR "⚠️ WP05 is 820 lines - consider splitting")
• Parallelization opportunities
• MVP scope
• Next command

Dependency Detection (0.11.0+)

Parse dependencies from tasks.md structure:

The LLM should 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

Generate dependencies in WP frontmatter:

Each WP prompt file MUST include a dependencies field:

---
work_package_id: "WP02"
title: "Build API"
lane: "planned"
dependencies: ["WP01"]  # Generated from tasks.md
subtasks: ["T001", "T002"]
---

Include the correct implementation command:

• No dependencies: spec-kitty implement WP01
• With dependencies: spec-kitty implement WP02 --base WP01

The WP prompt must show the correct command so agents don't branch from the wrong base.

⚠️ Common Mistakes to Avoid

❌ MISTAKE 1: Optimizing for WP Count

Bad thinking: "I'll create exactly 5-7 WPs to keep it manageable" → Results in: 20 subtasks per WP, 1200-line prompts, overwhelmed agents

Good thinking: "Each WP should be 3-7 subtasks (200-500 lines). If that means 15 WPs, that's fine." → Results in: Focused WPs, successful implementation, happy agents

❌ MISTAKE 2: Token Conservation During Planning

Bad thinking: "I'll save tokens by writing brief prompts with minimal guidance" → Results in: Agents confused during implementation, asking clarifying questions, doing work wrong, requiring rework

Good thinking: "I'll invest tokens now to write thorough prompts with examples and edge cases" → Results in: Agents implement correctly the first time, no rework needed, net token savings

❌ MISTAKE 3: Mixing Unrelated Concerns

Bad example: WP03: Misc Backend Work (12 subtasks)

• T010: Add user model
• T011: Configure logging
• T012: Set up email service
• T013: Add admin dashboard
• ... (8 more unrelated tasks)

Good approach: Split by concern

• WP03: User Management (T010-T013, 4 subtasks)
• WP04: Infrastructure Services (T014-T017, 4 subtasks)
• WP05: Admin Dashboard (T018-T021, 4 subtasks)

❌ MISTAKE 4: Insufficient Prompt Detail

Bad prompt (~20 lines per subtask):

### Subtask T001: Add user authentication

**Purpose**: Implement login

**Steps**:
1. Create endpoint
2. Add validation
3. Test it

Good prompt (~60 lines per subtask):

### Subtask T001: Implement User Login Endpoint

**Purpose**: Create POST /api/auth/login endpoint that validates credentials and returns JWT token.

**Steps**:
1. Create endpoint handler in `src/api/auth.py`:
   - Route: POST /api/auth/login
   - Request body: `{email: string, password: string}`
   - Response: `{token: string, user: UserProfile}` on success
   - Error codes: 400 (invalid input), 401 (bad credentials), 429 (rate limited)

2. Implement credential validation:
   - Hash password with bcrypt (matches registration hash)
   - Compare against stored hash from database
   - Use constant-time comparison to prevent timing attacks

3. Generate JWT token on success:
   - Include: user_id, email, issued_at, expires_at (24 hours)
   - Sign with SECRET_KEY from environment
   - Algorithm: HS256

4. Add rate limiting:
   - Max 5 attempts per IP per 15 minutes
   - Return 429 with Retry-After header

**Files**:
- `src/api/auth.py` (new file, ~80 lines)
- `tests/api/test_auth.py` (new file, ~120 lines)

**Validation**:
- [ ] Valid credentials return 200 with token
- [ ] Invalid credentials return 401
- [ ] Missing fields return 400
- [ ] Rate limit enforced (test with 6 requests)
- [ ] JWT token is valid and contains correct claims
- [ ] Token expires after 24 hours

**Edge Cases**:
- Account doesn't exist: Return 401 (same as wrong password - don't leak info)
- Empty password: Return 400
 SQL injection in email field: Prevented by parameterized queries
 Concurrent login attempts: Handle with database locking

Remember

This is the most important planning work you'll do.

A well-crafted set of work packages with detailed prompts makes implementation smooth and parallelizable.

A rushed job with vague, oversized WPs causes:

• Agents getting stuck
• Implementation taking 2-3x longer
• Rework and review cycles
• Feature failure

Invest the tokens now. Be thorough. Future agents will thank you.