spec-kitty-tasks-outline

name	spec-kitty.tasks-outline
description	Create a work package manifest
user-invocable	true

/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 project root checkout

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

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

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)

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