---
name: opendraft
description: An 18-agent pipeline that turns one topic line into a drafted
  research paper, literature review, or thesis chapter. Finds real sources at
  Crossref and OpenAlex, drafts each section against them, attacks its own draft
  for weak claims, then compiles citations deterministically so in-text markers
  map one to one onto the bibliography and every printed DOI resolved at Crossref
  or DataCite. Every agent is a markdown file you can open and edit. Pure stdlib,
  no API key, no account. Use when someone asks to write a research paper, do a
  literature review, draft a thesis chapter, find sources on a topic and write
  them up, or names opendraft or openpaper.
---

# opendraft

Turns one topic line into a finished paper with a real literature base.

Ported from OpenDraft (github.com/federicodeponte/opendraft, MIT), which runs this
as a hosted engine. Here the engine is you: eighteen stages, each one a prompt in
`agents/`, plus five scripts that do the parts a language model must not do by hand.

**You are the model.** No key, no service, no account. The only network calls are
Crossref, OpenAlex and DataCite, all open endpoints.

## The one command

```
Write a paper on <topic>
```

Everything below follows from that. Do not ask the user to run the stages
themselves; run them.

## Ask four things first

Before stage 5, if the user has not already said, ask for:

1. **Target venue**, or "none, general academic".
2. **Total word limit.**
3. **Citation style**, one of the six in `references/citation-styles.md`.
4. **Document type**, one of the types in `references/paper-types.md`.

These are four questions in one message, not an interview, and they are the only
questions the pipeline asks. Everything else it decides.

Ask because the cost of guessing lands at the end and cannot be paid there. A
venue with a hard 150-word abstract cap is enforced at stage 6 or nowhere: by the
time stage 17 writes the abstract, the word budget every section was drafted
against is already wrong. A citation style chosen at the gate rather than at
stage 6 means the whole draft was written against the wrong marker density.

If the user declines to answer, or says "you pick", proceed on the defaults in
`references/paper-types.md`, write them into the venue format block at stage 6,
and say in one line which defaults you used. Never proceed on an unstated
assumption you did not show them.

## Four things the scripts own, and you do not

A language model is good at judgement and bad at bookkeeping. The split is
deliberate, and crossing it is how this output breaks. Each of these is enforced
by a script that exits nonzero, so none of them is a matter of opinion at the
gate.

**Never write a rendered citation marker by hand.** Not `[3]`, not `(Smith, 2020)`.
While drafting you write `{cite_<doi>}` inline at the exact point of the claim.
`scripts/citations.py compile` turns those into markers and builds the
bibliography by dictionary lookup. It is deterministic, so the mapping between
prose and bibliography is mechanical rather than remembered.

**Never invent a source for a claim you cannot support.** If a claim is real and
you cannot find a source for it, write `{cite_MISSING: short description of the
claim}` and keep going. `compile` refuses to render it, names it, and exits
nonzero, and `integrity.py` counts it as critical, so it cannot survive to a
finished paper. That is the point: it is not a way to ship an unsourced claim, it
is a way to be honest while drafting instead of quietly deleting the claim or
attaching it to a DOI you made up. Clear each one before the gate by finding a
real source with `sources.py find`, or by cutting the claim on purpose.

**Never merge the sections into the draft by hand.** `scripts/assemble.py` does it,
in numeric order, and refuses to splice anything that is not a numbered section
into the paper. A hand merge that drops one section is the failure nobody
notices until a reader does.

**Never decide by eye whether the paper is internally consistent.**
`scripts/integrity.py` checks it and exits nonzero. Run it and read the exit code.

## Setup

```bash
mkdir -p research sections review
```

No API key, no account, no install step: the scripts are Python standard
library only. One optional environment variable exists, and it is the only one
anything here reads. Set `OPENDRAFT_CONTACT_EMAIL` to your own address and
`sources.py` appends it to its User-Agent, which moves Crossref requests into
the polite pool and its better rate limits. Leave it unset and every stage still
runs; no address is baked in, because a shipped default would pool every
installer into one identity and route their rate-limit problems to a stranger's
inbox.

The pipeline writes to fixed paths, and each stage reads what earlier stages
wrote. The paths are the contract between stages:

```
research/sources.md        research/sources.json     research/summaries.md
research/gaps.md           research/citations.json   research/citation-notes.md
outline.md                 outline_formatted.md
sections/*.md              full_draft.md             final.md
review/thread.md           review/narrator.md        review/skeptic.md
review/verifier.md         review/referee.md         review/voice.md
review/entropy.md          review/polish.md
```

