El comando /speckit.tasks

Del plan a las tareas ejecutables

Con el plan técnico generado por /speckit.plan, el equipo dispone de un documento que describe cómo construir la feature: stack tecnológico, modelo de datos, contratos de API y estructura del proyecto. Sin embargo, un plan técnico no es directamente ejecutable. Contiene decisiones y referencias, pero no indica el orden de trabajo, las dependencias entre componentes ni las unidades de trabajo concretas que un agente IA debe completar.

El comando /speckit.tasks cubre esta brecha. Transforma el plan técnico en una lista de tareas accionables, cada una con un identificador único, una descripción precisa, la ruta del archivo que debe crear o modificar, y las dependencias con otras tareas. El resultado es un archivo tasks.md que funciona como la hoja de ruta de implementación.

El plan.md responde a "cómo se construye el sistema". El tasks.md responde a "en qué orden se construye y qué hace cada paso concreto".

Esta separación entre planificación y descomposición en tareas tiene una justificación práctica. Un plan que intenta ser a la vez un documento de arquitectura y una lista de tareas se vuelve inmanejable en features complejas. Al separar ambos artefactos, cada uno se optimiza para su función: el plan para comunicar decisiones técnicas, las tareas para guiar la ejecución.

Cómo ejecutar el comando

El comando se ejecuta en el chat del agente IA sin argumentos adicionales. El agente detecta automáticamente la feature activa a partir de la rama Git o la variable de entorno SPECIFY_FEATURE:

/speckit.tasks

Al recibir el comando, el agente ejecuta una secuencia de operaciones:

• 1. Valida los prerrequisitos: verifica que existe un plan.md en el directorio de la feature activa. Si no existe, el comando se detiene con un error indicando que primero debe ejecutarse /speckit.plan.

• 2. Carga la constitución: lee .specify/memory/constitution.md para aplicar principios que afectan al orden de las tareas, como el principio de Test-First que exige crear los tests antes de la implementación.

• 3. Lee los artefactos del plan: carga el plan.md, el spec.md, el data-model.md, los contratos en contracts/ y el research.md cuando están disponibles. Cada artefacto aporta información que se traduce en tareas concretas.

• 4. Mapea user stories a componentes: extrae las user stories del spec.md con sus prioridades (P1, P2, P3) y las conecta con los modelos de datos, endpoints y servicios definidos en el plan.

• 5. Genera las tareas: crea el archivo tasks.md con las tareas organizadas por fases, incluyendo identificadores, dependencias, marcadores de paralelización y rutas de archivo.

• 6. Valida el grafo de dependencias: comprueba que no existen dependencias circulares, tareas huérfanas ni violaciones de orden entre fases.

flowchart LR
    SPEC["spec.md"] --> CMD["/speckit.tasks"]
    PLAN["plan.md"] --> CMD
    DM["data-model.md"] --> CMD
    CONTRACTS["contracts/"] --> CMD
    CONST["constitution.md"] --> CMD
    CMD --> TASKS["tasks.md"]

Validación previa a la generación

Antes de generar las tareas, el agente realiza un análisis de preparación que verifica la calidad de los artefactos de entrada. Este análisis detecta problemas que, si no se resuelven, producirían tareas incompletas o ambiguas.

El agente verifica tres aspectos principales:

Definición del stack tecnológico: si el plan.md contiene campos marcados como NEEDS CLARIFICATION en la sección Technical Context, el agente alerta de que las tareas generadas podrían ser demasiado genéricas. Un plan que no especifica el lenguaje o el framework produce tareas sin rutas de archivo concretas.

Criterios de aceptación en las user stories: para cada user story del spec.md, el agente comprueba que existen criterios de aceptación verificables. Una user story sin criterios de aceptación no puede producir tareas con condiciones de completitud claras.

Entidades compartidas entre user stories: el agente analiza el data-model.md para detectar entidades que participan en múltiples user stories. Estas entidades se convierten en tareas de la fase fundacional, ya que deben existir antes de que cualquier user story pueda implementarse.

PLAN READINESS REPORT

Tech Stack:       Defined           OK
User Stories:     5 with criteria   OK
Shared Entities:  2 (foundational)  OK
API Contracts:    4 endpoints       OK
Research Items:   3 decisions       OK

TASK GENERATION: READY

Si el informe detecta problemas, el agente los señala y sugiere ejecutar comandos previos para resolverlos. No bloquea la generación de tareas, pero advierte de que la calidad del resultado puede verse afectada.

Estructura del archivo tasks.md

El archivo tasks.md generado se organiza en fases secuenciales. Cada fase agrupa tareas relacionadas que deben completarse antes de pasar a la siguiente. Dentro de una fase, las tareas pueden ser secuenciales o paralelas.

Fases estándar

El agente organiza las tareas en un esquema de fases predefinido:

