Work Items

Un agente no puede ejecutar "mejora la app". Necesita trabajo especifico, acotado, con criterios de aceptacion claros. Los work items son como conviertes intencion en especificaciones ejecutables. Sin esta estructura, los agentes improvisan. Con ella, saben exactamente que hacer y cuando esta hecho.

Los work items son la unidad fundamental de trabajo en Almirant. Representan cualquier pieza de trabajo que necesita ser planificada, ejecutada y completada: desde un epic de alto nivel hasta una tarea tecnica concreta.

Tipos y jerarquia

Almirant organiza el trabajo en una jerarquia de cuatro niveles:

Epic
 └── Feature
      └── Story
           └── Task

Tipo	Nivel	Proposito	Ejemplo
Epic	1	Objetivo estrategico de alto nivel	"Sistema de autenticacion completo"
Feature	2	Funcionalidad concreta dentro de un epic	"Login con Google OAuth"
Story	3	Requerimiento desde la perspectiva del usuario	"Como usuario, quiero iniciar sesion con mi cuenta de Google"
Task	4	Unidad de trabajo tecnica ejecutable	"Implementar callback de OAuth en el backend"

Cuando usar cada tipo

• Epic: Cuando el objetivo abarca multiples features y requiere varias semanas o sprints. Los epics son el nivel mas alto de planificacion.
• Feature: Cuando describes una funcionalidad completa que el usuario puede percibir. Una feature puede tener multiples stories.
• Story: Cuando describes un requerimiento concreto desde la perspectiva del usuario. Las stories se completan tipicamente dentro de un sprint.
• Task: Cuando describes una accion tecnica especifica y acotada. Las tasks son el nivel que la IA implementa directamente.

Relacion padre-hijo

Cada work item puede tener un parentId que establece la relacion jerarquica. La vista del board permite agrupar items por su padre, facilitando la visualizacion del progreso a nivel de feature o epic.

Campos

Campo	Tipo	Descripcion	Obligatorio
title	string	Titulo descriptivo del work item	Si
description	string	Descripcion detallada, acepta Markdown	No
type	enum	Tipo: epic, feature, story, task	Si
priority	enum	Prioridad: urgent, high, medium, low, none	No
boardColumnId	uuid	Columna del board donde se encuentra el item	Si
parentId	uuid	Work item padre (para jerarquia)	No
taskId	string	Identificador legible auto-generado (e.g., A-T-37, MC-S-1)	Automatico
dueDate	date	Fecha limite de entrega	No
estimatedHours	number	Horas estimadas de trabajo	No
tags	array	Etiquetas para categorizar el item	No
metadata	object	Metadatos enriquecidos (contexto AI, notas tecnicas)	No
archived_at	timestamp	Fecha de archivado (si esta archivado)	No

Identificador legible (taskId)

Cada work item recibe automaticamente un identificador unico y legible basado en el proyecto y el tipo. Ejemplos:

• A-T-37 -- Task numero 37 del proyecto A.
• MC-S-1 -- Story numero 1 del proyecto MC.
• A-E-3 -- Epic numero 3 del proyecto A.

Este identificador se usa en toda la interfaz y en los tools MCP para referenciar items sin necesidad de UUIDs.

Asignaciones

Un work item puede tener multiples asignados, cada uno con un rol especifico:

Rol	Descripcion
responsible	Persona responsable de completar el item
collaborator	Persona que contribuye al trabajo
reviewer	Persona encargada de revisar el resultado

Un mismo item puede tener un responsable, varios colaboradores y uno o mas revisores simultaneamente.

Estado: derivado de la columna

Concepto clave

Los work items NO tienen un campo status. El estado se deriva directamente de la columna del board en la que se encuentra el item:

• Si la columna tiene el rol semantico in_progress, el item esta "en progreso".
• Si la columna tiene isDone = true, el item esta "completado".
• Si la columna tiene isDefault = true, es donde aterrizan los items nuevos.

Mover un item entre columnas cambia implicitamente su estado.

Operaciones

Crear un work item

Existen varias formas de crear work items:

1. Desde el board -- Haz clic en el boton "+" de cualquier columna. El item se crea directamente en esa columna.
2. Desde la vista de lista -- Usa el boton "Nuevo item" y selecciona el tipo, board y columna.
3. Via MCP -- Usa los tools create_work_item, create_task, create_story, create_feature o create_epic.

Editar un work item

