bookwright-cli 0.5.0

Spec-driven authoring toolkit for novels, essays, and memoirs.

Spec-driven authoring toolkit for novels, essays, and memoirs.
Léeme en español

Bookwright applies the Spec-Driven Development pattern to long-form writing: you distill your ideas into a handful of canonical documents (constitution, bible, outline, scenes) and let an AI agent write from them, not from a free-form chat. Your book lives in plain text, versioned in git, fully auditable, and outlives the toolkit.

Why? Because it warns you that your character has blue eyes in chapter 3 and green eyes in chapter 12 — before your reader does. Bookwright derives a knowledge graph from your work and validates continuity (characters, settings, chronology, focalization) deterministically.

Status: v0.5.0 — usable for researching, structuring, drafting and validating continuity. It researches with provenance, ingests the narrative structure (units, functions and sequences) and types it against the Propp and Greimas vocabularies. Validation is now robust: a validator reports not-evaluated(reason) instead of a misleading clean pass when it has nothing to look at. Change-by-change detail in the CHANGELOG.

---

How you use it, in one sentence

Bookwright is a CLI plus a set of skills for your agent. That defines where you type each thing, and it's the idea worth being clear on before you start:

When	Where	What
Once, at the start	in your terminal	bookwright init
95% of the time	inside your agent (Claude Code, etc.)	you invoke skills: /bookwright-constitution, /bookwright-bible, …
Now and then	in your terminal	bookwright graph build · bookwright validate · bookwright status

Skills are invoked inside the agent, by typing /bookwright-<command> in the prompt. Whatever you type after the command reaches the skill as its input (a reference to a file, pasted text, or the prior conversation).

---

Installation

The PyPI package is bookwright-cli; the command it installs is bookwright.

uv tool install bookwright-cli   # with uv (recommended)
pipx install bookwright-cli      # or with pipx
bookwright version

Want to try it once without installing anything?

uvx --from bookwright-cli bookwright version

Straight from the repository (latest main):

uv tool install "git+https://github.com/jmorenobl/bookwright"
# or:  pipx install "git+https://github.com/jmorenobl/bookwright"

To work on the toolkit itself, clone the repo and sync the environment:

git clone https://github.com/jmorenobl/bookwright && cd bookwright
uv sync
uv run bookwright --help

---

Quickstart: your first validated scene

1 · Create the project · [in your terminal]

bookwright init my-novel --integration claude
cd my-novel

This generates the structure (bible/, outline/, manuscript/), the manifest.toml, and materializes the Bookwright skills in .claude/skills/.

Dump your idea into a free-form Markdown, with no required format — the premise, the characters you already know, the tone:

echo "A pilgrim abandons the Camino de Santiago at stage 17..." > idea.md

2 · Distill your idea with the skills · [in your agent]

Open the project in Claude Code and invoke the first skill. This is typed in the agent's prompt, not in the terminal:

/bookwright-constitution read idea.md and distill the constitution

The skill reads your brief, drafts the artifact, and marks with [PENDING: …?] what your material does not yet decide — without inventing canon. A typical session:

You  ▸ /bookwright-constitution read idea.md and distill the constitution

Claude ▸ I've read idea.md and drafted the constitution in
         bible/constitution.md. Summary:
           · Voice: close third person, focused on the pilgrim
           · Pact with the reader: psychological realism, no supernatural twists
           · Red lines: don't resolve the conflict with coincidences
         I've left 2 pending items I need you to decide:
           · [PENDING: what year does it take place?]
           · [PENDING: does the narrator know the ending from the start?]

You resolve the pending items whenever you like (by editing the .md or re-invoking the skill) and continue with the rest of the pipeline, in order:

/bookwright-bible      ← characters, settings, chronology, relationships
/bookwright-outline    ← arcs and act/chapter structure
/bookwright-scenes     ← breakdown into concrete scenes
/bookwright-draft      ← draft the prose of ONE scene

These five are the main path. There are other support skills (/bookwright-synopsis, /bookwright-clarify to list open questions, /bookwright-checklist to check whether an artifact is complete, /bookwright-analyze, /bookwright-continuity, /bookwright-research, /bookwright-verify) that you'll use when you need them.

