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

Aperta
  • Qualcosa non va?
#166 1 commento 1 reazione 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
55/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
markdown
Ambito
documentation

Direzione di ricerca

Start with the repository documentation or website entry point mentioned in the proposal, then read issue #71 and the linked TASKS.md specification to compare the conventions. Done means adding an appropriate companion-standard reference, if the project agrees on the scope and placement, with the documentation still rendering correctly.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
TypeScript
Stelle
24.8k
Fork
1.9k
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di agentsmd/agents.md

Tutte le issue di agentsmd/agents.md

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.