Quirework

Write and research with an AI companion, and keep the work agreeing with itself.

Quirework sits under the AI companion you already work with in a terminal. It gives the collaboration a spec of what the work holds, procedures the companion follows, checks that catch drift between chapters, and a record of how the work was made. You set the aim and make the calls. The companion does the work and brings back the evidence.

The spec holds the center

A long work makes commitments. A year in, they live in one chapter’s phrasing and contradict another’s. Quirework gives them a file of their own. Each commitment is a section with a short name, its slug, and each chapter’s notes name the commitments the chapter carries. When one changes, the companion lists every chapter, post or edition that has to change with it, before a local edit turns into a contradiction somewhere else.

One commitment and every place that carries it A commitment in the spec is joined to the four places in the work that carry it: chapter 3 states it, chapter 9 builds on it, chapter 14 returns to it, and the short edition retells it. The short edition is circled: it still retells the old position, and it was listed when the commitment changed. The spec A commitment {#the-claim} Where the work carries it Chapter 3 states it Chapter 9 builds on it Chapter 14 returns to it The short edition retells it Still retells the old position. Listed when the commitment changed.
One commitment and every place that carries it A commitment in the spec is joined to the four places in the work that carry it: chapter 3 states it, chapter 9 builds on it, chapter 14 returns to it, and the short edition retells it. The short edition is circled: it still retells the old position, and it was listed when the commitment changed. The spec A commitment {#the-claim} Where the work carries it Chapter 3 states it Chapter 9 builds on it Chapter 14 returns to it The short edition retells it Still retells the old position. Listed when the commitment changed.
One commitment, and every place the work carries it. When the commitment changes, quirework spec notes bind --slug lists them all. The circle marks the one that still says what the work no longer holds.

Checks keep that structure honest. They fail a note left in the prose, a chapter that binds a commitment the spec does not declare, a quotation the text no longer contains, and a citation of a source the research register does not hold.

How the spec and the trail work

The trail remembers why

The spec says what the work holds now. The trail says how it got there. For each commitment it keeps pointers to the moments in your conversations where you seeded it, sharpened it, refused a wording, or changed your mind. A pointer is never a copy, so your words are read from the session itself. Before a companion changes a commitment, it reads your own turns about it, oldest first.

The trail of a commitment Six breadcrumbs from three sessions, oldest first, under one commitment. In a session in June, the author first stated it in passing, then made it precise. In one in August, the author refused a drafted wording, and tried a stronger version without settling it. Last week, the author changed position on new evidence, and took a wording the companion drafted. A commitment {#the-claim} 6 breadcrumbs, 3 sessions seed First stated, in passing sharpen Made precise correct Refused a drafted wording probe Tried a stronger version, unsettled reverse Changed position on new evidence accept Took the companion’s wording turn 2 turn 9 turn 4 turn 11 turn 1 turn 3 a session in June one in August one last week
The trail of one commitment, oldest first. Each breadcrumb points at the turn where you shaped it, and says what that turn did. A change of mind is added to the trail and never replaces what came before.

The trail is context, never authority. The spec states what the work holds, and what you ask for now outranks anything on it.

Procedures your companion follows

A procedure is a file your project writes: how this work drafts a chapter, checks a claim, researches a source or prepares a blind read. Quirework catalogs them, prints the reading each one requires in dependency order, and generates short entry points so a companion can be pointed at one by name. The procedure stays the source of truth.

Five patterns recur, and Quirework supplies their mechanics. What tells them apart is who sees what.

What each seat sees, in five procedures A prose workshop gives several writers one frozen packet, walled off from one another, and seals their drafts under letters. A writers room gives each seat its own packet, then a shared board between rounds. A roundtable seats models as themselves, taking turns, with every turn visible and a shared folder. A blind read gives a reader only the pages, never the spec. A consistency review gives a reviewer the guide, the spec, the notes and the exact change, with the work read-only. Prose workshop packet A B C One frozen packet, never another draft Drafts sealed under letters Writers room board Its own packet, then the board between rounds Personas, and a chair Roundtable 1 2 3 4 board and folder Every turn as it happens, and a shared folder Models as themselves Blind read spec Only the pages a reader would see One chapter at a time Consistency review guide spec notes change The work read-only, and the exact change A findings report
Five procedures, by what each seat may see.

The procedures, and what each one is for

How a session goes

You describe the job in conversation, the way you would to a collaborator: revise chapter five, check this claim, find what the sources say about it. The companion follows the procedure your project wrote for that kind of job.

  1. You name the aim and the scope.
  2. The companion reads the project’s guide and the procedure for the job.
  3. It loads the spec: what the work commits to, where each commitment is carried, and the notes on the chapter at hand.
  4. It drafts, revises or researches inside the procedure’s limits.
  5. Where other views would help, it convenes other models, each seeing only what the procedure allows.
  6. It weighs what they return against the spec. A model’s answer is evidence, never authority.
  7. It runs the checks the procedure names, and brings back the change, the evidence, and any decision that is yours to make.
A session, in three lanes You name the aim. Your companion reads the guide and the procedure, loads the spec and the notes, drafts or researches, and convenes other models, each with its own packet, which return evidence with receipts. The companion weighs that evidence against the spec, runs the checks, and hands you the change, the evidence and the decision that is yours. You Your companion Other models 1 The aim and the scope 2 Reads the guide and the procedure 3 Loads the spec, where each commitment is carried, and the chapter’s notes 4 Drafts, revises or researches 5 Convenes other views a frozen packet each seat seat seat each sees only what the procedure allows reports and receipts 6 Weighs it against the spec 7 Runs the checks, and returns the change and the evidence You decide
Every procedure runs the same loop. The companion is the operator. The other models are seats: each receives a declared packet and returns evidence.

You can run every command yourself, and the workflow guide shows how. The tool was made for the other way of working: describing the job, and judging what comes back.

Any model, in any seat

The companion you talk to is not tied to the models it calls on. One procedure can seat models from different makers, through different harnesses, beside a person. Each seat declares its model, its effort, and what it may see and use. Where the operating system can confine a seat, it is confined. Where only an audit is possible, the record says so instead of claiming isolation.

A run, from plan to receipts Your companion writes a run plan. The plan names each seat's harness and model, its effort, and what it may see and use, and is frozen and hashed. The seats can be models from different makers, through different harnesses, or a person. Their receipts record the model actually served and what was enforced, and go back to the companion. Your companion A run plan Each seat names its harness and model, its effort, and what it may see and use. Frozen and hashed A model from one maker confined by the operating system A model from another, by another harness where only an audit is possible, it says so A person described as a person, never as a model Receipts the model actually served, and what was enforced
A run is a plan, frozen before any seat starts. Each receipt records the model the provider actually served, which can differ from the one requested.

Independence is the reason. A draft can be reviewed by a model that did not write it, a blind reader can run on a different model from the one that drafted the chapter, and a work’s editions can be drafted on different models, so that they are not all one model’s voice.

A record of who did what

Your sessions are captured from each harness’s own records into a store outside your repository. They wait there until you read and accept them. The repository keeps only the decision: which sessions count, each with a hash of its bytes. The transcripts never bloat the work’s history, and the record still proves what was said.

Where the record of the work is kept Your sessions are captured from each harness's own records into a store outside the repository, where they wait as pending until you accept them. The repository keeps only the ledger: each accepted session with a hash of its bytes. From the store, Quirework searches your own words on your machine, the spec's trail points into it, and it estimates who did what, with its caveats attached. Your sessions where each harness keeps them capture The store outside the repository pending accepted you read, then accept The repository The ledger: each accepted session, with a hash of its bytes Search your words, locally The spec’s trail points into it Who did what, caveats attached
The record stays out of the repository, and the repository can still prove which sessions it stands on.

From that record, Quirework compiles your own words and searches them, by keyword or by meaning, with the index built and kept on your machine. It estimates the division of labor between you and the machine, with its caveats attached.

A book being written with it

A book by Ademar Reis, with the subtitle A software engineer’s philosophy of mind, is due in early 2027. It is being written with Quirework, and its site, mindwright.dev, describes the collaboration this way.

Human-directed, AI-articulated. The book is being written by a human and an AI together, over months and hundreds of sessions. The intuitions, the judgments and the direction are the author’s. Most of the sentences are the machine’s, and the book will account for exactly who did what.

The book is not published yet. When it is, it will be the measure of the tool. The two samples below are not.

Read about the book at mindwright.dev

Two samples, made to test the tool

Quirework’s repository carries two worked examples, a book and a blog. Both are test fixtures, not showcases. Their authors, their people and their stories are invented. AI wrote them, and no person edited or reviewed their prose. Quirework is built for an author who judges every page, and these two had no such author. So read them for the structure the tool keeps, not for the writing.

Side Quest is a short comic memoir by Cy Dequest, about building Quirework instead of finishing a book. Cy is invented: an AI played the author and drove the companion that did the work. It is not an account of how Quirework was made. The tool’s part is real, and it is the part to judge: a spec and its trail, a book in four formats, three derived editions bound to the same spec, and the fifteen sessions it was written in.

You can read it in the browser, or download it, in every format and edition.

One commitment and the four places that carry it A section of Side Quest's spec, "The name came from quire", is joined to the four documents that bind it: the book's chapter, the poems, the six-pager and the young readers' edition. The young readers' edition is circled: after the author corrected the story, it defined the word quire, where its own notes say to show it. The spec The name came from “quire” {#the-name} Where it is carried The book Chapter 5, The Name The poems The Name, in anapestic couplets The six-pager One memo, in the part about Otto The young readers’ edition The Name, for readers of about ten Defines “quire”, where its notes say to show it. Found by an independent consistency review.
One commitment and the four places that carry it A section of Side Quest's spec, "The name came from quire", is joined to the four documents that bind it: the book's chapter, the poems, the six-pager and the young readers' edition. The young readers' edition is circled: after the author corrected the story, it defined the word quire, where its own notes say to show it. The spec The name came from “quire” {#the-name} Where it is carried The book Chapter 5, The Name The poems The Name, in anapestic couplets The six-pager One memo, in the part about Otto The young readers’ edition The Name, for readers of about ten Defines “quire”, where its notes say to show it. Found by an independent consistency review.
One commitment in Side Quest, about where the tool’s name came from, and the four documents that carry it. When the invented author corrected the story, an independent review found that one edition now defined a word its notes say to show. The circle marks that finding.

The Lighthouse Log is the site version, and invented too: the log of a lighthouse keeper who does not exist. It is a small Hugo blog with a spec for each post, a shared spec for what the posts lean on, notes kept outside the tree Hugo renders, and a voice policy the checks enforce.

Both run in Quirework’s own test suite, so a change that would break a working project fails there first.

Get started

Quirework needs Python 3.11 or later. Make a directory for your book or site, and install Quirework in an environment inside it:

python3 -m venv --system-site-packages .venv
.venv/bin/python -m pip install 'quirework[quarto]'

The quarto extra installs what a book needs to render; leave it out for a site. Then open your companion there and ask it to start a book, or a site, by the authoring guide. The configuration guide connects a project you already have.