story-and-tasks

What this skill does

# 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

| Tool | Purpose | Key Parameters |
|------|---------|---------------|
| `select-tasks` | Query tasks with filtering | `task-id`, `parent-id`, `category`, `type`, `status`, `title-pattern`, `limit`, `unique` |
| `add-task` | Create new task | Required: `category`, `title`. Optional: `description`, `parent-id`, `type`, `prepend` |
| `update-task` | Update task fields | Required: `task-id`. Optional: `title`, `description`, `design`, `category`, `type`, `status`, `parent-id`, `meta`, `relations` |
| `complete-task` | Mark complete and archive | Identify by `task-id` or `title`. Optional: `completion-comment` |
| `delete-task` | Delete task | Identify by `task-id` or `title-pattern`. Cannot delete with non-closed children |

### 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

```clojure
;; 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