Work Items

Un agent ne peut pas exécuter « améliore l'application ». Il a besoin d'un travail précis, délimité, avec des critères d'acceptation clairs. Les work items transforment une intention en spécifications exécutables. Sans cette structure, les agents improvisent. Avec elle, ils savent exactement quoi faire et quand le travail est terminé.

Les work items sont l'unité fondamentale de travail dans Almirant. Ils représentent toute partie du travail qui doit être planifiée, exécutée et achevée : depuis un epic de haut niveau jusqu'à une tâche technique concrète.

Types et hiérarchie

Almirant organise le travail dans une hiérarchie à quatre niveaux :

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

Type	Niveau	Objectif	Exemple
Epic	1	Objectif stratégique de haut niveau	« Système d'authentification complet »
Feature	2	Fonctionnalité concrète au sein d'un epic	« Connexion avec Google OAuth »
Story	3	Exigence depuis le point de vue de l'utilisateur	« En tant qu'utilisateur, je veux me connecter avec mon compte Google »
Task	4	Unité de travail technique exécutable	« Implémenter le callback OAuth dans le backend »

Quand utiliser chaque type

• Epic : lorsque l'objectif couvre plusieurs features et nécessite plusieurs semaines ou sprints. Les epics constituent le niveau de planification le plus élevé.
• Feature : lorsque vous décrivez une fonctionnalité complète que l'utilisateur peut percevoir. Une feature peut avoir plusieurs stories.
• Story : lorsque vous décrivez une exigence concrète du point de vue de l'utilisateur. Les stories sont généralement achevées pendant un sprint.
• Task : lorsque vous décrivez une action technique précise et limitée. Les tasks sont le niveau directement implémenté par l'IA.

Relation parent-enfant

Chaque work item peut avoir un parentId qui établit la relation hiérarchique. La vue du board permet de regrouper les items par leur parent, ce qui facilite la visualisation de la progression au niveau d'une feature ou d'un epic.

Champs

Champ	Type	Description	Obligatoire
title	string	Titre descriptif du work item	Oui
description	string	Description détaillée, accepte Markdown	Non
type	enum	Type : epic, feature, story, task	Oui
priority	enum	Priorité : urgent, high, medium, low, none	Non
boardColumnId	uuid	Colonne du board où se trouve l'item	Oui
parentId	uuid	Work item parent, pour la hiérarchie	Non
taskId	string	Identifiant lisible généré automatiquement (e.g., A-T-37, MC-S-1)	Automatique
dueDate	date	Date limite de livraison	Non
estimatedHours	number	Heures de travail estimées	Non
tags	array	Étiquettes pour catégoriser l'item	Non
metadata	object	Métadonnées enrichies (contexte IA, notes techniques)	Non
archived_at	timestamp	Date d'archivage, si l'item est archivé	Non

Identifiant lisible (taskId)

Chaque work item reçoit automatiquement un identifiant unique et lisible basé sur le projet et le type. Exemples :

• A-T-37 -- Task numéro 37 du projet A.
• MC-S-1 -- Story numéro 1 du projet MC.
• A-E-3 -- Epic numéro 3 du projet A.

Cet identifiant est utilisé dans toute l'interface et dans les tools MCP pour référencer les items sans UUID.

Assignations

Un work item peut avoir plusieurs personnes assignées, chacune avec un rôle précis :

Rôle	Description
responsible	Personne chargée d'achever l'item
collaborator	Personne qui contribue au travail
reviewer	Personne chargée de vérifier le résultat

Un même item peut avoir simultanément une personne responsable, plusieurs collaborateurs et un ou plusieurs reviewers.

État : dérivé de la colonne

Concept clé

Les work items N'ONT PAS de champ status. Leur état est directement dérivé de la colonne du board dans laquelle ils se trouvent :

• Si la colonne a le rôle sémantique in_progress, l'item est « en cours ».
• Si la colonne a isDone = true, l'item est « terminé ».
• Si la colonne a isDefault = true, c'est là que les nouveaux items arrivent.

Déplacer un item entre des colonnes modifie implicitement son état.

Opérations

Créer un work item

Il existe plusieurs façons de créer des work items :

1. Depuis le board -- Cliquez sur le bouton « + » de n'importe quelle colonne. L'item est créé directement dans cette colonne.
2. Depuis la vue de liste -- Utilisez le bouton « New item » et sélectionnez le type, le board et la colonne.
3. Via MCP -- Utilisez les tools create_work_item, create_task, create_story, create_feature ou create_epic.

Modifier un work item

• Édition inline -- Cliquez sur le titre d'un item dans le board pour le modifier directement.
• Fenêtre de détail -- Cliquez sur la carte pour ouvrir le détail complet où vous pouvez modifier tous les champs.
• Description avec Markdown -- Le champ de description accepte Markdown complet et peut être mis en forme avec l'aide de l'IA.