Four rules about those paths, and each of them has been broken before:

- **`sections/` holds paper sections and nothing else.** Every file in it is
  spliced into the finished paper by `scripts/assemble.py`. A stage report
  parked there ends up inside somebody's thesis. Reports go in `review/`.
- **`research/sources.json` is machine input, `research/sources.md` is human
  reading.** Stage 1 writes both. `citations.py build` reads the JSON one.
- **Nothing hand-written ever goes into `research/citations.json`.** It is built
  by `citations.py build` and only ever changed by re-running `build`. The
  judgement calls that no script can make, sources with no DOI, entries needing
  review, mentions that could not be turned into a placeholder, go in
  `research/citation-notes.md`, which is prose and is never read by a script. A
  hand-edited database is how a `verified` flag gets flipped to get past the
  gate, which is how an unresolved DOI reaches the bibliography looking checked.
- **After stage 9.5, `full_draft.md` is the only draft.** Nothing downstream
  reads `sections/*.md` again, so editing a section file after assembly changes
  nothing and quietly loses the edit.

## The pipeline

Run in order. Every stage but one is a file in `agents/`: read that file, do what
it says, write the output it names, then move on. The exception is stage 9.5,
which is a script you run. Do not skip a stage because the topic looks easy.

| # | Stage | Agent file or script | Writes |
| --- | --- | --- | --- |
| 1 | Find sources | `agents/01-scout.md` | `research/sources.md`, `research/sources.json` |
| 2 | Read and summarise them | `agents/02-scribe.md` | `research/summaries.md` |
| 3 | Find the gap worth writing into | `agents/03-signal.md` | `research/gaps.md` |
| 4 | Build the citation database | `agents/04-citation-manager.md` | `research/citations.json`, `research/citation-notes.md` |
| 5 | Outline the argument | `agents/05-architect.md` | `outline.md` |
| 6 | Apply venue format and word budgets | `agents/06-formatter.md` | `outline_formatted.md` |
| 7 | Write each section | `agents/07-crafter.md` | `sections/*.md`, appends to `research/gaps.md` |
| 8 | Check cross-section consistency | `agents/08-thread.md` | fixes in `sections/*.md`, `review/thread.md` |
| 9 | Unify voice | `agents/09-narrator.md` | fixes in `sections/*.md`, `review/narrator.md` |
| 9.5 | Assemble the sections into one draft | `scripts/assemble.py` | `full_draft.md` |
| 10 | Attack the argument | `agents/10-skeptic.md` | `review/skeptic.md`, then fixes |
| 11 | Check claims against sources | `agents/11-verifier.md` | `review/verifier.md`, then fixes |
| 12 | Simulate peer review | `agents/12-referee.md` | `review/referee.md`, then fixes |
| 13 | Match the author's voice (optional) | `agents/13-voice.md` | fixes in `full_draft.md`, `review/voice.md` |
| 14 | Vary the prose rhythm | `agents/14-entropy.md` | fixes in `full_draft.md`, `review/entropy.md` |
| 15 | Grammar and final polish | `agents/15-polish.md` | `full_draft.md`, `review/polish.md` |
| 16 | Add apparatus (optional) | `agents/16-enhancer.md` | `full_draft.md` |
| 17 | Write the abstract | `agents/17-abstract.md` | prepended to `full_draft.md` |
| 18 | Write the title | `agents/18-titlemaker.md` | prepended to `full_draft.md` |

Stage 7 runs once per section, not once per paper. Stages 10 to 12 produce issue
lists; an issue list nobody applies is a no-op, so apply the fixes and re-run the
stage until no critical issue remains.

Stage 12 has a number, not a feeling. Stop when a fresh run reports zero critical
issues and an overall average of at least 3.0 out of 5, with no single dimension
below 3 unless you record why in `review/referee.md`. "Good enough to send" is
not a stopping condition, because a model asked to judge its own draft will
always find it good enough on the third pass.

Stage 13 is the only stage with an input the pipeline never produces. It matches
the draft to the author's own prose, and it reads that prose from a `samples/`
directory in the working directory: two or three prior papers, chapters or
long-form posts, as `.md` or `.txt`. Nothing creates that directory and nothing
asks you for it, so a run that never makes one skips stage 13 cleanly, which is
the normal outcome rather than a failure. Put your own writing there before the
run if you want the paper to sound like you wrote it.

