Tools - Work Items

Work Items sind die grundlegende Arbeitseinheit in Almirant. Sie können vom Typ task, story, feature, epic oder idea sein und werden in Spalten eines Boards organisiert. Dieser Abschnitt dokumentiert alle verfügbaren Tools zum Erstellen, Abfragen, Aktualisieren und Verwalten von Work Items über MCP.

Status eines Work Items

Work Items haben kein explizites Feld status. Ihr Status wird aus der Board-Spalte abgeleitet, in der sie sich befinden (zum Beispiel "Backlog", "In Progress", "Done").

Abfragen

`list_work_items`

Listet Work Items mit Paginierung und optionalen Filtern auf. Wenn in der MCP-Sitzung eine projectId konfiguriert ist, wird automatisch nach diesem Projekt gefiltert.

Parameter:

Name	Typ	Erforderlich	Beschreibung
page	number	Nein	Seitennummer (Standard: 1)
limit	number	Nein	Elemente pro Seite (Standard: 50, max.: 100)
search	string	Nein	Nach Titel oder Beschreibung suchen
projectId	string (UUID)	Nein	Nach Projekt filtern (verwendet die Sitzung als Fallback)
boardId	string (UUID)	Nein	Nach Board filtern
boardColumnId	string (UUID)	Nein	Nach Board-Spalte filtern
parentId	string (UUID)	Nein	Nach übergeordnetem Item filtern (Kinder eines Features/Epics)
type	string	Nein	Nach Typ filtern: `epic`, `feature`, `story`, `task`, `idea`
priority	string	Nein	Nach Priorität filtern: `low`, `medium`, `high`, `urgent`
assignee	string	Nein	Nach zugewiesener Person filtern

Beispiel:

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

Antwort:

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

Löst Work-Item-Identifikatoren (lesbare Task-IDs wie "A-T-37" oder UUIDs) in vollständige Objekte auf. Optional werden Nicht-Task-Items rekursiv in ihre Blattaufgaben aufgelöst.

Parameter:

Name	Typ	Erforderlich	Beschreibung
ids	string[]	Ja	Liste gemischter Identifikatoren (Task-IDs wie `A-T-37`, `A-F-12` oder UUIDs)
includeLeafTasks	boolean	Nein	Wenn `true` (Standard), werden Nicht-Task-Items rekursiv in Blattaufgaben aufgelöst
maxDepth	number	Nein	Maximale Rekursionstiefe (Standard: 3, max.: 10)

Beispiel:

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

Antwort:

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

Ruft den Ereignisverlauf (Changelog) eines Work Items ab. Enthalten sind Ereignisse zur Erstellung, Aktualisierung, Bewegung zwischen Spalten, KI-Sitzungen und Kommentare.

Parameter:

Name	Typ	Erforderlich	Beschreibung
workItemId	string (UUID)	Ja	ID des Work Items
eventType	string	Nein	Nach Typ filtern: `created`, `updated`, `moved`, `deleted`, `attachment_added`, `attachment_removed`, `ai_session`, `comment`
limit	number	Nein	Maximale Anzahl von Ereignissen (Standard: 50, max.: 200)

Beispiel:

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

Antwort:

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

Erstellung

`create_work_item`

Erstellt ein Work Item mit vollständiger Kontrolle über Board, Spalte, Typ und Projekt. boardId und boardColumnId müssen explizit angegeben werden.

Parameter:

Name	Typ	Erforderlich	Beschreibung
title	string	Ja	Titel des Work Items
description	string	Nein	Detaillierte Beschreibung
type	string	Ja	Typ: `epic`, `feature`, `story`, `task`, `idea`
priority	string	Nein	Priorität: `low`, `medium`, `high`, `urgent`
boardId	string (UUID)	Ja	Board, in dem das Item erstellt wird
boardColumnId	string (UUID)	Ja	Anfangsspalte
projectId	string (UUID)	Nein	Projekt (verwendet die MCP-Sitzung als Fallback)
assignee	string	Nein	Name oder Identifikator der zugewiesenen Person
parentId	string (UUID)	Nein	ID des übergeordneten Work Items
metadata	object	Nein	Beliebige Metadaten (z. B.: `{ definitionOfDone: "..." }`)

Beispiel:

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

Abkürzung zum Erstellen einer Aufgabe. Erzwingt type=task und wählt automatisch das Standard-Board des Projekts sowie die Spalte "Backlog". Erfordert eine in der MCP-Sitzung konfigurierte projectId.

Parameter:

Name	Typ	Erforderlich	Beschreibung
title	string	Ja	Titel der Aufgabe
description	string	Nein	Detaillierte Beschreibung
priority	string	Nein	Priorität: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Nein	ID des übergeordneten Work Items
metadata	object	Nein	Beliebige Metadaten

Beispiel:

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

`create_story`

