MCP-Tasks Story and Task Management

This skill provides guidance on using the mcp-tasks MCP server for task and story management.

Overview

The mcp-tasks MCP server provides:

• •Tools: For managing tasks (create, update, select, complete, delete)
• •Prompts: Workflow templates for executing tasks and stories
• •Resources: Category instructions and execution state

MCP Tools

Task Query and Modification

Task Environment Setup

work-on - Prepares task execution environment (called automatically by execute prompts)

• •Required: task-id
• •Actions: Records execution state, manages branches/worktrees (if configured)
• •Returns: Task info (:task-id, :category, :type, :title, :status), environment info (:worktree-path, :worktree-name, :branch-name, :worktree-clean?, :worktree-created?), state file path

Available Activities

Each activity can be invoked via slash command or by programmatically accessing the MCP resource using ReadMcpResourceTool.

Task Activities

Execute task by criteria

• •Slash command: /mcp-tasks:execute-task [selection-criteria...]
• •Arguments: category=X, parent-id=N, type=X (combinable)
• •MCP resource: prompt://execute-task
• •Implementation: Use slash command OR read resource and follow prompt instructions

Execute next task for category

• •Slash command: /mcp-tasks:next-<category>
• •Arguments: None
• •MCP resource: prompt://next-<category>
• •Implementation: Use slash command OR read resource and follow prompt instructions

Refine task

• •Slash command: /mcp-tasks:refine-task [task-spec] [context...]
• •Arguments: Task ID ("#59", "59", "task 59") or pattern ("Update prompt")
• •MCP resource: prompt://refine-task
• •Implementation: Use slash command OR read resource and follow prompt instructions

Review task implementation

• •Slash command: /mcp-tasks:review-task-implementation [task-spec]
• •Arguments: Task ID ("#59", "59", "task 59") or none (uses current execution state)
• •MCP resource: prompt://review-task-implementation
• •Implementation: Use slash command OR read resource and follow prompt instructions

Story Activities

Create story tasks

• •Slash command: /mcp-tasks:create-story-tasks [story-spec] [context...]
• •Arguments: Story ID ("#59", "59", "story 59") or pattern ("Story title")
• •MCP resource: prompt://create-story-tasks
• •Implementation: Use slash command OR read resource and follow prompt instructions

Execute story task

• •Slash command: /mcp-tasks:execute-story-child [story-spec] [context...]
• •Arguments: Same as create-story-tasks
• •MCP resource: prompt://execute-story-child
• •Implementation: Use slash command OR read resource and follow prompt instructions

Create story PR

• •Slash command: /mcp-tasks:create-story-pr [story-spec]
• •Arguments: Same as create-story-tasks
• •MCP resource: prompt://create-story-pr
• •Implementation: Use slash command OR read resource and follow prompt instructions

Review story implementation

• •Slash command: /mcp-tasks:review-story-implementation [story-spec]
• •Arguments: Same as create-story-tasks
• •MCP resource: prompt://review-story-implementation
• •Implementation: Use slash command OR read resource and follow prompt instructions

Complete story

• •Slash command: /mcp-tasks:complete-story [story-spec]
• •Arguments: Same as create-story-tasks
• •MCP resource: prompt://complete-story
• •Implementation: Use slash command OR read resource and follow prompt instructions

Story Creation Guidelines

Story creation and task breakdown are separate workflow steps.

When creating a story via add-task:

• •Create ONLY the story record itself
• •Do NOT automatically invoke create-story-tasks
• •Wait for explicit user request to break down the story into tasks

This separation ensures the user can:

1. •Review and refine the story before breakdown
2. •Control when task breakdown occurs
3. •Provide additional context or constraints before tasks are created

Correct workflow:

1. User requests story creation
2. Agent creates story with add-task (type: story)
3. Agent stops and informs user story is created
4. User reviews story, optionally requests refinement
5. User explicitly requests task breakdown
6. Agent invokes create-story-tasks

Incorrect workflow (never do this):

1. User requests story creation
2. Agent creates story with add-task
3. Agent immediately invokes create-story-tasks ← WRONG

Story Shared Context

Stories maintain a shared context (:shared-context field) that enables inter-task communication during story execution. This allows child tasks to coordinate by reading context from previous tasks and appending discoveries, decisions, and important information for subsequent tasks.

How It Works:

1. •Reading Context: Child tasks access parent story's shared context via :parent-shared-context field returned by select-tasks
2. •Writing Context: Tasks append to parent story's shared context using update-task with the story's task ID
3. •Automatic Prefixing: System reads current task ID from execution state (.mcp-tasks-current.edn) and automatically prefixes each entry with "Task NNN: "
4. •Persistence: Context persists with story throughout execution and is archived when story completes