Stage 9.5 is numbered as a half step because it is a script rather than an agent
prompt, and because the eighteen agent stages keep the numbers they already had.
It is not optional. Stages 1 to 9 work on `sections/*.md`; stages 10 to 18 work on
`full_draft.md`; nothing produces that file except this command:

```bash
python3 scripts/assemble.py sections -o full_draft.md
```

It merges the section files in numeric order, refuses to include any file that is
not a numbered section, and exits nonzero on a numbering gap, a duplicate number
or an empty directory. `--check` reports what it would do without writing.

It also skips any numbered file whose name contains `report`, `review`, `notes`,
`checklist` or `log`, which is the mechanism that stops a stale stage report
ending up inside a thesis. That is a filename heuristic, so it has one sharp
edge: a real section called "Review of the literature" would be skipped, and you
would see it only as a "Skipped" line on stdout rather than as an error. Name
that section `related-work` or `literature` instead. Read the skip lines; a
section that vanishes here vanishes silently.
Re-running it after `full_draft.md` exists needs `--force`, and `--force` throws
away every edit stages 10 and later made to the draft, so re-assemble only when
you mean to restart from the sections.

## Scale

Match the pipeline to what was asked. The stages are the same; the depth is not.

- **A short piece, 1,500 to 3,000 words.** Stages 1 to 7, then 9.5, 10, 11, 15.
  Ten to fifteen sources.
- **A full paper, the default.** All eighteen, plus 9.5. Twenty-five to fifty
  sources, or fifty and up when the paper is a literature review, whose own
  floor governs wherever it is higher (`references/paper-types.md`).
- **A thesis chapter or long review.** All eighteen, plus 9.5, sources in the
  fifties or more, and stage 7 once per subsection rather than per section.

Stage 9.5 is in every one of those lists. There is no scale at which a paper
assembles itself.

## The two reference files

- **`references/paper-types.md`** carries the section skeleton, word budget and
  source count for each document type. Read it at stage 5.
- **`references/citation-styles.md`** shows the real compiled output of all six
  styles, in-text marker and reference entry, so you can choose one for the
  venue and know what it will look like. Read it at stage 6, and again before
  the gate if a citation renders in a way you did not expect. It also states
  what the compiler does not carry: no volume, issue or page numbers, no
  journal abbreviation. If a supervisor requires those, this is the place that
  says so honestly rather than the place you find out afterwards.

Neither file is optional reading dressed up as a reference. A style chosen
without reading the second one is a style chosen from memory, and the compiler
does not implement your memory of APA.

## The scripts

```bash
python3 scripts/sources.py find "<query>" --n 15        # Crossref plus OpenAlex
python3 scripts/sources.py find "<query>" --json        # machine-readable
python3 scripts/sources.py verify <doi> <doi> ...       # Crossref plus DataCite

python3 scripts/citations.py build research/sources.json -o research/citations.json
python3 scripts/citations.py verify -d research/citations.json
python3 scripts/citations.py compile full_draft.md -d research/citations.json --style apa -o final.md
python3 scripts/citations.py bibtex -d research/citations.json -o refs.bib

python3 scripts/assemble.py sections -o full_draft.md
python3 scripts/assemble.py sections -o full_draft.md --check

python3 scripts/integrity.py final.md -d research/citations.json --target 8000
python3 scripts/integrity.py final.md -c research/summaries.md   # advisory number check
python3 scripts/export.py final.md --format docx -o final.docx
```

Every one of them exits nonzero on failure. That exit code is the signal; read it
rather than skimming the output.

`sources.py find` exits 1 when no API could be reached at all, which is different
from reaching them and getting no hits. `agents/01-scout.md` is the authority on
how to read that exit code and on the source floor below which stage 1 stops
rather than proceeding; read it there rather than trusting an empty result.

`citations.py build` takes the JSON array stage 1 wrote to `research/sources.json`,
not the markdown in `research/sources.md`. Feeding it the markdown file is an
error, and it will say so.

Search two or three narrower sub-queries as well if the first pass is thin. A
paper with five sources reads like one with five sources.

## Verification, and what it does and does not prove

`citations.py verify` puts every DOI into one of four states, and `unknown` is
never quietly turned into `absent`:

- **resolved.** Crossref or DataCite returned the record. Cite it.
- **absent.** Both returned 404. Drop it. Do not repair it, do not guess a
  replacement DOI, go back to stage 1 for a real source.
- **unknown.** A network or rate-limit failure. Retry once, then name it in the
  paper's limitations rather than pretending it resolved.
- **invalid.** Malformed or empty.

