01-task-system

Module 01: Task System

Tasks as the single source of truth.

The Concept

Instead of tracking progress in markdown checkboxes, use Claude Code's built-in task tools:

Tool	Purpose
TaskCreate	Create a new task with metadata
TaskUpdate	Change status, add notes, mark complete
TaskList	See all tasks and their current state
TaskGet	Get details on a specific task

Why This Matters

• Tasks reflect actual state, not someone's guess at state
• in_progress status prevents two agents from working on the same thing
• Metadata (risk, sprint, complexity) enables automation
• TaskList always returns the real picture

Task Lifecycle

              TaskCreate
                  |
                  v
    +---------[pending]---------+
    |             |             |
    v             v             v
[in_progress]  [blocked]   [cancelled]
    |             |
    v             |
[completed] <-----+

Required Metadata

Every task needs three fields:

{
  "project": "myapp",
  "sprint": "sprint-01-setup",
  "risk": "low | medium | high"
}

Risk Levels

Risk	Examples	Behavior
low	Read files, check status, run read-only queries	Proceed freely
medium	Edit code, create files, run npm/pip	Verify after
high	Delete data, deploy, modify auth, destructive git	Get approval

Optional Metadata

{
  "complexity": "routine | medium | complex | novel",
  "scope": "small | medium | large",
  "parallelizable": true,
  "phase": "foundation"
}

Complexity + Risk validation: A task can't be routine complexity with medium or high risk. If it's risky, it's not routine.

Artifact Handoffs

When one task produces output another task needs:

{
  "artifacts": {
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "summary": "Created user API with JWT auth",
    "files_changed": ["src/routes/users.py", "src/models/user.py"],
    "test_hints": ["Test expired tokens", "Test missing email field"],
    "api_contract": {
      "POST /users": "{ email, password } -> { id, token }",
      "GET /users/:id": "-> { id, email, created_at }"
    },
    "breaking_changes": ["User.name renamed to User.display_name"],
    "dependencies_added": ["pyjwt@2.8.0"]
  }
}

This gives downstream agents (tester, integrator) exactly what they need without re-reading everything.

CLAUDE.md Snippet

Copy this into your project's CLAUDE.md:

## Task Discipline

- Use `TaskList` at the start of every session
- Use `TaskUpdate(status="in_progress")` before modifying files
- Use `TaskUpdate(status="completed")` after finishing and verifying
- Include metadata: `{"project": "PROJECT", "sprint": "sprint-XX", "risk": "low|medium|high"}`
- Never track progress in markdown files -- Tasks are the source of truth

Schema

See task-metadata.schema.json for the full JSON Schema definition.