Spec Kitty.tasks Outline

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:

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:

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-outline - Create Work Package Manifest

Version: 3.2.0

Purpose

Create wps.yaml — the structured work package manifest that defines WP metadata, dependencies, and file ownership. tasks.md is generated automatically from this manifest by finalize-tasks.

⚠️ DO NOT write tasks.md. The system generates it from wps.yaml. Writing tasks.md manually will have it overwritten by finalize-tasks.

⚠️ CRITICAL: THIS IS THE MOST IMPORTANT PLANNING WORK

You are creating the blueprint for implementation. The quality of work packages determines:

• How easily agents can implement the feature
• How parallelizable the work is
• How reviewable the code will be
• Whether the feature succeeds or fails

QUALITY OVER SPEED: Take your time to understand the full scope deeply, break work into clear pieces, and write detailed guidance.

📍 WORKING DIRECTORY: Stay in the repository root checkout

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

Do NOT cd anywhere. Stay in the repository root checkout.

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).

Context Resolution

Before proceeding, resolve canonical command context:

spec-kitty agent context resolve --action tasks_outline --mission <mission-slug> --json

Treat that JSON as canonical for feature slug, feature directory, and target branch. Do not probe git branch state manually inside the prompt.

Steps

1. Setup

Run the exact check_prerequisites command returned by the resolver. Capture feature_dir plus available_docs. All paths must be absolute.

CRITICAL: The command returns JSON with feature_dir as an ABSOLUTE path. YOU MUST USE THIS PATH for ALL subsequent file operations.

2. Load Design Documents

Read from feature_dir (only those present):

• Required: plan.md (tech architecture, stack), spec.md (user stories & priorities)
• Optional: data-model.md (entities), contracts/ (API schemas), research.md (decisions), quickstart.md (validation scenarios)

Scale your effort to the feature: simple UI tweaks deserve lighter coverage, multi-system releases require deeper decomposition.

3. Derive Fine-Grained Subtasks

Create complete list of subtasks with IDs T001, T002, etc.:

• Parse plan/spec to enumerate concrete implementation steps, tests (only if explicitly requested), migrations, and operational work.
• Capture prerequisites, dependencies, and parallelizability markers ([P] means safe to parallelize per file/concern).
• Assign IDs sequentially in execution order.
• Ideal granularity: One clear action (e.g., "Create user model", "Add login endpoint")

4. Roll Subtasks into Work Packages

Group subtasks into work packages (IDs WP01, WP02, ...):

TARGET SIZE: 3-7 subtasks per WP (200-500 line prompts) MAXIMUM: 10 subtasks per WP (700 line prompts) If more than 10 subtasks needed: Create additional WPs, don't pack them in

GROUPING PRINCIPLES:

• Each WP should be independently implementable
• Root in a single user story or cohesive subsystem
• Ensure every subtask appears in exactly one work package
• Name with succinct goal (e.g., "User Story 1 – Real-time chat happy path")
• Record metadata: priority, success criteria, risks, dependencies, included subtasks, and requirement references
• Every WP must include a requirement_refs list referencing IDs from spec.md (FR/NFR/C)

4a. Cite plan concern refs for each WP

For each work package, record which implementation concern(s) from plan.md it addresses by populating plan_concern_refs in wps.yaml.

• If the WP covers exactly one concern: plan_concern_refs: [IC-01]
• If the WP spans multiple concerns: plan_concern_refs: [IC-01, IC-03]
• If the WP is cross-cutting infrastructure with no specific concern (e.g. a test harness setup WP), set cross_cutting: true and leave plan_concern_refs empty.

A WP missing both plan_concern_refs and cross_cutting: true will trigger a warning from finalize-tasks. Every WP should cite at least one IC-## ref or declare itself cross-cutting.

5. Write wps.yaml

Write to feature_dir/wps.yaml following the schema below. This is the single authoritative source for WP metadata in the planning pipeline.

Do NOT write tasks.md — it is generated automatically by finalize-tasks from wps.yaml.

Schema:

work_packages:
  - id: WP01
    title: "Foundation Setup"
    dependencies: []          # [] = explicitly no deps (authoritative)
    owned_files:
      - "src/myapp/core/**"
    requirement_refs:
      - FR-001
      - FR-002
    plan_concern_refs:
      - IC-01
    subtasks:
      - T001
      - T002
      - T003
    prompt_file: "tasks/WP01-foundation-setup.md"

  - id: WP02
    title: "API Layer"
    dependencies:
      - WP01
    owned_files:
      - "src/myapp/api/**"
    requirement_refs:
      - FR-003
    plan_concern_refs:
      - IC-02
      - IC-03
    subtasks:
      - T004
      - T005
    prompt_file: "tasks/WP02-api-layer.md"

  - id: WP03
    title: "Frontend Integration"
    dependencies:
      - WP02
    owned_files:
      - "src/myapp/frontend/**"
    requirement_refs:
      - FR-004
      - NFR-001
    plan_concern_refs:
      - IC-04
    subtasks:
      - T006
      - T007
      - T008
    prompt_file: "tasks/WP03-frontend-integration.md"

Field semantics:

• id: Work package identifier (WP01, WP02, …)
• title: Short human-readable name
• dependencies: List of WP IDs this WP depends on. [] = explicitly no deps (authoritative); if the key is absent, tasks-packages may fill it based on analysis.
• owned_files: Glob patterns for files this WP touches — no two WPs may overlap.
• requirement_refs: Requirement IDs from spec.md (FR/NFR/C) addressed by this WP.
• plan_concern_refs: Implementation concern IDs from plan.md (IC-##) addressed by this WP. Use cross_cutting: true instead if the WP is shared infrastructure with no specific concern.
• cross_cutting: Set to true for infrastructure WPs that span all concerns and have no specific IC-## ref.
• subtasks: Ordered list of subtask IDs included in this WP.
• prompt_file: Relative path (from feature_dir) to the WP prompt file — set by tasks-packages in the next step.

IMPORTANT: Leave prompt_file as null or omit it — tasks-packages fills this field.

6. Analyze Dependencies

Analyze the spec and plan for dependency relationships. Express them in wps.yaml dependencies fields.

Do NOT include a Dependency Graph section in prose — it is not needed and cannot be parsed by finalize-tasks.

Rules:

• A WP with no predecessors: dependencies: []
• A WP that depends on another: dependencies: [WP01]
• Phase grouping: Phase 2 WPs typically depend on Phase 1 WPs

DO NOT generate WP prompt files in this step. That happens in the next step.

Output

After completing this step:

• feature_dir/wps.yaml exists with all work package definitions
• Each WP has id, title, dependencies, owned_files, requirement_refs, subtasks
• prompt_file fields are absent or null (filled by tasks-packages)
• No WP prompt files have been created yet

Next step: spec-kitty next --agent <name> will advance to work package generation.

Work Package Sizing Guidelines

Target: 3-7 subtasks per WP → 200-500 line prompts Maximum: 10 subtasks → ~700 line prompts No arbitrary limit on WP count — let complexity dictate

Split if ANY of these are true:

• More than 10 subtasks
• Prompt would exceed 700 lines
• Multiple independent concerns mixed together
• Different phases or priorities mixed

Merge if ALL of these are true:

• Each WP has <3 subtasks
• Combined would be <7 subtasks
• Both address the same concern/component
• No natural parallelization opportunity

Context for work-package planning: (refer to the User Input section above)