3 · Build and validate · [in your terminal]

bookwright graph build      # derives the GOLEM graph → bible/graph.ttl
bookwright validate         # exit 0 if there are no continuity errors

---

The loop, not the staircase

That five-step order is only your first pass. Writing isn't linear: researching a scene you discover a fact that changes a character, you rethink the structure mid-draft, a late decision contradicts something you took as settled. Bookwright is built for that back-and-forth, not for a single descent down a staircase.

From the first pass onward, you work in a loop:

• You discover something that changes the canon (while researching, or just thinking) → you re-invoke the affected skill (/bookwright-bible, /bookwright-outline…). The generative skills update in place: they respect your prose and the pending items you've already resolved, and only fill in what's still open. They don't rewrite what you already decided.
• You rethink the structure → you go back to /bookwright-outline, and /bookwright-analyze points out what was left dangling across constitution, bible, outline and scenes (pre-draft consistency).
• You already have prose and want to know what you broke → bookwright validate (deterministic check over the graph) and /bookwright-continuity (the manuscript against the bible: compliance, arcs, chronology, post-draft).
• For fact-based work, research is its own sub-loop: /bookwright-research documents findings with provenance and marks which ones are anchors that constrain the fiction; /bookwright-verify checks the already-written prose against those anchors (anachronisms, procedural errors).
• Forgot where you were? bookwright focus set pins your current objective and bookwright status derives the state and the next step.

The engine behind all of this is the [PENDING] protocol: you leave a marked gap, keep moving, and resolve it once the material is ripe. An unanswered [PENDING] is treated as undecided, not as an answer — so a voice declaration still left as [PENDING: …] stays invisible to the continuity checks until you actually decide it, never a false alarm. /bookwright-clarify lists the project's open questions for you at any time. There is no "definitive" pass: there's a manuscript and a graph that converge iteration by iteration.

The full walkthrough is in Getting started.

---

Design principles

• Plain text is the source of truth. Manuscript, bible, constitution and graph are Markdown, TOML or Turtle (RDF). Human-auditable, git-diffable, portable.
• Batch, not conversational. You consolidate the input; the skill distills it into a versionable artifact. You iterate on the documents, not the chat. The agent is not a sentence-by-sentence co-writer.
• Agent-agnostic. Skills are materialized as portable Agent Skills. Bookwright ships two integrations (claude, generic); agents like Codex, Cursor or Copilot consume the generic output directly.
• GOLEM underneath. The narrative graph uses the GOLEM ontology serialized in Turtle. You don't need to touch RDF to use Bookwright.

---

Roadmap and out of scope

Bookwright already covers research with provenance, context orchestration (authored focus and derived state with a next step) and ingestion of the narrative structure: units, functions and sequences, with optional typing against the Propp and Greimas vocabularies and a narrative-continuity validator. The durable intent across versions lives in bookwright-roadmap.md.

Demand-pulled horizon (no version assigned), activated only by a concrete trigger, never as speculative plumbing: vector search (activated by a real multi-book / series corpus or a measured structural-recall failure) and export to EPUB / PDF / print (activated once the end-to-end flow is proven on a real book).

Cancelled (owner's decision), don't ask for it: genre presets / template packages; the Grafeo / GrafeoIndexer engine; integrations beyond claude and generic; the extension system.

---

Project documents

Note: the project documentation — the documentation site and the design spec linked below — is currently available in Spanish only. This README is the English-language entry point; the rest of the docs have not been translated yet.

• Documentation site — full user guide (getting started, commands, validation, extending, FAQ).
• bookwright-design.md — the complete design specification.
• bookwright-roadmap.md — the durable intent across versions.
• CONTRIBUTING.md — install, quality gates and how to extend the toolkit (new integration, validator, vocabulary).
• CHANGELOG.md — change history.

License

EUPL-1.2 (European Union Public Licence v. 1.2; the LICENSE file carries the official Spanish and English texts). See NOTICE for attribution.

This license covers the bookwright software only. The content you author with it — story bibles, outlines, manuscripts, and the derived knowledge graphs — remains entirely yours.