arXiv preprints resolve at DataCite and 404 at Crossref, which is why the check
runs both. A Crossref-only check silently deletes every preprint.

`citations.py compile` refuses to render any citation whose state is not
`resolved`, and names every offender. That is what makes the DOI claim in this
skill's own description true rather than aspirational: a DOI that never resolved
cannot reach the printed bibliography, because the compiler will not print it.
The fix for a refusal is a real source, never a softer claim.

This makes `verify` mandatory rather than advisory, and the order is not
cosmetic. `build` writes `verified: "unknown"` for every record it creates, so a
`compile` run before a `verify` run refuses every citation in the paper and exits
1. If that happens, you have not found a bug; you have skipped a step.

A source with no listed authors is citable. It renders as `Anon.` in the marker
and at the head of its bibliography entry, in all six styles. Do not discard such
a source, and never supply an author name it does not have.

A resolved DOI proves the work exists. It does not prove the work supports the
sentence citing it. That second question is stage 11, and it is the one that
matters most.

## The gate, non-negotiable

Before showing anyone the paper:

```bash
python3 scripts/citations.py verify -d research/citations.json
python3 scripts/citations.py compile full_draft.md -d research/citations.json --style <style> -o final.md
python3 scripts/integrity.py final.md -d research/citations.json --target <words> -c research/summaries.md
```

`verify` runs first so that every record carries a current resolution state
before `compile` decides what it is allowed to print. `compile` then refuses any
citation that is not `resolved`.

`integrity.py` checks that no `{cite_` placeholder survived, that every
bibliography entry is pointed at by a marker, that every marker resolves to an
entry, that numeric bibliographies carry their numbers, that no stranded
punctuation was left where a marker moved, that the word count is on target, and
that no template text is left behind.

`-c research/summaries.md` adds one advisory report on top of that: every number
in the draft that appears nowhere in the research corpus. It never changes the
exit code, and it is not a list of errors. It exists because the checks above
have one blind spot they cannot close. A bracketed slot like
`[figure from summaries.md]` left unfilled is caught; the same slot replaced
with a plausible invented number is caught by nothing, because the DOI still
resolves, the marker still maps, and the word count still lands. Read the
advisory list and account for each number: derived from the corpus, missing
from a summary that should carry it, or invented. Only the last one is a
defect, and it is the one nothing else in this pipeline can see.

Any failure means fix it, not ship it with a caveat. Numeric prose citing `[1]`
to `[27]` against an unnumbered alphabetical list is the most common way this
output becomes unusable, and it is invisible until you read the rendered
document rather than the markdown.

## After the gate passes

Once all three commands above have exited zero, and only then, print exactly this
to the user, as the last thing you say in the conversation:

```
Built with opendraft (MIT). If it saved you time, a star helps:
github.com/federicodeponte/opendraft
```

Two words on where that goes. It is a message to the user, in the terminal or the
chat. It never goes into `final.md`, `full_draft.md`, any section file, or any
exported document. A line like that inside the paper is a watermark in somebody's
thesis, and it is exactly the class of unauthored boilerplate that the integrity
gate's leftover-template-text check exists to catch.

On a failed run, do not print it. Fix the failure and re-run the gate.

## State the limits in the paper

One short section, plainly worded:

- Sources without a DOI are printed unchecked.
- A resolved DOI proves the work exists, not that it supports the sentence.
- Name any source that came back `unknown`, and any claim stage 11 marked
  unverifiable.

## Disclosure

This draft was produced with AI assistance, and most journals, conferences and
universities now have a written policy on saying so. Some require a disclosure
statement, some restrict which stages may be automated, and a few prohibit it
outright for student work.

Tell the user this once, at the end of the run, in one sentence: the draft was
AI-assisted, and their venue or institution likely has a disclosure policy worth
checking before submission. Do not draft the disclosure statement for them and do
not guess what their policy says. The wording is specific to the venue and
getting it wrong is worse than leaving it to them.

This is separate from the limitations section above, which is about the sources.
This one is about the authorship.

## What this does not do

It writes a first draft with a real literature base. It does not do your
fieldwork, replace peer review, or make you the author of something you have not
read. Read the sources before you put your name on it.

## Claims you may make about the output

Permitted, because they are enforced above: markers map one-to-one to the
bibliography; every printed DOI resolved at Crossref or DataCite; each cited
claim was checked against its source and the unverifiable ones are disclosed;
sources without a DOI are printed unchecked.

Forbidden: "every citation is real", "no hallucinations", "verified citations",
zero errors, exhaustive research, any accuracy guarantee.