Ferramentas - Work Items

Os work items são a unidade fundamental de trabalho no Almirant. Podem ser do tipo task, story, feature, epic ou idea e são organizados em colunas de um board. Esta seção documenta todas as ferramentas disponíveis para criar, consultar, atualizar e gerenciar work items por MCP.

Estado de um work item

Os work items não têm um campo status explícito. Seu estado é derivado da coluna do board em que se encontram (por exemplo, "Backlog", "In Progress", "Done").

Consulta

`list_work_items`

Lista work items com paginação e filtros opcionais. Se houver um projectId configurado na sessão MCP, filtra automaticamente por esse projeto.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
page	number	Não	Número da página (padrão: 1)
limit	number	Não	Itens por página (padrão: 50, máx.: 100)
search	string	Não	Buscar por título ou descrição
projectId	string (UUID)	Não	Filtrar por projeto (usa o da sessão como fallback)
boardId	string (UUID)	Não	Filtrar por board
boardColumnId	string (UUID)	Não	Filtrar por coluna do board
parentId	string (UUID)	Não	Filtrar por item pai (filhos de uma feature/epic)
type	string	Não	Filtrar por tipo: `epic`, `feature`, `story`, `task`, `idea`
priority	string	Não	Filtrar por prioridade: `low`, `medium`, `high`, `urgent`
assignee	string	Não	Filtrar por responsável

Exemplo:

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

Resposta:

{
  "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`

Resolve identificadores de work items (task IDs legíveis como "A-T-37" ou UUIDs) em objetos completos. Opcionalmente expande itens que não são task em suas tarefas folha recursivamente.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
ids	string[]	Sim	Lista de identificadores mistos (task IDs como `A-T-37`, `A-F-12` ou UUIDs)
includeLeafTasks	boolean	Não	Quando `true` (padrão), resolve recursivamente itens que não são task em tarefas folha
maxDepth	number	Não	Profundidade máxima de recursão (padrão: 3, máx.: 10)

Exemplo:

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

Resposta:

{
  "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`

Obtém o histórico de eventos (changelog) de um work item. Inclui eventos de criação, atualização, movimentação entre colunas, sessões de IA e comentários.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
workItemId	string (UUID)	Sim	ID do work item
eventType	string	Não	Filtrar por tipo: `created`, `updated`, `moved`, `deleted`, `attachment_added`, `attachment_removed`, `ai_session`, `comment`
limit	number	Não	Máximo de eventos (padrão: 50, máx.: 200)

Exemplo:

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

Resposta:

{
  "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"
    }
  ]
}

Criação

`create_work_item`

Cria um work item com controle total sobre board, coluna, tipo e projeto. Exige que boardId e boardColumnId sejam especificados explicitamente.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
title	string	Sim	Título do work item
description	string	Não	Descrição detalhada
type	string	Sim	Tipo: `epic`, `feature`, `story`, `task`, `idea`
priority	string	Não	Prioridade: `low`, `medium`, `high`, `urgent`
boardId	string (UUID)	Sim	Board onde criar o item
boardColumnId	string (UUID)	Sim	Coluna inicial
projectId	string (UUID)	Não	Projeto (usa o da sessão MCP como fallback)
assignee	string	Não	Nome ou identificador do responsável
parentId	string (UUID)	Não	ID do work item pai
metadata	object	Não	Metadados arbitrários (ex.: `{ definitionOfDone: "..." }`)

Exemplo:

