Proposal: TASKS.md as a companion standard for agent task queues

[cbrwizard]

Summary

AGENTS.md tells agents how to work. I've built TASKS.md to tell them what to work on — a lightweight, Markdown-based task queue spec that any agent can read and write.

This is related to #71 (.agent directory proposal), which includes a tasks.md file inside .agent/spec/. I think task queues deserve a top-level, standalone standard that works alongside AGENTS.md, just like AGENTS.md works alongside README.md.

The Core Idea

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. Writing a task down — even a one-liner — forces you 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.

What is TASKS.md?

# 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

How it works:

1. Plan — Write tasks as ideas come to you
2. Delegate — Agent claims a task, implements it
3. Remove — Delete when done; history lives in git log
4. Repeat — You keep adding, agents keep draining

Key properties:

• Async queue — you add tasks faster than agents complete them; nothing gets lost
• Git-native — version-controlled, next to the code, survives sessions
• Vendor-neutral — works with any agent, any IDE, today

The spec (v1.0) covers priorities (P0–P3), metadata fields (ID, Tags, Details, Files, Acceptance, Blocked by), multi-agent claiming, blocker resolution, sub-tasks, and multi-file discovery for monorepos.

The Ecosystem

• Website — single-page site explaining the convention
• Spec v1.0 — full specification
• 8 examples — web app, CLI, monorepo, multi-agent, Python API, Rust CLI, mobile app, complex tasks
• Agent commands for Claude Code, Codex, Cursor, Gemini CLI, and Windsurf — drop-in /next-task command
• @tasks-md/cli — unified CLI for pick, lint, stats, diff, sync, and install
• tasks-mcp — MCP server with list/pick/claim/unclaim/complete/add tools
• tasks-lint — linter with --fix mode (completed tasks, tag casing)
• @tasks-md/parser — shared parser library for all packages
• CI — validates examples, runs linter, builds and tests all packages on every push/PR (206 tests)

Proposal

I'd love to see AGENTS.md reference TASKS.md as a companion standard — something like a "See also" section in the docs or website. The two specs complement each other naturally:

• AGENTS.md = instructions for agents (how to work)
• TASKS.md = work queue for agents (what to work on)

Happy to discuss format alignment, naming, or any changes that would make this a better fit.