spec-kitty-tasks-packages

A standard Spec-Kitty workflow routine.

🔗 Workflow Provenance

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

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

/spec-kitty.tasks-packages - Generate Work Package Files

Version: 0.12.0+

Purpose

Generate individual tasks/WP*.md prompt files from the outline in tasks.md. This step assumes tasks.md already exists with complete WP definitions.

📍 WORKING DIRECTORY: Stay in the project root checkout

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

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

User Input

$ARGUMENTS

Steps

1. Setup

Run:

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

Then execute the returned check_prerequisites command and capture feature_dir. All paths must be absolute.

2. Load tasks.md

Read feature_dir/tasks.md — this must already exist from the previous step. Parse the work package definitions, subtask lists, and dependencies.

3. Generate Prompt Files

For each work package defined in tasks.md:

CRITICAL PATH RULE: All WP files MUST be created in a FLAT feature_dir/tasks/ directory, NOT in subdirectories!

  • Correct: feature_dir/tasks/WPxx-slug.md (flat, no subdirectories)
  • WRONG: feature_dir/tasks/planned/, feature_dir/tasks/doing/, or ANY status subdirectories

For each WP:

  1. Derive a kebab-case slug from the title
  2. Filename: WPxx-slug.md (e.g., WP01-create-html-page.md)
  3. Full path: feature_dir/tasks/WP01-create-html-page.md
  4. Follow the WP prompt template structure below (do NOT write instructions to read a template file from .kittify/)
  5. Include frontmatter with:
    • work_package_id, subtasks array, dependencies, history entry
    • requirement_refs array from the WP's Requirement Refs line in tasks.md
    • owned_files, authoritative_surface, execution_mode (required ownership fields)
  6. Include in body:
    • Objective, context, detailed guidance per subtask
    • Test strategy (only if requested)
    • Definition of Done, risks, reviewer guidance
  7. Update tasks.md to reference the prompt filename

TARGET PROMPT SIZE: 200-500 lines per WP (3-7 subtasks) MAXIMUM PROMPT SIZE: 700 lines per WP (10 subtasks max) If prompts are >700 lines: Split the WP — it's too large

IMPORTANT: All WP files live in flat tasks/ directory. Status is managed via status.events.jsonl, not by directory location or frontmatter fields.

4. Include Dependencies in Frontmatter

Each WP prompt file MUST include a dependencies field:

---
work_package_id: "WP02"
title: "Build API"
dependencies: ["WP01"]  # From tasks.md
requirement_refs: ["FR-001", "NFR-001"]  # From tasks.md Requirement Refs
subtasks: ["T001", "T002"]
owned_files: ["src/api/**"]
authoritative_surface: "src/api/"
execution_mode: "code_change"
---

Include the correct implementation command:

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

Ownership rules:

  • owned_files: List of glob patterns for files this WP touches — no two WPs may overlap.
  • authoritative_surface: Path prefix that must be a prefix of at least one owned_files entry.
  • execution_mode: "code_change" for source code changes, "planning_artifact" for kitty-specs docs.
  • Agents working on a WP must not modify files outside their owned_files list.

5. Self-Check

After generating each prompt:

  • 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

Output

After completing this step:

  • feature_dir/tasks/WP*.md prompt files exist for all work packages
  • Each has proper frontmatter with work_package_id, dependencies, owned_files, authoritative_surface, execution_mode
  • tasks.md references all prompt filenames

Next step: spec-kitty next --agent <name> will advance to finalization.

Prompt Quality Guidelines

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, 401, 429

2. Implement credential validation:
   - Hash password with bcrypt
   - Use constant-time comparison

**Files**: `src/api/auth.py` (new, ~80 lines)
**Validation**: Valid credentials return 200 with token

Bad prompt (~20 lines per subtask):

### T001: Add auth
Steps: Create endpoint. Add validation. Test it.

Context for work-package planning: $ARGUMENTS