Skip to content

VISION.md

Latest commit

 

History

History
83 lines (64 loc) · 6.13 KB

VISION.md

File metadata and controls

83 lines (64 loc) · 6.13 KB
schema vision-v1
version 1
last_reviewed 2026-05-29
goals
id name description
G1
Spec first, packages second
spec.md is canonical. parser, lint, mcp, cli are reference implementations that exist to validate the spec.
id name description
G2
Cross-agent commands are generated, not hand-edited
commands/next-task.md and commands/lint-tasks.md are canonical; per-agent variants regenerate. CI rejects manual edits to generated variants.
id name description
G3
One TASKS.md per repo, optionally federated
Workspace-mode aggregates per-host queues; per-repo queues stay the source of truth.
id name description
G4
No vendor lock-in
Every agent that adopts the spec works against the same file. Switching agents requires no migration.
id name description
G5
File-first, pluggable backends
TASKS.md (local markdown) is the default, canonical backend. The spec, parser, CLI, and MCP MAY target an alternative backend (e.g. GitHub Issues/Projects) as an explicit, off-by-default opt-in, so a team already living in an issue tracker can adopt the tasks.md workflow without migrating. The file backend stays the reference implementation; other backends are adapters behind the same spec surface, preserving G4 (the spec, not the storage, is the portable layer).
non_goals
id name description
NG1
Not a project management tool
No GUI, no team assignments beyond claim suffixes, no time tracking. Use Jira/Linear for those.
id name description
NG2
Not a workflow engine
TASKS.md describes what work exists, not how it gets routed.
id name description
NG3
Not a graph database
Blocked-by edges are a flat list, not a topological sort.

Vision

A lightweight, machine-readable spec for AI agent task queues. The "what to work on" companion to AGENTS.md's "how to work."

Who it's for

Primary audience: any team that has AI agents picking up coding work. Today's agents (Claude Code, Cursor, Windsurf, Devin, Codex, Gemini CLI, Codium, OpenHands, and 30+ others) need a way to ask "what should I work on?" and get back a structured, prioritized, tooling-friendly answer.

The current options all fail:

  • GitHub Issues as your only queue — too heavy for sub-PR-sized work, no priority semantics, no claim mechanics, requires network. tasks.md stays file-first for exactly these reasons; teams already living in Issues can opt into an Issues backend (G5) and keep the same spec / CLI / MCP surface, trading the file's offline simplicity for tracker integration.
  • Plain markdown checklists — no parser, no lint, no claims, no metadata.
  • Per-tool todo formats — fragment by agent. A task written for Claude can't be picked up by Cursor.

tasks.md is the open standard that fills the gap: one file, one spec, parsed by @tasks-md/parser, validated by @tasks-md/lint, exposed via tasks-mcp, manipulated through @tasks-md/cli, and consumed by /next-task skills in every major agent.

Strategy: spec first, packages second

The format is the product. The TypeScript packages and MCP server are reference implementations — they exist to validate the spec and bootstrap adoption.

  1. Spec is canonical. spec.md defines TASKS.md format. Examples in examples/ are normative fixtures. Behavior shifts in spec.md propagate to parser, lint, MCP, CLI, and every /next-task variant in the same commit.
  2. Reference packages stay small. Each of parser, lint, mcp, cli does exactly one thing. No package gains features that don't serve the spec.
  3. Cross-agent commands are generated, not hand-edited. commands/next-task.md and commands/lint-tasks.md are the canonical sources; per-agent variants under commands/{claude,codex,cursor,devin,gemini,windsurf}/ regenerate from those. CI rejects manual edits to generated variants.

Non-goals

  • A project management tool. No GUI, no team assignments beyond (@agent-id) claim suffixes, no time tracking. If you need Jira/Linear semantics, integrate with those tools — don't reinvent them in tasks.md.
  • A workflow engine. TASKS.md describes what work exists, not how it gets routed. Routing belongs to the agent + the human supervising it.
  • A graph database. Blocked-by edges are a flat list, not a topological sort. Agents pick tasks; humans curate priority.

Core beliefs

  • Tickets are agent prompts. (source) Tasks describe the outcome a human wants, not the implementation. The agent decomposes. This belief shapes every spec decision.
  • Removable, not toggleable. Completed tasks are removed entirely (history lives in git log), not marked [x]. Toggles accumulate noise; removal forces decisions.
  • One TASKS.md per repo, optionally federated. Workspace-mode (planned) aggregates per-host queues; per-repo queues stay the source of truth.
  • No vendor lock-in. Every agent that adopts the spec works against the same file. Switching agents doesn't require migration.

Where this fits in the agent ecosystem

Spec Tells agents… Maintained by
AGENTS.md how to work in this repo (conventions, tests, build) The agents.md community
TASKS.md (this spec) what to work on (queue, priority, claims) tasksmd contributors
Devin instructions / Claude CLAUDE.md / Cursor rules per-agent customization on top of AGENTS.md Each agent vendor

The three layers compose: AGENTS.md sets repo conventions, TASKS.md lists work, agent-specific files refine behavior.

Adoption

The spec lands in the wild any time an agent supports /next-task or reads TASKS.md at the repo root. The current commands/ directory ships skill/command variants for Claude Code, Codex, Cursor, Devin, Gemini CLI, and Windsurf — install via npx tasks generate-commands or via the upstream agent's marketplace.

Adoption is the only metric that matters. The spec's success is measured by how many repos have a TASKS.md at their root, not by how many features @tasks-md/cli ships.