book-writer

Files (9)

• README.md
• SKILL.md
• beats-fiction.md · docs/
• beats.md · docs/
• book-mode.md · docs/
• chapter-architecture.md · docs/
• long-form-orchestration.md · docs/
• shape-table.md · docs/
• workspace-management.md · docs/

SKILL.md (first lines)

# Book Writer

Book-scale orchestration skill. Pairs with `/authors-voice` (voice pipeline). Together: this skill specifies WHAT must land in each beat; `/authors-voice` specifies HOW the prose sounds.

## FIRM RULES

### 0. Author owns substance. The agent QUERIES — it does not propose from cold.

The load-bearing rule. It governs every book-start, not just beat work, and it is stated here (not only in `docs/beats.md`) so it is in context the moment any book begins. **Author owns substance + beat material; the agent owns process + shape.**

On ANY book-start intent — "write a book", "start writing it", "start a book project", "draft a chapter" — the substance comes OUT of the author before any beats or prose exist. The default is to QUERY, never to manufacture:

- **Every book (and every chapter) begins with the author DUMP** (`docs/beats.md` → 5-pass, Pass 1): the author brain-dumps the material; the agent captures it verbatim, then structures it. No beats, no chapter shape, and no prose exist before the author has dumped.
- **Never propose beats from cold** — mined from the premise, source docs, or the agent's own intuition. The documented failure mode: the author rejects them because they came from outside the author's brain. Pull the material out of the author with focused questions; structure what comes back.
- The agent proposes only in the narrow documented cases (`docs/beats.md` → "When proposing IS the right move"): the author explicitly asks for candidates, the agent is mechanically restructuring source the author already owns, or the author has said move fast on low-stakes draft work. Anything the agent originates this way is shown to the author as a proposal — the agent never calls its own output "locked."

If you reach for beats or prose and the author has not dumped the material, you have skipped step one. **STOP and run the dump.**

Full method: `docs/beats.md` (Query-first principle + the 5-pass extraction). Fiction runs the scene-shaped fork of the same 5-pass — `docs/beats-fiction.md`.

### 1. Book orchestration loads BEFORE per-chapter work.

The book-class question, chapter architecture, and workspace management must commit before any per-chapter beat work begins. Per-chapter beats without committed chapter containers land in arbitrary places, spill across boundaries, and produce a book the reader can't carry.

If the user asks for chapter-level work and the book hasn't run through architecture: **STOP** and run architecture first. Architecture passes are cheap; beat work in wrong containers is expensive.

### 2. Prose generation always delegates to /authors-voice.

This skill owns SHAPE — chapter containers, beats, workspace organization, vignette slots, the TASK brief. `/authors-voice` owns VOICE — anchor blend, NEVER rules, fingerprints, minion dispatch, post-write audit. When a chapter draft or any prose pour is needed, this skill's job ends at "the brief is locked"; the prose call goes through `/authors-voice`'s Apply Protocol with the brief as the TASK.

**If this skill catches itself drafting prose: STOP and spawn a authors-voice minion** — even for one sentence, one transition, one closer. Same Rule 1 as authors-voice, applied at the orchestration layer.

Two carve-outs (mirroring authors-voice):
- **Beat structure text** (declarative claim names, commitment paragraphs, chapter briefs, vignette slot descriptions) is editor territory — these are commitments, not prose.
- **Doc metadata** (frontmatter, structural flags, reshape history entries, source provenance notes, TODO lists) is editor territory.

### 3. Workspace management is enforced at creation, not retrofitted.

Every doc created during book work goes into its lifecycle-correct container at creation time. Per `docs/workspace-management.md` (v2 chapter-first lock 2026-05-20):
- **Book Spine** (top-level) — architectural docs (Thesis, TOC, Argument Arc, Voice & Form, etc.)
- **Working Notes** (top-level) — scratch, pilot tests, ephemera
- **Ch N — <Title>** (one container per chapter) — holds the chapter's Beats doc + Research Notes doc + a Drafts sub-container
- **Drafts** (sub-container under each chapter) — one per-beat prose doc (`Ch N — Bk: <Name>`)

**Ascending-order convention:** sidebar containers and ordered doc lists go ascending top-to-bottom (Ch 1 at top, Ch N at bottom; B1 at top, BN at bottom). Fix sidebar order in the same pass as any insert/reorder.

Creating in the wrong container, skipping the container parameter, or leaving newest-first ordering produces sidebar mess that takes a full pass to clean up.

### 4. Catalogue citations in `Ch N — Research Notes` as you find them.

Every chapter has a Research Notes doc alongside Beats. Sources land there the moment you find them — academic citations, URLs, supporting data, key quotes. Beats docs reference Research Notes by docId; never inline citations. Catalogue during build, not at the end.

