spec-kitty.tasks-packages

## Startup Upgrade Check

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:

```bash
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:

1. Upgrade now (recommended) - record `upgrade_now`, run `upgrade_command`, then continue.
2. Always keep me up to date - record `always`, run `upgrade_command`, then continue.
3. Not now - record `not_now`, then continue.
4. Never ask again - record `never_ask`, then continue.

Record the selected choice before continuing:

```bash
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.


# /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:

```bash
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:

```yaml
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:
```yaml
---
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
---
```

**IMPORTANT — `plan_concern_refs` lives in `wps.yaml` only.** Do NOT copy `plan_concern_refs` into WP prompt frontmatter. `WPMetadata` uses `extra="forbid"`,