/tasks

name: tasks
description: Manage tasks and plans using the .tasks/ directory.
model: opus

Task Management Skill

Manage the project backlog, track progress, and organize implementation plans.

---

Directory Structure

.tasks/
├── INDEX.md              # Index file - task numbers, titles, links
├── 0-inbox/              # Open tasks (not yet started)
├── 1-speccing/           # Spec being refined (interactive solicitation)
├── 2-planning/           # Plan being created
├── 3-plan-review/        # Plan review checkpoint
├── 4-implementing/       # Currently being worked on
├── 5-reviewing/          # Implementation complete, under review
├── 6-complete/           # Done
├── 7-rejected/           # Rejected or irrelevant
└── 8-consolidated/       # Consolidated into other tasks

**Note:** `.gitkeep` files ensure empty directories are tracked in git. Do not delete these files.

Each task is a folder named by its ID containing:

• `task.md` - the task description and metadata
• `plan.md` - the execution plan — implementation order, sequencing, and test plan (created during planning phase)
• `changes.md` - file changes summary (generated during review or before completion)

**Note:** Priority (high/medium/low) is a frontmatter field, not a directory. Tasks are organized by status in directories. In INDEX.md, priority sub-sections appear under the Inbox heading.

**Reference:** See [schemas.md](schemas.md) for full task/plan schemas and templates.

---

Commands

View Backlog

/tasks
/tasks list

Read `.tasks/INDEX.md` and display **all** non-archival tasks in a single markdown table. Omit Complete, Rejected, and Consolidated sections (archival). Never truncate, summarize, or collapse rows.

Render task references as clickable markdown links:

• If task has a plan.md file: link to plan.md, e.g., `[#67](.tasks/2-planning/67/plan.md)`
• Otherwise: link to task.md, e.g., `[#67](.tasks/0-inbox/67/task.md)`

**Table format** — one table, four columns: `Status`, `Priority`, `#`, `Task`:

| Status | Priority | # | Task |
|--------|----------|---|------|

**Status column values:**

• `📝 Speccing`
• `📐 Planning`
• `✅ Plan Review`
• `🔨 Implementing`
• `🔍 Reviewing`
• `📥 Inbox` (for tasks in 0-inbox/)

**Priority column values:**

• `🔴 High`
• `🟡 Med`
• `🔵 Low`
• `⚪ —` (unprioritized or null)

Read the `priority` field from each task's `task.md` frontmatter to populate the Priority column for all tasks, including active ones.

**Sort order:** Active statuses first (in the order listed above), then inbox tasks by priority (high, med, low, unprioritized). Within each group, sort by task ID descending.

End with a summary line:

**N open** — X high, Y med, Z low, W unprioritized

---

View Single Task

/tasks 19

Find and read the task file at `<status-dir>/19/task.md`.

---

Add New Task

/tasks add <description>

1. Determine next task number (highest N + 1) 2. Create `0-inbox/<N>/task.md` 3. Add to INDEX.md under Inbox 4. Use commit skill: `Skill(commit, args: '-m "Tasks: Add #<N>"')`

---

Prioritize Task

/tasks prioritize <id> <high|medium|low>

1. Update `task.md` frontmatter `priority` field 2. Move entry to correct priority sub-section under Inbox in INDEX.md 3. Use commit skill: `Skill(commit, args: '-m "Tasks: Prioritize #<id> as <priority>"')`

---

Start Speccing

/tasks spec <id>

Moves a task from inbox (or back from planning) to speccing, then interactively solicits the task spec from the user.

**From inbox:** Move folder to `1-speccing/`, update status to `speccing`, update INDEX.md, commit. Then begin interactive solicitation.

**From planning (back-transition for substantial rework):** Move folder back to `1-speccing/`, update status to `speccing`, update INDEX.md, commit. Then resume solicitation.

**Solicitation:** Ask guiding questions to fill in the 6 required sections (Description, Motivation, Scope, Constraints, Changes, Acceptance Criteria). Iterate as many times as needed — never rush the user toward planning. Only the user decides when the spec is complete.

**All decisions in the spec:** Every change must be fully defined during speccing — exact files, exact changes, no ambiguity. Never defer decisions to planning or label anything a "planning detail." Planning builds an execution plan for changes already decided here.

**Self-sufficiency check:** After each round of user input, re-read the spec and actively check for:

• **Gaps:** Changes referenced in acceptance criteria but missing from the Changes table (or vice versa). Scope items with no corresponding change.
• **Contradictions:** Constraints that conflict with proposed changes. Scope "out of scope" items that overlap with listed changes.
• **Ambiguity:** Changes described vaguely enough that two people could interpret them differently.

If any issues are found, raise them as open questions — one at a time, resolved before moving on. Do not suggest moving to planning while open questions exist.

**Never suggest planning prematurely.** Do not prompt the user to move to planning. When the user signals the spec is ready, run the validation gate. If it fails, explain what's missing and continue iterating.

Use commit skill: `Skill(commit, args: '-m "Tasks: Move #<id> to speccing"')`

---

Start Planning

/tasks plan <id>

**Precondition:** Task must be in `speccing` status. If not, refuse with: "Task #<id> must be specced before planning. Use `/tasks spec <id>` first."

**Speccing validation gate:** Before transitioning, verify: 1. All 6 required sections (Description, Motivation, Scope, Constraints, Changes, Acceptance Criteria) have meaningful content — not trivial one-liners or placeholders. 2. Every acceptance criterion has an external verification method (a command, test, grep, or observable output) — not just "Claude reads the file and confirms." 3. **Self-sufficiency:** The spec requires no further research