Generate Tasks — Task Decomposition Skill

Purpose

Turn an approved technical plan (plan.md) into tasks.md: an ordered, dependency-aware, user-story-organized task list that spec-kit-execute-tasks can run — without writing product code here. This skill is the third link in the spec-kit chain (spec-kit-generate-spec → spec-kit-generate-plan → spec-kit-generate-tasks): it does not redesign the plan, it decomposes an already-approved plan into atomic, independently verifiable work.

The output is tasks.md plus checklists/tasks-quality.md. It does not implement product code, and it does not validate cross-artifact consistency in depth — that deeper check is spec-kit-analyze-consistency's job, when that skill is invoked.

User Input

$ARGUMENTS

Always consider the complete user message and any files or attachments available in the current conversation, even when $ARGUMENTS appears literally or is empty. The most common input is a reference to an existing feature directory or plan.md, with optional constraints ("only generate tasks for the MVP story", "skip test tasks").

Core Principle

Organize by user story, not by technical layer. A story is only complete when its checkpoint holds — closure is structural, not an afterthought.

• tasks.md is grouped by user story (R-US##, in Priority order P1 → P2 → P3), so each story is independently implementable, testable, and deliverable as an MVP increment.
• Every story's closing checkpoint is the mechanism that enforces "cierre de ciclos": a story only counts as done when it is functional and verifiable on its own — which excludes, by construction, leaving the system broken.
• Every task traces back to an operation in plan.md and a requirement/acceptance criterion in spec.md.

Non-Negotiable Rules

1. Do not invent facts. Never fabricate a file path, an existing helper, or a test framework convention not already verified in plan.md's Technical Context or Project Structure. Use verify-before-implement when a task needs a fact plan.md didn't already establish.
2. Preserve plan intent. Do not reinterpret, split, or merge a PL-O## operation in a way that changes what plan.md decided. Decomposing into smaller tasks is expected; changing the approach is not.
3. Separate facts from assumptions. A task whose exact file path isn't yet verifiable is marked nuevo: <proposed path>, never presented as if the path is confirmed.
4. Surface conflicts. If decomposing an operation reveals it doesn't actually match spec.md/plan.md cleanly, report the mismatch — do not silently resolve it by picking whichever task shape is easiest to write.
5. Organize by user story — never a flat generic task list. Structure is always Setup → Foundational → one phase per R-US## in Priority order → Polish. An operation that doesn't belong cleanly to one story is assigned to the story that needs it first, with a forward dependency noted — never placed in an ad hoc "misc" phase.
6. No code before approval. tasks.md describes work; it does not contain product code.
7. No hollow tasks.md. Every task states a concrete action, a file (verified or explicitly proposed), a dependency (or "ninguna"), and an observable validation criterion. "Improve X" or "handle edge cases" without specifics is not a valid task.
8. Use verified project context. Reuse plan.md's Technical Context and Project Structure directly — do not re-derive the project's layout independently and risk disagreeing with it.
9. Keep scope controlled. No task introduces work absent from plan.md/spec.md. A gap found during decomposition is reported, not quietly filled with a "nice to have" task.
10. The Closure Rule is mandatory, not optional polish. Every user-story phase — and Setup/Foundational when it gates the whole feature — ends with an explicit [CIERRE] task (§ Closure Rule below). It is never omitted, never merged into a regular task, and never marked done by inference.
11. Safe Deferral consistency is enforced during decomposition. If plan.md's Safe Deferral table marks an operation Dormant for a later story, no task in an earlier story may invoke that deferred code path — doing so silently invalidates the Dormant classification. If this happens, report it as a conflict with plan.md, do not silently write the task anyway.
12. Every task is traceable. Each task cites the R-FR##/R-AC##/PL-O## it satisfies (a legacy plan's O-0# counts as its PL-O##, per the convention's Stable ID Namespaces).
13. Never claim readiness without validation. tasks.md is READY only after checklists/tasks-quality.md passes.
14. Generate portable agent pairs. If this workflow creates a task-decomposer (or other support agent), it must generate and validate both a Kiro CLI and a Claude Code definition per the shared portability contract.
15. Validations describe observable behavior, not implementation shape. A Validación names what to run and what to observe — a test, a grep with its expected count, an HTTP call and its status/body, a log line and what it must (not) contain. It never depends on a parameter name, a variable name, a hunk or line count, or "file X unchanged": those make a task impossible to close when a correct implementation differs in shape. A negative check is allowed only when it restates a spec S-SG## (cite it) and is phrased as behavior ("no request log contains the full phone number"), not as a file that must stay untouched.
16. Every runtime premise marked assumption gets a [SONDA] task (plan.md PL-D##/RS-## with evidence level assumption), placed in Foundational — or first in the earliest story that needs it — and listed in Depende de of every task built on that premise.
17. Closed tasks follow the Task Lifecycle in spec-kit-shared/artifact-conventions.md: never edited except for one appended Superada por: line; rework is an [ENMIENDA T0XX] task; each story keeps exactly one active [CIERRE], and a new one is created only when the story's R-AC set changes.

Shared Files

spec-kit-shared/… paths resolve against <skills-root>, the parent of this skill's own directory: .claude/skills/ or the host's equivalent once installed, the repository root in a checkout of the kit. Run shared scripts from the project root as node <skills-root>/spec-kit-shared/scripts/<script>.mjs, with <skills-root> written out as an absolute path; a bare spec-kit-shared/… script path resolves against the project and fails.

Cross-Platform Agent Compatibility

The complete portability contract lives in spec-kit-shared/agent-portability.md (same document spec-kit-generate-spec and spec-kit-generate-plan use). Before generating, validating, or reporting on the task-decomposer role — or any other agent this skill materializes — read that file completely and follow it exactly. If the active host cannot resolve the reference, follow its fallback section.

task-decomposer is the standard role for this skill: decomposing a disproportionately large plan operation or user story into atomic tasks, to keep the main context light. Do not invent a different name or redefine it for another purpose.

Artifact Conventions

The .speckit/ layout (including .speckit/specs/<feature-dir>/), feature.json, state.json, and the Content Fingerprint Convention all live in spec-kit-shared/artifact-conventions.md. Read it before Fase 0 below and follow it exactly.

Run Log

Record this run per spec-kit-shared/artifact-conventions.md § Run Log (<dir> is the feature directory): start with node <skills-root>/spec-kit-shared/scripts/log-event.mjs <dir> run.start --skill spec-kit-generate-tasks mode=<mode> and pass the printed RUN_ID to every later call; end with a run.end event (status, reason when it stops, next), also when the run stops early. Pass --log <RUN_ID> --skill spec-kit-generate-tasks to fingerprint.mjs --record … tasks and lint-artifacts.mjs so they record their own results. Record these decisions, each with a one- or two-sentence rationale citing its IDs:

• drift — in update mode, each changed plan ID classified material or non-material
• closure — for rework of a closed story: a new [CIERRE] (R-AC set changed) or a re-walk of the active one
• readiness — READY or DRAFT, citing the failed checklist items

If logging is off (RUN_LOG: off), continue normally.

Input Contract

Resolving the Target Plan

1. If the user gave an explicit plan.md path or feature directory, use it.
2. Otherwise, read .speckit/feature.json for the active feature directory.

3. If neither resolves to a readable plan.md, stop and ask:

   Provide the feature directory or plan.md path to decompose into tasks. If you haven't generated a plan yet, run spec-kit-generate-plan first.

4. Read plan.md, spec.md, and checklists/plan-quality.md completely.

Readiness Gate

• If plan-quality.md's STATUS is READY, proceed.
• If it is DRAFT — NEEDS CLARIFICATION, stop and ask the user to either resolve the blocking items in spec-kit-generate-plan first, or explicitly confirm decomposing a draft plan into tasks. If confirmed, proceed but record DECOMPOSED_FROM_DRAFT_PLAN: true in tasks.md's header and repeat the warning in the Completion Report.
• If spec.md's own STATUS is not READY either, surface both — a plan built on a draft spec compounds the risk of a draft plan.

New vs. Update Mode

• New mode: no tasks.md exists yet. Proceed through all phases below in order.
• Update mode: tasks.md already exists. Run Fase 0 below first; follow § Updating an Existing Task List rather than regenerating from scratch.

Fase 0 — Staleness Check (every invocation, new or update)

1. If .speckit/specs/<feature-dir>/state.json does not exist, or has no artifacts.tasks entry yet, this is the first task list for this plan — skip straight to Phase 1, and create/update state.json at the end (with schema_version, per artifact-conventions.md § Schema Versions and Migrations).
2. Otherwise, read spec-kit-sync-artifacts/SKILL.md and follow its Phase 1/2 mechanical detection procedure against artifacts.tasks.based_on_plan_hash vs. plan.md's current content hash — do not re-derive the hashing/comparison mechanism independently.
3. If spec-kit-sync-artifacts reports a match, plan.md hasn't changed since the last task generation — proceed normally.
4. If it reports drift, this skill does the classification spec-kit-sync-artifacts leaves to the consuming skill: identify which PL-O##/PL-D##/RS-##/Safe-Deferral entries actually changed (using spec-kit-sync-artifacts's best-effort localization, or a direct diff if it couldn't resolve one), and classify each as functionally material (a new/changed/removed operation, a changed Safe Deferral condition) or non-material (wording). Only material changes make tasks.md stale with impact.
   • Report the affected IDs and which task phases they touch before proceeding. If spec-kit-sync-artifacts flagged any already-[x] task as potentially affected, treat that with the same non-negotiable caution as § Updating an Existing Task List step 3 below.
5. This Fase 0 does not depend on spec-kit-sync-artifacts being invoked as a separate conversational step — apply its documented procedure directly, inline, as part of this phase.

Workflow

Phase 1 — Determine Story Order

Read every R-US## in spec.md's Actors and Scenarios, with its Priority (P1/P2/P3). Order user-story phases P1 → P2 → P3; within the same priority, preserve spec.md's original order. If a story has no assigned priority (an older spec.md predating the priority field), treat it as P1 and flag this in the Completion Report rather than silently guessing an order.

Cross-check every PL-O## in plan.md against which R-US##/R-FR## it satisfies, so each operation can be placed in the correct story phase in Phase 4 below.

Phase 2 — Setup Tasks

Shared, low-risk project setup: creating the structure plan.md's Project Structure describes, initializing dependencies from Technical Context. No story-specific logic here.

If the existing project structure and dependencies already satisfy everything Technical Context/Project Structure need — a small feature added to an already-scaffolded project — state that explicitly ("No setup tasks required — structure and dependencies already match plan.md") instead of manufacturing a task to fill the phase. An empty phase with a stated reason is honest; a busywork task is not (Rules 7, 9).

Phase 3 — Foundational Tasks (Blocking Prerequisites)

Infrastructure genuinely required by every user story (shared auth, shared schema setup, shared routing/middleware) — not just infrastructure convenient for one story. If in doubt whether something is Foundational or belongs to a specific story, prefer assigning it to the first story that actually needs it; an oversized Foundational phase delays every story's start unnecessarily.

Same rule as Setup: if no shared prerequisite work is actually needed beyond what already exists, say so explicitly rather than inventing a task.

[SONDA] tasks (Rule 16) for premises shared by several stories go here, first — a refuted premise found now costs a plan amendment; found after the stories are built, it costs rework of closed tasks.

Ends with a checkpoint statement: foundation ready, user stories may start.

Phase 4 — One Phase per User Story (in Priority order)

For each R-US##, in the order from Phase 1:

1. State the Goal (from R-US##) and Independent test (from its R-AC##).
2. Tests (optional — only if spec.md explicitly requests tests): write them first; they must fail before implementation exists.
3. Implementation tasks: decompose every PL-O## this plan assigned to this story into atomic tasks. Use the task format below.
4. Closure task (§ Closure Rule): always the last task of the phase as generated; later [ENMIENDA] tasks go after it under #### Enmiendas (Rule 17).
5. Checkpoint statement: the story works and is independently verifiable.

Task Format

- [ ] T0XX [P?] [USn] Description
      Traza a: R-FR0#, PL-O0#
      Archivo(s): ruta verificada, o "nuevo: ruta propuesta"
      Depende de: ninguna | T0YY
      Validación: comando o criterio observable

Field labels and tags (Traza a:, Validación:, [CIERRE], …) are the fixed Grammar Tokens of artifact-conventions.md: write them exactly as shown, whatever language the task descriptions use. Archivo(s) is where the work is expected to land, not a fence: touching another file the same PL-O## needs does not invalidate the task. Write Validación per Rule 15 — for example "npm test -- prelude-block pasa; GET /allow-list?phone=… deja en el log de request el teléfono enmascarado (+52…1234)", never "el parámetro se llama now" or "main.js sin cambios".

Probe task (Rule 16):

- [ ] T0XX [SONDA] Confirmar <premisa de runtime> (PL-D0#, RS-0#)
      Traza a: PL-D0#, RS-0#
      Archivo(s): ninguno (script en scratch, fuera del repo)
      Depende de: ninguna
      Validación: el comando <probe> muestra <comportamiento esperado>; si muestra otra cosa, la
        premisa queda refutada y se detienen las tareas que dependen de ella

• [P]: parallelizable — different files, no cross-dependency with other [P] tasks in the same phase.
• [USn]: which user story. Setup/Foundational tasks carry no story tag.
• Sequential numbering (T001, T002, ...) continues across the whole document — do not restart numbering per phase.

Closure Rule (mandatory — see Non-Negotiable Rule 10)

- [ ] T0XX [USn] [CIERRE] Verificar consistencia de cierre de USn
      Verifica:
        - Ninguna referencia colgante a código de una historia futura no marcada Dormant/Flagged/Aditiva
        - Ninguna rama/ruta alcanzable queda a medio conectar
        - Todo R-AC de esta historia está satisfecho o formalmente reclasificado como aplazamiento seguro (ver plan.md Safe Deferral)
      Validación: recorrido explícito de las condiciones anteriores, no una inferencia

This task is marked [x] only when it actively confirmed nothing was left half-done — never for merely producing code. Only the story's active [CIERRE] (no Superada por: line) counts; earlier ones are history. Cross-reference plan.md's Safe Deferral table: if this story is the target of a deferred operation from an earlier story, the closure task also confirms that operation genuinely remains Dormant/behind its Flag/purely Additive and hasn't been accidentally activated by this story's own work.

Phase 5 — Polish & Cross-Cutting Concerns

Work that spans multiple stories: documentation (delegate to code-documentation when applicable), cleanup, running quickstart.md as final validation. Depends on all targeted stories being complete.

Phase 6 — Closing Sections (always generated)

• Dependencies & Execution Order: phase dependencies (Setup → Foundational → stories → Polish) and, within each story, task-level order (tests before implementation, models before services, the active [CIERRE] last except for later [ENMIENDA] tasks).
• Parallel Example: one concrete block showing [P] tasks from the P1 story launchable together.
• Implementation Strategy: MVP-first (Setup + Foundational + the P1 story only, stop and validate its checkpoint), incremental delivery (one story at a time, each deployable), and parallel execution strategy (once Foundational is done, independent stories may go to separate task-executor agents in spec-kit-execute-tasks — the story boundary is the primary parallelism unit).

Traceability and Safe Deferral Consistency Checks

Before validating the checklist:

• Every task cites at least one R-FR##/R-AC## and the PL-O## it decomposes — except a [SONDA], which cites the PL-D##/RS-## it probes.
• Every PL-O## in plan.md appears in at least one task, in the story plan.md assigned it to.
• Every user-story phase has exactly one active [CIERRE] task covering all of that story's R-AC##; it is the last task of the phase except for [ENMIENDA] tasks under #### Enmiendas.
• Every PL-D## with evidence level assumption has a [SONDA] that precedes every task citing it.
• Every Validación follows Rule 15.
• No task in a story earlier than a Dormant-deferred operation's target story invokes that operation's code path (Non-Negotiable Rule 11).
• Task IDs are sequential and unique across the whole document.

Validate and Iterate

Create checklists/tasks-quality.md from the template in references/tasks-quality-checklist.md.

Validate item by item, fix non-blocking failures, re-run up to three iterations. If a blocking gap remains, set STATUS to DRAFT — NEEDS CLARIFICATION. Set READY only when every item passes.

Updating an Existing Task List

When plan.md changed materially since the last tasks.md (Fase 0 detected drift), or a tasks-layer change was decided, follow references/updating.md completely.

Pre-Execution Extension Hooks

Before task decomposition, check .speckit/extensions.yml per spec-kit-shared/artifact-conventions.md's schema, reading hooks.before_tasks. Follow the same enablement/condition/mandatory-vs-optional rules spec-kit-generate-spec and spec-kit-generate-plan use for their own hooks.

Mandatory Post-Execution Hooks

After task decomposition, process hooks.after_tasks the same way, using the same emit-then-execute format the other spec-kit skills use.

Completion Report

Report:

• RUN_ID: this run's log ID, or off.
• SPECIFY_FEATURE_DIRECTORY: resolved feature directory.
• TASKS_FILE: tasks.md path.
• CHECKLIST_FILE: checklists/tasks-quality.md path.
• STATUS: READY or DRAFT — NEEDS CLARIFICATION.
• DECOMPOSED_FROM_DRAFT_PLAN: true if plan.md was not READY when tasks were generated.
• STORIES: count of user-story phases and their priorities, in the order generated.
• SAFE_DEFERRAL: confirmation that every plan.md Safe Deferral entry maps to exactly one later task/story, or the mismatches found.
• VALIDATION: passed/total checklist items and unresolved failures.
• TRACEABILITY: operation/requirement coverage counts.
• CHANGES: for updates, the story phases changed, and any closed tasks flagged for review.
• AGENTS: none, or every generated Kiro/Claude path with validation and parity status.
• NEXT: clarification if blocked; otherwise recommend spec-kit-analyze-consistency (optional deeper cross-artifact check) and then spec-kit-execute-tasks, starting with the P1 story as the MVP.

Done When

• The run was logged from run.start to run.end (or logging is off).
• plan.md was resolved, read, and confirmed READY (or draft decomposition was explicitly confirmed by the user).
• Fase 0 Staleness Check ran and any material drift was reported before proceeding.
• Every R-US##'s Priority was read and used to order the story phases (or the missing- priority fallback was flagged).
• tasks.md follows Setup → Foundational → one phase per story (priority order) → Polish, with no task outside that structure.
• Every user-story phase has exactly one active [CIERRE] task covering that story's full R-AC## set.
• Every assumption runtime premise has a [SONDA] ahead of its dependent tasks.
• Every Validación describes observable behavior (Rule 15).
• No task violates a Dormant/Flagged/Additive classification from plan.md's Safe Deferral table.
• Every task is traceable to plan.md's PL-O## and spec.md's R-FR##/R-AC##.
• Dependencies & Execution Order, Parallel Example, and Implementation Strategy sections were generated.
• tasks.md and checklists/tasks-quality.md were written.
• state.json was created or updated with accurate content hashes.
• Every generated support agent has a validated Kiro/Claude pair, or AGENTS: none is reported.
• No product code was generated.