Three hard gates, and why only three
Ceremony is a cost. Every gate that blocks is a gate the author has to satisfy at the worst possible moment — mid-chapter, at the end of a long drafting session. Vellum spends that authority on exactly three moments where being wrong is expensive, and it buys each gate with a file on disk rather than a promise in chat.
Each gate has one artifact, one predicate, and one owner. The artifacts are ordinary markdown files in the project's work/ directory. The predicates live in hooks and the engine, not in an agent's instructions. The owner is you: approval, acceptance, and dismissal are all author actions.
Outline before prose
No write reaches manuscript/chapters/ without an approved outline for that chapter and a clean state check. A subagent cannot approve its own outline.
BlocksUnapproved prose · half-committed prior chapters · pending capture
Blind read on pivotal chapters
A chapter flagged pivotal: true needs a verdict from a reader with no access to the plan. Acceptance waits on the artifact, not on the muse's summary.
BlocksAccepting a pivotal chapter without a real blind verdict
Beta PASS before export
The four-reader readiness protocol must return PASS before the export build runs. Thresholds are numeric and enforced by the engine.
BlocksExport until every axis ≥ 7, mean ≥ 7.5, no early put-down
The gates explain themselves. When one blocks, you get the exact artifact it wanted and the command that satisfies it: approve the outline, run the blind reader, finish the pending capture. They never leave you guessing, and they never lock your manuscript — it is your git repository.
The gate table
| # | Gate | Enforced by | Blocks | Satisfied by |
|---|---|---|---|---|
| 1 | Approved outline before prose | PreToolUse hooks on Write/Edit and on Bash (redirection, heredoc, sed -i, copy-laundering all checked) |
Any write into manuscript/chapters/ |
work/outline/chapter-NN.md with approved: true, plus a clean state check. Subagents cannot self-approve outlines or forge critique artifacts. |
| 2 | Blind-reader verdict on pivotal chapters | state check at acceptance, cross-checked by vellum readiness |
Marking a pivotal: true chapter accepted |
work/critique-reports/blind-chapter-NN.md from a real @blind-reader run — verdict ≠ LOST, with the reader's self-recorded run stamp as provenance. |
| 3 | Beta-reader PASS before export | vellum readiness, required by /vellum:export |
Export | work/critique-reports/readiness-report.md with verdict: PASS — every axis ≥ 7, mean ≥ 7.5, no put-down point in chapters 1–3. |
A single conversation cannot honestly run a blind read. In single-agent mode the muse says so plainly and the author chooses: drop the pivotal flag, or explicitly enable the warned fallback (blind_gate_fallback: true in kb/project-config.json — the author's decision, never the muse's). The engine rejects a fallback-qualified run stamp unless the flag is set. The gate is never skipped silently.
The chapter loop
One command, /vellum:write-chapter, runs the whole editorial cycle. The author appears at two decision points: outline approval and chapter acceptance. Everything else is routed work.
- Outline
The outliner sequences the chapter into beats with per-beat word quotas summing to the outline target, POV, cast, verbatim anchor lines, and what must not be resolved.
- Approval
You see the outline. Setting
approved: trueis what disarms gate 1. Only your approval setspivotal: true. - Preconditions
state checkruns. Anything it reports is fixed or surfaced before a word is drafted. - Draft
The writer receives a fixed context pack: state card, scene brief, previous-chapter tail, cast cards, voice profile plus one exemplar, relevant vocabulary, craft pointers, word budget. Never raw critique; never the whole knowledge base.
- Post-write net
The hook scans silently. It speaks only on tells; debt is recorded, not re-litigated.
- Critique
One or two routine critic lanes, or three to five plus the blind reader when the chapter is pivotal. The muse synthesizes; raw reports are never forwarded.
- Present
The muse tells you what changed, what works, what concerns it, and what decision is needed. Your approval is the acceptance.
- Capture and close
Acceptance fires the mechanical close-out — word count, ledger check, state rebuild — then the knowledge lead captures what happened into the ledgers. The chapter stays pending until capture completes.
- Before final
One demolition pass is offered. Declining is recorded in one line. Demolition is a tool, not a tax.
Interrupt anywhere; the state card carries resume.
Architecture: four layers
Vellum separates four kinds of decision that most writing setups blend together: what is mechanically true, what is enforced, what is judged, and what is methodology.
1 · The deterministic engine
scripts/vellum + scripts/vellum_lib/. Python ≥ 3.8, stdlib only: no pip, no Node, no build step. State rebuild and check; ledger continuity (dead characters, promise ordering, knowledge boundaries, prop custody, clock monotonicity); word bands; bible validation; measured style statistics; context packing; exemptions; and the export build (markdown bundle plus a stdlib EPUB). project-setup copies it into your novel repo.
2 · The hooks
Seven scripts across six lifecycle events. The outline gate fires on both write paths and blocks unapproved prose. The post-write prose net scans drafts and stays silent when clean. Session start prints the state card; compact takes a snapshot; stop reminds you of pending capture; the writer's completion triggers the mechanical close-out. Hook contract →
3 · The agents
16 specialists. The muse coordinates and never judges its own work. Critics and readers are read-only by frontmatter. The writer writes only under manuscript/ and work/drafts/. Critique, drafting, and memory updates never share a context. See every agent →
4 · The skills
34 skills carrying the methodology: craft references, ledger schemas, the shared gate rubric, the cold-read protocol, demolition, voice work, project setup, the series operator's manual. Resources load on demand rather than filling the context up front. See every skill →
State, and who owns it
The manuscript is ground truth. The knowledge base is durable canon. state/ is derived and engine-owned. work/ is scratch. When state and prose disagree, Vellum surfaces the conflict; it never silently rewrites prose to match stale tracking.
manuscript/chapters/chapter-NN.md # the prose — ground truth
kb/ # the story bible — yours to edit
state/ # machine-authoritative — never hand-edit
work/ # outline, drafts, critique reports, cold reads
export/ # build artifacts onlyThe state card
A fixed seven-section resume card, hard-capped at 12 KB, rebuilt mechanically: story position, open promises and questions, active cast, knowledge boundaries, props and clock, next beats with quotas, and flags. Session start prints it. The writer's context pack inlines it.
Provenance
Gate artifacts are muse-transcribed, so each carries a provenance record that a real reader produced the verdict it holds. The default is the reader's self-recorded run_stamp: in its returned report frontmatter, transcribed verbatim like the verdict itself. Inventing it is the same fabrication as inventing the verdict.
Exemptions
vellum dismiss <key> --reason "your words" records an exemption in your own words and no agent re-raises it. If the underlying fact changes, the exemption goes stale and re-arms exactly once.
What stays advisory
Everything not in the three gates above, by default: the post-write prose net (AI-tell tiers, hard signals, voice-debt ledger), cold-read BLOCKER-class issues (they block export only until resolved or dismissed with your sign-off), the disruptor lane, and the persona panel. Two further gates — voice_debt_gate and stop_gate — ship off and are opt-in through kb/project-config.json.
The design rule is blunt: if a check can be done by code, it is done by code; if it needs judgment, it is advisory unless it guards a moment where being wrong is expensive. DESIGN.md carries the full build spec, including what was deliberately not built.
Windows is a first-class platform
- Hooks run under Git Bash, bundled with Git for Windows. No WSL.
- Interpreter resolution tries
python3, thenpython, then thepy -3launcher, each probed for ≥ 3.8. Gate 1's core predicate is pure bash, so it works with no Python at all. - Paths are tested on
windows-latestCI: drive letters, spaces, CRLF files, and UTF-8 BOMs are normalized. Repo files are pinned to LF;LC_ALL=Cwherever byte-stable matching matters. - Large payloads are piped to the interpreter via stdin, never passed as arguments, with a regression test above 128 KiB.
CI runs the suite on both ubuntu-latest and windows-latest.