spec-kitty-tasks-packages

name	spec-kitty.tasks-packages
description	Materialize work package files
user-invocable	true

/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_artifact for kitty-specs/docs-only WPs, otherwise code_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`.

---

1. ## Objective — 1–3 sentence goal
2. ## Context — why this WP exists, what depends on it, key design decisions from plan.md
3. ### 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
4. ## Definition of Done — verifiable checklist covering all subtasks
5. ## Risks — known risks and mitigations
6. ## 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 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.

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 Profile is 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, agent set 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*.md prompt files exist for all work packages
• Each has proper frontmatter with work_package_id, dependencies, owned_files, authoritative_surface, execution_mode
• feature_dir/wps.yaml is fully populated: all owned_files, requirement_refs, subtasks, and prompt_file fields 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)