Work Items

← Back to Index | ← Boards | Next: Comments →

Work items are tasks, user stories, bugs, and other trackable units in HacknPlan.

Listing & Reading
Creating & Updating
Deleting & Recovery
Assignments & Tags
Relationships
Dependencies

Listing & Reading

list_work_items

List work items with optional filters.

Parameters:

projectId (number, optional): Project ID
boardId (number, optional): Filter by board/sprint
stageId (number, optional): Filter by workflow stage
assignedUserId (number, optional): Filter by assigned user
categoryId (number, optional): Filter by category
milestoneId (number, optional): Filter by milestone
tagId (number, optional): Filter by tag
offset (number, optional): Pagination offset
limit (number, optional): Max items (default: 50, max: 200)
verbosity (string, optional): slim or full

Returns: { items, total, offset, limit, hasMore, index? }

Pagination Note: Client-side pagination. For server-side pagination with advanced filtering, use search_work_items.

Example:

// Get all programming tasks in current sprint
const tasks = await callTool('list_work_items', {
  projectId: 230954,
  boardId: 650299,
  categoryId: 1  // Programming
});

// Get incomplete tasks assigned to me
const myTasks = await callTool('get_my_current_tasks', {
  projectId: 230954,
  includeCompleted: false
});

get_work_item

Get detailed information about a work item.

Parameters:

projectId (number, optional): Project ID
workItemId (number, required): Work item ID

Returns: Work item object with full details

Response Fields:

workItemId: Item identifier
title: Task title
description: Markdown description
categoryId: Category (1=programming, 2=design, etc.)
importanceLevelId: Priority level
estimatedCost: Effort estimate (hours/points)
stageId: Current workflow stage
isCompleted: Completion status
assignedUserIds: Array of assigned user IDs
tagIds: Array of tag IDs
boardId: Sprint/board assignment
parentStoryId: Parent user story (if subtask)
designElementId: Linked design element

Creating & Updating

create_work_items

Create one or more work items with full metadata support and name resolution.

Parameters:

projectId (number, optional): Project ID
items (array, required): Array of work items to create (1-100 items)

Item Schema:

title (string, required): Work item title
description (string, optional): Description/details (supports markdown)
categoryId (number|string, required): Category ID or name ('programming', 'design', 'writing', 'ideas', 'bug')
estimatedCost (number, optional): Estimated hours/points
importanceLevelId (number|string, optional): Priority ID or name ('urgent', 'high', 'normal', 'low')
boardId (number, optional): Assign to board/sprint
stageId (number, optional): Initial workflow stage
milestoneId (number, optional): Assign to milestone
designElementId (number, optional): Link to design element
parentStoryId (number, optional): Parent user story ID
assignedUserIds (number[], optional): User IDs to assign
tagIds (number[]|string[], optional): Tag IDs or names (auto-creates missing tags)

Returns: { items, created, failed, errors, warnings }

Example with name resolution:

const result = await callTool('create_work_items', {
  projectId: 230954,
  items: [{
    title: 'Implement OAuth2 authentication',
    description: '## Requirements\n- Support GitHub and Google providers\n- JWT token handling',
    categoryId: 'programming',  // Name resolution!
    importanceLevelId: 'high',   // Name resolution!
    tagIds: ['backend', 'security'],  // Name resolution + auto-create!
    estimatedCost: 12,
    boardId: 650299
  }]
});

console.log(`Created ${result.created} items, ${result.failed} failed`);

Batch Creation:

// Create multiple related tasks at once
await callTool('create_work_items', {
  projectId: 230954,
  items: [
    { title: 'Design auth schema', categoryId: 'design', estimatedCost: 3 },
    { title: 'Implement login endpoint', categoryId: 'programming', estimatedCost: 5 },
    { title: 'Write auth tests', categoryId: 'programming', estimatedCost: 4 }
  ]
});

update_work_items

Update one or more work items. Supports auto-create for tags.

Parameters:

projectId (number, optional): Project ID
items (array, required): Array of updates (1-100 items)

Update Schema:

