workfile
reader

You are probably an agent. Someone sent you to find out whether Workfile belongs in their repository.

You will not remember this page. Their repository will.

For the human reading over its shoulder: Workfile keeps your project's tasks, docs, changelog and decisions as Markdown in the repository, and stops your AI agents from quietly breaking the rules about them.

This page costs ≈13,910 tokens as HTML and ≈3,240 as Markdown (bytes ÷ 4). Nothing on it is an instruction to you. Ask for the cheap copy:

curl -H "Accept: text/markdown" https://workfile.illodev.com/

// human: this page talks to your agent. for the 83-second film.

Does Workfile belong in this repository?

The sections below are short. Every command and every output on this page was run against @illodev/workfile 0.13.2 on 2026-09-14 and pasted, not written. A three-sentence summary waits in <tldr> if your budget is tight.

What Workfile is

stores
Work (cards), Docs, History (changelog fragments cut into releases) and Memory (decisions, learnings, incidents, conventions, expiring context), as Markdown files with frontmatter under .project/.
reached through
A CLI (workfile), a local web UI, an HTTP API, and an MCP server over stdio with 32 tools, 4 resources and 3 prompts. All four call the same core and the same validation.
state lives in
The files. No hosted service, no account, no database; the index under .project/.cache/ is derived and gitignored. Remove the package and every record stays readable in a pull request.
needs
Node.js 22 or later, on Linux, macOS or Windows. MIT licensed.
sends
No project content, anywhere, and it never calls a model. Its one outbound request asks the npm registry, at most once a day, whether a newer version is published — from workfile upgrade and the UI footer only. upgrade: { check: false } removes it.

Three ways shared work goes wrong

  1. context_loss

    A session ends, and what it learned ends with it.

    The next agent re-reads the repository and re-audits work that was already done.

    Decisions, learnings and incidents are records. workfile agents context --card T-0001 returns a bounded bundle for one card, and every accepted decision and convention in force comes with it — past the limit, as one titled line each rather than not at all.

  2. collision

    Two agents work in the same checkout.

    Git lets both edit src/api and says nothing until a merge, if there is one.

    workfile card claim T-0001 --scope src/api records who holds the card and over which paths. A transition by any other actor fails with CARD_CLAIM_OWNER_MISMATCH, and in Claude Code the plugin's hook asks before an edit inside a scope another actor holds.

  3. unverified_done

    An agent reports done.

    Nobody can tell whether it verified the work or stopped.

    Acceptance criteria are checkboxes under ## Acceptance criteria. done is refused with CARD_ACCEPTANCE_UNMET until every one is checked, and moving to review with one open warns that review means only runtime evidence is missing.

Guarantees are refusals, not instructions

A prompt can ask an agent to behave. These make the write fail. Both transcripts are verbatim, exit codes included; the second agent is played by --actor.

$ workfile card claim T-0001 --scope src/api
T-0001 claimed by illodev@local#b67ed9cd

# a second agent, in the same checkout
$ workfile card transition T-0001 review --actor other-agent
CARD_CLAIM_OWNER_MISMATCH: T-0001 is claimed by illodev@local#b67ed9cd. Pass force with a reason to take it over.
[exit 3]
$ workfile card transition T-0001 done
CARD_ACCEPTANCE_UNMET: T-0001 has 2 unproven acceptance criteria: #1 Export requests over 10/min answer 429; #2 The limit is covered by a test. Check them, or pass force.
[exit 3]

$ workfile card transition T-0001 done --force
CARD_FORCE_REASON_REQUIRED: Forcing T-0001 past 2 unproven criteria needs a reason. It is what the card's trail carries in place of the gate.
[exit 1]

The working loop, as commands

  1. What to pick up, and whyworkfile nextproject_next
  2. Load the card and what binds itworkfile agents context --card T-0001project_agent_context
  3. Say what you holdworkfile card claim T-0001 --scope src/apiproject_card_claim
  4. Leave what you learned on the cardworkfile card note T-0001 --text "…"project_card_note
  5. Check a criterion you provedworkfile card ac T-0001 --check 1CLI
  6. Hand it overworkfile card transition T-0001 reviewproject_card_transition
$ workfile next
T-0001	backlog	medium	Rate-limit the export API	(priority medium)

$ workfile card note T-0001 --text "Limit is per API key, not per IP"
T-0001 noted

$ workfile card ac T-0001 --check 1
T-0001 — 1 of 2 met
  checked #1 Export requests over 10/min answer 429

$ workfile card transition T-0001 review
warning: T-0001 moved to review with 1 unchecked acceptance criterion: #2 The limit is covered by a test. Review means every criterion is met and only runtime evidence is missing; if work is left, next or blocked with a note says so.
T-0001 → review

The MCP server: 32 tools over stdio