Phase 1 (Setup): tareas de configuración inicial del proyecto. Incluyen la creación de la estructura de directorios, la instalación de dependencias y la configuración del entorno de desarrollo. Estas tareas no tienen dependencia con ninguna user story concreta.

Phase 2 (Foundational): tareas de componentes compartidos que bloquean a varias user stories. Si el data-model.md define una entidad User que necesitan tres user stories diferentes, la creación de ese modelo se ubica en esta fase.

Phase 3+ (User Stories): una fase por cada user story, ordenadas por prioridad (P1 primero, P2 después). Cada fase contiene las tareas específicas para implementar esa user story: modelos, servicios, endpoints, validaciones y tests.

Fase final (Polish): tareas transversales que afectan a todo el proyecto. Documentación, configuración de CI/CD, optimización de rendimiento y ajustes de accesibilidad.

flowchart TB
    subgraph Phases["Estructura de fases"]
        P1["Phase 1<br>Setup"]
        P2["Phase 2<br>Foundational"]
        P3["Phase 3<br>User Story 1 (P1)"]
        P4["Phase 4<br>User Story 2 (P2)"]
        P5["Phase 5<br>Polish"]
    end
    P1 --> P2 --> P3 --> P4 --> P5

Formato de las tareas

Cada tarea sigue un formato estandarizado que incluye todos los elementos necesarios para su ejecución:

- [ ] T001 Create project structure per plan
- [ ] T002 [P] Install dependencies from quickstart.md
- [ ] T003 [P] Configure environment variables
- [ ] T004 [US1] Create CalendarEvent model
      in src/models/event.py
- [ ] T005 [US1] [P] Create EventShare model
      in src/models/share.py
- [ ] T006 [US1] Implement event creation service
      in src/services/event_service.py

Los componentes de cada tarea son:

• Checkbox (- [ ]): indica el estado de completitud. Se marca como [x] cuando la tarea se completa durante la implementación.
• Task ID (T001, T002): identificador secuencial único que permite referenciar tareas en las dependencias.
• Marcador [P]: indica que la tarea puede ejecutarse en paralelo con otras tareas del mismo grupo que también tienen el marcador [P].
• Etiqueta de user story ([US1], [US2]): vincula la tarea con la user story que implementa, proporcionando trazabilidad desde las tareas hasta los requisitos.
• Descripción: acción concreta que debe realizarse, redactada como un verbo en imperativo seguido del objetivo.
• File path: ruta del archivo que la tarea crea o modifica. Permite al agente saber exactamente dónde trabajar.

Mapeo de artefactos a tareas

El agente no genera tareas de forma arbitraria. Cada tarea tiene su origen en un artefacto del plan:

Desde el data-model.md: cada entidad definida en el modelo de datos produce al menos una tarea de creación del modelo. Las relaciones entre entidades producen tareas adicionales para los servicios que las gestionan.

Desde los contracts/: cada endpoint definido en los contratos genera tareas de implementación de la ruta, validación de entrada y serialización de respuesta. Si un contrato define un endpoint POST /api/events, aparecen tareas para crear el endpoint, validar el cuerpo de la request y formatear la response.

Desde el research.md: las decisiones técnicas documentadas en la investigación se traducen en tareas de setup. Si el research.md documenta que se eligió la librería icalendar para generar archivos .ics, aparece una tarea para instalar esa dependencia y otra para integrarla en el servicio correspondiente.

Desde el quickstart.md: los pasos de configuración del entorno se convierten en tareas de la Phase 1 (Setup).

La trazabilidad entre artefactos y tareas garantiza que ningún requisito se pierda en la traducción. Cada decisión del plan se materializa en al menos una tarea concreta del tasks.md.

Iteración sobre las tareas

El archivo tasks.md puede regenerarse si las condiciones cambian. Si el equipo modifica el plan técnico, ejecutar /speckit.tasks de nuevo produce un archivo actualizado que refleja las nuevas decisiones.

Cuando ya existe un tasks.md previo, el agente realiza un merge semántico que preserva el estado de las tareas completadas. Las tareas marcadas como [x] se mantienen completadas en la nueva versión, siempre que la descripción de la tarea siga siendo relevante. Las tareas nuevas se añaden como pendientes. Las tareas eliminadas (porque un requisito cambió) se señalan para que el equipo revise si el trabajo realizado sigue siendo válido.

SEMANTIC DIFF: tasks.md

Tasks:
  + Added: T025-T030 (new user story US4)
  ~ Renamed: T012 description updated
  - Removed: T008 (was for deleted FR-008)
  OK Preserved: 15 completed tasks kept

COMPLETION STATUS:
  Previously completed: 15 tasks
  Mapped to new tasks: 14 tasks
  Lost (task removed): 1 task

Esta capacidad de regeneración segura permite que el equipo itere sobre la planificación sin perder el progreso de implementación. Si una revisión del plan cambia el framework de testing pero no afecta al modelo de datos, las tareas de modelo se preservan como completadas y solo se regeneran las tareas de testing.