A task format for AI agents.
.tasks is an open format for tracking work that outlives a single session. Tasks are markdown files in your repository, committed alongside the code they describe. No server, no account, no network.
What is .tasks?
It is a directory of markdown files. Each task is one file: a YAML frontmatter block the tooling owns, and a body you write yourself.
The directory a task sits in is its phase — a milestone, a quarter, a workstream, whatever you group work by. That is the whole structure.
.tasks/
├── config.yml # Optional: statuses, default scope
├── auth-rework/ # A phase — just a directory
│ ├── token-schema.md # One task
│ └── wire-refresh.md
├── .archive/ # Deleted tasks, ids stay reserved
└── _index.md # Optional: generated overview---id: token-schemaphase: auth-reworkstatus: PENDINGdepends_on: [audit-current-claims]claimed_by: null---# Design the token schema## Acceptance criteria- [ ] Refresh tokens are single-use
A person with a text editor can do anything the tooling can — and the tooling can repair what they get wrong.
Why .tasks?
An agent working across sessions needs somewhere to put state that survives losing its context. Left alone, it invents something: a TODO.md, a checklist buried in a pull request, a plan rewritten from scratch every session.
None of that survives a second agent working in parallel, and none of it says what is actually ready to start. A shared format gives you:
One source of truth
Task state is committed with the code it describes, so it branches, merges, and reviews like everything else in the repo.
Safe to run in parallel
A task is claimed before it is worked, and a claim takes an exclusive lock. Two agents cannot pick up the same task.
Order that means something
Tasks declare what they wait on, so "what can I start right now" is a real answer instead of a guess.
How does .tasks work?
Every tool that implements the format answers one question the same way: what can be worked on right now? A task is ready when it has not been started and everything it depends on is done.
Describe the work
Create a task in a phase and say what it waits on. The phase directory is created for you.
Claim it
Claiming records who took the task and when, and it fails if the task is blocked or someone else already has it. Claim before working, not after.
Finish it
Completing a task unblocks whatever was waiting on it, so the next
readyanswer is different.
tasks new auth-rework "Wire refresh"✓ Created wire-refresh in phase auth-reworktasks dep add wire-refresh token-schematasks ready ID STATUS PHASE DEPENDS ON UPDATED token-schema PENDING auth-rework — 2026-08-21 09:14# wire-refresh is blocked, so it is not listedtasks claim token-schema✓ Claimed token-schema as dan → IN_PROGRESStasks status token-schema DONE✓ token-schema IN_PROGRESS → DONE# wire-refresh is now ready
Where can you use .tasks?
The format is the interface, so nothing is obliged to shell out to a particular tool. Anything that can read a directory can read a task tree.
The CLI
@speekl/tasks is the reference implementation. It enforces every rule in the specification, and it is the fastest way to try the format.
An agent, directly
Agents already read and write files. An agent can open the directory, parse the frontmatter, and answer what is ready without installing anything.
Something you build
A CI check, an editor plugin, a dashboard, an MCP server. Pick a conformance role and implement against the spec.
An open format
The specification is written independently of any tool and versioned on its own. .tasks v1 is current.
An implementation states which role it fills, so you know what it can be trusted to do. Where the spec and an implementation disagree, that is a bug in one of them.
- Reader
- Parses a tree and answers questions about it. Never writes.
- Writer
- Creates and modifies tasks, preserving every invariant.
- Manager
- Writer, plus claims, validation, repair, and archival.
Who builds it
Dan Zabrotski
Dan writes the .tasks specification and maintains the CLI that implements it. Questions, disagreements with the spec, and implementations of your own are all welcome.