{
  "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`

Atalho para criar uma tarefa. Força type=task e seleciona automaticamente o board padrão do projeto e a coluna "Backlog". Exige projectId configurado na sessão MCP.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
title	string	Sim	Título da tarefa
description	string	Não	Descrição detalhada
priority	string	Não	Prioridade: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Não	ID do work item pai
metadata	object	Não	Metadados arbitrários

Exemplo:

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

`create_story`

Atalho para criar uma story. Força type=story e seleciona automaticamente o board e a coluna "Backlog".

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
title	string	Sim	Título da story
description	string	Não	Descrição detalhada
priority	string	Não	Prioridade: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Não	ID da feature pai
metadata	object	Não	Metadados arbitrários

Exemplo:

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

`create_feature`

Atalho para criar uma feature. Força type=feature e seleciona automaticamente o board e a coluna "Backlog".

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
title	string	Sim	Título da feature
description	string	Não	Descrição detalhada
priority	string	Não	Prioridade: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Não	ID do epic pai
metadata	object	Não	Metadados arbitrários

Exemplo:

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

`create_epic`

Atalho para criar um epic. Força type=epic e seleciona automaticamente o board e a coluna "Backlog".

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
title	string	Sim	Título do epic
description	string	Não	Descrição detalhada
priority	string	Não	Prioridade: `low`, `medium`, `high`, `urgent`
metadata	object	Não	Metadados arbitrários

Exemplo:

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

Atualização e movimentação

`update_work_item`

Atualiza os campos de um work item existente. Apenas os campos fornecidos são modificados. Os metadados são mesclados aos existentes (não são substituídos).

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	ID do work item
title	string	Não	Novo título
description	string	Não	Nova descrição
type	string	Não	Novo tipo: `epic`, `feature`, `story`, `task`, `idea`
priority	string	Não	Nova prioridade: `low`, `medium`, `high`, `urgent`
assignee	string	Não	Novo responsável
boardColumnId	string (UUID)	Não	Mover para outra coluna
parentId	string (UUID) ou null	Não	Novo pai (`null` para desvincular)
metadata	object	Não	Metadados a mesclar aos existentes

Exemplo:

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

`move_work_item`

Move um work item para uma coluna diferente do board. Gerencia automaticamente as flags de processamento de IA de acordo com a coluna de destino.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
workItemId	string (UUID)	Sim	ID do work item a mover
boardColumnId	string (UUID)	Sim	ID da coluna de destino
isAutoSync	boolean	Não	`true` quando a movimentação ocorre por sincronização em cascata (padrão: `false`)
setAiProcessing	boolean	Não	Forçar `isAiProcessing=true` independentemente da coluna de destino
aiProvider	string	Não	Provedor de IA (`openai`, `anthropic`). Quando combinado com `setAiProcessing`, define metadados do provedor

Exemplo:

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

Comportamento automático das flags de IA

Ao mover para In Progress: isAiProcessing=true é ativado automaticamente
Ao mover para Review ou Done: isAiProcessing=false é desativado automaticamente
Com setAiProcessing=true: a flag é forçada independentemente da coluna

`batch_move_work_items`

Move vários work items para uma coluna de destino em uma única operação. Opcionalmente define flags de processamento de IA para todos os itens movidos.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
workItemIds	string[] (UUID)	Sim	Lista de IDs de work items a mover
boardColumnId	string (UUID)	Sim	ID da coluna de destino
setAiProcessing	boolean	Não	Ativar `isAiProcessing=true` para todos os itens
aiProvider	string	Não	Provedor de IA a registrar nos metadados

Exemplo:

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

Resposta:

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

`delete_work_item`

Exclui permanentemente um work item pelo seu ID.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	ID do work item a excluir

Exemplo:

{
  "id": "wi-001"
}

Resposta:

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

Prompts de implementação

`generate_work_item_prompt`

Gera um prompt de implementação enriquecido com o contexto do projeto (tech stack, repositórios, tarefas irmãs, fluxo do board). O prompt é gerado por IA e salvo nos metadados do work item.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	ID do work item

Exemplo:

{
  "id": "wi-001"
}

Resposta:

{
  "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 o prompt de implementação gerado anteriormente e armazenado nos metadados do work item.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	ID do work item

Exemplo:

{
  "id": "wi-001"
}

Resposta:

{
  "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"
}

Fluxo de review e validação

`complete_review`

Conclui a revisão de código de um work item. Se a revisão for aprovada, o item é movido para Testing. Se falhar, volta para In Progress. Os metadados de revisão são armazenados no work item.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
workItemId	string (UUID)	Sim	ID do work item
result	string	Sim	Resultado: `pass` (move para Testing) ou `fail` (move para In Progress)
summary	string	Sim	Resumo da revisão
issues	string[]	Não	Lista de problemas encontrados (relevante quando `result=fail`)
reviewedFiles	string[]	Não	Lista de arquivos revisados

Exemplo:

{
  "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`

Conclui atomicamente a validação de uma tarefa: move uma validação aprovada para sua coluna de destino, normalmente To Document, limpa as flags de IA, mescla metadados de documentação e resultados de testes e registra a sessão de IA. Se a coluna Validating for informada por engano, a tool redireciona para To Document quando essa coluna existe no board.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
workItemId	string (UUID)	Sim	ID do work item
toDocumentColumnId	string (UUID)	Não	ID da coluna de destino para uma validação aprovada. Preferencialmente a coluna `To Document`
validatingColumnId	string (UUID)	Não	Alias legado do destino. Se apontar para `Validating`, a tool tentará redirecionar para `To Document`
documentation	object	Não	Metadados de documentação (veja o subobjeto abaixo)
documentation.summary	string	Não	Resumo do que foi validado
documentation.screenshots	string[]	Não	URLs dos screenshots anexados
documentation.mermaidDiagrams	string[]	Não	Diagramas Mermaid como strings
documentation.changelogEntry	string	Não	Entrada de changelog
testResults	object	Não	Resultados de testes (veja o subobjeto abaixo)
testResults.passed	number	Não	Testes aprovados
testResults.failed	number	Não	Testes falhos
testResults.testFiles	string[]	Não	Paths de arquivos de teste
model	string	Sim	Modelo de IA usado (ex.: `claude-opus-4-6`)
provider	string	Não	Provedor de IA (padrão: `anthropic`)
totalTokens	number	Sim	Total de tokens consumidos
durationMs	number	Não	Duração da sessão em milissegundos
taskId	string	Não	Task ID legível (ex.: `A-T-37`)

Exemplo:

{
  "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`

Conclui atomicamente o trabalho de IA em uma tarefa: move para Review, limpa as flags de IA, define userActions e registra a sessão com consumo de tokens. Substitui a necessidade de chamar move_work_item + update_work_item + record_ai_session separadamente.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
workItemId	string (UUID)	Sim	ID do work item
reviewColumnId	string (UUID)	Sim	ID da coluna Review
userActions	string	Não	Lista em Markdown de etapas manuais que o usuário deve verificar
model	string	Sim	Modelo de IA usado (ex.: `claude-opus-4-6`)
provider	string	Não	Provedor (padrão: `openai`)
totalTokens	number	Sim	Total de tokens consumidos
durationMs	number	Não	Duração da sessão em ms
sessionType	string	Não	Tipo de sessão (padrão: `implement`)
taskId	string	Não	Task ID legível (ex.: `A-T-37`)

Exemplo:

{
  "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"
}

Resposta:

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

Uso recomendado

Use complete_ai_task ao finalizar a implementação de uma tarefa por IA. É a forma mais eficiente de encerrar o ciclo de trabalho: uma única chamada de tool que move, limpa flags e registra custos.

Anexos

`upload_work_item_attachment`

Envia um anexo para um work item a partir de um caminho de arquivo local. Projetado para tooling de IA (por exemplo, anexar screenshots do Playwright).

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
workItemId	string (UUID)	Sim	ID do work item
filePath	string	Sim	Caminho absoluto ou relativo ao repositório (permitido: `/tmp/*` ou abaixo do diretório de trabalho)
fileName	string	Não	Nome do arquivo a armazenar (padrão: basename do caminho)
mimeType	string	Não	Tipo MIME (padrão: inferido pelo nome)
uploadedBy	string	Não	Rótulo de quem enviou
metadata	object	Não	Metadados do anexo (ex.: `{ kind: "review-screenshot", page: "/boards" }`)
deleteAfterUpload	boolean	Não	Excluir o arquivo local após o envio (padrão: `true`)

Exemplo:

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

Contexto avançado

`get_implement_context`

Resolve identificadores em tarefas folha pendentes, classifica por estado da coluna, inclui mapeamento de boards, dependências intra-batch e ondas de execução pré-calculadas.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
ids	string[]	Sim	Lista de task IDs/UUIDs a implementar
projectId	string (UUID)	Não	ID do projeto (padrão: sessão MCP)

Exemplo:

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

`get_ideation_context`

Obtém contexto de ideação: work items relacionados por keywords, possíveis pais e configuração dinâmica de boards.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
keywords	string[]	Sim	Palavras-chave de busca
projectId	string (UUID)	Não	ID do projeto (padrão: sessão MCP)
limit	number	Não	Limite de resultados (padrão: 20, máx.: 50)

Exemplo:

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

`get_review_context`

Obtém contexto completo de review para uma tarefa ou feature: detalhes do item, colunas de roteamento, dependências, itens irmãos e filhos revisáveis.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
taskId	string	Sim	Identificador da tarefa (UUID ou taskId como `A-T-37`)
featureReview	boolean	Não	Quando `true`, inclui filhos revisáveis para review de feature/epic

Exemplo:

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

`get_validate_context`

Resolve identificadores em tarefas folha, classifica por coluna do board (revisável em Review, testável em Testing, ignorado nos outros casos), inclui mapeamento de boards com a coluna Validating e resumos dos itens pai.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
ids	string[]	Sim	Lista de task IDs/UUIDs a validar
projectId	string (UUID)	Não	ID do projeto (padrão: sessão MCP)

Exemplo:

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

Consulta​

list_work_items​

resolve_work_items​

get_work_item_events​

Criação​

create_work_item​

create_task​

create_story​

create_feature​

create_epic​

Atualização e movimentação​

update_work_item​

move_work_item​

batch_move_work_items​

delete_work_item​

Prompts de implementação​

generate_work_item_prompt​

get_work_item_prompt​

Fluxo de review e validação​

complete_review​

complete_validation​

complete_ai_task​

Anexos​

upload_work_item_attachment​

Contexto avançado​

get_implement_context​

get_ideation_context​

get_review_context​

get_validate_context​

Consulta

`list_work_items`

`resolve_work_items`

`get_work_item_events`

Criação

`create_work_item`

`create_task`

`create_story`

`create_feature`

`create_epic`

Atualização e movimentação

`update_work_item`

`move_work_item`

`batch_move_work_items`

`delete_work_item`

Prompts de implementação

`generate_work_item_prompt`

`get_work_item_prompt`

Fluxo de review e validação

`complete_review`

`complete_validation`

`complete_ai_task`

Anexos

`upload_work_item_attachment`

Contexto avançado

`get_implement_context`

`get_ideation_context`

`get_review_context`

`get_validate_context`