Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
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.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/spec-kitty/gapdb --skill spec-kitty-tasksThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
| name | spec-kitty.tasks |
| description | Translate implementation concerns into work packages |
| user-invocable | true |
Run this at most once per active agent session before the first Spec Kitty command workflow.
If you already ran spec-kitty upgrade --agent-check --json in this session, reuse that result and skip this block.
Do not run or announce an upgrade check again for later Spec Kitty commands in the same session.
Otherwise, before continuing, run:
spec-kitty upgrade --agent-check --json
If JSON action is none, continue.
If action is auto_upgrade, run upgrade_command before continuing. If it fails, tell the user and continue with the current Spec Kitty version.
If action is guidance, show upgrade_note briefly, then continue.
If action is prompt, ask the user with the host-native question UI when available:
Spec Kitty {latest_version} is available. You are on {installed_version}. Upgrade now?
Use these choices:
upgrade_now, run upgrade_command, then continue.always, run upgrade_command, then continue.not_now, then continue.never_ask, then continue.Record the selected choice before continuing:
spec-kitty upgrade --agent-choice <upgrade_now|always|not_now|never_ask> --agent-latest <latest_version> --json
If no host-native question UI is available, present the same four choices in plain text and wait for the user.
In non-interactive hosts, choose not_now and continue.
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 repository 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 repository root checkout
# - kitty-specs/<mission_slug>/tasks/WP02-*.md → In repository 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 repository root checkout.
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, ...):
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:
Txxx ids, tracked via mark-status)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.
After finalize-tasks completes, review all available doctrine-provided and user-created agent profiles and assign the most relevant profile to each work package.
List available profiles:
spec-kitty agent profile list --json
Only a read-only harness that cannot invoke the CLI may inspect profiles under
src/doctrine/agent_profiles/built-in/and any user-defined profile directory. This degraded fallback can diverge because organization/project overlays,specializes_fromlineage, andenhances/overridessemantics are not applied; state that limitation when selecting a profile this way.
For each work package, select the best-matching profile based on:
task_type (implement / review / plan / specify / research)authoritative_surface and owned_files (what domain the WP touches)Update each WP prompt file's frontmatter directly (do NOT re-run finalize-tasks) with:
agent_profile: the profile identifier (e.g., "implementer-ivan", "architect-alphonso", "curator-carla")role: the role within the profile (e.g., "implementer", "reviewer")agent: the CLI agent/tool identifier (e.g., "claude", "codex", "copilot")model: the model identifier (optional, e.g., "claude-sonnet-4-6")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.Required pre-implementation gate:
/spec-kitty.analyzemust run before any WP implementation. It persists ananalysis-report.mdand reviews spec/plan/task consistency; the implement gate refuses to start (analysis_report_required) until that report exists. This is not optional — it is the readiness gate/spec-kitty.implementenforces.
/spec-kitty.analyze has been run for this mission (run it now if analysis-report.md is missing — implementation cannot claim a WP without it), then invoke the 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 — reminding them that /spec-kitty.analyze is a required prerequisite the implement gate enforces./spec-kitty.analyze --mission <mission-slug> (also the required gate) and wait for the user's decision on whether to address findings before invoking implementation.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:
[P] means safe to parallelize per file/concern).Per-WP subtask rows in tasks.md are reference rows, not checkboxes. Subtask
completion is solely event-sourced — the reduced event-log snapshot is the
authority (#2816 IC-10 / FR-016); there is no - [ ] box to tick. Emit each
Txxx as a plain reference row under its work package:
T001 Description of task (WP01)
T002 Another task (WP01)
Record completion with spec-kitty agent tasks mark-status T001 T002 --status done
(single or batch). mark-status writes the completion into the event log; it does
not flip a markdown checkbox. Do not use pipe-table format for tracking rows
in work-package sections.
Important distinction — Subtask Index vs. reference 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 records
completion in the reduced event-log snapshot keyed by the Txxx id, never by
editing a markdown row.
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 ids, tracked via mark-status)spec-kitty agent tasks mark-status, not by ticking boxesGenerate 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, agent_profile, role, agent, model (optional), and history entry
## ⚡ Do This First: Load Agent Profile — REQUIRED, must be the first body section (before Objective). Instructs the implementing agent to load the assigned profile via /ad-hoc-profile-load before reading anything else. See task-prompt-template.md for the exact block.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/"create_intent: List of repo-root-relative literal paths this WP will create. Use this when an owned_files entry names a planned-new file that does not exist yet, so finalize-tasks treats the zero-match as an intentional planned-new-file instead of a validation failure. Example: ["tests/myapp/test_new_auth.py"]. Keep a single create_intent key; if a stub create_intent: [] already exists, replace it instead of adding a duplicate block.Ownership rules:
owned_files.src/**.owned_files list; a small, well-justified out-of-map edit is acceptable when recorded with a one-line rationale (the no-overlap rule above is the real guard against parallel-WP collisions).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 validate-only first to prove the finalization requirements are met:
CRITICAL: Run this preflight command from repo root:
spec-kitty agent mission finalize-tasks --validate-only --mission <mission-slug> --json
If the JSON output contains "error": "Requirement mapping validation failed",
do not run the mutating finalization command. Report
missing_requirement_refs_wps, unknown_requirement_refs, and
unmapped_functional_requirements, then fix mappings with
spec-kitty agent tasks map-requirements --mission <mission-slug> --json or
by updating WP requirement_refs.
Only after validate-only exits successfully, run the mutating command from repo root:
spec-kitty agent mission finalize-tasks --mission <mission-slug> --json
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## ⚡ Do This First section/spec-kitty.analyze or /spec-kitty.implement)