Outils - Work Items

Les work items constituent l'unité fondamentale de travail dans Almirant. Ils peuvent être de type task, story, feature, epic ou idea, et sont organisés en colonnes d'un board. Cette section documente tous les outils disponibles pour créer, consulter, mettre à jour et gérer des work items via MCP.

État d'un work item

Les work items n'ont pas de champ status explicite. Leur état est déterminé par la colonne du board dans laquelle ils se trouvent (par exemple, "Backlog", "In Progress", "Done").

Consultation

`list_work_items`

Liste les work items avec pagination et filtres facultatifs. Si un projectId est configuré dans la session MCP, les résultats sont automatiquement filtrés par ce projet.

Paramètres :

Nom	Type	Obligatoire	Description
page	number	Non	Numéro de page (par défaut : 1)
limit	number	Non	Éléments par page (par défaut : 50, max. : 100)
search	string	Non	Recherche par titre ou description
projectId	string (UUID)	Non	Filtre par projet (utilise celui de la session comme valeur de repli)
boardId	string (UUID)	Non	Filtre par board
boardColumnId	string (UUID)	Non	Filtre par colonne du board
parentId	string (UUID)	Non	Filtre par élément parent (enfants d'une feature/epic)
type	string	Non	Filtre par type : `epic`, `feature`, `story`, `task`, `idea`
priority	string	Non	Filtre par priorité : `low`, `medium`, `high`, `urgent`
assignee	string	Non	Filtre par assigné

Exemple :

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

Réponse :

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

Résout les identifiants de work items (des task IDs lisibles tels que "A-T-37" ou des UUID) en objets complets. Développe facultativement les éléments autres que les tasks en leurs tâches feuilles, de manière récursive.

Paramètres :

Nom	Type	Obligatoire	Description
ids	string[]	Oui	Liste d'identifiants mixtes (task IDs tels que `A-T-37`, `A-F-12` ou UUID)
includeLeafTasks	boolean	Non	Lorsque `true` (par défaut), résout récursivement les éléments autres que les tasks en tâches feuilles
maxDepth	number	Non	Profondeur maximale de récursion (par défaut : 3, max. : 10)

Exemple :

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

Réponse :

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

Récupère l'historique des événements (changelog) d'un work item. Inclut les événements de création, de mise à jour, de déplacement entre colonnes, les sessions IA et les commentaires.

Paramètres :

Nom	Type	Obligatoire	Description
workItemId	string (UUID)	Oui	ID du work item
eventType	string	Non	Filtre par type : `created`, `updated`, `moved`, `deleted`, `attachment_added`, `attachment_removed`, `ai_session`, `comment`
limit	number	Non	Nombre maximal d'événements (par défaut : 50, max. : 200)

Exemple :

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

Réponse :

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

Création

`create_work_item`

Crée un work item avec un contrôle total sur le board, la colonne, le type et le projet. Nécessite de spécifier explicitement boardId et boardColumnId.

Paramètres :

Nom	Type	Obligatoire	Description
title	string	Oui	Titre du work item
description	string	Non	Description détaillée
type	string	Oui	Type : `epic`, `feature`, `story`, `task`, `idea`
priority	string	Non	Priorité : `low`, `medium`, `high`, `urgent`
boardId	string (UUID)	Oui	Board dans lequel créer l'élément
boardColumnId	string (UUID)	Oui	Colonne initiale
projectId	string (UUID)	Non	Projet (utilise celui de la session MCP comme valeur de repli)
assignee	string	Non	Nom ou identifiant de l'assigné
parentId	string (UUID)	Non	ID du work item parent
metadata	object	Non	Métadonnées arbitraires (ex. : `{ definitionOfDone: "..." }`)

Exemple :

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

Raccourci pour créer une tâche. Force type=task et sélectionne automatiquement le board par défaut du projet ainsi que la colonne "Backlog". Nécessite qu'un projectId soit configuré dans la session MCP.

Paramètres :

Nom	Type	Obligatoire	Description
title	string	Oui	Titre de la tâche
description	string	Non	Description détaillée
priority	string	Non	Priorité : `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Non	ID du work item parent
metadata	object	Non	Métadonnées arbitraires

Exemple :

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

`create_story`

Raccourci pour créer une story. Force type=story et sélectionne automatiquement le board et la colonne "Backlog".

Paramètres :

Nom	Type	Obligatoire	Description
title	string	Oui	Titre de la story
description	string	Non	Description détaillée
priority	string	Non	Priorité : `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Non	ID de la feature parent
metadata	object	Non	Métadonnées arbitraires

Exemple :

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

`create_feature`

Raccourci pour créer une feature. Force type=feature et sélectionne automatiquement le board et la colonne "Backlog".

Paramètres :

Nom	Type	Obligatoire	Description
title	string	Oui	Titre de la feature
description	string	Non	Description détaillée
priority	string	Non	Priorité : `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Non	ID de l'epic parent
metadata	object	Non	Métadonnées arbitraires

Exemple :

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

`create_epic`

Raccourci pour créer une epic. Force type=epic et sélectionne automatiquement le board et la colonne "Backlog".

Paramètres :

Nom	Type	Obligatoire	Description
title	string	Oui	Titre de l'epic
description	string	Non	Description détaillée
priority	string	Non	Priorité : `low`, `medium`, `high`, `urgent`
metadata	object	Non	Métadonnées arbitraires

Exemple :

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

Mise à jour et déplacement

`update_work_item`

Met à jour les champs d'un work item existant. Seuls les champs fournis sont modifiés. Les métadonnées sont fusionnées avec celles existantes (elles ne sont pas écrasées).

Paramètres :

Nom	Type	Obligatoire	Description
id	string (UUID)	Oui	ID du work item
title	string	Non	Nouveau titre
description	string	Non	Nouvelle description
type	string	Non	Nouveau type : `epic`, `feature`, `story`, `task`, `idea`
priority	string	Non	Nouvelle priorité : `low`, `medium`, `high`, `urgent`
assignee	string	Non	Nouvel assigné
boardColumnId	string (UUID)	Non	Déplacer vers une autre colonne
parentId	string (UUID) ou null	Non	Nouveau parent (`null` pour dissocier)
metadata	object	Non	Métadonnées à fusionner avec celles existantes

Exemple :

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

`move_work_item`

Déplace un work item vers une autre colonne du board. Gère automatiquement les indicateurs de traitement par IA en fonction de la colonne de destination.

Paramètres :

Nom	Type	Obligatoire	Description
workItemId	string (UUID)	Oui	ID du work item à déplacer
boardColumnId	string (UUID)	Oui	ID de la colonne de destination
isAutoSync	boolean	Non	`true` lorsque le déplacement provient d'une synchronisation en cascade (par défaut : `false`)
setAiProcessing	boolean	Non	Force `isAiProcessing=true` indépendamment de la colonne de destination
aiProvider	string	Non	Fournisseur IA (`openai`, `anthropic`). Lorsqu'il est associé à `setAiProcessing`, définit les métadonnées du fournisseur

Exemple :

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

Comportement automatique des indicateurs IA

Lors d'un déplacement vers In Progress : isAiProcessing=true est automatiquement activé
Lors d'un déplacement vers Review ou Done : isAiProcessing=false est automatiquement désactivé
Avec setAiProcessing=true : l'indicateur est forcé indépendamment de la colonne

`batch_move_work_items`

Déplace plusieurs work items vers une colonne de destination en une seule opération. Définit facultativement les indicateurs de traitement par IA pour tous les éléments déplacés.

Paramètres :

Nom	Type	Obligatoire	Description
workItemIds	string[] (UUID)	Oui	Liste des IDs de work items à déplacer
boardColumnId	string (UUID)	Oui	ID de la colonne de destination
setAiProcessing	boolean	Non	Active `isAiProcessing=true` pour tous les éléments
aiProvider	string	Non	Fournisseur IA à enregistrer dans les métadonnées

Exemple :

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

Réponse :

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

`delete_work_item`

Supprime définitivement un work item par son ID.

Paramètres :

Nom	Type	Obligatoire	Description
id	string (UUID)	Oui	ID du work item à supprimer

Exemple :

{
  "id": "wi-001"
}

Réponse :

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

Prompts d'implémentation

`generate_work_item_prompt`

Génère un prompt d'implémentation enrichi avec le contexte du projet (stack technique, dépôts, tâches sœurs, flux du board). Le prompt est généré par IA et enregistré dans les métadonnées du work item.

Paramètres :

Nom	Type	Obligatoire	Description
id	string (UUID)	Oui	ID du work item

Exemple :

{
  "id": "wi-001"
}

Réponse :

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

Récupère le prompt d'implémentation généré précédemment et enregistré dans les métadonnées du work item.

Paramètres :

Nom	Type	Obligatoire	Description
id	string (UUID)	Oui	ID du work item

Exemple :

{
  "id": "wi-001"
}

Réponse :

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

Flux de review et de validation

`complete_review`

Termine la review de code d'un work item. Si la review est réussie, l'élément est déplacé vers Testing. En cas d'échec, il revient à In Progress. Les métadonnées de review sont enregistrées dans le work item.

Paramètres :

Nom	Type	Obligatoire	Description
workItemId	string (UUID)	Oui	ID du work item
result	string	Oui	Résultat : `pass` (déplace vers Testing) ou `fail` (déplace vers In Progress)
summary	string	Oui	Résumé de la review
issues	string[]	Non	Liste des problèmes détectés (pertinent lorsque `result=fail`)
reviewedFiles	string[]	Non	Liste des fichiers examinés

Exemple :

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

Termine de manière atomique la validation d'une tâche : déplace une validation approuvée vers sa colonne de destination, généralement To Document, efface les indicateurs IA, fusionne les métadonnées de documentation et les résultats de tests, puis enregistre la session IA. Si la colonne Validating est fournie par erreur, l'outil redirige vers To Document lorsque cette colonne existe dans le board.

Paramètres :

Nom	Type	Obligatoire	Description
workItemId	string (UUID)	Oui	ID du work item
toDocumentColumnId	string (UUID)	Non	ID de la colonne de destination pour une validation approuvée. De préférence, la colonne `To Document`
validatingColumnId	string (UUID)	Non	Alias historique de la destination. S'il pointe vers `Validating`, l'outil tentera de rediriger vers `To Document`
documentation	object	Non	Métadonnées de documentation (voir le sous-objet ci-dessous)
documentation.summary	string	Non	Résumé de ce qui a été validé
documentation.screenshots	string[]	Non	URL des captures d'écran jointes
documentation.mermaidDiagrams	string[]	Non	Diagrammes Mermaid sous forme de chaînes
documentation.changelogEntry	string	Non	Entrée de changelog
testResults	object	Non	Résultats de tests (voir le sous-objet ci-dessous)
testResults.passed	number	Non	Tests réussis
testResults.failed	number	Non	Tests échoués
testResults.testFiles	string[]	Non	Chemins des fichiers de test
model	string	Oui	Modèle IA utilisé (ex. : `claude-opus-4-6`)
provider	string	Non	Fournisseur IA (par défaut : `anthropic`)
totalTokens	number	Oui	Nombre total de tokens consommés
durationMs	number	Non	Durée de la session en millisecondes
taskId	string	Non	Task ID lisible (ex. : `A-T-37`)

Exemple :

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

Termine de manière atomique le travail de l'IA sur une tâche : déplace vers Review, efface les indicateurs IA, définit userActions et enregistre la session avec la consommation de tokens. Remplace la nécessité d'appeler séparément move_work_item + update_work_item + record_ai_session.

Paramètres :

Nom	Type	Obligatoire	Description
workItemId	string (UUID)	Oui	ID du work item
reviewColumnId	string (UUID)	Oui	ID de la colonne Review
userActions	string	Non	Liste Markdown des étapes manuelles que l'utilisateur doit vérifier
model	string	Oui	Modèle IA utilisé (ex. : `claude-opus-4-6`)
provider	string	Non	Fournisseur (par défaut : `openai`)
totalTokens	number	Oui	Nombre total de tokens consommés
durationMs	number	Non	Durée de la session en ms
sessionType	string	Non	Type de session (par défaut : `implement`)
taskId	string	Non	Task ID lisible (ex. : `A-T-37`)

Exemple :

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

Réponse :

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

Utilisation recommandée

Utilisez complete_ai_task à la fin de l'implémentation d'une tâche par IA. C'est la manière la plus efficace de clôturer le cycle de travail : un unique appel d'outil qui déplace, efface les indicateurs et enregistre les coûts.

Pièces jointes

`upload_work_item_attachment`

Téléverse une pièce jointe vers un work item depuis un chemin de fichier local. Conçu pour l'outillage IA (par exemple, joindre des captures d'écran Playwright).

Paramètres :

Nom	Type	Obligatoire	Description
workItemId	string (UUID)	Oui	ID du work item
filePath	string	Oui	Chemin absolu ou relatif au dépôt (autorisé : `/tmp/*` ou sous le répertoire de travail)
fileName	string	Non	Nom du fichier à stocker (par défaut : nom de base du chemin)
mimeType	string	Non	Type MIME (par défaut : déduit du nom)
uploadedBy	string	Non	Étiquette de l'auteur du téléversement
metadata	object	Non	Métadonnées de la pièce jointe (ex. : `{ kind: "review-screenshot", page: "/boards" }`)
deleteAfterUpload	boolean	Non	Supprime le fichier local après le téléversement (par défaut : `true`)

Exemple :

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

Contexte avancé

`get_implement_context`

Résout les identifiants en tâches feuilles en attente, classe par état de colonne, inclut le mappage des boards, les dépendances intra-lot et les vagues d'exécution précalculées.

Paramètres :

Nom	Type	Obligatoire	Description
ids	string[]	Oui	Liste des task IDs/UUID à implémenter
projectId	string (UUID)	Non	ID du projet (par défaut : session MCP)

Exemple :

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

`get_ideation_context`

Obtient le contexte d'idéation : work items associés par mots-clés, parents potentiels et configuration dynamique des boards.

Paramètres :

Nom	Type	Obligatoire	Description
keywords	string[]	Oui	Mots-clés de recherche
projectId	string (UUID)	Non	ID du projet (par défaut : session MCP)
limit	number	Non	Limite de résultats (par défaut : 20, max. : 50)

Exemple :

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

`get_review_context`

Obtient le contexte complet de review pour une tâche ou une feature : détails de l'élément, colonnes de routage, dépendances, éléments frères et enfants examinables.

Paramètres :

Nom	Type	Obligatoire	Description
taskId	string	Oui	Identifiant de la tâche (UUID ou taskId tel que `A-T-37`)
featureReview	boolean	Non	Lorsque `true`, inclut les enfants examinables pour la review d'une feature/epic

Exemple :

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

`get_validate_context`

Résout les identifiants en tâches feuilles, classe selon la colonne du board (examinable dans Review, testable dans Testing, ignoré dans les autres cas), inclut le mappage des boards avec une colonne Validating et les résumés des éléments parents.

Paramètres :

Nom	Type	Obligatoire	Description
ids	string[]	Oui	Liste des task IDs/UUID à valider
projectId	string (UUID)	Non	ID du projet (par défaut : session MCP)

Exemple :

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

Consultation​

list_work_items​

resolve_work_items​

get_work_item_events​

Création​

create_work_item​

create_task​

create_story​

create_feature​

create_epic​

Mise à jour et déplacement​

update_work_item​

move_work_item​

batch_move_work_items​

delete_work_item​

Prompts d'implémentation​

generate_work_item_prompt​

get_work_item_prompt​

Flux de review et de validation​

complete_review​

complete_validation​

complete_ai_task​

Pièces jointes​

upload_work_item_attachment​

Contexte avancé​

get_implement_context​

get_ideation_context​

get_review_context​

get_validate_context​

Consultation

`list_work_items`

`resolve_work_items`

`get_work_item_events`

Création

`create_work_item`

`create_task`

`create_story`

`create_feature`

`create_epic`

Mise à jour et déplacement

`update_work_item`

`move_work_item`

`batch_move_work_items`

`delete_work_item`

Prompts d'implémentation

`generate_work_item_prompt`

`get_work_item_prompt`

Flux de review et de validation

`complete_review`

`complete_validation`

`complete_ai_task`

Pièces jointes

`upload_work_item_attachment`

Contexte avancé

`get_implement_context`

`get_ideation_context`

`get_review_context`

`get_validate_context`