Abkürzung zum Erstellen einer Story. Erzwingt type=story und wählt automatisch das Board und die Spalte "Backlog".

Parameter:

Name	Typ	Erforderlich	Beschreibung
title	string	Ja	Titel der Story
description	string	Nein	Detaillierte Beschreibung
priority	string	Nein	Priorität: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Nein	ID des übergeordneten Features
metadata	object	Nein	Beliebige Metadaten

Beispiel:

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

`create_feature`

Abkürzung zum Erstellen eines Features. Erzwingt type=feature und wählt automatisch das Board und die Spalte "Backlog".

Parameter:

Name	Typ	Erforderlich	Beschreibung
title	string	Ja	Titel des Features
description	string	Nein	Detaillierte Beschreibung
priority	string	Nein	Priorität: `low`, `medium`, `high`, `urgent`
parentId	string (UUID)	Nein	ID des übergeordneten Epics
metadata	object	Nein	Beliebige Metadaten

Beispiel:

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

`create_epic`

Abkürzung zum Erstellen eines Epics. Erzwingt type=epic und wählt automatisch das Board und die Spalte "Backlog".

Parameter:

Name	Typ	Erforderlich	Beschreibung
title	string	Ja	Titel des Epics
description	string	Nein	Detaillierte Beschreibung
priority	string	Nein	Priorität: `low`, `medium`, `high`, `urgent`
metadata	object	Nein	Beliebige Metadaten

Beispiel:

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

Aktualisierung und Verschiebung

`update_work_item`

Aktualisiert die Felder eines vorhandenen Work Items. Nur die bereitgestellten Felder werden geändert. Die Metadaten werden mit den vorhandenen zusammengeführt (sie werden nicht überschrieben).

Parameter:

Name	Typ	Erforderlich	Beschreibung
id	string (UUID)	Ja	ID des Work Items
title	string	Nein	Neuer Titel
description	string	Nein	Neue Beschreibung
type	string	Nein	Neuer Typ: `epic`, `feature`, `story`, `task`, `idea`
priority	string	Nein	Neue Priorität: `low`, `medium`, `high`, `urgent`
assignee	string	Nein	Neue zugewiesene Person
boardColumnId	string (UUID)	Nein	In eine andere Spalte verschieben
parentId	string (UUID) oder null	Nein	Neues übergeordnetes Element (`null` zum Aufheben der Zuordnung)
metadata	object	Nein	Mit den vorhandenen zusammenzuführende Metadaten

Beispiel:

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

`move_work_item`

Verschiebt ein Work Item in eine andere Board-Spalte. Verwaltet die Flags für die KI-Verarbeitung entsprechend der Zielspalte automatisch.

Parameter:

Name	Typ	Erforderlich	Beschreibung
workItemId	string (UUID)	Ja	ID des zu verschiebenden Work Items
boardColumnId	string (UUID)	Ja	ID der Zielspalte
isAutoSync	boolean	Nein	`true`, wenn die Verschiebung durch eine kaskadierende Synchronisierung erfolgt (Standard: `false`)
setAiProcessing	boolean	Nein	Erzwingt `isAiProcessing=true` unabhängig von der Zielspalte
aiProvider	string	Nein	KI-Anbieter (`openai`, `anthropic`). In Verbindung mit `setAiProcessing` werden Anbieter-Metadaten gesetzt

Beispiel:

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

Automatisches Verhalten der KI-Flags

Bei einer Verschiebung nach In Progress: isAiProcessing=true wird automatisch aktiviert
Bei einer Verschiebung nach Review oder Done: isAiProcessing=false wird automatisch deaktiviert
Mit setAiProcessing=true: Das Flag wird unabhängig von der Spalte erzwungen

`batch_move_work_items`

Verschiebt mehrere Work Items in einem einzelnen Vorgang in eine Zielspalte. Optional werden für alle verschobenen Items Flags für die KI-Verarbeitung gesetzt.

Parameter:

Name	Typ	Erforderlich	Beschreibung
workItemIds	string[] (UUID)	Ja	Liste der IDs der zu verschiebenden Work Items
boardColumnId	string (UUID)	Ja	ID der Zielspalte
setAiProcessing	boolean	Nein	`isAiProcessing=true` für alle Items aktivieren
aiProvider	string	Nein	In den Metadaten zu registrierender KI-Anbieter

Beispiel:

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

Antwort:

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

`delete_work_item`

Löscht ein Work Item anhand seiner ID dauerhaft.

Parameter:

Name	Typ	Erforderlich	Beschreibung
id	string (UUID)	Ja	ID des zu löschenden Work Items

Beispiel:

{
  "id": "wi-001"
}

Antwort:

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

Implementierungs-Prompts

`generate_work_item_prompt`

