Work Items

Um agente não consegue executar "melhore o app". Ele precisa de trabalho específico, delimitado e com critérios de aceitação claros. Os work items são como você transforma intenção em especificações executáveis. Sem essa estrutura, os agentes improvisam. Com ela, eles sabem exatamente o que fazer e quando o trabalho está concluído.

Os work items são a unidade fundamental de trabalho no Almirant. Eles representam qualquer parte do trabalho que precisa ser planejada, executada e concluída: de um epic de alto nível a uma tarefa técnica concreta.

Tipos e hierarquia

O Almirant organiza o trabalho em uma hierarquia de quatro níveis:

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

Tipo	Nível	Finalidade	Exemplo
Epic	1	Objetivo estratégico de alto nível	"Sistema completo de autenticação"
Feature	2	Funcionalidade concreta dentro de um epic	"Login com Google OAuth"
Story	3	Requisito sob a perspectiva do usuário	"Como usuário, quero iniciar sessão com minha conta do Google"
Task	4	Unidade de trabalho técnico executável	"Implementar callback de OAuth no backend"

Quando usar cada tipo

• Epic: Quando o objetivo abrange várias features e exige várias semanas ou sprints. Os epics são o nível mais alto de planejamento.
• Feature: Quando você descreve uma funcionalidade completa que o usuário consegue perceber. Uma feature pode ter várias stories.
• Story: Quando você descreve um requisito concreto sob a perspectiva do usuário. As stories normalmente são concluídas dentro de um sprint.
• Task: Quando você descreve uma ação técnica específica e delimitada. As tasks são o nível que a IA implementa diretamente.

Relação pai-filho

Cada work item pode ter um parentId que estabelece a relação hierárquica. A visualização do board permite agrupar itens por seu pai, facilitando a visualização do progresso no nível de feature ou epic.

Campos

Campo	Tipo	Descrição	Obrigatório
title	string	Título descritivo do work item	Sim
description	string	Descrição detalhada, aceita Markdown	Não
type	enum	Tipo: epic, feature, story, task	Sim
priority	enum	Prioridade: urgent, high, medium, low, none	Não
boardColumnId	uuid	Coluna do board em que o item está	Sim
parentId	uuid	Work item pai, para hierarquia	Não
taskId	string	Identificador legível gerado automaticamente (e.g., A-T-37, MC-S-1)	Automático
dueDate	date	Data limite de entrega	Não
estimatedHours	number	Horas estimadas de trabalho	Não
tags	array	Etiquetas para categorizar o item	Não
metadata	object	Metadados enriquecidos (contexto de IA, notas técnicas)	Não
archived_at	timestamp	Data de arquivamento, se arquivado	Não

Identificador legível (taskId)

Cada work item recebe automaticamente um identificador único e legível baseado no projeto e no tipo. Exemplos:

• A-T-37 -- Task número 37 do projeto A.
• MC-S-1 -- Story número 1 do projeto MC.
• A-E-3 -- Epic número 3 do projeto A.

Esse identificador é usado em toda a interface e nas tools MCP para referenciar itens sem precisar de UUIDs.

Atribuições

Um work item pode ter vários responsáveis, cada um com um papel específico:

Papel	Descrição
responsible	Pessoa responsável por concluir o item
collaborator	Pessoa que contribui para o trabalho
reviewer	Pessoa responsável por revisar o resultado

Um mesmo item pode ter um responsável, vários colaboradores e um ou mais revisores simultaneamente.

Estado: derivado da coluna

Conceito-chave

Os work items NÃO têm um campo status. O estado é derivado diretamente da coluna do board em que o item está:

• Se a coluna tiver o papel semântico in_progress, o item estará "em andamento".
• Se a coluna tiver isDone = true, o item estará "concluído".
• Se a coluna tiver isDefault = true, será nela que os novos itens chegarão.

Mover um item entre colunas altera implicitamente seu estado.

Operações

Criar um work item

Há várias formas de criar work items:

1. Pelo board -- Clique no botão "+" de qualquer coluna. O item é criado diretamente nessa coluna.
2. Pela visualização de lista -- Use o botão "Novo item" e selecione o tipo, o board e a coluna.
3. Via MCP -- Use as tools create_work_item, create_task, create_story, create_feature ou create_epic.

