Tools - Work Items

Work items are the fundamental unit of work in Almirant. They can be of type task, story, feature, epic, or idea, and are organized in board columns. This section documents all available tools for creating, querying, updating, and managing work items via MCP.

Work item status

Work items do not have an explicit status field. Their status is derived from the board column they are in (for example, "Backlog", "In Progress", "Done").

---

Query

list_work_items

Lists work items with pagination and optional filters. If a projectId is configured in the MCP session, it automatically filters by that project.

Parameters:

Name	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 50, max: 100)
search	string	No	Search by title or description
projectId	string (UUID)	No	Filter by project (uses session value as fallback)
boardId	string (UUID)	No	Filter by board
boardColumnId	string (UUID)	No	Filter by board column
parentId	string (UUID)	No	Filter by parent item (children of a feature/epic)
type	string	No	Filter by type: epic, feature, story, task, idea
priority	string	No	Filter by priority: low, medium, high, urgent
assignee	string	No	Filter by assignee

Example:

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

Response:

{
  "workItems": [
    {
      "id": "wi-001",
      "taskId": "A-T-37",
      "title": "Implement OAuth authentication",
      "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

Resolves work item identifiers (human-readable task IDs like "A-T-37" or UUIDs) into full objects. Optionally expands non-task items into their leaf tasks recursively.

Parameters:

Name	Type	Required	Description
ids	string[]	Yes	List of mixed identifiers (task IDs like A-T-37, A-F-12, or UUIDs)
includeLeafTasks	boolean	No	When true (default), recursively resolves non-task items to leaf tasks
maxDepth	number	No	Maximum recursion depth (default: 3, max: 10)

Example:

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

Response:

{
  "inputIds": ["A-T-37", "A-F-12", "550e8400-..."],
  "notFound": [],
  "items": [
    {
      "id": "wi-001",
      "taskId": "A-T-37",
      "title": "Implement login",
      "type": "task",
      "resolvedFrom": ["A-T-37"]
    },
    {
      "id": "wi-003",
      "taskId": "A-T-40",
      "title": "Validate tokens",
      "type": "task",
      "resolvedFrom": ["A-F-12"]
    }
  ]
}

---

get_work_item_events

Gets the event history (changelog) of a work item. Includes creation, update, column movement, AI session, and comment events.

Parameters:

Name	Type	Required	Description
workItemId	string (UUID)	Yes	ID of the work item
eventType	string	No	Filter by type: created, updated, moved, deleted, attachment_added, attachment_removed, ai_session, comment
limit	number	No	Maximum number of events (default: 50, max: 200)

Example:

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

Response:

{
  "workItemId": "wi-001",
  "taskId": "A-T-37",
  "title": "Implement login",
  "totalEvents": 3,
  "events": [
    {
      "eventType": "moved",
      "data": {
        "fromColumn": "To Do",
        "toColumn": "In Progress"
      },
      "createdAt": "2025-02-01T10:30:00.000Z"
    }
  ]
}

---

Creation

create_work_item

Creates a work item with full control over board, column, type, and project. Requires specifying boardId and boardColumnId explicitly.

Parameters:

Name	Type	Required	Description
title	string	Yes	Work item title
description	string	No	Detailed description
type	string	Yes	Type: epic, feature, story, task, idea
priority	string	No	Priority: low, medium, high, urgent
boardId	string (UUID)	Yes	Board where the item will be created
boardColumnId	string (UUID)	Yes	Initial column
projectId	string (UUID)	No	Project (uses MCP session value as fallback)
assignee	string	No	Name or identifier of the assignee
parentId	string (UUID)	No	ID of the parent work item
metadata	object	No	Arbitrary metadata (e.g., { definitionOfDone: "..." })

Example:

{
  "title": "Implement login endpoint",
  "description": "Create POST /api/auth/login endpoint with JWT validation",
  "type": "task",
  "priority": "high",
  "boardId": "b1234567-89ab-cdef-0123-456789abcdef",
  "boardColumnId": "col-001",
  "parentId": "wi-feature-01"
}

---

create_task

Shortcut to create a task. Forces type=task and automatically selects the project's default board and the "Backlog" column. Requires projectId to be configured in the MCP session.

Parameters:

Name	Type	Required	Description
title	string	Yes	Task title
description	string	No	Detailed description
priority	string	No	Priority: low, medium, high, urgent
parentId	string (UUID)	No	ID of the parent work item
metadata	object	No	Arbitrary metadata

Example:

{
  "title": "Add email validation",
  "priority": "medium",
  "parentId": "wi-feature-01"
}

---

create_story

Shortcut to create a story. Forces type=story and automatically selects the board and "Backlog" column.

Parameters:

Name	Type	Required	Description
title	string	Yes	Story title
description	string	No	Detailed description
priority	string	No	Priority: low, medium, high, urgent
parentId	string (UUID)	No	ID of the parent feature
metadata	object	No	Arbitrary metadata

Example:

{
  "title": "As a user I want to sign in with Google",
  "priority": "high",
  "parentId": "wi-feature-01"
}

---

create_feature

Shortcut to create a feature. Forces type=feature and automatically selects the board and "Backlog" column.

Parameters:

Name	Type	Required	Description
title	string	Yes	Feature title
description	string	No	Detailed description
priority	string	No	Priority: low, medium, high, urgent
parentId	string (UUID)	No	ID of the parent epic
metadata	object	No	Arbitrary metadata

Example:

{
  "title": "Authentication system",
  "description": "OAuth authentication with Google and email/password",
  "priority": "high"
}

---

create_epic

Shortcut to create an epic. Forces type=epic and automatically selects the board and "Backlog" column.

Parameters:

Name	Type	Required	Description
title	string	Yes	Epic title
description	string	No	Detailed description
priority	string	No	Priority: low, medium, high, urgent
metadata	object	No	Arbitrary metadata

Example:

{
  "title": "Epic: Security and authentication",
  "description": "All authentication and authorization flows for the platform",
  "priority": "urgent"
}

---

Update and movement

update_work_item

Updates the fields of an existing work item. Only the provided fields are modified. Metadata is merged with existing values (not overwritten).

Parameters:

Name	Type	Required	Description
id	string (UUID)	Yes	Work item ID
title	string	No	New title
description	string	No	New description
type	string	No	New type: epic, feature, story, task, idea
priority	string	No	New priority: low, medium, high, urgent
assignee	string	No	New assignee
boardColumnId	string (UUID)	No	Move to another column
parentId	string (UUID) or null	No	New parent (null to unlink)
metadata	object	No	Metadata to merge with existing values

Example:

{
  "id": "wi-001",
  "priority": "urgent",
  "metadata": {
    "definitionOfDone": "Unit tests + integration tests passing"
  }
}

---

move_work_item

Moves a work item to a different board column. Automatically manages AI processing flags based on the destination column.

Parameters:

Name	Type	Required	Description
workItemId	string (UUID)	Yes	ID of the work item to move
boardColumnId	string (UUID)	Yes	ID of the destination column
isAutoSync	boolean	No	true when the movement is due to cascade synchronization (default: false)
setAiProcessing	boolean	No	Force isAiProcessing=true regardless of the destination column
aiProvider	string	No	AI provider (openai, anthropic). When combined with setAiProcessing, sets provider metadata

Example:

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

Automatic AI flag behavior

• When moving to In Progress: isAiProcessing=true is activated automatically
• When moving to Review or Done: isAiProcessing=false is deactivated automatically
• With setAiProcessing=true: the flag is forced regardless of the column

---

batch_move_work_items

Moves multiple work items to a destination column in a single operation. Optionally sets AI processing flags for all moved items.

Parameters:

Name	Type	Required	Description
workItemIds	string[] (UUID)	Yes	List of work item IDs to move
boardColumnId	string (UUID)	Yes	ID of the destination column
setAiProcessing	boolean	No	Activate isAiProcessing=true for all items
aiProvider	string	No	AI provider to record in metadata

Example:

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

Response:

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

---

delete_work_item

Permanently deletes a work item by its ID.

Parameters:

Name	Type	Required	Description
id	string (UUID)	Yes	ID of the work item to delete

Example:

{
  "id": "wi-001"
}

Response:

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

---

Implementation prompts

generate_work_item_prompt

Generates an implementation prompt enriched with project context (tech stack, repositories, sibling tasks, board flow). The prompt is AI-generated and saved in the work item's metadata.

Parameters:

Name	Type	Required	Description
id	string (UUID)	Yes	Work item ID

Example:

{
  "id": "wi-001"
}

Response:

{
  "prompt": "## Project context\n...\n## Task\n...",
  "context": {
    "workItemId": "wi-001",
    "taskId": "A-T-37",
    "title": "Implement login",
    "type": "task",
    "projectName": "My Project",
    "siblingsCount": 4,
    "hasParent": true
  },
  "savedToDb": true
}

---

get_work_item_prompt

Retrieves the previously generated implementation prompt stored in the work item's metadata.

Parameters:

Name	Type	Required	Description
id	string (UUID)	Yes	Work item ID

Example:

{
  "id": "wi-001"
}

Response:

{
  "prompt": "## Project context\n...",
  "context": {
    "workItemId": "wi-001",
    "taskId": "A-T-37",
    "title": "Implement login",
    "type": "task"
  },
  "generatedAt": "2025-02-01T10:00:00.000Z"
}

---

Review and validation flow

complete_review

Completes the code review of a work item. If the review passes, the item is moved to Testing. If it fails, it returns to In Progress. Review metadata is stored in the work item.

Parameters:

Name	Type	Required	Description
workItemId	string (UUID)	Yes	Work item ID
result	string	Yes	Result: pass (moves to Testing) or fail (moves to In Progress)
summary	string	Yes	Review summary
issues	string[]	No	List of issues found (relevant when result=fail)
reviewedFiles	string[]	No	List of reviewed files

Example:

{
  "workItemId": "wi-001",
  "result": "pass",
  "summary": "Clean code, tests passing, meets definition of done",
  "reviewedFiles": ["src/auth/login.ts", "src/auth/login.test.ts"]
}

---

complete_validation

Atomically completes a task's validation: moves a passing task to its destination column, normally To Document, clears AI flags, merges documentation and test results metadata, and records the AI session. If the Validating column is passed by mistake, the tool redirects to To Document when available on the board.

Parameters:

Name	Type	Required	Description
workItemId	string (UUID)	Yes	Work item ID
toDocumentColumnId	string (UUID)	No	Destination column for a passing validation result. Prefer the board's To Document column
validatingColumnId	string (UUID)	No	Legacy destination alias. If it points to Validating, the tool attempts to redirect to To Document
documentation	object	No	Documentation metadata (see sub-object below)
documentation.summary	string	No	Summary of what was validated
documentation.screenshots	string[]	No	URLs of attached screenshots
documentation.mermaidDiagrams	string[]	No	Mermaid diagrams as strings
documentation.changelogEntry	string	No	Changelog entry
testResults	object	No	Test results (see sub-object below)
testResults.passed	number	No	Tests passed
testResults.failed	number	No	Tests failed
testResults.testFiles	string[]	No	Paths of test files
model	string	Yes	AI model used (e.g., claude-opus-4-6)
provider	string	No	AI provider (default: anthropic)
totalTokens	number	Yes	Total tokens consumed
durationMs	number	No	Session duration in milliseconds
taskId	string	No	Human-readable task ID (e.g., A-T-37)

Example:

{
  "workItemId": "wi-001",
  "toDocumentColumnId": "col-to-document",
  "documentation": {
    "summary": "Google login verified 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

Atomically completes AI work on a task: moves to Review, clears AI flags, sets userActions, and records the session with token consumption. Replaces the need to call move_work_item + update_work_item + record_ai_session separately.

Parameters:

Name	Type	Required	Description
workItemId	string (UUID)	Yes	Work item ID
reviewColumnId	string (UUID)	Yes	ID of the Review column
userActions	string	No	Markdown list of manual steps the user should verify
model	string	Yes	AI model used (e.g., claude-opus-4-6)
provider	string	No	Provider (default: openai)
totalTokens	number	Yes	Total tokens consumed
durationMs	number	No	Session duration in ms
sessionType	string	No	Session type (default: implement)
taskId	string	No	Human-readable task ID (e.g., A-T-37)

Example:

{
  "workItemId": "wi-001",
  "reviewColumnId": "col-004",
  "userActions": "- Verify that login redirects to /dashboard\n- Check that the token is saved in cookies",
  "model": "claude-opus-4-6",
  "provider": "anthropic",
  "totalTokens": 85000,
  "durationMs": 300000,
  "taskId": "A-T-37"
}

Response:

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

Recommended usage

Use complete_ai_task when finishing an AI implementation of a task. It is the most efficient way to close the work cycle: a single tool call that moves, clears flags, and records costs.

---

Attachments

upload_work_item_attachment

Uploads an attachment to a work item from a local file path. Designed for AI tooling (for example, attaching Playwright screenshots).

Parameters:

Name	Type	Required	Description
workItemId	string (UUID)	Yes	Work item ID
filePath	string	Yes	Absolute or repo-relative path (allowed: /tmp/* or under the working directory)
fileName	string	No	File name to store (default: basename of the path)
mimeType	string	No	MIME type (default: inferred from name)
uploadedBy	string	No	Uploader label
metadata	object	No	Attachment metadata (e.g., { kind: "review-screenshot", page: "/boards" })
deleteAfterUpload	boolean	No	Delete the local file after upload (default: true)

Example:

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

---

Advanced context

get_implement_context

Resolves identifiers into pending leaf tasks, classifies by column state, includes board mapping, intra-batch dependencies, and pre-calculated execution waves.

Parameters:

Name	Type	Required	Description
ids	string[]	Yes	List of task IDs/UUIDs to implement
projectId	string (UUID)	No	Project ID (default: MCP session)

Example:

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

---

get_ideation_context

Gets ideation context: related work items by keywords, potential parents, and dynamic board configuration.

Parameters:

Name	Type	Required	Description
keywords	string[]	Yes	Search keywords
projectId	string (UUID)	No	Project ID (default: MCP session)
limit	number	No	Result limit (default: 20, max: 50)

Example:

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

---

get_review_context

Gets complete review context for a task or feature: item details, routing columns, dependencies, sibling items, and reviewable children.

Parameters:

Name	Type	Required	Description
taskId	string	Yes	Task identifier (UUID or taskId like A-T-37)
featureReview	boolean	No	When true, includes reviewable children for feature/epic review

Example:

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

---

get_validate_context

Resolves identifiers into leaf tasks, classifies by board column (reviewable in Review, testable in Testing, skipped otherwise), includes board mapping with Validating column and parent item summaries.

Parameters:

Name	Type	Required	Description
ids	string[]	Yes	List of task IDs/UUIDs to validate
projectId	string (UUID)	No	Project ID (default: MCP session)

Example:

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