Generiert einen Implementierungs-Prompt, der mit dem Projektkontext (Tech-Stack, Repositories, verwandten Aufgaben, Board-Ablauf) angereichert ist. Der Prompt wird durch KI generiert und in den Metadaten des Work Items gespeichert.

Parameter:

Name	Typ	Erforderlich	Beschreibung
id	string (UUID)	Ja	ID des Work Items

Beispiel:

{
  "id": "wi-001"
}

Antwort:

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

Ruft den zuvor generierten und in den Metadaten des Work Items gespeicherten Implementierungs-Prompt ab.

Parameter:

Name	Typ	Erforderlich	Beschreibung
id	string (UUID)	Ja	ID des Work Items

Beispiel:

{
  "id": "wi-001"
}

Antwort:

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

Review- und Validierungsablauf

`complete_review`

Schließt den Code-Review eines Work Items ab. Wenn der Review erfolgreich ist, wird das Item nach Testing verschoben. Bei einem Fehler kehrt es zu In Progress zurück. Die Review-Metadaten werden im Work Item gespeichert.

Parameter:

Name	Typ	Erforderlich	Beschreibung
workItemId	string (UUID)	Ja	ID des Work Items
result	string	Ja	Ergebnis: `pass` (verschiebt nach Testing) oder `fail` (verschiebt nach In Progress)
summary	string	Ja	Zusammenfassung des Reviews
issues	string[]	Nein	Liste der gefundenen Probleme (relevant bei `result=fail`)
reviewedFiles	string[]	Nein	Liste der überprüften Dateien

Beispiel:

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

Schließt die Validierung einer Aufgabe atomar ab: Eine erfolgreiche Validierung wird in ihre Zielspalte verschoben, normalerweise To Document; KI-Flags werden bereinigt, Dokumentationsmetadaten und Testergebnisse zusammengeführt und die KI-Sitzung wird aufgezeichnet. Wenn die Spalte Validating versehentlich übergeben wird, leitet das Tool zu To Document weiter, sofern diese Spalte im Board vorhanden ist.

Parameter:

Name	Typ	Erforderlich	Beschreibung
workItemId	string (UUID)	Ja	ID des Work Items
toDocumentColumnId	string (UUID)	Nein	ID der Zielspalte für eine erfolgreiche Validierung. Vorzugsweise die Spalte `To Document`
validatingColumnId	string (UUID)	Nein	Legacy-Alias für das Ziel. Wenn er auf `Validating` zeigt, versucht das Tool zu `To Document` weiterzuleiten
documentation	object	Nein	Dokumentationsmetadaten (siehe Unterobjekt unten)
documentation.summary	string	Nein	Zusammenfassung der Validierung
documentation.screenshots	string[]	Nein	URLs angehängter Screenshots
documentation.mermaidDiagrams	string[]	Nein	Mermaid-Diagramme als Strings
documentation.changelogEntry	string	Nein	Changelog-Eintrag
testResults	object	Nein	Testergebnisse (siehe Unterobjekt unten)
testResults.passed	number	Nein	Bestandene Tests
testResults.failed	number	Nein	Fehlgeschlagene Tests
testResults.testFiles	string[]	Nein	Pfade zu Testdateien
model	string	Ja	Verwendetes KI-Modell (z. B.: `claude-opus-4-6`)
provider	string	Nein	KI-Anbieter (Standard: `anthropic`)
totalTokens	number	Ja	Gesamtzahl verbrauchter Tokens
durationMs	number	Nein	Dauer der Sitzung in Millisekunden
taskId	string	Nein	Lesbare Task-ID (z. B.: `A-T-37`)

Beispiel:

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

Schließt die KI-Arbeit an einer Aufgabe atomar ab: Sie wird nach Review verschoben, KI-Flags werden bereinigt, userActions wird gesetzt und die Sitzung einschließlich Tokenverbrauch aufgezeichnet. Ersetzt die Notwendigkeit, move_work_item + update_work_item + record_ai_session separat aufzurufen.

Parameter:

Name	Typ	Erforderlich	Beschreibung
workItemId	string (UUID)	Ja	ID des Work Items
reviewColumnId	string (UUID)	Ja	ID der Spalte Review
userActions	string	Nein	Markdown-Liste manueller Schritte, die der Benutzer prüfen muss
model	string	Ja	Verwendetes KI-Modell (z. B.: `claude-opus-4-6`)
provider	string	Nein	Anbieter (Standard: `openai`)
totalTokens	number	Ja	Gesamtzahl verbrauchter Tokens
durationMs	number	Nein	Dauer der Sitzung in ms
sessionType	string	Nein	Sitzungstyp (Standard: `implement`)
taskId	string	Nein	Lesbare Task-ID (z. B.: `A-T-37`)

Beispiel:

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

Antwort:

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

Empfohlene Verwendung