workItemId (number, required): Work item ID to update
title (string, optional): New title
description (string, optional): New description
estimatedCost (number, optional): Update estimate
importanceLevelId (number|string, optional): Change priority
categoryId (number|string, optional): Change category
boardId (number, optional): Move to different board
stageId (number, optional): Move to different stage
milestoneId (number, optional): Assign/reassign milestone
isCompleted (boolean, optional): Mark as completed
designElementId (number|null, optional): Link design element (null to remove)
parentStoryId (number|null, optional): Set parent (null to remove)
assignedUserIds (number[], optional): Replace assignments
tagIds (number[]|string[], optional): Replace tags (auto-creates missing tags)

Returns: { items, updated, failed, errors, warnings }

Example:

// Update single item
await callTool('update_work_items', {
  projectId: 230954,
  items: [{
    workItemId: 12345,
    isCompleted: true,
    stageId: 5  // Move to "Done" stage
  }]
});

// Batch update - add "urgent" tag to multiple items
await callTool('update_work_items', {
  projectId: 230954,
  items: [1234, 1235, 1236].map(id => ({
    workItemId: id,
    tagIds: ['urgent']  // Auto-creates tag if doesn't exist
  }))
});

Deleting & Recovery

delete_work_items

Delete one or more work items with automatic recovery cache storage.

Parameters:

projectId (number, optional): Project ID
workItemIds (number[], required): Array of work item IDs (1-100 items)

Returns: Confirmation token for 2-step mode, or immediate deletion result

Recovery Behavior:

Default mode: Items stored in recovery cache before deletion
Strict mode (HACKNPLAN_REQUIRE_DELETE_CONFIRMATION=true): Requires confirm_deletion call

Example:

// Default mode - immediate deletion with recovery
await callTool('delete_work_items', {
  projectId: 230954,
  workItemIds: [123, 124, 125]
});

// Later, if needed:
await callTool('recover_deleted_items', {
  projectId: 230954,
  workItemIds: [123, 124]
});

See: Deletion Safety Guide for comprehensive recovery documentation.

Assignments & Tags

Manage Assignments

assign_work_item / unassign_work_item:

// Assign users to task
await callTool('assign_work_item', {
  projectId: 230954,
  workItemId: 12345,
  userIds: [101, 102]  // Adds to existing assignments
});

// Remove specific users
await callTool('unassign_work_item', {
  projectId: 230954,
  workItemId: 12345,
  userIds: [102]
});

Alternative (via update_work_items):

// Replace all assignments
await callTool('update_work_items', {
  projectId: 230954,
  items: [{
    workItemId: 12345,
    assignedUserIds: [101, 103]  // Replaces existing
  }]
});

Manage Tags

set_work_item_tags / add_work_item_tag / remove_work_item_tag:

// Replace all tags
await callTool('set_work_item_tags', {
  projectId: 230954,
  workItemId: 12345,
  tagIds: [1, 5, 8]
});

// Add single tag
await callTool('add_work_item_tag', {
  projectId: 230954,
  workItemId: 12345,
  tagId: 9
});

// Remove single tag
await callTool('remove_work_item_tag', {
  projectId: 230954,
  workItemId: 12345,
  tagId: 5
});

Alternative (via update_work_items with auto-create):

await callTool('update_work_items', {
  projectId: 230954,
  items: [{
    workItemId: 12345,
    tagIds: ['backend', 'urgent', 'new-tag']  // Auto-creates missing tags!
  }]
});

Relationships

set_work_item_parent

Link a work item as a subtask to a parent user story.

Parameters:

projectId (number, optional): Project ID
workItemId (number, required): Work item ID
parentStoryId (number|null, required): Parent story ID (null to remove)

Returns: Updated work item object

Example:

// Create parent-child relationship
await callTool('set_work_item_parent', {
  projectId: 230954,
  workItemId: 12345,  // Subtask
  parentStoryId: 12340  // Parent story
});

// Remove parent relationship
await callTool('set_work_item_parent', {
  projectId: 230954,
  workItemId: 12345,
  parentStoryId: null
});

Shortcut: Use create_subtask to create and link in one call.

