A small CLI that discovers, schedules, and runs work across many repos,
autonomously and as a guided human loop, on a file-based work/ contract with an atomic git-ref claim protocol. Folders hold the durable status,
lock refs hold the live one. No database.
Words In The Heart Can Not Be Taken
Four jobs, one tireless golem: discover, schedule, claim, run.
Point Dorfl at your repos. It finds the ones participating in the file-based work/ contract and surveys what is ready to build.
Ready tasks are picked and ordered across many repos at once, as a guided human loop or as an unattended autonomous runner.
Claiming a task acquires its own per-item lock ref with a single create-only push. First to create it wins; the loser is told no. No coordination server, no lock table.
Each claimed task is built in its own isolated worktree, taken to a green acceptance gate, and integrated. Then Dorfl moves on.
No coordination server, no shared index. Git refs and folders do the bookkeeping.
Every work item is one markdown file, on a Kanban board of folders (tasks: backlog → todo → done). Its resting status is the folder it lives in, never a field. No database to keep in sync.
Claiming a task acquires a per-item lock ref, not a file move: a create-only push that is self-arbitrating, with no retry budget. The task stays in the pool, so a worker can even claim on a protected main.
A worker builds the task on a work/<slug> branch, runs the acceptance gate, and proposes or merges. Conflicts rebase-or-abort, never auto-resolve.
Dorfl comes in three layers, in this order. Adopt the contract with a
skill; that gives you the file-based work/ substrate; then the CLI executes against it. Adopt is a skill, execute is
a command.
The front door. Install the dorfl skills, then point your agent at from-idea (from scratch) or setup (an existing repo). Runner-agnostic — nothing to install globally; the
skills go in via npx dorfl, and adopting the contract needs no dorfl runtime.
# install the dorfl skills into your agent (no install needed — run via npx)
npx dorfl skills add
# (or install the CLI once — `npm install -g dorfl` — then `dorfl skills add`)
# then, in your agent:
from-idea # from scratch: idea → scaffolded work/-contract repo + spec
setup # existing repo: onboard onto the work/ contractwork/ contract, versioned with your codeWhat adoption gives you: a durable, file-based substrate the CLI later consumes. One markdown file per item; status is the folder it lives in, never a field. No database.
# what setup / from-idea scaffold into your repo
work/
tasks/ # backlog/ → ready/ → done/ (+ cancelled/)
specs/ # proposed/ → ready/ → tasked/ (+ dropped/)
notes/ # ideas / observations / findings — capture buckets
protocol/ # vendored WORK-CONTRACT.md, ADR-FORMAT.md, templates
dorfl.json # the per-repo acceptance gate (verify / prepare) + the pinned dorfl (dorflCmd)Once the contract is in place, the CLI is the runner that consumes
it. Use dorfl do in one repo, or dorfl run across many. In CI, dorfl intake is the issue → spec/task front door.
# install the runner
npm install -g dorfl
# register a repo and let Dorfl pick a ready task
dorfl remote add <url>
dorfl do # one repo, in place
dorfl run # across every registered repo, in parallel
# CI: turn an issue into a spec or task
dorfl intakeFull docs and the work/ contract live in the repository.