Tools - Work Items

Los work items son la unidad fundamental de trabajo en Almirant. Pueden ser de tipo task, story, feature, epic o idea, y se organizan en columnas de un board. Esta seccion documenta todos los tools disponibles para crear, consultar, actualizar y gestionar work items via MCP.

Estado de un work item

Los work items no tienen un campo status explicito. Su estado se deriva de la columna del board en la que se encuentran (por ejemplo, "Backlog", "In Progress", "Done").

Consulta

`list_work_items`

Lista work items con paginacion y filtros opcionales. Si hay un projectId configurado en la sesion MCP, filtra automaticamente por ese proyecto.

Parametros:

Nombre	Tipo	Requerido	Descripcion
page	number	No	Numero de pagina (defecto: 1)
limit	number	No	Elementos por pagina (defecto: 50, max: 100)
search	string	No	Buscar por titulo o descripcion
projectId	string (UUID)	No	Filtrar por proyecto (usa el de sesion como fallback)
boardId	string (UUID)	No	Filtrar por board
boardColumnId	string (UUID)	No	Filtrar por columna del board
parentId	string (UUID)	No	Filtrar por item padre (hijos de un feature/epic)
type	string	No	Filtrar por tipo: `epic`, `feature`, `story`, `task`, `idea`
priority	string	No	Filtrar por prioridad: `low`, `medium`, `high`, `urgent`
assignee	string	No	Filtrar por asignado

Ejemplo:

{
  "boardId": "b1234567-89ab-cdef-0123-456789abcdef",
  "type": "task",
  "priority": "high"
}

Respuesta:

