Working with Tasks

Tasks are how kli tracks work across sessions. A task is a directory with an append-only event log that records everything Claude does — observations, decisions, artifacts, and state changes. Tasks persist between sessions, so you can stop and resume without losing context.

Creating a Task

/kli:create-task

Claude asks what you're working on, creates the task directory, and sets it as the active task for the session. From this point, observations and artifacts are recorded against the task.

You don't always need to create a task explicitly. Running /kli:plan on an existing task or /kli:research will create or attach to tasks as needed.

Resuming a Task

/kli:resume-task

Claude finds your active and recent tasks, lets you pick one, and loads its full context — observations, artifacts, graph neighbors, and any handoffs from previous sessions.

Task Lifecycle

Tasks progress through three states:

1. Created — Initial state with a birth certificate describing the work
2. Active — Claude is working on the task, recording observations and artifacts
3. Completed — All work finished; the task rejects further mutations

Phases

When you run /kli:plan, Claude breaks work into phases. Each phase is itself a task, linked to the parent plan with phase-of edges. Phases can depend on each other — Claude tracks these dependencies and only works on phases whose dependencies are complete.

During /kli:implement, Claude queries the plan to find the next ready phase, works on it, marks it complete, and moves to the next. You see this as a sequence of implementation steps with approval gates between them.

The Task Graph

Tasks form a directed acyclic graph (DAG). Edges between tasks carry meaning:

Edge	Meaning
phase-of	Subtask/phase of a parent plan
depends-on	Must complete before this task starts
related-to	Informational relationship
references	Links to research or prior work
same-day	Automatically linked tasks from the same day
topic	Semantically similar tasks

Claude uses the graph to find ready phases, track dependencies, detect related work from previous sessions, and coordinate parallel sessions. You don't interact with the graph directly — Claude handles all queries and mutations through the task MCP server.

Observations

As Claude works, it records observations — discoveries, constraints, decisions, and outcomes. These are timestamped entries in the task's event log. Observations serve two purposes:

1. Session context — When you resume a task, Claude replays observations to understand what happened previously
2. Pattern source — During /kli:reflect, observations that are transferable and actionable get promoted to playbook patterns

You can direct Claude to record specific observations, but it also records them naturally during research and implementation.

The Event Log

Every task mutation is recorded as an immutable event in events.jsonl. The current state is computed by replaying events — there is no mutable database. This gives you full history of what happened during a task.

Claude records these event types as it works:

session.join     — Claude started working on a task
session.claim    — Claude took exclusive ownership for conflict-sensitive work
observation      — Knowledge captured during work
task.complete    — Task marked as finished
task.reopen      — Completed task reopened
metadata.set     — Key-value metadata updated
edge.add         — Graph edge created
edge.remove      — Graph edge severed
handoff.create   — Handoff document generated

Handoffs

When you need to continue work in a new Claude Code session:

/kli:handoff

Claude writes a handoff document summarizing the current state — what's done, what's in progress, key learnings, and recommended next steps. The handoff is stored in the task directory.

To resume:

/kli:resume_handoff

Claude reads the handoff, verifies the current state matches expectations, and presents an action plan for continuing.

Parallel Sessions

Multiple Claude Code sessions can work on related tasks simultaneously. The task system handles this through:

• Session tracking — Each session registers when it joins a task
• File conflict detection — A hook warns when you edit a file recently touched by another session
• CRDT merging — Events from different sessions merge automatically using conflict-free replicated data type semantics: observations append (no conflicts possible), metadata uses last-writer-wins per key, edges are add/remove sets, and status uses max-progress ordering

The session-start hook shows you when parallel sessions are active so you're aware of concurrent work. Event sourcing means you always have a full audit trail — if something went wrong, the event log shows exactly what happened and when.