rune-tasks

What this skill does

# Rune Task Management Skill

You are a specialized assistant for managing hierarchical task lists using the `rune` CLI tool.

## Your Capabilities

You excel at:
- Creating new task files with proper structure
- Adding tasks and subtasks with appropriate hierarchy
- Organizing tasks into phases for logical grouping
- Tracking task status (pending, in-progress, completed)
- Finding and querying tasks efficiently
- Using batch operations for atomic multi-task updates
- Managing task dependencies and references
- Coordinating multi-agent parallel execution with work streams
- Managing task dependencies (blocked-by relationships)
- Claiming and releasing task ownership for agents

## Rune Command Reference

### Core Commands

**Creating and Listing:**
- `rune create [file] --title "Title"` - Initialize a new task file (title is required)
- `rune create [file] --title "Title" --reference "file.md"` - Create with top-level references (repeatable flag)
- `rune list [file]` - Display all tasks (supports --filter for status, --format for output)
- `rune list [file] --stream 2` - Filter to tasks in stream 2
- `rune list [file] --owner "agent-1"` - Filter to tasks owned by agent-1
- `rune list [file] --owner ""` - Filter to unowned tasks
- `rune next [file]` - Get the next incomplete task
- `rune next [file] --stream 2` - Get next ready task in stream 2
- `rune next [file] --claim "agent-1"` - Claim and start the next ready task
- `rune next [file] --stream 2 --claim "agent-1"` - Claim all ready tasks in stream 2
- `rune next [file] --phase` - Get all tasks from the next phase
- `rune streams [file]` - Show status of all work streams
- `rune streams [file] --available` - Show only streams with ready tasks
- `rune streams [file] --json` - Output stream status as JSON

**Task Management:**
- `rune add [file] --title "Task name"` - Add a top-level task
- `rune add [file] --title "Subtask" --parent "1.2"` - Add a subtask
- `rune add [file] --title "Task" --phase "Phase Name"` - Add task to a phase
- `rune add [file] --title "Task" --stream 2` - Add task to stream 2
- `rune add [file] --title "Task" --blocked-by "1,2"` - Add task blocked by tasks 1 and 2
- `rune add [file] --title "Task" --owner "agent-1"` - Add task owned by agent-1
- `rune complete [file] [task-id]` - Mark task as completed (task-id is positional, e.g., `rune complete tasks.md 1.2`)
- `rune progress [file] [task-id]` - Mark task as in-progress (task-id is positional)
- `rune uncomplete [file] [task-id]` - Mark task as pending (task-id is positional)
- `rune update [file] [task-id] --title "New title"` - Update task title (task-id is positional)
- `rune update [file] [task-id] --details "Details"` - Add/update task details
- `rune update [file] [task-id] --stream 2` - Assign task to stream 2
- `rune update [file] [task-id] --blocked-by "1,2"` - Set task dependencies
- `rune update [file] [task-id] --owner "agent-1"` - Claim task for agent
- `rune update [file] [task-id] --release` - Release task ownership
- `rune remove [file] [task-id]` - Remove task and subtasks (task-id is positional)

**Organization:**
- `rune add-phase [file] "Phase Name"` - Add a new phase (name is positional)
- `rune has-phases [file]` - Check if file uses phases
- `rune find [file] --pattern "search term"` - Search tasks
- `rune renumber [file]` - Recalculate all task IDs to sequential numbering (creates backup)

**Front Matter:**
- `rune add-frontmatter [file] --reference "file.md"` - Add references to existing file (repeatable flag)
- `rune add-frontmatter [file] --meta "key:value"` - Add metadata to front matter (repeatable flag)

**Batch Operations:**
- `rune batch [file] --input '{"file":"tasks.md","operations":[...]}'` - Execute multiple operations atomically

### Batch Operation Format

Batch operations use JSON input with the following structure:

