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 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 to understand what changes to make. Every change is fully defined — exact files, exact behavior, no TBD items.
4. Internal consistency: No contradictions between sections (e.g., scope vs. changes, constraints vs. changes). Every acceptance criterion maps to a change; every change maps to an acceptance criterion.
5. No open questions remain. If any check fails, refuse with details.

Critic exit gate: Invoke /critic to validate spec quality before transitioning.

Phase 1 — Transition (do this first, before any planning work):

1. Move folder to 2-planning/
2. Update task.md: status: planning
3. Create empty plan.md skeleton (frontmatter + headings only, no content)
4. Update INDEX.md
5. Use commit skill: Skill(commit, args: '-m "Tasks: Move #<id> to planning"')

Phase 2 — Build execution plan (only after commit completes): 6. Research the codebase and write the execution plan in plan.md — sequencing, step-by-step implementation order, and test plan for the changes already defined in the spec. Do not redefine what changes to make; that belongs in the spec. 7. If planning reveals spec gaps (missing files, unclear changes), update task.md directly (never plan.md) and commit as a planning-phase spec update. This should be rare — a well-specced task needs no planning-phase amendments.

Critic check: After writing the plan, invoke /critic for self-review before presenting the plan to the user.

Output clickable link: [plan.md](.tasks/2-planning/<id>/plan.md)

Mark Plan Review

/tasks plan-review <id>

Critic check: Before moving, invoke /critic for plan review self-check.

1. Move to 3-plan-review/
2. Update status
3. Update INDEX.md
4. Use commit skill: `Skill(commit, args: '-m "Tasks: Move #<id> to plan-review"

Start Implementing

/tasks implement <id>

1. Move to 4-implementing/
2. Update status
3. Update INDEX.md
4. Use commit skill on main: Skill(commit, args: '-m "Tasks: Move #<id> to implementing"')
5. Create feature branch: feature/task-<id>-<slug>
6. Create worktree at `.