Work Items

Ein Agent kann nicht "Verbessere die App" ausführen. Er braucht konkrete, abgegrenzte Arbeit mit klaren Akzeptanzkriterien. Mit Work Items verwandelst du Absichten in ausführbare Spezifikationen. Ohne diese Struktur improvisieren Agenten. Mit ihr wissen sie genau, was zu tun ist und wann es erledigt ist.

Work Items sind die grundlegende Arbeitseinheit in Almirant. Sie bilden jede Arbeit ab, die geplant, ausgeführt und abgeschlossen werden muss: vom übergeordneten Epic bis zu einer konkreten technischen Aufgabe.

Typen und Hierarchie

Almirant organisiert Arbeit in einer Hierarchie mit vier Ebenen:

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

Typ	Ebene	Zweck	Beispiel
Epic	1	Übergeordnetes strategisches Ziel	"Vollständiges Authentifizierungssystem"
Feature	2	Konkrete Funktionalität innerhalb eines Epics	"Login mit Google OAuth"
Story	3	Anforderung aus Benutzersicht	"Als Benutzer möchte ich mich mit meinem Google-Konto anmelden"
Task	4	Ausführbare technische Arbeitseinheit	"OAuth-Callback im Backend implementieren"

Wann jeder Typ verwendet wird

• Epic: Wenn das Ziel mehrere Features umfasst und mehrere Wochen oder Sprints benötigt. Epics sind die höchste Planungsebene.
• Feature: Wenn du eine vollständige, für den Benutzer wahrnehmbare Funktionalität beschreibst. Ein Feature kann mehrere Stories haben.
• Story: Wenn du eine konkrete Anforderung aus Benutzersicht beschreibst. Stories werden typischerweise in einem Sprint abgeschlossen.
• Task: Wenn du eine spezifische und abgegrenzte technische Aktion beschreibst. Tasks sind die Ebene, die die KI direkt implementiert.

Eltern-Kind-Beziehung

Jedes Work Item kann eine parentId haben, die die hierarchische Beziehung festlegt. Die Board-Ansicht kann Items nach ihrem Eltern-Item gruppieren und erleichtert so die Darstellung des Fortschritts auf Feature- oder Epic-Ebene.

Felder

Feld	Typ	Beschreibung	Erforderlich
title	string	Aussagekräftiger Titel des Work Items	Ja
description	string	Detaillierte Beschreibung, akzeptiert Markdown	Nein
type	enum	Typ: epic, feature, story, task	Ja
priority	enum	Priorität: urgent, high, medium, low, none	Nein
boardColumnId	uuid	Board-Spalte, in der sich das Item befindet	Ja
parentId	uuid	Übergeordnetes Work Item (für Hierarchie)	Nein
taskId	string	Automatisch erzeugte lesbare Kennung (e.g., A-T-37, MC-S-1)	Automatisch
dueDate	date	Lieferfrist	Nein
estimatedHours	number	Geschätzte Arbeitsstunden	Nein
tags	array	Tags zur Kategorisierung des Items	Nein
metadata	object	Angereicherte Metadaten (KI-Kontext, technische Notizen)	Nein
archived_at	timestamp	Archivierungsdatum (falls archiviert)	Nein

Lesbare Kennung (taskId)

Jedes Work Item erhält automatisch eine eindeutige, lesbare Kennung auf Basis des Projekts und des Typs. Beispiele:

• A-T-37 -- Task Nummer 37 des Projekts A.
• MC-S-1 -- Story Nummer 1 des Projekts MC.
• A-E-3 -- Epic Nummer 3 des Projekts A.

Diese Kennung wird in der gesamten Oberfläche und in MCP-Tools verwendet, um auf Items ohne UUIDs zu verweisen.

Zuweisungen

Ein Work Item kann mehrere Zugewiesene haben, jeweils mit einer bestimmten Rolle:

Rolle	Beschreibung
responsible	Person, die für das Abschließen des Items verantwortlich ist
collaborator	Person, die zur Arbeit beiträgt
reviewer	Person, die das Ergebnis prüft

Dasselbe Item kann gleichzeitig eine verantwortliche Person, mehrere Mitwirkende und einen oder mehrere Reviewer haben.

Status: aus der Spalte abgeleitet

Schlüsselkonzept

Work Items haben KEIN Feld status. Der Status wird direkt aus der Board-Spalte abgeleitet, in der sich das Item befindet:

• Hat die Spalte die semantische Rolle in_progress, ist das Item "in Bearbeitung".
• Hat die Spalte isDone = true, ist das Item "abgeschlossen".
• Hat die Spalte isDefault = true, landen neue Items dort.

Das Verschieben eines Items zwischen Spalten ändert implizit seinen Status.

Operationen

Work Item erstellen

Es gibt mehrere Möglichkeiten, Work Items zu erstellen:

1. Über das Board -- Klicke auf die Schaltfläche "+" einer beliebigen Spalte. Das Item wird direkt in dieser Spalte erstellt.
2. Über die Listenansicht -- Verwende die Schaltfläche "Neues Item" und wähle Typ, Board und Spalte.
3. Über MCP -- Verwende die Tools create_work_item, create_task, create_story, create_feature oder create_epic.

Work Item bearbeiten

