What You’ll Learn

• The difference between in-session todos and durable tasks
• How to implement a file-based task graph with dependencies
• How tasks coordinate work across sessions

The Problem

Todo lists live and die with a session. A multi-day project needs tasks that persist across sessions, with dependencies, status, and ownership.

The Solution

A file-based task system with CRUD operations and dependency graphs.

tasks/
  task-001.json  {"id": "001", "title": "Set up CI", "deps": [], "status": "done"}
  task-002.json  {"id": "002", "title": "Add tests", "deps": ["001"], "status": "in_progress"}
  task-003.json  {"id": "003", "title": "Deploy",    "deps": ["002"], "status": "pending"}

How It Works

1. Each task is a JSON file with id, title, description, dependencies, status.

2. A TaskManager provides CRUD + dependency resolution.

class TaskManager:
    def __init__(self, tasks_dir: Path):
        self.tasks_dir = tasks_dir

    def create(self, title, deps=None) -> str:
        task = {"id": uuid4(), "title": title, "deps": deps or [],
                "status": "pending"}
        (self.tasks_dir / f"{task['id']}.json").write_text(
            json.dumps(task, indent=2))
        return task["id"]

    def ready(self, task_id) -> bool:
        task = self.get(task_id)
        return all(self.get(d)["status"] == "done" for d in task["deps"])

3. The agent uses task_create, task_list, task_update tools.

What Changed From s11

Component	Before (s11)	After (s12)
Planning	In-session todos	File-based task graph
Persistence	None	JSON files per task
Dependencies	None	deps field + resolution

Try It

cd learn-claude-code
python agents/s12_task_system.py

1. Create a task plan for building a CLI tool with 5 subtasks
2. List all tasks and their dependencies
3. Mark a task as done and check which tasks are now ready

Key Takeaway

Todo lists help a session; durable task graphs coordinate work that outlives it. Persist tasks to disk with explicit dependencies.