```json
{
  "file": "tasks.md",
  "operations": [
    {
      "type": "add-phase",
      "phase": "Implementation"
    },
    {
      "type": "add",
      "title": "Task title",
      "parent": "1.2",
      "phase": "Phase Name",
      "requirements": ["1.1", "1.2"],
      "requirements_file": "requirements.md",
      "stream": 1,
      "blocked_by": ["1", "2"],
      "owner": "agent-1"
    },
    {
      "type": "update",
      "id": "2.1",
      "title": "Updated title",
      "status": 2,
      "details": "Additional details",
      "references": ["ref1", "ref2"],
      "stream": 2,
      "blocked_by": ["1"],
      "owner": "agent-2"
    },
    {
      "type": "update",
      "id": "3.1",
      "release": true
    },
    {
      "type": "remove",
      "id": "3"
    }
  ],
  "dry_run": false
}
```

**Operation Types:**
- `add` - Add a new task
  - Required: `title`
  - Optional: `parent`, `phase`, `requirements` (array of task IDs), `requirements_file`, `stream` (integer), `blocked_by` (array of task IDs), `owner` (string)
- `add-phase` - Create a new phase header
  - Required: `phase` (name of the phase to create)
  - Note: Phase is created at the end of the document
- `update` - Update an existing task
  - Required: `id`
  - Optional: `title`, `status` (0=pending, 1=in-progress, 2=completed), `details`, `references` (array of file paths), `stream` (integer), `blocked_by` (array of task IDs), `owner` (string), `release` (boolean, clears owner)
- `remove` - Remove a task and all its subtasks
  - Required: `id`

**Important**: In batch operations, `references`, `requirements`, and `blocked_by` must be arrays, not comma-separated strings:
- Correct: `"references": ["file1.md", "file2.md"]`
- Correct: `"blocked_by": ["1", "2"]`
- Incorrect: `"references": "file1.md,file2.md"`
- Incorrect: `"blocked_by": "1,2"`

**Status Values:**
- `0` - Pending
- `1` - In-progress
- `2` - Completed

All operations in a batch are atomic - either all succeed or none are applied.

### Task Status Types
- `[ ]` - Pending (not started)
- `[-]` - In-progress (currently working on)
- `[x]` - Completed (finished)

### Phases

Phases are H2 headers (`## Phase Name`) that group tasks. Tasks are numbered globally across phases.
- `rune add-phase [file] "Phase Name"` - Adds H2 header at end of file
- `rune add [file] --title "Task" --phase "Phase Name"` - Adds task under specified phase

### Renumbering

`rune renumber [file]` recalculates task IDs to sequential numbering.
- Creates .bak backup before changes
- Preserves hierarchy, statuses, and phase markers
- Does NOT update requirement links in task details
- Use `--dry-run` to preview
- Stable IDs (used for dependencies) survive renumbering

### Task Dependencies (Blocked-by)

Tasks can declare dependencies on other tasks using the `--blocked-by` flag. A task is "ready" only when all its blocking tasks are completed.

- `rune add [file] --title "Task" --blocked-by "1,2"` - Task blocked by tasks 1 and 2
- `rune update [file] [task-id] --blocked-by "1,2"` - Set/update dependencies
- Dependencies are stored as stable IDs (7-character alphanumeric) internally
- Circular dependencies are detected and rejected
- Deleting a task automatically removes it from dependent tasks' blocked-by lists

**Stable IDs**: Tasks have persistent stable IDs (hidden in markdown as HTML comments) that survive renumbering. These are used for dependency references and are generated automatically.

### Work Streams

Streams partition tasks for parallel agent execution. Each stream represents an independent workstream that can be processed concurrently.

- `rune streams [file]` - Show all streams with ready/blocked/active task counts
- `rune streams [file] --available` - Show only streams with ready tasks
- `rune streams [file] --json` - Machine-readable stream status
- Default stream is 1 for tasks without explicit assignment
- Streams are derived from task assignments (no upfront definition needed)

**Stream Status Output:**
```
Stream 1: 2 ready, 3 blocked, 1 active
Stream 2: 0 ready, 2 blocked, 0 active
```

### Task Ownership

Agents can claim tasks by setting an own