Déplacer entre les colonnes

• Drag and drop -- Faites glisser la carte d'une colonne à l'autre dans la vue Kanban.
• Via MCP -- Utilisez le tool move_work_item ou batch_move_work_items pour déplacer un ou plusieurs items par programmation.

Lorsqu'un item est déplacé vers une colonne avec isDone = true, il est considéré comme terminé.

Assigner et désassigner

Depuis la fenêtre de détail, ajoutez ou retirez des personnes assignées en sélectionnant l'utilisateur et son rôle (responsible, collaborator, reviewer).

Pièces jointes (attachments)

Les work items acceptent les fichiers joints stockés dans S3. Vous pouvez téléverser des images, documents, captures d'écran ou tout fichier pertinent depuis la fenêtre de détail.

Archiver

Les work items sont archivés au lieu d'être supprimés. L'archivage définit un timestamp dans archived_at. Les items archivés ne s'affichent plus dans les vues principales, mais sont conservés à des fins de référence historique.

Pour archiver un item :

1. Ouvrez le détail du work item.
2. Sélectionnez Archive.
3. L'item disparaît du board, mais reste consultable dans la vue des archives.

Vue de détail

La vue de détail d'un work item comprend :

• Tous les champs modifiables (titre, description, type, priorité, personnes assignées, dates).
• Historique des événements -- Journal de toutes les modifications apportées à l'item.
• Sessions IA -- Historique des interactions de l'IA avec l'item, y compris le coût de chaque session.
• Documents liés -- Liens vers les documents associés.
• Dépendances -- Dépendances avec d'autres work items.
• Pièces jointes -- Fichiers téléversés pour l'item.
• Commentaires et notes.

Opérations en lot (bulk)

Depuis la vue de liste, vous pouvez sélectionner plusieurs items et exécuter des actions en lot :

• Les déplacer vers une autre colonne.
• Modifier la priorité.
• Les assigner à un utilisateur.
• Les archiver.

Vues enregistrées et filtres

Les filtres de la vue des work items sont conservés dans l'URL, ce qui permet de partager des liens avec les filtres appliqués. Vous pouvez filtrer par :

• Type (epic, feature, story, task).
• Priorité.
• Personne assignée.
• Tags.
• Colonne.

Vous pouvez aussi regrouper les items par leur parent afin de visualiser la hiérarchie dans la vue de liste.

Fonctionnalités IA

Les work items intègrent directement des fonctionnalités IA :

• Mise en forme de texte par IA -- L'IA peut mettre en forme et améliorer la description de l'item.
• Dictée vocale -- Dictez la description ou les commentaires et l'IA les transcrit.
• Copy as prompt -- Copiez le contexte de l'item comme prompt pour l'utiliser dans votre IDE.
• Sessions IA avec suivi des coûts -- Chaque interaction IA avec un item est enregistrée avec son coût associé.

Pour les développeurs

Pour les développeurs

Outils MCP

Création

Tool	Description	Paramètres principaux
create_work_item	Crée un work item de n'importe quel type	title, type, boardId, columnId, description, priority, parentId
create_task	Raccourci pour créer une task	title, boardId, description, priority, parentId
create_story	Raccourci pour créer une story	title, boardId, description, priority, parentId
create_feature	Raccourci pour créer une feature	title, boardId, description, priority, parentId
create_epic	Raccourci pour créer un epic	title, boardId, description, priority

Consultation

Tool	Description	Paramètres principaux
list_work_items	Liste les work items avec des filtres	boardId, type, priority, assigneeId, parentId, columnId

Mise à jour

Tool	Description	Paramètres principaux
update_work_item	Met à jour les champs d'un work item	workItemId, champs à mettre à jour
move_work_item	Déplace un item vers une autre colonne	workItemId, columnId
batch_move_work_items	Déplace plusieurs items vers une colonne	workItemIds, columnId
resolve_work_items	Marque les items comme résolus, en les déplaçant vers la colonne done	workItemIds
complete_ai_task	Termine une tâche IA et la déplace vers done	workItemId, summary

Exemple : créer une task via MCP

Tool: create_task
Paramètres :
  title: "Implémenter l'endpoint d'authentification"
  boardId: "uuid-del-board"
  description: "Créer l'endpoint POST /api/auth/login avec validation JWT"
  priority: "high"
  parentId: "uuid-de-la-story-padre"

Exemple : déplacer des items en lot

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

Exemple : lister les items filtrés d'un board

Tool: list_work_items
Paramètres :
  boardId: "uuid-del-board"
  type: "task"
  priority: "high"