Task Planning

Task Planning

Overview

TASKS.md at the root of the unit of work you are actively in — usually a package, or the directory you're working in when there is no package (e.g. a skill, a hook, a script) — is the durable, committed task ledger for that work. It survives context resets and new sessions, so both you and the user can resume mid-task and see exactly what is done, in progress, and pending.

It is distinct from in-session TodoWrite: TodoWrite is ephemeral scratch for the current turn; TASKS.md is the persistent source of truth that lives in the repo. Use your judgment about when a task warrants one — err toward creating it.

Never reach for a background task chip (spawn_task) to record a follow-up on the work you're doing — that follow-up belongs in TASKS.md. Task chips are only for genuinely separate work that should spin off into its own session.

Projects (registry)

A project is a work-stream — one coherent effort, usually one branch/worktree — with its own TASKS.md (the ledger) and DESIGN.md (the why: spec + decisions). All projects are listed in a committed registry so you and any future session can see everything in flight and resume the right one.

Registry — one entry per project, recording where its docs and PRs live. Its location is not fixed by this skill: the /dxos:project directive ends with a BACKEND: line naming the store (by default the file .agents/projects/registry.yml, overridable via DX_PROJECT_REGISTRY). Obey that line; a future backend is a service rather than a file, and the schema below is the shape either way.

projects:
  - name: mailbox-research # stable slug
    status: active # active | paused | blocked | ended
    user: burdon # owner (git/system username, e.g. `whoami`)
    host: burdon-mbp-2022 # machine the project lives on (`hostname -s`)
    created: 2026-07-05
    summary: One line — what this stream delivers.
    tasks: path/to/TASKS.md # a package file, or <registry-dir>/<name>/TASKS.md
    design: path/to/DESIGN.md # spec + decisions (a REPORT.md counts)
    prs: [12163]
    resume: 'The single next action.'
ended: []

• The registry records the location of each doc, so an existing effort points at its package files and a brand-new project defaults to <registry-dir>/<name>/{TASKS.md,DESIGN.md}. Keep it committed and current.

The /dxos:project command

/dxos:project VERB [ARGS] drives the registry — (bare) | list [all] | tasks | new | end | track | hydrate | resume. The per-verb instructions are not repeated here. The plugin's hooks/track.sh reads the raw typed text on UserPromptSubmit and injects the directive for the verb actually given; that directive is authoritative and arrives whether or not the command expansion does. Follow it, obey its BACKEND: line, and confirm in one short line.

This file covers what applies without the command — the TASKS.md convention, the registry schema, and the handoff steps below — because the skill loads on "work spans several steps" or "resuming work", when nobody has typed anything.

A lone number in the user's next message after a /dxos:project list table means "resume the project at that row". With no argument, resume/hydrate fall back to the single active entry for the current user; if more than one is active, ask which (list them numbered) — never a guess.

The registry deliberately does not record a branch/worktree. Each session runs in a fresh harness-assigned worktree, and a project's original branch is typically already merged to main, so there is nothing stable to match. On resume, never warn about a worktree/branch "mismatch" — a fresh worktree is the expected state — and never leave the assigned worktree to chase the project's old one: do not cd into, edit in, or adopt another worktree or branch as a working directory. If unmerged prior work lives elsewhere, report where it is and ask the user; continuing the work-stream always happens in this session's own worktree.

When to Use

• Work spans 3+ distinct steps, multiple files, or phases.
• The task will likely outlive one session (you'll resume it later).
• The user asks for a plan, roadmap, or to track progress.
• The user uses /dxos:project track <text> — always record the item, never a task chip.
• You are resuming work — read the existing TASKS.md first to reload state.

When NOT to use:

• Throwaway one-offs (a single edit, a quick answer) — just do them.
• Cross-package chores with no single home — keep those in TodoWrite.
• Duplicating TodoWrite — pick one; don't mirror the same list in both.

Location & Format

One file per unit of work: <root>/TASKS.md, where <root> is the package root when there is one (e.g. packages/plugins/plugin-magazine/TASKS.md), or otherwise the directory you're working in (e.g. tools/claude/plugins/dxos/skills/task-planning/TASKS.md). Match the existing convention:

# <Package> — Tasks

## Phase 2: <goal>

Short paragraph of context — what this phase delivers and why.

### Tasks

- [ ] **Headline task**
  - Concrete sub-step with the specific API/file involved.
  - Another sub-step.
- [x] **Completed task** — one-line note on what shipped.

### References

- Links to specs, external docs, related PRs.

• Phases are ##; tasks are - [ ] / - [x]; detail as nested bullets.
• Keep headlines imperative and specific; put the why in the phase context.

Workflow

1. At task start — read the existing TASKS.md (if any) to reload state; otherwise create one with the phase and its tasks.
2. As you work — check off - [x] in the same change that completes the work. Never leave checkboxes stale, and never batch-check everything at the end.
3. When parking a task — leave a one-line status note on the item (what's blocked, what's next) so it's resumable.
4. Before claiming done — reconcile TASKS.md against reality: every checked item is actually complete, and no completed work is left unchecked.
5. Commit it — TASKS.md is committed alongside the work it tracks. Do not leave it as an uncommitted local edit (see "commit nothing silently").

Project handoff (/dxos:project hydrate / /dxos:project resume)

TASKS.md is the handoff medium — no separate HANDOFF.md (keep plans in the original doc). The two verbs are the explicit checkpoint/reload actions.

/dxos:project hydrate — checkpoint before stopping or opening a PR

1. Reconcile TASKS.md — check off what's done; add a one-line status note to each in-progress item (what's blocked, what's next).
2. Refresh the resume pointer — a single italic line under the title: _Resume: <the one next action>. Uncommitted: <none | files>. Last: <what just landed>._
3. Push the why into the design doc (if the work has one — REPORT.md, DESIGN.md, a spec): decisions and findings live there; TASKS.md stays the ledger. Save durable, cross-session direction to memory (it auto-loads next session) — not to a doc.
4. Account for uncommitted work — git status; commit everything or state plainly in the resume pointer what's left uncommitted. Uncommitted work is the number-one thing a resumed session loses.
5. Confirm the checkpoint in one short block (done / in-progress / next / uncommitted).

/dxos:project resume — reload at the start of a session

1. Stay put — resume continues the work-stream in this session's assigned worktree; never cd into or adopt the project's previous worktree/branch. If unmerged prior work lives elsewhere, report it and ask the user.
2. Read the active TASKS.md (and any doc it links); memory is already loaded.
3. Check the tree — git status + recent git log; surface uncommitted work and the last commits.
4. Report a concise state: done / in-progress / next action / uncommitted.
5. Continue with the next action, or wait for direction if the user gave any.

Viewing

Open TASKS.md directly to see it rendered — Claude Code previews Markdown files in the Browser pane, so the checklist is visible while you work.

Common Mistakes