• Edicion inline -- Haz clic en el titulo de un item en el board para editarlo directamente.
• Modal de detalle -- Haz clic en la tarjeta para abrir el detalle completo donde puedes editar todos los campos.
• Descripcion con Markdown -- El campo de descripcion soporta Markdown completo y se puede formatear con ayuda de la IA.

Mover entre columnas

• Drag and drop -- Arrastra la tarjeta de una columna a otra en la vista Kanban.
• Via MCP -- Usa el tool move_work_item o batch_move_work_items para mover uno o varios items programaticamente.

Al mover un item a una columna con isDone = true, el item se considera completado.

Asignar y desasignar

Desde el modal de detalle, anade o elimina asignados seleccionando el usuario y su rol (responsible, collaborator, reviewer).

Adjuntos (attachments)

Los work items soportan archivos adjuntos almacenados en S3. Puedes subir imagenes, documentos, capturas de pantalla o cualquier archivo relevante desde el modal de detalle.

Archivar

En lugar de eliminar, los work items se archivan. El archivado establece un timestamp en archived_at. Los items archivados dejan de aparecer en las vistas principales pero se conservan para referencia historica.

Para archivar un item:

1. Abre el detalle del work item.
2. Selecciona Archivar.
3. El item desaparece del board pero se puede consultar en la vista de archivados.

Vista de detalle

La vista de detalle de un work item incluye:

• Todos los campos editables (titulo, descripcion, tipo, prioridad, asignados, fechas).
• Historial de eventos -- Registro de todos los cambios realizados al item.
• Sesiones AI -- Historial de interacciones de la IA con el item, incluyendo el coste de cada sesion.
• Documentos vinculados -- Enlaces a documentos relacionados.
• Dependencias -- Dependencias con otros work items.
• Adjuntos -- Archivos subidos al item.
• Comentarios y notas.

Operaciones en lote (bulk)

Desde la vista de lista puedes seleccionar multiples items y ejecutar acciones en lote:

• Mover a otra columna.
• Cambiar prioridad.
• Asignar a un usuario.
• Archivar.

Vistas guardadas y filtros

Los filtros de la vista de work items se persisten en la URL, permitiendo compartir enlaces con filtros aplicados. Puedes filtrar por:

• Tipo (epic, feature, story, task).
• Prioridad.
• Asignado.
• Tags.
• Columna.

Tambien puedes agrupar los items por su padre para visualizar la jerarquia en la vista de lista.

Funcionalidades AI

Los work items integran funcionalidades AI directamente:

• Formateo AI de texto -- La IA puede formatear y mejorar la descripcion del item.
• Dictado por voz -- Dicta la descripcion o comentarios por voz y la IA los transcribe.
• Copy as prompt -- Copia el contexto del item como prompt para usarlo en tu IDE.
• Sesiones AI con tracking de coste -- Cada interaccion AI con un item se registra con su coste asociado.

Para developers

Para Developers

Herramientas MCP

Creacion

Tool	Descripcion	Parametros principales
create_work_item	Crea un work item de cualquier tipo	title, type, boardId, columnId, description, priority, parentId
create_task	Atajo para crear un task	title, boardId, description, priority, parentId
create_story	Atajo para crear una story	title, boardId, description, priority, parentId
create_feature	Atajo para crear una feature	title, boardId, description, priority, parentId
create_epic	Atajo para crear un epic	title, boardId, description, priority

Consulta

Tool	Descripcion	Parametros principales
list_work_items	Lista work items con filtros	boardId, type, priority, assigneeId, parentId, columnId

Actualizacion

Tool	Descripcion	Parametros principales
update_work_item	Actualiza campos de un work item	workItemId, campos a actualizar
move_work_item	Mueve un item a otra columna	workItemId, columnId
batch_move_work_items	Mueve multiples items a una columna	workItemIds, columnId
resolve_work_items	Marca items como resueltos (mueve a columna done)	workItemIds
complete_ai_task	Completa una tarea AI y la mueve a done	workItemId, summary

Ejemplo: Crear una task via MCP

Tool: create_task
Parametros:
  title: "Implementar endpoint de autenticacion"
  boardId: "uuid-del-board"
  description: "Crear el endpoint POST /api/auth/login con validacion JWT"
  priority: "high"
  parentId: "uuid-de-la-story-padre"

Ejemplo: Mover items en lote

Tool: batch_move_work_items
Parametros:
  workItemIds: ["uuid-1", "uuid-2", "uuid-3"]
  columnId: "uuid-columna-done"

Ejemplo: Listar items de un board filtrados

Tool: list_work_items
Parametros:
  boardId: "uuid-del-board"
  type: "task"
  priority: "high"