Workfile

The repository is the database.

@illodev/workfile is a repository-native protocol for coordinating Work, Docs, History and durable project Memory between humans and software agents.

Markdown files in the repository are canonical. The CLI, HTTP API and local UI use the same core services, collection registry, index and validation rules. No exclusive state is kept in the browser or in a database.

Work, Docs, History and Memory share the common

ProjectRecord index. The core, CLI, HTTP server and MCP runtime are authored in

TypeScript and distributed as compiled ESM with public declarations. The local UI is

precompiled and included in the package, and semantic search runs on-device through

the optional @illodev/workfile-search-local workspace package.

[Try the live demo](https://workfiledemo.illodev.com) — it replays this repository's own workspace: the real cards, releases, incidents and learnings of Workfile's development. Mutations work per browser session and reset on reload.

https://github.com/user-attachments/assets/c9cd3035-6729-4cda-9172-984829ab5dbc

Used by

In production

Workfile — dogfooding: every release is planned and recorded in this repo's own .project/

Boundaries

Workfile records work. It does not configure agents.

The two get confused because both live next to the same repository. Ecosystem configurators — gentle-ai is a good example — install a persona, curated skills, model routing, MCP servers and review gates into the agents you already use, across many agents at once. Their question is *how your agent works*. Workfile's question is *what was done, who holds it and on what evidence*, and its answer is Markdown files that outlive the agent, the session and this package.

They compose. A well-configured agent still needs somewhere durable to write down what it did.

What is here, and is not a configurator's job:

• The repository is canonical. A card is a file in the pull request: reviewed in the diff, reported by workfile doctor when malformed. No exclusive state in a browser, a database or ~/.config. Remove the package and the records stay readable.
• Claims are enforced, not agreed. Ownership is checked at the mutation, so a card another actor holds refuses your transition with CARD_CLAIM_OWNER_MISMATCH instead of quietly accepting it — a guarantee no sentence in a prompt can make.
• `review` is not `done`. done requires evidence from somewhere the code actually ran. A merge is not evidence.
• Humans read the same records. The UI, the rendered changelog and the releases are derived from exactly what the agent writes; there is no machine view and human view to keep in sync.

What is deliberately absent: Workfile does not install or update agents, ship a persona, route models or curate a skill catalogue. It syncs its own protocol into the instruction files an agent already reads (workfile agents sync) and exposes every operation over MCP — vendor neutral, but a server, not an ecosystem.

Requirements

• Node.js 22 or newer.
• npm, pnpm, yarn or Bun may invoke the package.

Install

Every workfile … command in this README requires the package to be installed — pnpm dlx / npx one-offs run a command and discard the binary afterwards:

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 workfile doctor wf doctor # wf is the same binary, for typing by hand

wf is an alias, not a rename: both names reach the same entry point, and the help and error hints answer in whichever one you typed. Keep the long form in anything generated or shared. wf only resolves once the package is installed, and an unrelated wf exists on the registry — so npx wf would fetch someone else's tool where npx workfile fails outright.

pnpm dlx @illodev/workfile init is fine for one-shot initialization, but keep the package as a devDependency afterwards: that is what makes the project* scripts that init adds to package.json resolve. That prefix is an npm script namespace — pnpm project opens the UI, pnpm project:doctor runs the checks — and has nothing to do with the old binary name.

TypeScript API

The published surface exposes JavaScript and declarations through conditional package exports. TypeScript consumers receive typed configuration, workspace, record, search and integration contracts from the root package and every documented subpath:

import {

defineProject, type CardStatus, type ProjectConfig, type ProjectRecord } from "@illodev/workfile"; import { createSemanticSearchProvider } from "@illodev/workfile/search";

const config: ProjectConfig = defineProject({ schemaVersion: 2, name: "Billing", cards: { areas: ["api", "web"] } });

const status: CardStatus = "doing";

The CLI and UI do not require TypeScript in consuming projects. React, Primer, Vite and the UI type packages are build-only dependencies; the installed package serves bundled browser assets from dist/ui.

Workspace

A project is discovered through project.config.mjs and normally stores protocol-owned files under .project/:

project.config.mjs

.project/ ├── VERSION ├── cards/ │ └── archive/ ├── assets/ ├── docs/ ├── changelog/ │ ├── unreleased/ │ └── releases/ ├── memory/ │ ├── learnings/ │ ├── decisions/ │ ├── incidents/ │ ├── conventions/ │ └── context/ ├── agents/ └── .cache/

Minimal configuration — a plain object, not defineProject(...). The loader applies defineProject itself, and an import here is a bare specifier the file can only resolve with node_modules present, which breaks the two consumers that run without one: a pnpm dlx-initialized workspace before the package is installed, and the generated CI job's npx run on a clean clone. The JSDoc annotation keeps editor typing without a runtime import:

/** @type {import("@illodev/workfile").ProjectConfigInput} */

export default { schemaVersion: 2, name: "My project", cards: { areas: ["api", "web", "infra", "docs"] }, docs: { sources: [ "README.md", "docs/**/*.md", "apps/*/README.md", ".project/specs/**/*.md" ] }, changelog: { releaseStrategy: "semver", defaultVisibility: "public" }, memory: { collections: [ "learnings", "decisions", "incidents", "conventions", "context" ] }, agents: { targets: ["agents-md", "cursor"] }, ci: { targets: ["github"] }, mcp: { allowMutations: true }, search: { semanticWeight: 0.35, maxProviderRecords: 500 } };

Project-specific areas, paths and vocabularies are resolved at runtime and exposed through the effective schema. The eight Work statuses and the schema-v2 memory collection semantics remain protocol contracts.

Work

Cards are managed Markdown records under .project/cards/. The Work module provides hierarchy, dependencies, claims, scope, status transitions, archives, assets and conflict-aware writes.

workfile card list --json

workfile card show T-0042 --json workfile card create --title "Implement runtime schema" --area infra workfile card create --json-input card.json # body, parent, source and tags in one call workfile card claim T-0042 --scope apps/api,packages/sdk # actor resolves itself workfile card transition T-0042 review workfile card patch T-0042 --json-input changes.json --expected-revision sha256:... workfile card archive T-0042 workfile card reopen T-0042 --status backlog

Docs

Docs combines two sources without copying existing documentation:

• Indexed documents discovered from configured globs. They receive deterministic PATH-* IDs and remain read-only through the protocol.
• Managed documents stored in .project/docs/ with stable DOC-NNNN IDs, typed frontmatter and revision-aware mutations.

Managed documents are read recursively, so they can be grouped in folders — including folders you create by hand. IDs stay global and sequential: a folder is organization, not identity. New documents follow docs.layout (kind, the default, groups them by document kind; flat writes them to the managed root) and --folder overrides it.

workfile doc list --query billing

workfile doc show DOC-0012 --json workfile doc create --title "Deployment runbook" --kind runbook --status current workfile doc create --title "Rate limiting" --folder architecture/billing workfile doc move DOC-0012 --folder architecture workfile doc patch DOC-0012 --json-input changes.json --expected-revision sha256:...

The doctor detects broken local links, unresolved related or superseded records, missing scope paths and stale review/source relationships.

History

History uses atomic change fragments rather than asking multiple branches or agents to edit one shared CHANGELOG.md.

Unreleased fragment:

---

id: CHG-0042 title: Add portable history workspace type: added area: infra visibility: public cards: [T-0042] created: 2026-07-28 updated: 2026-07-28

---

A release consumes selected fragments, moves them beneath the release directory and creates a canonical REL-NNNN record. Public or internal changelogs are derived output.

workfile changelog list --unreleased

workfile changelog add --title "Add portable history" --type added --area infra workfile changelog preview workfile changelog release 0.4.0 --title "History and Memory" workfile changelog render --visibility public workfile changelog render --visibility public --write workfile changelog verify

Release versions can use semver, calendar or freeform validation according to configuration. Fragments and releases participate in the same workfile search and backlink graph as cards, docs and memory.

Memory

Memory is a set of typed, atomic and lifecycle-aware records rather than a single growing conversation transcript:

workfile memory list --collection learnings --status active

workfile memory add learning --title "Atomic fragments avoid merge conflicts" \ --confidence high workfile memory add decision --title "Keep Markdown canonical" --status accepted workfile memory add incident --title "Release pipel