Plan & Task Persistence

Goal

Maintain plans and task progress across Claude Code sessions so that work can be resumed without losing context.

When to Use

• Starting a multi-step task that may span multiple sessions
• Resuming work — check .claude/tasks/readme.md for incomplete plans
• Updating progress on an existing plan
• Closing out or archiving a completed plan

Directory Naming

.claude/tasks/<slug>-<account>-<date>/           # Without issue reference
.claude/tasks/<slug>-i<issue>-<account>-<date>/  # With issue reference

• Separate components with - (hyphen)
• Separate words within slug with _ (underscore)
• Slug uses lowercase alphanumeric only; date is YYYYMMDD
• Example: docker_migration-alice-20260304/
• Example: auth_refactor-i42-bob-20260304/

Directory Structure

.claude/tasks/
├── readme.md                  # Index of all plans (status and summary)
├── <slug>-<account>-<date>/
│   ├── readme.md              # Purpose, current state, file listing
│   ├── plan-v1.md             # Initial plan (approach, design decisions, context)
│   ├── plan-v2.md             # Revised plan (v1 remains unchanged)
│   ├── todo.md                # Current task progress (frequently updated)
│   └── ...

Creating a Plan

1. Create .claude/tasks/<slug>-<account>-<date>/ following the naming convention
2. Write plan-v1.md with: approach, design decisions, background, completion criteria
3. Write todo.md with a checkbox task list
4. Write readme.md with the plan's purpose and current state
5. Add an entry to .claude/tasks/readme.md

Working on Tasks

• Update todo.md only — do not modify plan files
• Mark task status: - [ ] (pending) → - [~] (in progress) → - [x] (done)
• Record discovered issues or blockers indented below the relevant task
• Add new task lines to todo.md as work expands

Issue Tracker Sync (Optional)

If the plan is linked to an issue in your project's issue tracker:

• Check the issue for updates before starting work on .claude/tasks/
• Reflect any direction changes or new comments into .claude/tasks/
• Include the issue reference in commit messages
• Post progress comments to the issue when milestones are reached

Revising a Plan

• Do NOT edit existing plan-vN.md files — create plan-vN+1.md instead
• Reset todo.md to match the new plan (carry over incomplete items)
• Update <slug>/readme.md with which version is current and why the revision was needed
• Claude Code reads only the latest plan-vN.md and todo.md

Committing Progress

• Commit when task progress changes (completion, blockers found, etc.)
• If linked to an issue, report progress there as well

Pausing or Completing Work

On session end or interruption

• Update <slug>/readme.md with current state and handoff notes
• Next session starts by checking .claude/tasks/readme.md for incomplete plans

On plan completion

• Mark all tasks in todo.md as done
• Update <slug>/readme.md state to "completed"
• Move the entry in .claude/tasks/readme.md from the active table to the completed table