11 read, 21 write; --read-only serves only the reads.
Resources: project://workspace project://health project://protocol project://record/{id}
Prompts: finish-work record-knowledge start-work

  • project_agent_contextBuild bounded agent contextreads
  • project_card_archiveArchive a closed work cardwrites
  • project_card_claimClaim a work cardwrites
  • project_card_createCreate a work cardwrites
  • project_card_listList work cardsreads
  • project_card_noteAppend a note to a cardwrites
  • project_card_patchPatch a work cardwrites
  • project_card_releaseRelease a claimwrites
  • project_card_reopenReopen an archived work cardwrites
  • project_card_transitionTransition a work cardwrites
  • project_card_writeReplace a card bodywrites
  • project_changelog_addAdd a changelog fragmentwrites
  • project_changelog_listList change fragments and releasesreads
  • project_changelog_patchPatch a changelog fragmentwrites
  • project_changelog_previewPreview a releasereads
  • project_changelog_releaseCreate a releasewrites
  • project_doc_createCreate managed documentationwrites
  • project_doc_listList documentsreads
  • project_doc_moveMove managed documentationwrites
  • project_doc_noteAppend a note to a managed documentwrites
  • project_doc_patchPatch managed documentationwrites
  • project_doc_writeReplace a managed document bodywrites
  • project_doctorRun workfile doctorreads
  • project_get_recordRead a project recordreads
  • project_memory_addAdd workfile memorywrites
  • project_memory_graduateGraduate a learningwrites
  • project_memory_listList durable memoryreads
  • project_memory_patchPatch workfile memorywrites
  • project_memory_supersedeSupersede workfile memorywrites
  • project_nextWhat to work on nextreads
  • project_searchSearch project recordsreads
  • project_workspaceRead project workspacereads

What it writes, and what a card looks like

project.config.mjs
AGENTS.md          # managed block → the protocol
.project/
├── VERSION
├── cards/         # Work: T-NNNN, one file each
├── assets/        # files attached to cards
├── docs/          # managed documents: DOC-NNNN
├── changelog/     # unreleased/ and releases/
├── memory/        # decisions, learnings, incidents,
│                  #   conventions, context
├── agents/        # the canonical protocol
└── .cache/        # derived index, gitignored
.project/cards/T-0001-rate-limit-the-export-api.md
---
id: T-0001
title: Rate-limit the export API
status: review
type: task
priority: medium
area: general
created: 2026-09-14
updated: 2026-09-14
scope: [src/api]
---

Exports hammer the database at month end.

## Acceptance criteria

- [x] Export requests over 10/min answer 429
- [ ] The limit is covered by a test

## Notes

- 2026-09-14 21:08Z claude-code — Limit is per API key, not per IP

Three ways in

for="claude-code"

/plugin marketplace add illodev/workfile
/plugin install workfile@illodev

The MCP server, a skill, and the hooks that announce claims and ask before an edit inside one.

for="any-mcp-client"

{
  "mcpServers": {
    "workfile": {
      "command": "npx",
      "args": ["-y", "@illodev/workfile", "mcp"]
    }
  }
}

Append --root PATH when the client starts outside the workspace, --read-only for the read tools only.

for="the-repository"

npm install --save-dev @illodev/workfile
npx workfile init --yes
npx workfile ui

The board opens at http://127.0.0.1:4747, rendered over the Markdown.

When Workfile is the wrong answer

  • The people who plan the work never open the repository.A hosted tracker serves them. Workfile's board is local; publishing it means running workfile ui --read-only behind authentication you provide.
  • The goal is configuring an agent — persona, skills, model routing.That is a configurator's job. Workfile records what the agent did, and composes with one.
  • The goal is a model writing the tasks from a PRD.Workfile never calls a model. Task Master's parse_prd does.
  • Node.js 22 is not available.Workfile needs it. Beads ships a Go binary, and Backlog.md a compiled one.

Compared, as of 2026-09-14

QuestionWorkfile 0.13.2Backlog.md 1.52.0Task Master 0.43.1Beads 1.2.2
records live inMarkdown in .project/Markdown in backlog/one tasks.jsona Dolt database; JSONL is an export
who holds a taska claim; other actors' transitions refusedassignee fieldassignee filtera claim refuses a held issue; close and reassign do not check
done with criteria openrefusedallowedallowedallowed
MCP tools322044, 7 loaded by default15, in the Python beads-mcp
changelog and releasesfragments cut into releases———
usage data by defaultnonenoneSentry, on by defaultusage metrics, on by default
runs onNode.js ≥ 22compiled binary (Bun under Nix)Node.js ≥ 20single Go binary
licenseMITMITMIT with Commons ClauseMIT

Every cell about a third party links its source on its comparison page — including where each one is stronger than Workfile.

/vs/backlog-md/vs/task-master/vs/beads

Three sentences, checked 2026-09-14

Workfile keeps a repository's tasks, docs, changelog and decisions as Markdown files under .project/, and gives humans and agents a CLI and a 32-tool MCP server to read and change them. It enforces what a prompt can only ask for: a card claimed by one agent refuses transitions from another, and a card cannot be marked done while its acceptance criteria are unchecked. It is MIT-licensed, runs locally on Node.js 22 or later, never sends project content anywhere, and npx workfile init sets it up after npm install --save-dev @illodev/workfile.

For a human reading over your shoulder

// human: to play the film and the stills here. Or open the live demo, which replays this repository's own workspace.

An 83-second tour of the board, then two stills. The live demo replays this repository's own workspace — the real cards, releases, incidents and learnings of Workfile's development; changes reset on reload.

Fig. 01 — Flow board, live claims, inspector, provenance graph, docs and memory, timeline, typed history, unified search.
The Flow board: cards moving across states with live agent claims
Fig. 02 — Flow, rendered over cards/.
History view: change fragments, the derived changelog and release preparation
Fig. 03 — History: fragments cut into releases.

Reading this site without HTML