Plan & Task Persistence

Goal

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

Session Start / Post-Compaction / Session Resume

On new session start, after context compaction, or on session resume, perform the following:

1. Consume checkpoints: Check .claude/context-checkpoints/ for any checkpoint files
   • Read each checkpoint file
   • Integrate modified file lists and user decisions into the active task's context-*.md
   • If a checkpoint contains knowledge-worthy findings, invoke record-knowledge
   • Delete consumed checkpoint files
2. Check incomplete work:
   • Git-tracked mode: Read .claude/tasks/readme.md for active plans, then read the active task's latest context-*.md to restore detailed context
   • Issue-centric mode: Check assigned issues (e.g., gh issue list --assignee=@me) for open tasks
3. On progress update, also update the issue tracker (comments, checklists) if applicable.

Progress Update Triggers

• Explicit: User says "progress update" or equivalent → execute immediately
• Implicit: User signals a break or completion (e.g., "thanks", "taking a break", "that's it for today") → suggest "Shall I update progress?" before proceeding
• Milestone: A significant chunk of work is completed → suggest "Shall I update progress?"

Progress update procedure:

1. Check related issues (gh issue list)
2. Post a progress comment (completed work, next steps, related work)
3. Update issue checklists if applicable
4. Commit and push if there are pending changes

Setup

Copy the template files to .claude/tasks/:

mkdir -p .claude/tasks
cp assets/tasks-CLAUDE.md .claude/tasks/CLAUDE.md
cp assets/tasks-readme.md .claude/tasks/readme.md

For Issue-centric mode, also add .claude/tasks/ to .gitignore.

Two Modes

Choose the mode that fits your team's workflow:

Issue-centric mode

When an issue tracker is the primary source of truth:

• .claude/tasks/ is gitignored — add .claude/tasks/ to .gitignore
• Plans and progress live in the issue tracker; .claude/tasks/ is a local scratchpad for the current session
• Anything worth sharing with the team belongs in the issue tracker, not in .claude/tasks/
• At session start, check assigned issues in your tracker instead of .claude/tasks/readme.md

The rest of this document describes Git-tracked mode. For issue-centric mode, adapt the procedures below: use .claude/tasks/ as a local memo and post shared artifacts to the issue tracker.

Git-tracked mode

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              # Handoff notes: current state, next actions, blockers
│   ├── plan-v1.md             # Initial plan (approach, design decisions, context)
│   ├── plan-v2.md             # Revised plan (v1 remains unchanged)
│   ├── todo.md                # Current task progress (frequently updated)
│   ├── context-*.md           # Session context: investigation details, trial & error, decisions
│   └── ...

context-*.md (Session Context Files)

Captures detailed working context that is too granular for plan-vN.md but essential for resuming work after compaction or across sessions. Each file represents a focused context segment.

Naming: context-YYYYMMDD-HHMMSS-topic.md

Format:

---
created: YYYY-MM-DD HH:MM:SS
status: active | consumed
tags: "#tag1 #tag2"
---

## HH:MM - <summary>

<details — investigation findings, configuration tried, error messages, decision rationale>

Lifecycle:

• active: Being written to during the current session
• consumed: Content has been integrated into knowledge entries or a new plan revision; kept for reference but not actively read on session start

Source of truth hierarchy:

Creating a Plan

1. Create .claude/tasks/<slug>-<account>-<date>/ following the naming convention
2. Issue link check (strongly recommended): a. Search for related issues: gh issue list -S "<keywords>" (includes open issues) b. Search closed issues too: gh issue list -S "<keywords>" --state closed to avoid creating duplicate work c. If a related issue exists, use the -i<issue> naming convention (e.g., auth_refactor-i42-bob-20260304/) d. If no issue exists, consider creating one for team visibility before proceeding
3. Search related knowledge: Grep .claude/knowledge/entries/ for tags and keywords related to the plan's topic. Look for:
   • Past pitfalls (#pitfall) that may recur
   • Design decisions and their rationale
   • Related tooling or configuration knowledge
4. Write plan-v1.md with: approach, design decisions, background, completion criteria. If related knowledge was found in step 3, include a Related Knowledge section:
   markdownCopy

   ## Related Knowledge
   - [entry title](../../knowledge/entries/YYYY/MM/slug.md) — why it's relevant
   

5. Capture detailed context: If the plan involves context too detailed for plan-v1.md (investigation results, API behavior, configuration specifics, design trade-off analysis), create context-YYYYMMDD-HHMMSS-topic.md in the task directory. Plans summarize what and why; context files preserve the details that future sessions need to resume work. Only invoke record-knowledge for findings that are universally valuable to the team beyond this specific task
6. Write todo.md with a checkbox task list
7. Write readme.md with the plan's purpose and current state
8. Add an entry to .claude/tasks/readme.md
9. Issue sync: If linked to an issue, update the issue body with the plan summary (approach, phases, completion criteria)

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
• Capture context incrementally: When detailed findings emerge during work (investigation results, root causes, configuration specifics, trial & error), write them to context-*.md in the task directory. This is automated by the PostToolUse hook for file changes, but also write manually for reasoning, decisions, and analysis that don't correspond to file edits. This ensures details survive context compaction
• Promote to knowledge selectively: Only invoke record-knowledge for findings that are universally valuable beyond this specific task (team-shared pitfalls, reusable patterns, tool quirks). Task-specific details stay in context-*.md
• Issue sync: When updating todo.md or readme.md, also update the linked issue (if any) with the same progress. This is not optional — if an issue link exists, keep it in sync

Issue Tracker Sync

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
• Update the issue body or post a progress comment when task status changes

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
• Issue sync: If linked to an issue, update the issue body to reflect the revised plan

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 handoff notes: current state, next actions, any blockers
• Mark completed context files as status: consumed if their content has been fully integrated
• Next session starts by checking .claude/tasks/readme.md for incomplete plans and reading active context-*.md files

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
• Issue sync: If linked to an issue, update the issue with completion status and final summary
• Knowledge extraction (retrospective): Review the completed work and extract lessons learned:
  1. Scan context-*.md files and todo.md for blockers, workarounds, and unexpected discoveries
  2. Check for overlap with existing knowledge entries to avoid duplication — Grep .claude/knowledge/entries/ for key terms from the findings
  3. Compare the plan (what was expected) with the actual outcome (what happened)
  4. For each piece of team-valuable tacit knowledge found (not task-specific details), invoke record-knowledge to create an entry
  5. If related knowledge entries were referenced in the plan, update them with new findings
  6. Mark all context files as status: consumed
• Retrospective prompt: Notify the user with a brief summary:
  • What was completed
  • What knowledge was promoted from context to entries
  • Ask: "Are there lessons from this work not yet captured?"