### 5. Every doc-to-doc reference is declared via `link_to` at create/edit time.

When any workspace doc draws from another workspace doc, call `link_to(source_doc_id, target_doc_id)` at the moment the connection is made. Writes the target into the source's `references:` frontmatter — metadata only, no prose mutation. Idempotent. The target's inbound list (backlinks) is computed live by scanning every doc's references, so the target picks the connection up without any work on its end.

Applies to:
- **Every beat-prose draft** → links to its Beats doc + Research Notes + any Concept doc whose content it draws on.
- **Every Beats doc** → links to its Research Notes + every Concept doc it references + sibling chapter Beats it does callbacks to.
- **Every Research Notes doc** → links to every Concept doc it cites in the source list.
- **Any later edit that pulls in a new Concept doc** → link in the same pass as the edit lands.

**External references** (papers, DOIs, web URLs) stay inline markdown `[Author Year, Journal](URL)` in Research Notes. They don't need `link_to` — backlinks are an internal-workspace primitive.

If the editor skips `link_to` as the workspace fills in, the graph drifts. Downstream context-recovery crawls (`get_graph`) miss load-bearing connections, and the agent loses the ability to walk from a chapter back to its concept sources or its sibling chapter beats.

## The book-class question (run FIRST, every book project)

Before any chapter work, answer two questions:

### Question 1 — Fiction or nonfiction?

| Signal | Class |
|---|---|
| Narrative, scene-structured, character-driven | Fiction |
| Argument, mechanism, evidence, source-material-driven | Nonfiction |
| Memoir / personal essay collection | Nonfiction (treat as domain-driven, the domains are life-themes) |
| Hybrid (Sebastian Junger, John McPhee — narrative nonfiction) | Nonfiction with fiction-style scene structure inside chapters |

### Question 2 — Nonfiction only: argument-driven or domain-driven?

Detail in `docs/chapter-architecture.md` (the book-class question section runs the full decision logic). Quick form:

| Signal | Class |
|---|---|
| Author has one extended argument to make; no rich knowledge graph yet | Argument-driven |
| Author has concept docs / research notes / prior drafts / a domain library | Domain-driven |
| Prescriptive transformation popular science | Domain-driven default |
| One big idea unpacked | Argument-driven |
| "Complete picture of X domain" | Domain-driven |

**Fiction handling:** fiction runs the **scene-shaped fork** of the same methodology — `docs/beats-fiction.md`. The beat unit changes from a declarative CLAIM to a SCENE (who wants what, what blocks it, how the value turns), and two of the 5 passes read on that unit (DRIVE, CATEGORY). Everything else is shared with nonfiction `docs/beats.md`: author owns substance + beat material, the agent QUERIES, the DUMP comes first, one beat = one dispatch, prose pours through /authors-voice. At the book-class question, fiction → `docs/beats-fiction.md`; nonfiction → `docs/beats.md`.

## Architecture

```
book-writer/
├── SKILL.md                       (this file — router + firm rules + book-class question)
└── docs/                          (loaded on routing match)
    ├── chapter-architecture.md    (chunk-to-container commit; substantive-name rule; 2 pipelines)
    ├── beats.md                   (per-chapter beat methodology; nonfiction default — declarative claims)
    ├── long-form-orchestration.md (book-scale workflow pipeline; multi-minion patterns)
    ├── book-mode.md               (per-session book-writing workflow + openwriter integration)
    ├── workspace-management.md    (container hierarchy + doc naming + rename discipline)
    └── shape-table.md             (canonical project dashboard — chapters × beats × drafts × % done)
```

These docs are canonical in this skill. The `/authors-voice` skill may reference them during the transition period — when in doubt, the copy here is authoritative.

## Routing

| User intent | Action |
|---|---|
| "/book-writer" / "/book" / "start a book project" | Run **Book-Class Question** → **Workspace Setup** (`docs/workspace-management.md`) → **Chapter Architecture** (`docs/chapter-architecture.md`) → **Per-Chapter Beat Work** (`docs/beats.md`) |
| "chapter architecture" / "TOC" / "chapter list" / "book outline" | `docs/chapter-architecture.md` |
| "chapter beats" / "beat map" / "beat draft" / "beat sheet" | `docs/beats.md` (nonfiction — declarative-claim beats) · `docs/beats-fiction.md` (fiction — scene beats). Both start with the author DUMP; never propose beats from cold. |
| "workspace organize" / "where does X go" / "container structure" / "rename chapter" | `docs/workspace-management.md` |
| "shape table" / "project shape" / "where are we" / "% done" / "book status" / "progress" / "dashboard" | `docs/shape-table.md` |
| "book mode" / "session workflow" / "openwriter book setup" | `docs/book-mode.md` |

From travsteward/openwriter, MIT.

More from travsteward/openwriter