Context Precedence Rule:

Shared context takes precedence over a task's static :description and :design fields when conflicts exist or new information emerges. This ensures tasks work with the most current state.

When to Update Shared Context:

Update during execution when you:

• •Make architectural or design decisions
• •Discover important information (API endpoints, configuration, constraints)
• •Find edge cases or issues
• •Implement features that subsequent tasks depend on
• •Choose between alternatives that affect later work

The system automatically prefixes your update with "Task NNN:" where NNN is the current task ID. Multiple updates accumulate with newest first.

Key Points:

• •Append Only: New entries are appended to existing context (not replaced)
• •Chronological Order: Entries maintain order with task ID prefix showing sequence
• •Size Limit: 50KB total serialized EDN (enforced by update-task)
• •Story Scope: Context shared only among story and its children (not across stories)
• •Security: Don't store sensitive data - context appears in task files and may appear in PRs

Other Resources

Category instructions:

• •prompt://category-<category> - Execution instructions for specific category (e.g., prompt://category-simple)

Execution state:

• •resource://current-execution - Current execution state (story-id, task-id, started-at)

Accessing MCP Resources Programmatically

;; Example: Access execute-task prompt
(ReadMcpResourceTool
  :server "mcp-tasks"
  :uri "prompt://execute-task")

Common workflow: All execution activities follow: Find task → Call work-on → Execute category workflow → Mark complete

Common Workflows

Execute simple task:

/mcp-tasks:next-simple

Story workflow:

/mcp-tasks:create-story-tasks 59       # Break into tasks
/mcp-tasks:execute-story-child 59       # Execute (repeat for each task)
/mcp-tasks:review-story-implementation 59
/mcp-tasks:complete-story 59

Refine then execute:

/mcp-tasks:refine-task 123
/mcp-tasks:execute-task task-id=123

Complete Task Lifecycle Walkthrough

Prerequisites

• •mcp-tasks MCP server configured and running
• •Project initialized with .mcp-tasks/ directory
• •Optional: :worktree-management? enabled in .mcp-tasks.edn
• •Optional: :base-branch configured for branch management

This section covers two workflows: Standalone Tasks and Story-Based Workflows.

Workflow A: Standalone Task

Example: Executing standalone task #123 "Add user authentication" (category: medium).

1. Refine Task (Optional - Skip for Simple/Clear Tasks)

/mcp-tasks:refine-task 123

What happens:

• •Agent analyzes task in project context
• •Reviews design patterns and codebase
• •Suggests improvements interactively
• •Updates task with update-task tool
• •Sets meta: {"refined": "true"}

When to skip: Simple tasks with clear requirements need no refinement.

2. Execute Task

/mcp-tasks:execute-task task-id=123

Behind the scenes - work-on tool (automatic):

The execute prompt calls work-on which:

• •Writes execution state to .mcp-tasks-current.edn
• •Creates/switches to worktree (if :worktree-management? enabled)
• •Creates/switches to branch 123-add-user-authentication (if branch management configured)

See work-on Tool Reference for complete return value specification.

Agent displays working environment:

Worktree: project-123-add-user-authentication
Directory: /Users/user/project-123-add-user-authentication
Branch: 123-add-user-authentication

Category workflow execution (medium):

1. •Analyze - Agent reviews task spec, researches patterns
2. •Check understanding - Agent confirms understanding with user
3. •Plan - Agent creates implementation plan
4. •Implement - Agent writes code
5. •Commit - Agent creates git commit in main repository

3. Complete Task

After successful implementation, the agent calls:

(complete-task :task-id 123 :completion-comment "Implemented JWT auth")

What happens:

• •Task status changed to :closed
• •Task moved from tasks.ednl to complete.ednl
• •Execution state cleared from .mcp-tasks-current.edn
• •Automatic worktree cleanup (if :worktree-management? enabled) - see Worktree Cleanup Mechanism

Configuration Impact

See Git Integration for naming conventions and Error Recovery for failure handling.

Workflow B: Story-Based Workflow

Example: Story #408 "Improve mcp-tasks skill" with multiple child tasks.

1. Refine Story (Optional but Recommended)

/mcp-tasks:refine-task 408

What happens:

• •Agent analyzes story in project context
• •Suggests improvements to requirements
• •Updates story with update-task tool
• •Sets meta: {"refined": "true"}

Note: The create-story-tasks prompt will halt and require explicit user confirmation to proceed if story is unrefined. Agents must never proceed automatically.

2. Create Story Tasks

/mcp-tasks:create-story-tasks 408

What happens:

