Menu
Break a plan into work packages
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Interview and compile a project charter
Generate a requirements-quality checklist
Execute a work package implementation
Create an implementation plan
Generate research documents for the current mission
Review a work package implementation
| name | spec-kitty.tasks |
| description | Break a plan into work packages |
| user-invocable | true |
Version: 0.11.0+
You are creating the blueprint for implementation. The quality of work packages determines:
QUALITY OVER SPEED: This is NOT the time to save tokens or rush. Take your time to:
Token usage is EXPECTED and GOOD here. A thorough task breakdown saves 10x the effort during implementation. Do not cut corners.
IMPORTANT: Tasks works in the project root checkout. 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/<mission_slug>/tasks/WP01-*.md → In project root checkout
# - kitty-specs/<mission_slug>/tasks/WP02-*.md → In project root checkout
# (the NNN- prefix in directory listings is display-only metadata)
# - Commits ALL to target branch
# - NO worktrees created
Do NOT cd anywhere. Stay in the project root checkout root.
Worktrees created later: After tasks are finalized, run your agent loop: spec-kitty next --agent <agent> --mission <handle>. Your agent will call spec-kitty agent action implement WP## --agent <name> for each WP. finalize_tasks computes the execution lanes, and each lane gets exactly one worktree.
In repos with multiple missions, always pass --mission <handle> to every spec-kitty command. The <handle> can be the mission's mission_id (ULID), mid8 (first 8 chars of the ULID), or mission_slug. The resolver disambiguates by mission_id and returns a structured MISSION_AMBIGUOUS_SELECTOR error on ambiguity — there is no silent fallback.
The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after /spec-kitty.<command> or $spec-kitty.<command>) is the User Input referenced elsewhere in these instructions.
You MUST consider this user input before proceeding (if not empty).
Before proceeding, resolve canonical command context:
spec-kitty agent context resolve --action tasks --mission <mission-slug> --json
Treat the resolver JSON as canonical for:
mission_slugfeature_dircurrent_branchtarget_branchplanning_base_branchmerge_target_branchbranch_matches_targetcheck_prerequisites, finalize_tasks)Prompts do not rediscover feature context. Commands do.
Setup: Run the exact check_prerequisites command returned by the resolver and capture:
feature_dirartifact_files / artifact_dirs (if present)available_docscurrent_branchtarget_branch / base_branchplanning_base_branch / merge_target_branchbranch_matches_target
All paths must be absolute.If branch_matches_target is false, stop and tell the user the checkout is on the wrong planning branch instead of probing git manually in the prompt.
CRITICAL: The command returns JSON with feature_dir as an ABSOLUTE path. 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 = "/path/to/project/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)Load design documents from feature_dir (only those present):
Derive fine-grained subtasks (IDs T001, T002, ...):
[P] means safe to parallelize per file/concern).Use checkbox format for all per-WP task tracking rows in tasks.md:
- [ ] T001 Description of task (WP01)
- [ ] T002 Another task (WP01)
Do not use pipe-table format for tracking rows in work-package sections.
mark-status targets these per-WP checkbox rows; it also supports pipe-table
rows for backward compatibility, but new generation must use checkboxes exclusively.
Important distinction — Subtask Index vs. tracking rows:
The top-level Subtask Index pipe-table (e.g. | T001 | desc | WP | Parallel |) is
a reference table only — it is not a tracking surface. The [P] marker in its
"Parallel" column indicates parallelism, not task status. mark-status tracks
progress via the per-WP checkbox rows (- [ ] T001 …) below each work-package
heading, not via the index table.
Roll subtasks into work packages (IDs WP01, WP02, ...):
IDEAL WORK PACKAGE SIZE (most important guideline):
WHY SIZE MATTERS:
NUMBER OF WPs: Let the work dictate the count
GROUPING PRINCIPLES:
Write tasks.md following the tasks template structure defined below in this prompt (do NOT write instructions to read a template file from .kittify/):
feature_dir/tasks.md (use the absolute feature_dir path from step 1)WPxx entriesTxxx)Generate prompt files (one per work package):
feature_dir/tasks/ directory, NOT in subdirectories!feature_dir/tasks/WPxx-slug.md (flat, no subdirectories)feature_dir/tasks/planned/, feature_dir/tasks/doing/, or ANY status subdirectories/tasks/, tasks/, or any path not under feature_dirartifact_dirs.tasks_dir when available.mkdir -p; create already creates tasks/ in normal flow.tasks/ is missing unexpectedly, report the mismatch instead of improvising shell directory setup.WPxx-slug.mdfeature_dir/tasks/WP01-create-html-page.md (use ABSOLUTE path from feature_dir variable).kittify/) to capture:work_package_id, subtasks array, dependencies, planning_base_branch, merge_target_branch, branch_strategy, owned_files, authoritative_surface, execution_mode, and history entry
lanes.jsontasks.md to reference the prompt filenameIMPORTANT: All WP files live in flat tasks/ directory.
OWNERSHIP METADATA (required by finalize-tasks): Each WP MUST declare these fields in frontmatter. If omitted, the finalizer infers them (often incorrectly, causing validation failures):
execution_mode: Either "code_change" (source code) or "planning_artifact" (kitty-specs docs)owned_files: List of glob patterns for files this WP touches. Example: ["src/myapp/auth/**", "tests/myapp/test_auth.py"]authoritative_surface: Path prefix that must be a prefix of at least one owned_files entry. Example: "src/myapp/auth/"Ownership rules:
owned_files.src/**.owned_files list.spec-kitty agent mission finalize-tasks --validate-only --mission <mission-slug> --json to check ownership before committing.Finalize tasks with dependency parsing and commit: After generating all WP prompt files, run the finalization command to:
CRITICAL: Run this command from repo root:
spec-kitty agent mission finalize-tasks --json --mission <mission-slug>
This step is MANDATORY. Without it:
lanes.json won't be available to resolve the real workspace path/branch for each WPIMPORTANT - DO NOT COMMIT AGAIN AFTER THIS COMMAND:
Report: Provide a concise outcome summary:
tasks.md/spec-kitty.analyze or /spec-kitty.implement)Context for work-package planning: (refer to the User Input section above)
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.
Parse dependencies from tasks.md structure:
The LLM should analyze tasks.md for dependency relationships:
Generate dependencies in WP frontmatter:
Each WP prompt file MUST include a dependencies field:
---
work_package_id: "WP02"
title: "Build API"
dependencies: ["WP01"] # Generated from tasks.md
subtasks: ["T001", "T002"]
---
Include the correct implementation command:
spec-kitty agent action implement WP01 --agent <name>spec-kitty agent action implement WP02 --agent <name>The WP prompt must show the correct command so agents don't branch from the wrong base.
After creating all WP sections and prompt files, register requirement mappings using the CLI.
The CLI validates each ref against spec.md and writes requirement_refs directly into each
WP file's YAML frontmatter — no sidecar files needed.
Batch mode (recommended) — register all WP mappings at once:
spec-kitty agent tasks map-requirements --batch '{"WP01":["FR-001","FR-002"],"WP02":["FR-003","FR-004"]}' --mission <mission-slug> --json
Individual mode — register one WP at a time:
spec-kitty agent tasks map-requirements --wp WP01 --refs FR-001,FR-002 --mission <mission-slug> --json
The response includes a coverage summary showing which FRs are still unmapped. Keep calling
until unmapped_functional is empty. Default mode unions new refs with existing ones in
frontmatter. Use --replace to overwrite a WP's refs (e.g., to correct a bad mapping).
Target: 3-7 subtasks per WP
Examples of well-sized WPs:
WP01: Foundation Setup (5 subtasks, ~300 lines)
WP02: User Authentication (6 subtasks, ~400 lines)
Hard limit: 10 subtasks, ~700 lines
If you need more than 10 subtasks: SPLIT into multiple WPs.
DO NOT limit based on WP count. Limit based on SIZE.
Feature complexity scales with subtask count, not WP count:
The goal is manageable WP size, not minimizing WP count.
Split if ANY of these are true:
How to split:
Merge if ALL of these are true:
Don't merge just to hit a WP count target!
Tests remain optional. Only include testing tasks/steps if the feature spec or user explicitly demands them.
Subtask derivation:
Txxx sequentially in execution order.[P] for parallel-safe items (different files/components).Work package grouping:
Prioritisation & dependencies:
tasks.md and the prompts.Prompt composition:
Quality checkpoints:
Think like a reviewer: Any vague requirement should be tightened until a reviewer can objectively mark it done or not done.
Resolve the feature slug from explicit user direction, current branch, or current directory path.
If ambiguous, run check-prerequisites once without --mission, parse the JSON candidate list, and select one explicit mission slug.
Run spec-kitty agent mission check-prerequisites --json --paths-only --include-tasks --mission <mission-slug> and capture feature_dir.
Read from feature_dir:
Create complete list of subtasks with IDs T001, T002, etc.
Don't worry about count yet - capture EVERYTHING needed.
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:
Too large - MUST SPLIT:
Too small - CONSIDER MERGING:
Create work package sections with:
For each WP, generate feature_dir/tasks/WPxx-slug.md using the template.
CRITICAL VALIDATION: After generating each prompt:
Self-check:
Run the resolver-returned finalize_tasks command to:
DO NOT run git commit after this - finalize-tasks commits automatically. Check JSON output for "commit_created": true and "commit_hash" to verify.
Provide summary with:
After reporting, ask the user directly:
Should I use the
/spec-kitty-implement-reviewskill to fully implement all WPs until completion? This will dispatch implementing and reviewing agents for every WP, handle rejection cycles, and merge all lanes when done.
spec-kitty-implement-review skill with the mission slug. The user may also specify which agents to use for implementation and review (e.g., "yes, use sonnet for implementing and opus for reviewing")./spec-kitty.implement at their own pace.This handoff is the natural transition from planning to execution. Do NOT skip the question — always offer it explicitly so the user can choose their execution strategy.
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
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
Bad example: WP03: Misc Backend Work (12 subtasks)
Good approach: Split by concern
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
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: