/spec-kitty.tasks-packages - Generate Work Package Files
Version: 3.2.0
Purpose
Generate individual tasks/WP*.md prompt files from the manifest in wps.yaml.
This step reads wps.yaml (written in tasks-outline), updates it with per-WP
details, then generates the WP prompt files.
This step assumes wps.yaml already exists with complete WP definitions.
📍 WORKING DIRECTORY: Stay in the repository root checkout
IMPORTANT: This step works in the repository root checkout. NO worktrees created.
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.
User Input
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).
Steps
1. Setup
Run:
spec-kitty agent context resolve --action tasks_packages --mission <mission-slug> --json
Then execute the returned check_prerequisites command and capture
feature_dir. All paths must be absolute.
2. Load wps.yaml
Read feature_dir/wps.yaml. This is the manifest written in the previous step.
Each entry defines a WP with its id, title, dependencies, and partial metadata.
Parse all work package entries. The YAML structure is:
work_packages:
- id: WP01
title: "..."
dependencies: [...] # may be present (authoritative) or absent
owned_files: [...] # may be absent — fill in this step
requirement_refs: [...] # may be absent — fill in this step
subtasks: [...]
prompt_file: null # fill in this step
3. Generate Prompt Files in Parallel
Parse all WP definitions from wps.yaml. Each WP prompt file is independent —
dispatch one sub-agent per WP in a single message so they run concurrently
rather than generating all WP content in one serial response.
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
Batching for large missions: If there are more than 6 WPs, dispatch in groups of 4. Send all agents in a group in one message, wait for all to complete, then start the next group.
Sub-agent prompt (send one per WP, all dispatched simultaneously in one message):
You are writing a single Work Package prompt file for the spec-kitty planning pipeline. Write exactly one file and return the filename and final line count.
Feature directory: {feature_dir} (absolute path)
Write to: {feature_dir}/tasks/{wp_id}-{slug}.md
Work Package (from wps.yaml):
- id:
{wp_id} - title:
{title} - dependencies:
{dependencies} - owned_files:
{owned_files} - execution_mode: derive from
owned_files(planning_artifactfor kitty-specs/docs-only WPs, otherwisecode_change) - requirement_refs:
{requirement_refs} - subtasks:
{subtasks}
Read for context (all from feature_dir):
plan.md(required — tech architecture, stack)spec.md(required — user stories, acceptance criteria)data-model.md,research.md(read if present)
Write the WP prompt file with this structure:
Frontmatter:
---
work_package_id: "{wp_id}"
title: "{title}"
dependencies: {dependencies}
requirement_refs: {requirement_refs}
subtasks: {subtasks}
owned_files: {owned_files}
authoritative_surface: "{longest common path prefix of owned_files}"
execution_mode: "{execution_mode}"
agent_profile: "" # filled in Step 4a — profile identifier (e.g., implementer-ivan)
role: "" # filled in Step 4a — role within the profile (e.g., "implementer")
agent: "" # filled in Step 4a — CLI agent identifier (claude, codex, copilot, etc.)
model: "" # filled in Step 4a — model identifier (e.g., claude-sonnet-4-6), optional
---
Body sections (in order):
0. ## ⚡ Do This First: Load Agent Profile — REQUIRED. Must be the first section after the H1 title, before Objective. Instructs the implementing agent to load the assigned profile via /ad-hoc-profile-load before reading anything else. Use this exact structure, substituting frontmatter values:
## ⚡ Do This First: Load Agent Profile
Use the `/ad-hoc-profile-load` skill to load the agent profile specified in the frontmatter, and behave according to its guidance before parsing the rest of this prompt.
- **Profile**: `{agent_profile}`
- **Role**: `{role}`
- **Agent/tool**: `{agent}`
If no profile is specified, run `spec-kitty agent profile list` and select the best match for this work package's `task_type` and `authoritative_surface`.
---
## Objective— 1–3 sentence goal## Context— why this WP exists, what depends on it, key design decisions from plan.md### Subtask {T-id}: {name}— one section per subtask, ~60 lines each:- Purpose: what this subtask accomplishes
- Steps: numbered, with specific file paths and implementation details
- Files: what to create/modify, approximate size
- Validation: how to verify it works
## Definition of Done— verifiable checklist covering all subtasks## Risks— known risks and mitigations## Reviewer Guidance— what reviewers should focus on
Include the implementation command: spec-kitty agent action implement {wp_id} --agent <name>
Sizing: target 200–500 lines (3–7 subtasks), maximum 700 lines (10 subtasks).
If >700 lines would be needed: write the file anyway but add a > NOTE: This WP should be split callout at the top.
After all sub-agents confirm completion, proceed to Step 4.
Fallback — if your host does not support sub-agents: Generate all WP files sequentially and issue all Write tool calls in a single batched response.
Do NOT update wps.yaml during sub-agent dispatch — collect all confirmations,
then update once in Step 4.
4. Update wps.yaml With Per-WP Details
After all sub-agents have confirmed completion, update wps.yaml once with all
per-WP details collected from sub-agent results: owned_files, requirement_refs,
subtasks, and prompt_file for every WP. Write the updated wps.yaml in a
single write.
Critical rule: Do NOT modify a dependencies field that is already present in
wps.yaml — even if it is empty ([]). It is authoritative. Only populate
dependencies for entries where the key is absent from wps.yaml.
Example of a fully-populated entry after this step:
- id: WP02
title: "Build API"
dependencies:
- WP01
owned_files:
- "src/api/**"
requirement_refs:
- FR-001
- NFR-001
subtasks:
- T001
- T002
prompt_file: "tasks/WP02-build-api.md"
The frontmatter in each WP prompt file MUST include a dependencies field:
---
work_package_id: "WP02"
title: "Build API"
dependencies: ["WP01"] # From wps.yaml
requirement_refs: ["FR-001", "NFR-001"] # From wps.yaml requirement_refs
subtasks: ["T001", "T002"]
owned_files: ["src/api/**"]
authoritative_surface: "src/api/"
execution_mode: "code_change"
---
Include the correct implementation command:
spec-kitty agent action implement WP01 --agent <name>spec-kitty agent action implement WP02 --agent <name>
finalize_tasks computes execution lanes from dependencies and write ownership. Agents never choose a base branch manually.
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 oneowned_filesentry.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_fileslist.
4a. Assign Agent Profiles
After all WP files are written and wps.yaml is updated, 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
If this command is unavailable, look for profiles under
src/doctrine/agent_profiles/shipped/and any user-defined profiles in.kittify/agent_profiles/or equivalent.
For each WP, select the best-matching profile based on task_type, authoritative_surface, owned_files, and subtask content. Then update the WP prompt file's frontmatter in place 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")
Also update the corresponding entry in wps.yaml with these fields.
5. Self-Check
After all sub-agents complete, verify each generated prompt:
## ⚡ Do This First: Load Agent Profileis the first body section (before Objective)? ✓ ❌ if missing- Subtask count: 3-7? ✓ | 8-10? ⚠️ | 11+? ❌ needs splitting
- Estimated lines: 200-500? ✓ | 500-700? ⚠️ | 700+? ❌ needs splitting
agent_profile,role,agentset for every WP? ✓- owned_files glob patterns non-overlapping across all WPs? ✓
- Can implement in one session? ✓ | Multiple sessions needed? ❌ needs splitting
Output
After completing this step:
feature_dir/tasks/WP*.mdprompt files exist for all work packages- Each has proper frontmatter with
work_package_id,dependencies,owned_files,authoritative_surface,execution_mode feature_dir/wps.yamlis fully populated: allowned_files,requirement_refs,subtasks, andprompt_filefields are set
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: (refer to the User Input section above)