Tasks Md

TASKS.md

[](https://github.com/tasksmd/tasks.md/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@tasks-md/parser) [](https://www.npmjs.com/package/@tasks-md/lint) [](https://www.npmjs.com/package/@tasks-md/cli) [](https://www.npmjs.com/package/tasks-mcp)

A lightweight spec for AI agent task queues — the companion to AGENTS.md.

Website · [Spec](spec.md) · [Examples](examples/) · [MCP Server](packages/mcp/) · [Linter](packages/lint/)

AGENTS.md tells agents how to work. TASKS.md tells them what to work on.

Highlights

• One Markdown file any agent or human reads and writes — no accounts, no API, no server, works offline.
• In your editor, in git — add a task without leaving your IDE; every change is version-controlled next to the code.
• Agent-native — LLMs parse Markdown directly, and the [/next-task](#the-next-task-command) command turns the queue into an autonomous work loop.
• Vendor-neutral — one spec, six agents (Claude Code, Cursor, Devin, Codex, Gemini CLI, Windsurf), any CI.
• Scales with you — start solo on the file backend; switch to the collision-free [git-native backend](#backends) the instant a second writer or a fleet of agents shares the queue — configuration, never a migration.

Installation

Two ways to add TASKS.md to a repo. Both are idempotent — safe to re-run, they merge and never clobber.

1. Copy this prompt into your agent

Paste this into whatever agent you use (Claude Code, Cursor, Devin, Codex, Gemini CLI, Windsurf) and it does the rest — scaffolds the queue, wires up AGENTS.md, installs its own /next-task command, verifies, and reports back:

Set up tasks.md in this repo: run `npx -y @tasks-md/cli init --install` to create
TASKS.md and a "## Task Management" section in AGENTS.md, then install your own
/next-task command with `npx -y @tasks-md/cli install --agent `, verify
with `npx -y @tasks-md/lint TASKS.md`, and tell me what you did. If Node isn't
available, write the files directly from https://github.com/tasksmd/tasks.md.

The same steps ship as a /setup command for all six agents — see [commands/setup.md](commands/setup.md).

2. Or run this single command

npx @tasks-md/cli init --install

Creates TASKS.md, adds (or creates) a ## Task Management section in AGENTS.md, and installs the /next-task command for every agent it detects in the repo. Drop the npx prefix after a global npm install -g @tasks-md/cli. Running a fleet — a team of machines each driving parallel agents on one queue? Also run tasks fleet init to switch to the collision-free [git-native backend](spec.md#fleet-coordination).

What a TASKS.md looks like

No Node required — this is the whole format, and you can write it by hand. Most tasks are just checkboxes under priority headings; metadata is optional and added only when a task needs context:

# Tasks

## P0

- [ ] Fix authentication crash on token refresh
  - **ID**: auth-fix
  - **Details**: JWT refresh returns 500 on expired tokens
  - **Files**: `src/auth/refresh.ts`, `src/middleware/auth.ts`
  - **Acceptance**: Refresh works, tests pass, regression test added

## P1

- [ ] Add rate limiting to public API endpoints
  - **Blocked by**: auth-fix
- [ ] Migrate database queries to prepared statements

## P2

- [ ] Update README with new API endpoints

Tasks with dependencies get an ID so blockers can reference them stably. That's the zero-setup file backend (best-effort (@you) claims) — perfect for a solo repo. The moment you have more than one writer, switch to the collision-free [git-native backend](#backends) with /migrate so two agents can never grab the same task.

Worked example: first 10 minutes

Nine commands take a fresh repo from zero to a queue an agent can pick from. Output snippets below are real (tasks here is npx -y @tasks-md/cli — npm install -g @tasks-md/cli once to drop the npx -y prefix).

1. Bootstrap a project.

``bash mkdir my-project && cd my-project && git init -q echo "# README" > README.md && git add README.md && git commit -m "feat: init" ``

1. Scaffold the queue — tasks init writes TASKS.md and creates (or updates) a ## Task Management section in AGENTS.md.

``bash npx -y @tasks-md/cli init ` Prints ✓ Created TASKS.md and ✓ Created AGENTS.md with Task Management section`.

1. Install the /next-task command for your agent — auto-detects from agent dirs (.claude/, .cursor/, .devin/, etc.). See [story 3 → Auto-detect algorithm](docs/user-stories/03-agents-work-through-queue.md#auto-detect-algorithm) for the full table.

``bash npx -y @tasks-md/cli install ``

1. Edit TASKS.md — paste these two tasks under the existing priority headings:

```markdown ## P0

• [ ] Fix the crash on startup
• ID: fix-startup
• Details: Service exits 1 when DATABASE_URL is missing.

## P1

• [ ] Add request logging middleware
• Tags: backend

```

1. Pick the next task — read-only inspection of what /next-task would claim.

``bash npx -y @tasks-md/cli pick ` ` Picked "Fix the crash on startup" (P0) File: TASKS.md:5 ID: fix-startup Details: Service exits 1 when DATABASE_URL is missing. Candidates: 2 ``

1. Validate the queue against the spec.

``bash npx -y @tasks-md/lint TASKS.md # → Checked 1 file(s), found 0 error(s) ``

1. Check queue health.

``bash npx -y @tasks-md/cli stats ` ` 📋 Queue Overview P0 P1 P2 P3 Total 1 1 0 0 2 Blocked: 0 Claimed: 0 Available: 2 Files: 1 ``

1. Commit, then look at queue changes since the last commit.

``bash git add TASKS.md && git commit -m "chore: queue 2 items" echo "- [ ] Update README" >> TASKS.md npx -y @tasks-md/cli diff # → ➕ Added (1): Update README ``

1. Run the autonomous loop — /next-task from inside your agent picks, claims, works, removes, and repeats. See [story 3](docs/user-stories/03-agents-work-through-queue.md) for the precise picking algorithm and [story 6](docs/user-stories/06-issue-tracker-flows-to-agents.md) when you want issues from GitHub / Jira / Linear feeding the queue automatically.

Why TASKS.md?

You think faster than agents can code. Ideas come in bursts — while an agent implements one feature, you've already thought of three more. Without a queue, those ideas live in your head or scatter across chat windows. TASKS.md is your buffer: write tasks down as they come, and agents work through them at their own pace.

Planning first leads to better results. When you write a task down — even a one-liner — you're forced to think about what you actually want before the agent starts coding. That small act of planning is the difference between an agent that builds the right thing and one that guesses. TASKS.md makes planning the natural first step, not an afterthought.

Zero friction beats any tool. Opening Jira to write a task takes you out of flow — you switch context, fill in fields, pick a project, assign a sprint. With TASKS.md, you add a line to a file that's already open in your editor. The lower the friction, the more likely you are to actually write tasks down — and written tasks are the whole point.

How It Works

1. Plan — Write tasks under P0–P3 priority headings as ideas come to you
2. Delegate — Agent reads the file, claims a task with (@agent-name), implements it
3. Remove — Completed tasks are deleted from the file; history lives in git log
4. Repeat — You keep adding tasks while agents keep working through them

You're always adding to the queue; agents are always draining it. No ideas get lost, and agents never run out of work.

The contract is the same on every backend: humans read the queue and tell agents what to do; agents (or tools) mutate task state. In the default file backend the file is the surface, so hand-editing TASKS.md is the zero-setup path. In a generated backend the queue is a projection and an agent runs the operation — but the human's experience ("add a task", "mark it done") is unchanged.

Backends

TASKS.md (local markdown) is the default, zero-infra backend. The same spec / parser / CLI / MCP surface can target another backend — switching is configuration in .tasksmd.json, never a migration ([spec.md § Task backends](spec.md#task-backends)):

| Backend | Capability | Use it when | |---|---|---| | File (tasks-md, default) | spec-compatible, offline, human-editable TASKS.md, best-effort claims | solo or offline — the zero-setup default | | Git-native (recommended for shared repos) | spec-compatible, collision-free claims via git ref compare-and-swap; TASKS.md becomes a generated snapshot | more than one writer: a multi-contributor project, or a fleet of machines each running parallel agents on one queue ([Fleet coordination](spec.md#fleet-coordination)). Run tasks fleet init | | GitHub Issues | spec-compatible, infra-required (a tracker) | a team already living in GitHub Issues | | Atomic queue / MCP broker | server-backed | only where that infra already exists |

"Collision-free" means no two agents ever hold the same task at once — not a globally reproducible race winner; only the fold of the log is reproducible. Move an existing file queue to git-native with the /migrate command (or tasks migrate --apply then tasks fleet init) — it imports your current TASKS.md into the log first, so no task is lost. The portable layer is the spec; the coordination is borrowed. This repo runs git-native to dogfood it (G8) — its own TASKS.md is a generated snapshot, produced by the very /migrate path you'd run.

Writing your own backend? Any backend works behind the same surface if it passes the capability-scoped [@tasks-md/conformance](packages/conformance/) suite — implement a ConformanceTarget, run it, and publish the JSON report. tasks.md is not a backend registry; you self-certify which compatibility classes (file / operation / collision-free) you support.

Workspaces (many repos, one queue)

Have a parent folder of repos that each carry a TASKS.md? Workspace mode picks the highest-priority unblocked task across all of them:

tasks next --workspace ~/apps/tooling          # one workspace
tasks next --workspaces ~/apps/tooling,~/apps/oncall-hub   # several
tasks workspaces add ~/apps/tooling --name tooling          # save to config
tasks next                                      # no flag → aggregate all configured

Declared workspaces live in ~/.config/tasks-md/workspaces.json; once configured, plain tasks next aggregates across them and prints :::. Tasks can depend across repos (**Blocked by**: api#fix) or across workspaces (**Blocked by**: oncall-hub::api#fix). With no config and no flag, tasks next reads the local ./TASKS.md as before. See [spec.md § Workspaces](spec.md#workspaces).

Writing Good Tasks

The quality of your task description directly affects the quality of the agent's output. A task is a small contract between you and the agent — the more specific you are, the better the result.

A one-liner is fine for obvious work:

- [ ] Add input validation to the /users endpoint

Add metadata when the task needs context:

- [ ] Fix race condition in WebSocket reconnect
  - **Details**: When the server restarts, clients reconnect but sometimes
    miss messages sent during the reconnect window. Add a sequence number
    to messages and request missed messages after reconnecting.
  - **Files**: `src/ws/client.ts`, `src/ws/server.ts`
  - **Acceptance**: No dropped messages during server restart in integration test

Tips for writing tasks agents can actually complete:

• One session, one task — If it takes you more than a sentence to describe, it might be two tasks
• Include file paths — Agents explore faster when they know where to look
• Define "done" — An Acceptance field turns a vague ask into a testable outcome
• Use IDs for dependencies — If task B depends on task A, give A an ID and add **Blocked by**: task-a to B. The agent will skip B until A is gone.
• Pre-register the metric for non-trivial changes — when a task is a feature, refactor, or non-cosmetic bugfix, write a Hypothesis (what observable will move and by how much), a Success / Pivot threshold, and a Measurement (the exact runnable command). This is the [rule-#9 pre-registration block](spec.md#rule-9-pre-registration-block); it prevents picking a flattering metric after seeing the result.

The Format

Priority: ## P0 through ## P3 — a widely-used scale (PagerDuty, Google SRE). P0 is "drop everything", P3 is "nice to have".

Tasks: Markdown checkboxes (- [ ]). Each task should be completable in a single agent session.

IDs: **ID**: kebab-case — stable identifiers for tasks that other tasks depend on. Don't rename once assigned.

Blockers: **Blocked by**: auth-fix, rate-limit — references task IDs across all files. A task is unblocked when the referenced IDs no longer exist in any file.

Blocked for a reason: **Blocked**: needs-user-approval — ... — free-form text for blocks that aren't another task. Use it when the agent can't complete the task without an external change (missing approval, refused policy, missing credentials). Any non-empty value marks the task as blocked; the lint keeps the reason field from going empty. Agents running /next-task add this field themselves when they detect an action that is blocked by default (see [Refuse forbidden work](#what-it-does)). See [the spec](spec.md#blocked-for-a-reason) for details.

Research / Last-enriched: **Research**: + **Last-enriched**: YYYY-MM-DD — agent-managed fields for research notes accumulated while the task is blocked. When /next-task runs on a queue where every task is blocked, it spends the turn adding read-only research (drafted message text, file paths, consumer sketches) to the task's Research field and stamps Last-enriched so the next session knows how fresh the notes are. Enrichment never touches the block itself — only the metadata around it. See [Enriching blocked tasks](spec.md#enriching-blocked-tasks) in the spec.

Plan / Parent: **Plan**: + **Parent**: task-id — agent-managed fields for complex-task planning and decomposition. /next-task adds a Plan checklist before coding on multi-file or architectural tasks, and uses Parent when splitting a large task into smaller top-level tasks. Users do not need to add either field manually.

Tags: **Tags**: backend, auth — lowercase labels for filtering and routing to specialized agents.

Estimate / Verification / Risk: **Estimate**: 2-3d (free-form duration), **Verification**: (procedure for confirming done — distinct from Acceptance, which is the criterion), **Risk**: . Mitigation: . — author-managed fields that surface session-fit, the doneness procedure, and the failure mode considered up front.

Rule-#9 pre-registration: **Hypothesis**: + **Success**: + **Pivot**: + **Measurement**: + **Anchor**: — five fields used together to declare what observable a non-trivial change expects to move before the code is written. Hypothesis captures the predicted effect, Success and Pivot are the keep / abandon thresholds, Measurement is the exact runnable command (no English instructions), and Anchor is the literature citation justifying the threshold. Pre-registering the metric prevents post-hoc fishing for flattering observables (Munafò et al. 2017); the Pivot threshold pre-registers the

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tasksmd
• Source: tasksmd/tasks.md
• License: MIT
• Homepage: https://tasksmd.github.io/tasks.md/

Install and usage instructions live in the source repository linked above.