Editar um work item

• Edição inline -- Clique no título de um item no board para editá-lo diretamente.
• Modal de detalhes -- Clique no cartão para abrir os detalhes completos, onde você pode editar todos os campos.
• Descrição em Markdown -- O campo de descrição oferece suporte completo a Markdown e pode ser formatado com a ajuda da IA.

Mover entre colunas

• Drag and drop -- Arraste o cartão de uma coluna para outra na visualização Kanban.
• Via MCP -- Use a tool move_work_item ou batch_move_work_items para mover um ou vários itens programaticamente.

Ao mover um item para uma coluna com isDone = true, ele é considerado concluído.

Atribuir e remover atribuições

No modal de detalhes, adicione ou remova responsáveis selecionando o usuário e seu papel (responsible, collaborator, reviewer).

Anexos (attachments)

Os work items oferecem suporte a arquivos anexados armazenados no S3. Você pode enviar imagens, documentos, capturas de tela ou qualquer arquivo relevante pelo modal de detalhes.

Arquivar

Em vez de serem excluídos, os work items são arquivados. O arquivamento define um timestamp em archived_at. Os itens arquivados deixam de aparecer nas visualizações principais, mas são mantidos para consulta histórica.

Para arquivar um item:

1. Abra os detalhes do work item.
2. Selecione Arquivar.
3. O item desaparece do board, mas pode ser consultado na visualização de arquivados.

Visualização de detalhes

A visualização de detalhes de um work item inclui:

• Todos os campos editáveis (título, descrição, tipo, prioridade, responsáveis, datas).
• Histórico de eventos -- Registro de todas as alterações feitas no item.
• Sessões de IA -- Histórico das interações da IA com o item, incluindo o custo de cada sessão.
• Documentos vinculados -- Links para documentos relacionados.
• Dependências -- Dependências com outros work items.
• Anexos -- Arquivos enviados para o item.
• Comentários e notas.

Operações em lote (bulk)

Na visualização de lista, você pode selecionar vários itens e executar ações em lote:

• Mover para outra coluna.
• Alterar a prioridade.
• Atribuir a um usuário.
• Arquivar.

Visualizações salvas e filtros

Os filtros da visualização de work items são mantidos na URL, permitindo compartilhar links com filtros aplicados. Você pode filtrar por:

• Tipo (epic, feature, story, task).
• Prioridade.
• Responsável.
• Tags.
• Coluna.

Você também pode agrupar os itens por seu pai para visualizar a hierarquia na visualização de lista.

Funcionalidades de IA

Os work items integram funcionalidades de IA diretamente:

• Formatação de texto com IA -- A IA pode formatar e melhorar a descrição do item.
• Ditado por voz -- Dite a descrição ou comentários por voz, e a IA os transcreve.
• Copy as prompt -- Copia o contexto do item como prompt para usá-lo no IDE.
• Sessões de IA com rastreamento de custo -- Cada interação de IA com um item é registrada com seu custo associado.

Para desenvolvedores

Para desenvolvedores

Ferramentas MCP

Criação

Tool	Descrição	Parâmetros principais
create_work_item	Cria um work item de qualquer tipo	title, type, boardId, columnId, description, priority, parentId
create_task	Atalho para criar uma task	title, boardId, description, priority, parentId
create_story	Atalho para criar uma story	title, boardId, description, priority, parentId
create_feature	Atalho para criar uma feature	title, boardId, description, priority, parentId
create_epic	Atalho para criar um epic	title, boardId, description, priority

Consulta

Tool	Descrição	Parâmetros principais
list_work_items	Lista work items com filtros	boardId, type, priority, assigneeId, parentId, columnId

Atualização

Tool	Descrição	Parâmetros principais
update_work_item	Atualiza campos de um work item	workItemId, campos a atualizar
move_work_item	Move um item para outra coluna	workItemId, columnId
batch_move_work_items	Move vários itens para uma coluna	workItemIds, columnId
resolve_work_items	Marca itens como resolvidos (move para a coluna done)	workItemIds
complete_ai_task	Conclui uma tarefa de IA e a move para done	workItemId, summary

Exemplo: criar uma 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"

Exemplo: mover itens em lote

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

Exemplo: listar itens filtrados de um board

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