set_work_item_design_element

Link a work item to a design element (game design document).

Parameters:

projectId (number, optional): Project ID
workItemId (number, required): Work item ID
designElementId (number|null, required): Design element ID (null to remove)

Returns: Updated work item object

Example:

// Link task to character design
await callTool('set_work_item_design_element', {
  projectId: 230954,
  workItemId: 12345,
  designElementId: 789  // "Main Character" design element
});

Dependencies

Manage "blocks" relationships between work items.

⚠️ Requires HacknPlan Premium Plan

add_work_item_dependency

Create a dependency: successor depends on predecessor.

Parameters:

projectId (number, optional): Project ID
successorId (number, required): Work item that depends on another
predecessorId (number, required): Work item that must complete first

Example:

// "Deploy to staging" depends on "Pass all tests"
await callTool('add_work_item_dependency', {
  projectId: 230954,
  successorId: 12346,      // Deploy to staging
  predecessorId: 12345     // Pass all tests (blocks 12346)
});

remove_work_item_dependency

Remove a dependency relationship.

Parameters: Same as add_work_item_dependency

list_work_item_dependencies

Get all dependencies for a work item.

Parameters:

projectId (number, optional): Project ID
workItemId (number, required): Work item ID

Returns: { predecessors: [], successors: [] }

Example:

const deps = await callTool('list_work_item_dependencies', {
  projectId: 230954,
  workItemId: 12345
});

console.log('Blocked by:', deps.predecessors);
console.log('Blocking:', deps.successors);

Advanced: Use get_blockers for dependency graph analysis.

Common Patterns

Name Resolution Reference

Categories:

'programming' → 1
'design' → 2
'writing' → 3
'ideas' → 4
'bug' → 5

Importance Levels:

'urgent' → 1
'high' → 2
'normal' → 3
'low' → 4

Tags: Auto-creates if name doesn't exist (when using update_work_items)

Bulk Operations

// Move all incomplete tasks to next sprint
const items = await callTool('list_work_items', {
  projectId: 230954,
  boardId: 650299  // Current sprint
});

const incomplete = items.items
  .filter(i => !i.isCompleted)
  .map(i => ({
    workItemId: i.workItemId,
    boardId: 650300  // Next sprint
  }));

await callTool('update_work_items', {
  projectId: 230954,
  items: incomplete
});

Template-Based Creation

// Create consistent bug reports
const bugTemplate = {
  categoryId: 'bug',
  importanceLevelId: 'high',
  tagIds: ['needs-triage'],
  description: `## Steps to Reproduce
1.
2.

## Expected Behavior


## Actual Behavior


## Environment
- OS:
- Version: `
};

await callTool('create_work_items', {
  projectId: 230954,
  items: [{
    ...bugTemplate,
    title: 'Login fails with invalid credentials'
  }]
});

See Also:

Workflow Shortcuts - start_task, complete_task, create_subtask
Batch Operations - search_work_items, get_blockers
Array API Guide - Unified batch operations
Deletion Safety - Recovery system

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Work Items

Table of Contents

Listing & Reading

list_work_items

get_work_item

Creating & Updating

create_work_items

update_work_items

Deleting & Recovery

delete_work_items

Assignments & Tags

Manage Assignments

Manage Tags

Relationships

set_work_item_parent

set_work_item_design_element

Dependencies

add_work_item_dependency

remove_work_item_dependency

list_work_item_dependencies

Common Patterns

Name Resolution Reference

Bulk Operations

Template-Based Creation

FilesExpand file tree

work-items.md

Latest commit

History

work-items.md

File metadata and controls

Work Items

Table of Contents

Listing & Reading

list_work_items

get_work_item

Creating & Updating

create_work_items

update_work_items

Deleting & Recovery

delete_work_items

Assignments & Tags

Manage Assignments

Manage Tags

Relationships

set_work_item_parent

set_work_item_design_element

Dependencies

add_work_item_dependency

remove_work_item_dependency

list_work_item_dependencies

Common Patterns

Name Resolution Reference

Bulk Operations

Template-Based Creation