• •Retrieves story using select-tasks (type: story)
• •Checks refinement status, warns if not refined
• •Displays story content to user
• •Analyzes and breaks down into specific tasks
• •Presents task breakdown for user approval
• •Adds each task using add-task with:
  • •parent-id: Story ID (408)
  • •category: Appropriate category per task
  • •type: Usually :task, :feature, or :bug

Example tasks created:

Task #410: Add walkthrough section (category: medium, parent-id: 408)
Task #411: Document git integration (category: medium, parent-id: 408)
Task #412: Add error recovery section (category: simple, parent-id: 408)

3. Execute Story Tasks (Repeat for Each Task)

/mcp-tasks:execute-story-child 408

What happens:

• •Finds story and first incomplete child task
• •Shows progress: "2 of 5 tasks completed"
• •Calls work-on tool with task ID
• •For first task only (if worktree/branch management enabled):
  • •Creates worktree: project-408-improve-mcp-tasks-skill/
  • •Creates branch: 408-improve-mcp-tasks-skill
  • •All story tasks use same worktree/branch
• •Executes task using its category workflow
• •Creates git commit
• •Marks task complete with complete-task
• •Preserves worktree for remaining story tasks

Repeat until all story tasks complete.

4. Create Pull Request (Optional)

/mcp-tasks:create-story-pr 408

What happens:

• •Finds story using select-tasks
• •Verifies current branch (must not be master/main)
• •Collects commits from story branch
• •Generates PR content:
  • •Title: Story title (with optional semantic prefix)
  • •Description: Story details + commit summary
• •Creates PR targeting default branch
• •Returns PR URL

Prerequisites:

• •Must be on story branch
• •Remote repository configured
• •gh CLI or similar tool available

5. Complete Story (After PR Merged)

/mcp-tasks:complete-story 408

What happens:

• •Requires user confirmation before archiving. Never complete a story without explicit user approval.
• •Moves story and all child tasks to archive
• •Preserves implementation history

Worktree cleanup: After PR is merged, manually remove worktree:

git worktree remove /path/to/project-408-improve-mcp-tasks-skill

Or if automatic cleanup enabled, it happens on last task completion.

work-on Tool Reference

Invocation Rules

When to call manually:

• •Custom workflows outside standard execute prompts
• •Debugging execution state issues
• •Setting up environment without executing task

When Agents Should Call work-on Directly

Agents must call the work-on tool explicitly when the user instructs them to work on a specific task or story:

User instruction patterns requiring explicit work-on call:

• •"Work on task 123"
• •"Start working on task 123"
• •"Work on story 59"
• •"Begin task 123"
• •Similar direct instructions to start working on a specific task/story

Process:

1. •Parse user instruction to identify task/story ID
2. •Call mcp__mcp-tasks__work-on with the task ID
3. •Display working environment context (worktree, branch if present)
4. •Proceed with task execution according to the category workflow

Contrast with execute prompts:

• •Execute prompts (e.g., /mcp-tasks:execute-story-child) call work-on automatically
• •When user gives direct instruction to work on a task, agent must call work-on before proceeding

Return Value Specification

work-on returns a map with task and environment information:

Example response (with worktree management enabled):

{:task-id 123
 :category "medium"
 :type :task
 :title "Add user authentication"
 :status :open
 :message "Task validated successfully and execution state written"
 :worktree-path "/Users/user/project-123-add-user-authentication"
 :worktree-name "project-123-add-user-authentication"
 :branch-name "123-add-user-authentication"
 :worktree-clean? true
 :worktree-created? true
 :execution-state-file "/Users/user/project-123-add-user-authentication/.mcp-tasks-current.edn"}

Example response (worktree management disabled):

{:task-id 123
 :category "medium"
 :type :task
 :title "Add user authentication"
 :status :open
 :message "Task validated successfully and execution state written"
 :execution-state-file ".mcp-tasks-current.edn"}

Git Integration

Branch Naming Convention

Format: <id>-<title-slug>

Slugification process:

1. •Extract first N words from title (default: 4, configurable via :branch-title-words)
2. •Convert to lowercase
3. •Replace spaces with dashes
4. •Remove all special characters (keep only a-z, 0-9, -)

Examples:

Worktree Naming Convention

Format: Depends on :worktree-prefix configuration

Title slug: Same process as branch naming (first N words, slugified)

Location: Sibling directory to main repository

/Users/user/project/                           # Main repo
/Users/user/project-123-add-auth/              # Worktree (with :project-name prefix)
/Users/user/123-add-auth/                      # Worktree (with :none prefix)

Commit Timing and Location

When commits occur:

• •During category workflow execution (varies by category)
• •Simple: After implementation complete
• •Medium: After implementation complete
• •Large: After each significant milestone + final implementation