• Inline-Bearbeitung -- Klicke im Board auf den Titel eines Items, um ihn direkt zu bearbeiten.
• Detailmodal -- Klicke auf die Karte, um die vollständige Detailansicht zu öffnen, in der du alle Felder bearbeiten kannst.
• Beschreibung mit Markdown -- Das Beschreibungsfeld unterstützt vollständiges Markdown und kann mit Hilfe der KI formatiert werden.

Zwischen Spalten verschieben

• Drag and Drop -- Ziehe die Karte in der Kanban-Ansicht von einer Spalte in eine andere.
• Über MCP -- Verwende move_work_item oder batch_move_work_items, um ein oder mehrere Items programmatisch zu verschieben.

Wenn du ein Item in eine Spalte mit isDone = true verschiebst, gilt es als abgeschlossen.

Zuweisen und Zuweisung entfernen

Füge in der Detailansicht Zugewiesene hinzu oder entferne sie, indem du Benutzer und Rolle auswählst (responsible, collaborator, reviewer).

Anhänge (attachments)

Work Items unterstützen in S3 gespeicherte Anhänge. Du kannst Bilder, Dokumente, Screenshots oder andere relevante Dateien aus dem Detailmodal hochladen.

Archivieren

Work Items werden nicht gelöscht, sondern archiviert. Die Archivierung setzt einen Zeitstempel in archived_at. Archivierte Items erscheinen nicht mehr in den Hauptansichten, bleiben aber für historische Referenz erhalten.

So archivierst du ein Item:

1. Öffne die Detailansicht des Work Items.
2. Wähle Archivieren.
3. Das Item verschwindet vom Board, kann aber in der Archivansicht eingesehen werden.

Detailansicht

Die Detailansicht eines Work Items enthält:

• Alle editierbaren Felder (Titel, Beschreibung, Typ, Priorität, Zugewiesene, Daten).
• Ereignisverlauf -- Protokoll aller am Item vorgenommenen Änderungen.
• KI-Sitzungen -- Verlauf der KI-Interaktionen mit dem Item, einschließlich der Kosten jeder Sitzung.
• Verknüpfte Dokumente -- Links zu zugehörigen Dokumenten.
• Abhängigkeiten -- Abhängigkeiten mit anderen Work Items.
• Anhänge -- Zum Item hochgeladene Dateien.
• Kommentare und Notizen.

Stapeloperationen (bulk)

In der Listenansicht kannst du mehrere Items auswählen und Stapelaktionen ausführen:

• In eine andere Spalte verschieben.
• Priorität ändern.
• Einem Benutzer zuweisen.
• Archivieren.

Gespeicherte Ansichten und Filter

Die Filter der Work-Item-Ansicht werden in der URL gespeichert, sodass Links mit angewendeten Filtern geteilt werden können. Du kannst filtern nach:

• Typ (epic, feature, story, task).
• Priorität.
• Zugewiesener Person.
• Tags.
• Spalte.

Du kannst Items auch nach ihrem Eltern-Item gruppieren, um die Hierarchie in der Listenansicht darzustellen.

KI-Funktionen

Work Items integrieren KI-Funktionen direkt:

• KI-Textformatierung -- Die KI kann die Beschreibung eines Items formatieren und verbessern.
• Sprachdiktat -- Diktiere die Beschreibung oder Kommentare, die die KI transkribiert.
• Copy as prompt -- Kopiert den Item-Kontext als Prompt zur Verwendung in deiner IDE.
• KI-Sitzungen mit Kosten-Tracking -- Jede KI-Interaktion mit einem Item wird mit den zugehörigen Kosten protokolliert.

Für Entwickler

Für Entwickler

MCP-Tools

Erstellung

Tool	Beschreibung	Wichtigste Parameter
create_work_item	Erstellt ein Work Item beliebigen Typs	title, type, boardId, columnId, description, priority, parentId
create_task	Abkürzung zum Erstellen eines Tasks	title, boardId, description, priority, parentId
create_story	Abkürzung zum Erstellen einer Story	title, boardId, description, priority, parentId
create_feature	Abkürzung zum Erstellen eines Features	title, boardId, description, priority, parentId
create_epic	Abkürzung zum Erstellen eines Epics	title, boardId, description, priority

Abfrage

Tool	Beschreibung	Wichtigste Parameter
list_work_items	Listet Work Items mit Filtern auf	boardId, type, priority, assigneeId, parentId, columnId

Aktualisierung

Tool	Beschreibung	Wichtigste Parameter
update_work_item	Aktualisiert Felder eines Work Items	workItemId, zu aktualisierende Felder
move_work_item	Verschiebt ein Item in eine andere Spalte	workItemId, columnId
batch_move_work_items	Verschiebt mehrere Items in eine Spalte	workItemIds, columnId
resolve_work_items	Markiert Items als gelöst (verschiebt sie in die Done-Spalte)	workItemIds
complete_ai_task	Schließt eine KI-Aufgabe ab und verschiebt sie nach Done	workItemId, summary

Beispiel: Task über MCP erstellen

Tool: create_task
Parameter:
  title: "Authentifizierungsendpunkt implementieren"
  boardId: "uuid-del-board"
  description: "Den POST-Endpunkt /api/auth/login mit JWT-Validierung erstellen"
  priority: "high"
  parentId: "uuid-de-la-story-padre"

Beispiel: Items stapelweise verschieben

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

Beispiel: Gefilterte Items eines Boards auflisten

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