{
  "workItems": [
    {
      "id": "wi-001",
      "taskId": "A-T-37",
      "title": "Implementar autenticacion OAuth",
      "type": "task",
      "priority": "high",
      "assignee": "javier",
      "boardId": "b1234567-...",
      "boardColumnId": "col-003",
      "columnName": "In Progress",
      "parentId": "wi-feature-01",
      "projectId": "550e8400-..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

`resolve_work_items`

Resuelve identificadores de work items (task IDs legibles como "A-T-37" o UUIDs) en objetos completos. Opcionalmente expande items no-task a sus tareas hoja recursivamente.

Parametros:

Nombre	Tipo	Requerido	Descripcion
ids	string[]	Si	Lista de identificadores mixtos (task IDs como `A-T-37`, `A-F-12`, o UUIDs)
includeLeafTasks	boolean	No	Cuando `true` (defecto), resuelve recursivamente items no-task a tareas hoja
maxDepth	number	No	Profundidad maxima de recursion (defecto: 3, max: 10)

Ejemplo:

{
  "ids": ["A-T-37", "A-F-12", "550e8400-e29b-41d4-a716-446655440000"],
  "includeLeafTasks": true
}

Respuesta:

{
  "inputIds": ["A-T-37", "A-F-12", "550e8400-..."],
  "notFound": [],
  "items": [
    {
      "id": "wi-001",
      "taskId": "A-T-37",
      "title": "Implementar login",
      "type": "task",
      "resolvedFrom": ["A-T-37"]
    },
    {
      "id": "wi-003",
      "taskId": "A-T-40",
      "title": "Validar tokens",
      "type": "task",
      "resolvedFrom": ["A-F-12"]
    }
  ]
}

`get_work_item_events`

Obtiene el historial de eventos (changelog) de un work item. Incluye eventos de creacion, actualizacion, movimiento entre columnas, sesiones de IA y comentarios.

Parametros:

Nombre	Tipo	Requerido	Descripcion
workItemId	string (UUID)	Si	ID del work item
eventType	string	No	Filtrar por tipo: `created`, `updated`, `moved`, `deleted`, `attachment_added`, `attachment_removed`, `ai_session`, `comment`
limit	number	No	Maximo de eventos (defecto: 50, max: 200)

Ejemplo:

{
  "workItemId": "wi-001",
  "eventType": "moved",
  "limit": 20
}

Respuesta:

{
  "workItemId": "wi-001",
  "taskId": "A-T-37",
  "title": "Implementar login",
  "totalEvents": 3,
  "events": [
    {
      "eventType": "moved",
      "data": {
        "fromColumn": "To Do",
        "toColumn": "In Progress"
      },
      "createdAt": "2025-02-01T10:30:00.000Z"
    }
  ]
}

Creacion

`create_work_item`

Crea un work item con control total sobre board, columna, tipo y proyecto. Requiere especificar boardId y boardColumnId explicitamente.

Parametros:

Nombre	Tipo	Requerido	Descripcion
title	string	Si	Titulo del work item
description	string	No	Descripcion detallada
type	string	Si	Tipo: `epic`, `feature`, `story`, `task`, `idea`
priority	string	No	Prioridad: `low`, `medium`, `high`, `urgent`
boardId	string (UUID)	Si	Board donde crear el item
boardColumnId	string (UUID)	Si	Columna inicial
projectId	string (UUID)	No	Proyecto (usa el de sesion MCP como fallback)
assignee	string	No	Nombre o identificador del asignado
parentId	string (UUID)	No	ID del work item padre
metadata	object	No	Metadatos arbitrarios (ej: `{ definitionOfDone: "..." }`)

Ejemplo:

{
  "title": "Implementar endpoint de login",
  "description": "Crear endpoint POST /api/auth/login con validacion JWT",
  "type": "task",
  "priority": "high",
  "boardId": "b1234567-89ab-cdef-0123-456789abcdef",
  "boardColumnId": "col-001",
  "parentId": "wi-feature-01"
}

`create_task`

Atajo para crear una tarea. Fuerza type=task y selecciona automaticamente el board por defecto del proyecto y la columna "Backlog". Requiere projectId configurado en la sesion MCP.

Parametros:

Nombre	Tipo	Requerido	Descripcion
title	string	Si	Titulo de la tarea
description	string	No	Descripcion detallada
priority	string	No	Prioridad: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	No	ID del work item padre
metadata	object	No	Metadatos arbitrarios

Ejemplo:

{
  "title": "Anadir validacion de email",
  "priority": "medium",
  "parentId": "wi-feature-01"
}

`create_story`

Atajo para crear una story. Fuerza type=story y selecciona automaticamente el board y columna "Backlog".

Parametros:

Nombre	Tipo	Requerido	Descripcion
title	string	Si	Titulo de la story
description	string	No	Descripcion detallada
priority	string	No	Prioridad: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	No	ID del feature padre
metadata	object	No	Metadatos arbitrarios

Ejemplo:

{
  "title": "Como usuario quiero poder iniciar sesion con Google",
  "priority": "high",
  "parentId": "wi-feature-01"
}

`create_feature`

Atajo para crear un feature. Fuerza type=feature y selecciona automaticamente el board y columna "Backlog".

Parametros:

Nombre	Tipo	Requerido	Descripcion
title	string	Si	Titulo del feature
description	string	No	Descripcion detallada
priority	string	No	Prioridad: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	No	ID del epic padre
metadata	object	No	Metadatos arbitrarios

Ejemplo:

{
  "title": "Sistema de autenticacion",
  "description": "Autenticacion OAuth con Google y email/password",
  "priority": "high"
}

`create_epic`

Atajo para crear un epic. Fuerza type=epic y selecciona automaticamente el board y columna "Backlog".

Parametros:

Nombre	Tipo	Requerido	Descripcion
title	string	Si	Titulo del epic
description	string	No	Descripcion detallada
priority	string	No	Prioridad: `low`, `medium`, `high`, `urgent`
metadata	object	No	Metadatos arbitrarios

Ejemplo:

{
  "title": "Epic: Seguridad y autenticacion",
  "description": "Todos los flujos de autenticacion y autorizacion de la plataforma",
  "priority": "urgent"
}

Actualizacion y movimiento

`update_work_item`

Actualiza los campos de un work item existente. Solo los campos proporcionados se modifican. Los metadatos se fusionan con los existentes (no se sobreescriben).

Parametros:

Nombre	Tipo	Requerido	Descripcion
id	string (UUID)	Si	ID del work item
title	string	No	Nuevo titulo
description	string	No	Nueva descripcion
type	string	No	Nuevo tipo: `epic`, `feature`, `story`, `task`, `idea`
priority	string	No	Nueva prioridad: `low`, `medium`, `high`, `urgent`
assignee	string	No	Nuevo asignado
boardColumnId	string (UUID)	No	Mover a otra columna
parentId	string (UUID) o null	No	Nuevo padre (`null` para desasociar)
metadata	object	No	Metadatos a fusionar con los existentes

Ejemplo:

{
  "id": "wi-001",
  "priority": "urgent",
  "metadata": {
    "definitionOfDone": "Tests unitarios + integration tests pasando"
  }
}

`move_work_item`

Mueve un work item a una columna diferente del board. Gestiona automaticamente los flags de procesamiento IA segun la columna destino.

Parametros:

Nombre	Tipo	Requerido	Descripcion
workItemId	string (UUID)	Si	ID del work item a mover
boardColumnId	string (UUID)	Si	ID de la columna destino
isAutoSync	boolean	No	`true` cuando el movimiento es por sincronizacion en cascada (defecto: `false`)
setAiProcessing	boolean	No	Forzar `isAiProcessing=true` independientemente de la columna destino
aiProvider	string	No	Proveedor de IA (`openai`, `anthropic`). Cuando se combina con `setAiProcessing`, establece metadatos de proveedor

Ejemplo:

{
  "workItemId": "wi-001",
  "boardColumnId": "col-003",
  "setAiProcessing": true,
  "aiProvider": "anthropic"
}

Comportamiento automatico de AI flags

Al mover a In Progress: se activa isAiProcessing=true automaticamente
Al mover a Review o Done: se desactiva isAiProcessing=false automaticamente
Con setAiProcessing=true: se fuerza el flag independientemente de la columna

`batch_move_work_items`

Mueve multiples work items a una columna destino en una unica operacion. Opcionalmente establece flags de procesamiento IA para todos los items movidos.

Parametros:

Nombre	Tipo	Requerido	Descripcion
workItemIds	string[] (UUID)	Si	Lista de IDs de work items a mover
boardColumnId	string (UUID)	Si	ID de la columna destino
setAiProcessing	boolean	No	Activar `isAiProcessing=true` para todos los items
aiProvider	string	No	Proveedor de IA a registrar en los metadatos

Ejemplo:

{
  "workItemIds": ["wi-001", "wi-002", "wi-003"],
  "boardColumnId": "col-003",
  "setAiProcessing": true,
  "aiProvider": "anthropic"
}

Respuesta:

{
  "movedCount": 3,
  "items": [ ... ],
  "note": "batch_move_work_items uses bulk update and does not run cascade/position logic"
}

`delete_work_item`

Elimina permanentemente un work item por su ID.

Parametros:

Nombre	Tipo	Requerido	Descripcion
id	string (UUID)	Si	ID del work item a eliminar

Ejemplo:

{
  "id": "wi-001"
}

Respuesta:

{
  "deleted": true,
  "id": "wi-001"
}

Prompts de implementacion

`generate_work_item_prompt`

Genera un prompt de implementacion enriquecido con el contexto del proyecto (tech stack, repositorios, tareas hermanas, flujo del board). El prompt es generado por IA y se guarda en los metadatos del work item.

Parametros:

Nombre	Tipo	Requerido	Descripcion
id	string (UUID)	Si	ID del work item

Ejemplo:

{
  "id": "wi-001"
}

Respuesta:

{
  "prompt": "## Contexto del proyecto\n...\n## Tarea\n...",
  "context": {
    "workItemId": "wi-001",
    "taskId": "A-T-37",
    "title": "Implementar login",
    "type": "task",
    "projectName": "Mi Proyecto",
    "siblingsCount": 4,
    "hasParent": true
  },
  "savedToDb": true
}

`get_work_item_prompt`

Recupera el prompt de implementacion previamente generado y almacenado en los metadatos del work item.

Parametros:

Nombre	Tipo	Requerido	Descripcion
id	string (UUID)	Si	ID del work item

Ejemplo:

{
  "id": "wi-001"
}

Respuesta:

{
  "prompt": "## Contexto del proyecto\n...",
  "context": {
    "workItemId": "wi-001",
    "taskId": "A-T-37",
    "title": "Implementar login",
    "type": "task"
  },
  "generatedAt": "2025-02-01T10:00:00.000Z"
}

Flujo de review y validacion

`complete_review`

Completa la revision de codigo de un work item. Si la revision pasa, el item se mueve a Testing. Si falla, vuelve a In Progress. Los metadatos de revision se almacenan en el work item.

Parametros:

Nombre	Tipo	Requerido	Descripcion
workItemId	string (UUID)	Si	ID del work item
result	string	Si	Resultado: `pass` (mueve a Testing) o `fail` (mueve a In Progress)
summary	string	Si	Resumen de la revision
issues	string[]	No	Lista de problemas encontrados (relevante cuando `result=fail`)
reviewedFiles	string[]	No	Lista de archivos revisados

Ejemplo:

{
  "workItemId": "wi-001",
  "result": "pass",
  "summary": "Codigo limpio, tests pasando, cumple la definicion de done",
  "reviewedFiles": ["src/auth/login.ts", "src/auth/login.test.ts"]
}

`complete_validation`

Completa atomicamente la validacion de una tarea: mueve una validacion aprobada a su columna destino, normalmente To Document, limpia los flags de IA, fusiona metadatos de documentacion y resultados de tests, y registra la sesion de IA. Si se pasa por error la columna Validating, la tool redirige a To Document cuando esa columna existe en el board.

Parametros:

Nombre	Tipo	Requerido	Descripcion
workItemId	string (UUID)	Si	ID del work item
toDocumentColumnId	string (UUID)	No	ID de la columna destino para una validacion aprobada. Preferiblemente la columna `To Document`
validatingColumnId	string (UUID)	No	Alias legacy del destino. Si apunta a `Validating`, la tool intentara redirigir a `To Document`
documentation	object	No	Metadatos de documentacion (ver subobjeto abajo)
documentation.summary	string	No	Resumen de lo validado
documentation.screenshots	string[]	No	URLs de screenshots adjuntos
documentation.mermaidDiagrams	string[]	No	Diagramas Mermaid como strings
documentation.changelogEntry	string	No	Entrada de changelog
testResults	object	No	Resultados de tests (ver subobjeto abajo)
testResults.passed	number	No	Tests pasados
testResults.failed	number	No	Tests fallidos
testResults.testFiles	string[]	No	Paths de archivos de test
model	string	Si	Modelo de IA usado (ej: `claude-opus-4-6`)
provider	string	No	Proveedor de IA (defecto: `anthropic`)
totalTokens	number	Si	Total de tokens consumidos
durationMs	number	No	Duracion de la sesion en milisegundos
taskId	string	No	Task ID legible (ej: `A-T-37`)

Ejemplo:

{
  "workItemId": "wi-001",
  "toDocumentColumnId": "col-to-document",
  "documentation": {
    "summary": "Login con Google verificado end-to-end",
    "screenshots": ["/api/work-items/wi-001/attachments/local?key=screenshot.png"]
  },
  "testResults": {
    "passed": 12,
    "failed": 0,
    "testFiles": ["src/auth/__tests__/login.test.ts"]
  },
  "model": "claude-opus-4-6",
  "provider": "anthropic",
  "totalTokens": 45000,
  "durationMs": 120000
}

`complete_ai_task`

Completa atomicamente el trabajo de IA sobre una tarea: mueve a Review, limpia los flags de IA, establece userActions y registra la sesion con consumo de tokens. Reemplaza la necesidad de llamar move_work_item + update_work_item + record_ai_session por separado.

Parametros:

Nombre	Tipo	Requerido	Descripcion
workItemId	string (UUID)	Si	ID del work item
reviewColumnId	string (UUID)	Si	ID de la columna Review
userActions	string	No	Lista en Markdown de pasos manuales que el usuario debe verificar
model	string	Si	Modelo de IA usado (ej: `claude-opus-4-6`)
provider	string	No	Proveedor (defecto: `openai`)
totalTokens	number	Si	Total de tokens consumidos
durationMs	number	No	Duracion de la sesion en ms
sessionType	string	No	Tipo de sesion (defecto: `implement`)
taskId	string	No	Task ID legible (ej: `A-T-37`)

Ejemplo:

{
  "workItemId": "wi-001",
  "reviewColumnId": "col-004",
  "userActions": "- Verificar que el login redirige a /dashboard\n- Comprobar que el token se guarda en cookies",
  "model": "claude-opus-4-6",
  "provider": "anthropic",
  "totalTokens": 85000,
  "durationMs": 300000,
  "taskId": "A-T-37"
}

Respuesta:

{
  "completed": true,
  "workItemId": "wi-001",
  "movedTo": "Review",
  "sessionId": "session-uuid",
  "estimatedCost": "$0.1275",
  "totalTokens": 85000
}

Uso recomendado

Usa complete_ai_task al finalizar la implementacion de una tarea por IA. Es la forma mas eficiente de cerrar el ciclo de trabajo: un unico tool call que mueve, limpia flags y registra costes.

Adjuntos

`upload_work_item_attachment`

Sube un adjunto a un work item desde una ruta de archivo local. Disenado para tooling de IA (por ejemplo, adjuntar screenshots de Playwright).

Parametros:

Nombre	Tipo	Requerido	Descripcion
workItemId	string (UUID)	Si	ID del work item
filePath	string	Si	Ruta absoluta o relativa al repo (permitido: `/tmp/*` o bajo el directorio de trabajo)
fileName	string	No	Nombre del archivo a almacenar (defecto: basename del path)
mimeType	string	No	Tipo MIME (defecto: inferido del nombre)
uploadedBy	string	No	Etiqueta del uploader
metadata	object	No	Metadatos del adjunto (ej: `{ kind: "review-screenshot", page: "/boards" }`)
deleteAfterUpload	boolean	No	Eliminar el archivo local tras la subida (defecto: `true`)

Ejemplo:

{
  "workItemId": "wi-001",
  "filePath": "/tmp/screenshot-login.png",
  "metadata": {
    "kind": "review-screenshot",
    "page": "/sign-in"
  }
}

Contexto avanzado

`get_implement_context`

Resuelve identificadores en tareas hoja pendientes, clasifica por estado de columna, incluye mapeo de boards, dependencias intra-batch y oleadas de ejecucion precalculadas.

Parametros:

Nombre	Tipo	Requerido	Descripcion
ids	string[]	Si	Lista de task IDs/UUIDs a implementar
projectId	string (UUID)	No	ID del proyecto (defecto: sesion MCP)

Ejemplo:

{
  "ids": ["A-T-37", "A-T-38", "A-F-12"]
}

`get_ideation_context`

Obtiene contexto de ideacion: work items relacionados por keywords, padres potenciales y configuracion dinamica de boards.

Parametros:

Nombre	Tipo	Requerido	Descripcion
keywords	string[]	Si	Palabras clave de busqueda
projectId	string (UUID)	No	ID del proyecto (defecto: sesion MCP)
limit	number	No	Limite de resultados (defecto: 20, max: 50)

Ejemplo:

{
  "keywords": ["autenticacion", "OAuth", "login"]
}

`get_review_context`

Obtiene contexto completo de review para una tarea o feature: detalles del item, columnas de enrutamiento, dependencias, items hermanos e hijos revisables.

Parametros:

Nombre	Tipo	Requerido	Descripcion
taskId	string	Si	Identificador de la tarea (UUID o taskId como `A-T-37`)
featureReview	boolean	No	Cuando `true`, incluye hijos revisables para review de feature/epic

Ejemplo:

{
  "taskId": "A-T-37",
  "featureReview": false
}

`get_validate_context`

Resuelve identificadores en tareas hoja, clasifica por columna del board (revisable en Review, testeable en Testing, omitido en otros casos), incluye mapeo de boards con columna Validating y resumenes de items padre.

Parametros:

Nombre	Tipo	Requerido	Descripcion
ids	string[]	Si	Lista de task IDs/UUIDs a validar
projectId	string (UUID)	No	ID del proyecto (defecto: sesion MCP)

Ejemplo:

{
  "ids": ["A-T-37", "A-T-38"]
}

Consulta​

list_work_items​

resolve_work_items​

get_work_item_events​

Creacion​

create_work_item​

create_task​

create_story​

create_feature​

create_epic​

Actualizacion y movimiento​

update_work_item​

move_work_item​

batch_move_work_items​

delete_work_item​

Prompts de implementacion​

generate_work_item_prompt​

get_work_item_prompt​

Flujo de review y validacion​

complete_review​

complete_validation​

complete_ai_task​

Adjuntos​

upload_work_item_attachment​

Contexto avanzado​

get_implement_context​

get_ideation_context​

get_review_context​

get_validate_context​

Consulta

`list_work_items`

`resolve_work_items`

`get_work_item_events`

Creacion

`create_work_item`

`create_task`

`create_story`

`create_feature`

`create_epic`

Actualizacion y movimiento

`update_work_item`

`move_work_item`

`batch_move_work_items`

`delete_work_item`

Prompts de implementacion

`generate_work_item_prompt`

`get_work_item_prompt`

Flujo de review y validacion

`complete_review`

`complete_validation`

`complete_ai_task`

Adjuntos

`upload_work_item_attachment`

Contexto avanzado

`get_implement_context`

`get_ideation_context`

`get_review_context`

`get_validate_context`