Where commits occur:

• •Always in the main repository (.git directory location)
• •Even when working in a worktree, commits are recorded in main repo
• •Worktrees share the same commit history

Who creates commits:

• •The agent executing the category workflow
• •Follows category-specific commit instructions
• •Uses git operations in current working directory

Task/Branch/Worktree Relationships

Story Task #408 "Improve mcp-tasks skill"
  ├─ Branch: 408-improve-mcp-tasks-skill
  ├─ Worktree: /path/to/project-408-improve-mcp-tasks-skill/
  │
  ├─ Child Task #410 (category: medium)
  │   └─ Uses same branch + worktree as parent story
  │
  ├─ Child Task #411 (category: medium)
  │   └─ Uses same branch + worktree as parent story
  │
  └─ Child Task #412 (category: simple)
      └─ Uses same branch + worktree as parent story

Standalone Task #123 "Add authentication"
  ├─ Branch: 123-add-authentication
  └─ Worktree: /path/to/project-123-add-authentication/

Rules:

• •Story tasks share parent story's branch and worktree
• •Standalone tasks get unique branch and worktree
• •One worktree per task/story (not per child task)
• •All commits for story tasks go to story branch

Worktree Cleanup Mechanism

Automatic cleanup (when :worktree-management? enabled):

Triggered by complete-task tool when:

• •Task is completed successfully
• •Current working directory is inside a worktree

Safety checks before removal:

Cleanup outcomes:

Manual cleanup commands:

# From main repository directory
git worktree remove /path/to/worktree

# Force removal (use with caution)
git worktree remove --force /path/to/worktree

# List all worktrees
git worktree list

# Remove worktree that was already deleted from filesystem
git worktree prune

When to use manual cleanup:

• •Automatic cleanup failed due to safety checks
• •Worktree directory deleted manually
• •Need to clean up multiple worktrees at once
• •Worktree in inconsistent state

Error Recovery

Task Execution Failures

If task execution fails or is interrupted:

1. •Execution state persists: .mcp-tasks-current.edn remains with :started-at timestamp
2. •Task status unchanged: Stays :open (not marked complete)
3. •Worktree/branch preserved: Environment remains set up
4. •To resume: Re-run the execute prompt
   • •work-on overwrites stale execution state automatically
   • •Execution continues from current code state

Common failure scenarios:

Handling Blocked Tasks

When a task depends on another task:

;; Mark current task as blocked
(update-task
  :task-id 123
  :status :blocked
  :relations [{:relates-to 456, :as-type :blocked-by}])

Relation types:

Unblocking workflow:

1. •Execute blocking task first (e.g., task #456)
2. •Complete blocking task
3. •Update blocked task to remove relation and set status to :open
4. •Execute previously blocked task

Delete vs Update vs Complete

Decision matrix:

Constraints:

• •Cannot delete task with non-closed children (must complete or delete children first)
• •Cannot complete task if blocked (must update to :open first)
• •Deleted tasks are archived, not permanently removed

Recovering from Interrupted Execution

Stale execution state detection:

External tools detect stale executions via :started-at timestamp in .mcp-tasks-current.edn:

{:story-id 408
 :task-id 411
 :started-at "2025-10-29T10:30:00Z"}  ; If hours/days old = likely stale

Recovery steps:

1. •

   Check current execution state:

   bash

   cat .mcp-tasks-current.edn
   

2. •

   Verify if execution actually stale:

   • •Check timestamp age
   • •Check if agent still running
   • •Check if work in progress
3. •

   Resume or restart:

   • •If continuing same task: Re-run execute prompt
   • •If switching tasks: Run execute prompt for different task (overwrites state)
   • •If abandoning task: Manually delete .mcp-tasks-current.edn
4. •

   Manual state cleanup (if needed):

   bash

   rm .mcp-tasks-current.edn
   

Note: work-on automatically overwrites execution state, so manual cleanup rarely needed.

Best Practices

• •Refine complex/unclear tasks before execution
• •Match task complexity to category
• •Use parent-id when creating story tasks
• •Monitor execution via resource://current-execution
• •Never create story child tasks for unrefined stories without explicit user confirmation
• •Always call work-on tool when user instructs you to work on a specific task or story
• •Never complete stories without explicit user confirmation

File Locations

• •Tasks: .mcp-tasks/tasks.ednl
• •Completed: .mcp-tasks/complete.ednl
• •Execution state: .mcp-tasks-current.edn
• •Category prompts: .mcp-tasks/prompts/<category>.md (optional overrides)
• •Story prompts: .mcp-tasks/story/prompts/<name>.md (optional overrides)