task-tracker

Files (4)

• SKILL.md
• YTTRI.md
• tasks.py · scripts/
• test_tasks.py · scripts/

SKILL.md (first lines)

# Task Tracker — Managing tasks in TASKS.md

Script: `<SKILL_DIR>/scripts/tasks.py`, where `<SKILL_DIR>` is this skill's
installed directory — e.g. `~/.claude/skills/task-tracker` (user scope) or
`.claude/skills/task-tracker` (project scope). Substitute the real path in
every command below.

Two files, both in the project root:

| File | Holds | Written by |
|------|-------|------------|
| `TASKS.md` | Active tasks (and Backlog, until it's split off) | `add`, `update`, `promote` |
| `TASKS_BACKLOG.md` | Backlog — someday/maybe, once `split-backlog` ran | `add-backlog`, `promote` |
| `TASKS_ARCHIVE.md` | Everything finished this year, in dated sections, newest on top | `archive`, `archive-done`, `migrate-archive` |

**A status is closed only when its marker LEADS the cell.** Real statuses are
long and quote per-phase progress inside the text — «🔄 In progress — phases
1-5/7 ✅», «👀 In review — all 7 phases ✅». Matching ✅ anywhere in the cell
files live work into the archive (caught in Yttri on 2026-08-20, two active
tasks one command away from being archived). `is_done_status` /
`is_cancelled_status` / `is_in_progress_status` in `tasks.py` are the single
place that decides this; tests in `StatusMarkerTests` hold the line.
| `TASKS_ARCHIVE_YYYY.md` | Past years, split off once the year turns | `rotate-archive` |

`TASKS.md` is the file that gets read into context on every session, so it has
to stay small. Completed tasks belong in the archive file, not in it.

## When to activate

- The user asks: "tasks", "status", "what's left", "show tasks"
- The user requests: "update TASKS.md", "mark task as done"
- **After context compaction** — if the user continues work on a task
- When a new plan is created (to register it in TASKS.md)
- When a task is completed (to update its status)

## Script commands

All commands return JSON. Run from the project root.

### Reading

```bash
# All tasks (active + backlog) with a summary
python3 <SKILL_DIR>/scripts/tasks.py list

# Active tasks only
python3 <SKILL_DIR>/scripts/tasks.py active

# Backlog only
python3 <SKILL_DIR>/scripts/tasks.py backlog

# Details of a single task
python3 <SKILL_DIR>/scripts/tasks.py show T-001

# Next free ID
python3 <SKILL_DIR>/scripts/tasks.py next-id
```

### Writing

```bash
# Update task status (Active tasks only — Backlog has no Status column)
python3 <SKILL_DIR>/scripts/tasks.py update T-001 "✅ Done"

# Add a task to Active
python3 <SKILL_DIR>/scripts/tasks.py add "Task title" "docs/plans/plan.md"

# Add a task to Backlog
python3 <SKILL_DIR>/scripts/tasks.py add-backlog "Title" "docs/plans/plan.md" "Note"

# Backlog → Active (keeps the ID, the Note column becomes 📝 Planning)
python3 <SKILL_DIR>/scripts/tasks.py promote T-009
```

### Splitting the backlog off

```bash
# One-shot: move the "## 📦 Backlog" section into TASKS_BACKLOG.md
python3 <SKILL_DIR>/scripts/tasks.py split-backlog
```

Worth doing when the backlog is a meaningful share of `TASKS.md` — it's
someday/maybe work that isn't needed in context for today's task. Every
backlog command routes through the file automatically, so a project that
never splits keeps working exactly as before.

### Archiving (moves rows out to `TASKS_ARCHIVE.md`)

```bash
# One or several tasks
python3 <SKILL_DIR>/scripts/tasks.py archive T-001 T-002

# Every CLOSED task at once (✅ done and ❌ cancelled) — the usual answer to
# overflow. The marker is read from the START of the status cell, so a live
# task reporting "🔄 In progress — phases 1-5/7 ✅" is never swept up.
python3 <SKILL_DIR>/scripts/tasks.py archive-done

# One-shot for older projects: pull the in-file "## ✅ Archived …" sections
# out of TASKS.md into TASKS_ARCHIVE.md
python3 <SKILL_DIR>/scripts/tasks.py migrate-archive

# Keep the archive to the current year — past years get TASKS_ARCHIVE_YYYY.md
python3 <SKILL_DIR>/scripts/tasks.py rotate-archive
```

The whole table row travels, so the plan link and the final status survive.
IDs are never reused — `next-id` scans every archive file, rotated ones too.

## Workflow: Show tasks

When the user asks to show tasks:

1. Run `python3 <SKILL_DIR>/scripts/tasks.py active`
2. Get the JSON with tasks
3. Output to the user in a readable format:
   - 🔄 In progress tasks — highlight as current
   - ✅ Done tasks — mark as completed
   - Show an overall summary (how many in progress, how many done)
4. **If TodoWrite/task tool is available**: sync 🔄 tasks to track them in the UI.

From askidmobile/ai-spec-kit, MIT.

More from askidmobile/ai-spec-kit