Work Items

An agent cannot execute "make the app better". It needs specific, scoped work with clear acceptance criteria. Work items are how you turn intent into executable specifications. Without this structure, agents improvise. With it, they know exactly what to do and when it is done.

Work items are the fundamental unit of work in Almirant. They represent any piece of work that needs to be planned, executed, and completed: from a high-level epic to a specific technical task.

Types and hierarchy

Almirant organizes work in a four-level hierarchy:

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

Type	Level	Purpose	Example
Epic	1	High-level strategic objective	"Complete authentication system"
Feature	2	Concrete functionality within an epic	"Login with Google OAuth"
Story	3	Requirement from the user's perspective	"As a user, I want to sign in with my Google account"
Task	4	Executable technical unit of work	"Implement OAuth callback in the backend"

When to use each type

• Epic: When the objective spans multiple features and requires several weeks or sprints. Epics are the highest level of planning.
• Feature: When you describe a complete functionality that the user can perceive. A feature can have multiple stories.
• Story: When you describe a concrete requirement from the user's perspective. Stories are typically completed within a sprint.
• Task: When you describe a specific, scoped technical action. Tasks are the level that the AI implements directly.

Parent-child relationship

Each work item can have a parentId that establishes the hierarchical relationship. The board view allows grouping items by their parent, making it easy to visualize progress at the feature or epic level.

Fields

Field	Type	Description	Required
title	string	Descriptive title of the work item	Yes
description	string	Detailed description, accepts Markdown	No
type	enum	Type: epic, feature, story, task	Yes
priority	enum	Priority: urgent, high, medium, low, none	No
boardColumnId	uuid	Board column where the item is located	Yes
parentId	uuid	Parent work item (for hierarchy)	No
taskId	string	Auto-generated readable identifier (e.g., A-T-37, MC-S-1)	Automatic
dueDate	date	Delivery deadline	No
estimatedHours	number	Estimated work hours	No
tags	array	Tags to categorize the item	No
metadata	object	Enriched metadata (AI context, technical notes)	No
archived_at	timestamp	Archive date (if archived)	No

Readable identifier (taskId)

Each work item automatically receives a unique, readable identifier based on the project and type. Examples:

• A-T-37 -- Task number 37 in project A.
• MC-S-1 -- Story number 1 in project MC.
• A-E-3 -- Epic number 3 in project A.

This identifier is used throughout the interface and in MCP tools to reference items without needing UUIDs.

Assignments

A work item can have multiple assignees, each with a specific role:

Role	Description
responsible	Person responsible for completing the item
collaborator	Person who contributes to the work
reviewer	Person in charge of reviewing the result

A single item can have one responsible person, multiple collaborators, and one or more reviewers simultaneously.

Status: derived from the column

Key concept

Work items do NOT have a status field. The status is derived directly from the board column where the item is located:

• If the column has the semantic role in_progress, the item is "in progress".
• If the column has isDone = true, the item is "completed".
• If the column has isDefault = true, it is where new items land.

Moving an item between columns implicitly changes its status.

Operations

Creating a work item

There are several ways to create work items:

1. From the board -- Click the "+" button on any column. The item is created directly in that column.
2. From the list view -- Use the "New item" button and select the type, board, and column.
3. Via MCP -- Use the create_work_item, create_task, create_story, create_feature, or create_epic tools.

Editing a work item

• Inline editing -- Click on an item's title on the board to edit it directly.
• Detail modal -- Click on the card to open the full detail view where you can edit all fields.
• Markdown description -- The description field supports full Markdown and can be formatted with AI assistance.

Moving between columns

• Drag and drop -- Drag the card from one column to another in the Kanban view.
• Via MCP -- Use the move_work_item or batch_move_work_items tool to move one or multiple items programmatically.

When moving an item to a column with isDone = true, the item is considered completed.

Assigning and unassigning

From the detail modal, add or remove assignees by selecting the user and their role (responsible, collaborator, reviewer).

Attachments

Work items support file attachments stored in S3. You can upload images, documents, screenshots, or any relevant file from the detail modal.

Archiving

Instead of deleting, work items are archived. Archiving sets a timestamp on archived_at. Archived items stop appearing in the main views but are preserved for historical reference.

To archive an item:

1. Open the work item detail.
2. Select Archive.
3. The item disappears from the board but can be viewed in the archived items view.

Detail view

The work item detail view includes:

• All editable fields (title, description, type, priority, assignees, dates).
• Event history -- Record of all changes made to the item.
• AI sessions -- History of AI interactions with the item, including the cost of each session.
• Linked documents -- Links to related documents.
• Dependencies -- Dependencies with other work items.
• Attachments -- Files uploaded to the item.
• Comments and notes.

Bulk operations

From the list view you can select multiple items and execute bulk actions:

• Move to another column.
• Change priority.
• Assign to a user.
• Archive.

Saved views and filters

Work item view filters are persisted in the URL, allowing you to share links with applied filters. You can filter by:

• Type (epic, feature, story, task).
• Priority.
• Assignee.
• Tags.
• Column.

You can also group items by their parent to visualize the hierarchy in the list view.

AI features

Work items integrate AI features directly:

• AI text formatting -- The AI can format and improve the item's description.
• Voice dictation -- Dictate descriptions or comments by voice and the AI transcribes them.
• Copy as prompt -- Copy the item's context as a prompt for use in your IDE.
• AI sessions with cost tracking -- Each AI interaction with an item is recorded with its associated cost.

For developers

For Developers

MCP tools

Creation

Tool	Description	Main parameters
create_work_item	Creates a work item of any type	title, type, boardId, columnId, description, priority, parentId
create_task	Shortcut to create a task	title, boardId, description, priority, parentId
create_story	Shortcut to create a story	title, boardId, description, priority, parentId
create_feature	Shortcut to create a feature	title, boardId, description, priority, parentId
create_epic	Shortcut to create an epic	title, boardId, description, priority

Query

Tool	Description	Main parameters
list_work_items	Lists work items with filters	boardId, type, priority, assigneeId, parentId, columnId

Update

Tool	Description	Main parameters
update_work_item	Updates fields of a work item	workItemId, fields to update
move_work_item	Moves an item to another column	workItemId, columnId
batch_move_work_items	Moves multiple items to a column	workItemIds, columnId
resolve_work_items	Marks items as resolved (moves to done column)	workItemIds
complete_ai_task	Completes an AI task and moves it to done	workItemId, summary

Example: Create a task via MCP

Tool: create_task
Parameters:
  title: "Implement authentication endpoint"
  boardId: "board-uuid"
  description: "Create the POST /api/auth/login endpoint with JWT validation"
  priority: "high"
  parentId: "parent-story-uuid"

Example: Move items in batch

Tool: batch_move_work_items
Parameters:
  workItemIds: ["uuid-1", "uuid-2", "uuid-3"]
  columnId: "done-column-uuid"

Example: List filtered board items

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