Verwende complete_ai_task, wenn die KI-Implementierung einer Aufgabe abgeschlossen ist. Dies ist die effizienteste Methode, den Arbeitszyklus zu schließen: ein einzelner Tool-Aufruf, der verschiebt, Flags bereinigt und Kosten erfasst.

Anhänge

`upload_work_item_attachment`

Lädt einen Anhang aus einem lokalen Dateipfad in ein Work Item hoch. Entwickelt für KI-Tooling (zum Beispiel zum Anhängen von Playwright-Screenshots).

Parameter:

Name	Typ	Erforderlich	Beschreibung
workItemId	string (UUID)	Ja	ID des Work Items
filePath	string	Ja	Absoluter oder zum Repository relativer Pfad (zulässig: `/tmp/*` oder unter dem Arbeitsverzeichnis)
fileName	string	Nein	Zu speichernder Dateiname (Standard: Basename des Pfads)
mimeType	string	Nein	MIME-Typ (Standard: aus dem Namen abgeleitet)
uploadedBy	string	Nein	Kennzeichnung des Uploaders
metadata	object	Nein	Metadaten des Anhangs (z. B.: `{ kind: "review-screenshot", page: "/boards" }`)
deleteAfterUpload	boolean	Nein	Lokale Datei nach dem Upload löschen (Standard: `true`)

Beispiel:

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

Erweiterter Kontext

`get_implement_context`

Löst Identifikatoren in ausstehenden Blattaufgaben auf, klassifiziert sie nach Spaltenstatus, enthält das Mapping von Boards, Abhängigkeiten innerhalb des Batches und vorab berechnete Ausführungswellen.

Parameter:

Name	Typ	Erforderlich	Beschreibung
ids	string[]	Ja	Liste zu implementierender Task-IDs/UUIDs
projectId	string (UUID)	Nein	ID des Projekts (Standard: MCP-Sitzung)

Beispiel:

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

`get_ideation_context`

Ruft den Ideation-Kontext ab: verwandte Work Items anhand von Schlüsselwörtern, potenzielle übergeordnete Elemente und dynamische Board-Konfiguration.

Parameter:

Name	Typ	Erforderlich	Beschreibung
keywords	string[]	Ja	Suchbegriffe
projectId	string (UUID)	Nein	ID des Projekts (Standard: MCP-Sitzung)
limit	number	Nein	Begrenzung der Ergebnisse (Standard: 20, max.: 50)

Beispiel:

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

`get_review_context`

Ruft den vollständigen Review-Kontext für eine Aufgabe oder ein Feature ab: Item-Details, Routing-Spalten, Abhängigkeiten, verwandte Items und überprüfbare Kinder.

Parameter:

Name	Typ	Erforderlich	Beschreibung
taskId	string	Ja	Identifikator der Aufgabe (UUID oder Task-ID wie `A-T-37`)
featureReview	boolean	Nein	Wenn `true`, werden überprüfbare Kinder für den Review eines Features/Epics einbezogen

Beispiel:

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

`get_validate_context`

Löst Identifikatoren in Blattaufgaben auf, klassifiziert sie nach Board-Spalte (in Review überprüfbar, in Testing testbar, andernfalls übersprungen), enthält das Mapping von Boards mit der Spalte Validating sowie Zusammenfassungen übergeordneter Items.

Parameter:

Name	Typ	Erforderlich	Beschreibung
ids	string[]	Ja	Liste zu validierender Task-IDs/UUIDs
projectId	string (UUID)	Nein	ID des Projekts (Standard: MCP-Sitzung)

Beispiel:

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

Abfragen​

list_work_items​

resolve_work_items​

get_work_item_events​

Erstellung​

create_work_item​

create_task​

create_story​

create_feature​

create_epic​

Aktualisierung und Verschiebung​

update_work_item​

move_work_item​

batch_move_work_items​

delete_work_item​

Implementierungs-Prompts​

generate_work_item_prompt​

get_work_item_prompt​

Review- und Validierungsablauf​

complete_review​

complete_validation​

complete_ai_task​

Anhänge​

upload_work_item_attachment​

Erweiterter Kontext​

get_implement_context​

get_ideation_context​

get_review_context​

get_validate_context​

Abfragen

`list_work_items`

`resolve_work_items`

`get_work_item_events`

Erstellung

`create_work_item`

`create_task`

`create_story`

`create_feature`

`create_epic`

Aktualisierung und Verschiebung

`update_work_item`

`move_work_item`

`batch_move_work_items`

`delete_work_item`

Implementierungs-Prompts

`generate_work_item_prompt`

`get_work_item_prompt`

Review- und Validierungsablauf

`complete_review`

`complete_validation`

`complete_ai_task`

Anhänge

`upload_work_item_attachment`

Erweiterter Kontext

`get_implement_context`

`get_ideation_context`

`get_review_context`

`get_validate_context`