cclohmar
8763b36378
Some checks failed
Create Release / Check if Version Bump PR Merged (push) Has been cancelled
Post-Merge Version Bump / Check if Version Bump Needed (push) Has been cancelled
Create Release / Create Git Tag and GitHub Release (push) Has been cancelled
Post-Merge Version Bump / Create Version Bump PR (push) Has been cancelled
The pack had a premise (a few sentences), per-book summaries and a weekly timeline, but no single spine saying what the main line is and which threads are side stories. plot.md is the one prose file in DATA/: the author's telling, split into backbone beats, an explicit side-story register, the verbatim transcription (spoken tellings are expected - dictating into a note app is often the easiest way to produce a baseline), deviations once the novel departs from it, and open threads. The hierarchy is written into the file so it cannot drift: plot.md is INTENT, the manuscript is REALISED, the wiki is DETAIL; on conflict the agent reports instead of silently picking. Side stories are first-class - an unregistered thread is invisible to the agent. Wired in: SCHEMA (tree, naming table, new 5.4), templates/DATA/plot.md, OpenNovelAgent load list + read-both-backbone-and-side-stories rule, /init asks for a spoken telling and scaffolds the file, Importer maps fragments into it, StoryReviewer measures chapters against it.
303 lines
12 KiB
Markdown
303 lines
12 KiB
Markdown
# OpenNovelWriter — SCHEMA
|
||
|
||
> **Canonical reference** for the OpenNovelWriter ecosystem.
|
||
> These conventions apply to ALL authors and projects — not just a single book.
|
||
> The `OpenNovelAgent` loads this document to handle structure, filenames, and data formats correctly.
|
||
|
||
---
|
||
|
||
## 1. Project Structure
|
||
|
||
**Concept: one container vault, one folder per book.** A single Obsidian vault
|
||
(e.g. "Novels") holds every book. Each book is a subfolder and *is* the workspace
|
||
you open opencode in. The agent pack lives **once**, at the vault root, and is
|
||
inherited by every book — a book never carries its own `.opencode/`. The canonical
|
||
`docs/SCHEMA.md` likewise exists once, at the vault root.
|
||
|
||
```
|
||
Novels/ # the container vault (Obsidian)
|
||
├── .opencode -> /Users/Shared/NovelPack/.opencode # ONE shared agent pack
|
||
├── docs/ -> /Users/Shared/NovelPack/docs # canonical SCHEMA.md
|
||
├── AGENTS.md # house rules that apply to every book
|
||
├── Scruffy/ # a BOOK = a workspace
|
||
│ ├── AGENTS.md # this book's metadata and rules
|
||
│ ├── DATA/ # this book's world
|
||
│ │ ├── wiki.yaml.md # world wiki (canonical)
|
||
│ │ ├── timeline.yaml.md # timeline (lore history + plot)
|
||
│ │ ├── glossary.yaml.md # translation glossary
|
||
│ │ ├── plot.md # the story baseline: main line + side stories
|
||
│ │ └── style.md # the author's writing style
|
||
│ ├── 01/ # Book 1 (folder = number, title optional)
|
||
│ │ ├── DE/ # language folder (ISO-639-1 code)
|
||
│ │ │ ├── Kapitel 001.md
|
||
│ │ │ └── ...
|
||
│ │ ├── EN/
|
||
│ │ │ ├── Chapter 001.md
|
||
│ │ │ └── ...
|
||
│ │ └── images/ # illustrations for this book
|
||
│ │ ├── prompts/ # image prompts (Markdown, one per image)
|
||
│ │ └── generated/ # generated image files
|
||
│ └── 02/ # Book 2 of the same series
|
||
└── Kessler/ # another book — same shape, own AGENTS.md + DATA/
|
||
```
|
||
|
||
### Multiple books in parallel
|
||
|
||
Each book is a **separate folder inside the one vault**. opencode is always started
|
||
*inside* the book folder; it finds the shared pack by walking up to the vault root,
|
||
so books never duplicate the agents. The `OpenNovelAgent` is identical everywhere —
|
||
what makes a workspace "the Scruffy book" vs. "the Kessler book" is its own
|
||
`AGENTS.md` + `DATA/`. Switch books by switching folders; never put two books in one
|
||
folder. (If several books live in one vault and a book needs to be verifiable on its
|
||
own, make the *book folder* a git repository — not the vault.)
|
||
|
||
## 2. Naming Conventions
|
||
|
||
| Element | Rule | Example |
|
||
|---------|------|---------|
|
||
| **Book folder** | number (2-digit), title optional | `01` → later `01 - Der Dieb im Eulental` |
|
||
| **Language folder** | ISO-639-1 code (code only) | `DE`, `EN`, `PT` |
|
||
| **Chapter file** | localized chapter word + 3-digit number | `Kapitel 001.md` |
|
||
| **Chapter number** | 3 digits, zero-padded | `001` … `100` |
|
||
| **DATA files** | fixed English names | `wiki.yaml.md`, `timeline.yaml.md`, `glossary.yaml.md`, `plot.md` |
|
||
|
||
**Chapter word per language** (defined in `.opencode/languages.yaml`):
|
||
- `de` → `Kapitel`
|
||
- `en` → `Chapter`
|
||
- `pt` → `Capítulo`
|
||
- (the community can add more languages)
|
||
|
||
**Important:** language folder names are ALWAYS the code (`DE`), never spelled out. Chapter files use the *localized* word.
|
||
|
||
---
|
||
|
||
## 3. Data Format: YAML inside `.md` code blocks
|
||
|
||
All DATA files are `.yaml.md` files: Markdown files whose content is a ` ```yaml ` code block.
|
||
|
||
```markdown
|
||
# Title (optional, human-readable)
|
||
|
||
```yaml
|
||
meta:
|
||
title: "..."
|
||
```
|
||
```
|
||
|
||
**Why:** Obsidian renders the code block cleanly; the AI assistant strips the ` ```yaml ` markers and reads the content as pure YAML.
|
||
|
||
---
|
||
|
||
## 4. Key Language: English, Values: localized
|
||
|
||
**Canonical rule:** YAML **keys** are always English and stable. YAML **values** are in the author's canonical language.
|
||
|
||
```yaml
|
||
# CORRECT — keys English, values German
|
||
characters:
|
||
- name: "Leah Kessler"
|
||
role: "Hauptcharakter"
|
||
```
|
||
|
||
```yaml
|
||
# WRONG — localized keys (breaks the schema)
|
||
characters:
|
||
- name: "Leah Kessler"
|
||
Rolle: "Hauptcharakter"
|
||
```
|
||
|
||
**Reason:** the agent parses keys reliably regardless of the canonical language. An author in Spain uses the same schema; only the values are Spanish.
|
||
|
||
---
|
||
|
||
## 5. DATA File Schemas
|
||
|
||
### 5.1 `wiki.yaml.md` — World Wiki
|
||
|
||
```yaml
|
||
meta:
|
||
title: "" # series title
|
||
author: "" # author
|
||
canonical: "" # ISO-639-1 (writing language)
|
||
languages: [] # publication languages
|
||
genre: ""
|
||
audience: ""
|
||
|
||
concept: {} # premises, series ideas (keys are free-form)
|
||
|
||
characters: [] # people
|
||
locations: {} # places
|
||
magic: {} # magic system, spells, creatures
|
||
```
|
||
|
||
### 5.2 `timeline.yaml.md` — Timeline
|
||
|
||
```yaml
|
||
history: # lore history (world background, beyond the plot)
|
||
- date: "" # ISO date OR free text (e.g. "1268-12", "long ago")
|
||
event: ""
|
||
|
||
story: # plot events (the fictional present)
|
||
- date: "" # e.g. "2011-08"
|
||
book: 1 # optional, when multiple books
|
||
chapter: 13 # optional
|
||
event: ""
|
||
```
|
||
|
||
**Rule:** `history` = world background (e.g. a dragon hatches in 1268). `story` = plot progression (e.g. the 2011 school year). Both live in ONE file.
|
||
|
||
### 5.3 `glossary.yaml.md` — Translation Glossary
|
||
|
||
```yaml
|
||
terms:
|
||
- de: "" # canonical term
|
||
en: "" # translation (or missing)
|
||
# pt: "" # more languages as additional keys
|
||
```
|
||
|
||
**Rule:** a term is defined ONCE and used consistently throughout the story. The `ContinuityEditor` checks translations against this glossary.
|
||
|
||
---
|
||
|
||
### 5.4 `plot.md` — the Story Baseline
|
||
|
||
The one DATA file that is **prose, not YAML**. It carries the author's own telling of
|
||
the story — the spine that both author and agent build around — and an explicit register
|
||
of the side stories that weave around it.
|
||
|
||
```markdown
|
||
# Plot — <series title>
|
||
|
||
> Baseline = the author's telling. It is the *main line*, not the whole story:
|
||
> side stories, subplots and new characters are expected and MUST be recorded here,
|
||
> or they are invisible to the agent.
|
||
|
||
## 1. Backbone — what must happen
|
||
### Book 1 — <title>
|
||
1. beat …
|
||
2. beat …
|
||
|
||
## 2. Side stories (register)
|
||
| thread | whose story | spans | status |
|
||
|---|---|---|---|
|
||
| … | … | book 1–2 | planned / placed / written |
|
||
|
||
## 3. Baseline telling (verbatim, dated)
|
||
Paste the transcription here, newest first. Never delete an older telling.
|
||
|
||
## 4. Deviations — where the written novel left the baseline
|
||
## 5. Open threads / unresolved questions
|
||
```
|
||
|
||
**Rules**
|
||
|
||
1. **Hierarchy:** `plot.md` is *intent* (what should happen), the manuscript is
|
||
*realised* (what is written), `Notizen/`/`wiki.yaml.md` is *detail canon*. On conflict,
|
||
the agent **reports** rather than silently picking; the author rules per case.
|
||
2. **The telling is verbatim material.** Spoken word transcribed by a note app is full of
|
||
errors, especially in invented names. Keep it as it came — it is the author's voice —
|
||
but when anything from it is *used*, normalise names against `wiki.yaml.md` and the
|
||
glossary first.
|
||
3. **Side stories are first-class.** A thread that is not in the register does not exist
|
||
as far as the agent is concerned. Add it the moment it is invented.
|
||
4. **Never delete a telling.** Re-recordings are appended as new dated sections; the older
|
||
one is history and shows how the story grew.
|
||
|
||
---
|
||
|
||
## 6. Chapter Conventions
|
||
|
||
- One `.md` file per chapter.
|
||
- First line: `# [Chapter word] NNN - Title` (localized chapter word).
|
||
- Prose follows `style.md` (the author's voice).
|
||
- Numbers written out in prose, if `style.md` dictates it.
|
||
|
||
---
|
||
|
||
## 7. Images & Illustrations
|
||
|
||
Each book has an `images/` folder for illustrations. The `Illustrator` subagent
|
||
handles image generation.
|
||
|
||
```
|
||
01/images/
|
||
├── prompts/ # one .md per image — the prompt + metadata
|
||
└── generated/ # the actual image files (png/jpg/webp)
|
||
```
|
||
|
||
**Prompt file convention** (`images/prompts/NNN - description.md`):
|
||
|
||
```markdown
|
||
---
|
||
chapter: 006 # optional — which chapter the image illustrates
|
||
character: "Scruffy" # optional — subject(s)
|
||
status: draft # draft | approved | generated
|
||
---
|
||
|
||
The image prompt (written in the author's language) that was sent to the
|
||
image generator, plus a short note on why this image matters to the story.
|
||
```
|
||
|
||
**Rules:**
|
||
- Prompts are derived from the **wiki** (character appearance, locations) so images stay consistent with the story.
|
||
- The `Illustrator` is a *subagent* — `OpenNovelAgent` delegates image requests to it, it does not interrupt the author.
|
||
- Generated files land in `images/generated/`, named to match their prompt file.
|
||
|
||
---
|
||
|
||
## 8. The Co-Authoring Cycle
|
||
|
||
```
|
||
Author: "next chapter: X should happen"
|
||
↓
|
||
Agent loads: AGENTS.md + DATA/ (wiki, timeline, glossary, style) + previous chapter summary
|
||
↓
|
||
Agent proposes a chapter draft (beats, POV, ~length) → author approves
|
||
↓
|
||
Agent writes the chapter → author reads/edits in Obsidian
|
||
↓
|
||
Agent harvests new facts (characters, events) → updates wiki.yaml.md / timeline.yaml.md
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Context-Window Strategy (long works)
|
||
|
||
- **Always loaded:** `AGENTS.md`, `style.md`, the `meta:` block, current chapter outline + previous chapter summary.
|
||
- **On-demand (RAG):** remaining wiki entries, specific spells/places — load only when the chapter touches them.
|
||
- **Never** read the whole manuscript at once — reference it via `timeline.yaml.md` (summaries).
|
||
|
||
---
|
||
|
||
## 9. Temperature Policy (creativity vs. hallucination)
|
||
|
||
Temperature is set **per agent role**, not once for the whole system. The principle:
|
||
creative agents run hot (imagination), verification agents run cold (accuracy).
|
||
|
||
| Agent | Role | Temp | Rationale |
|
||
|-------|------|------|-----------|
|
||
| `OpenNovelAgent` | Creative drafting | **0.8** | Imagination — the "write prose" brain |
|
||
| `Illustrator` | Image prompt/creation | 0.7 | Creative visual, but grounded in wiki |
|
||
| `PlotArchitect` | Plot structure | 0.6 | Creative but coherent |
|
||
| `CharacterDeveloper` | Character depth | 0.6 | Creative |
|
||
| `Translator` | Translation | 0.4 | Fidelity first, some idiom |
|
||
| `StyleAnalyst` | Voice extraction | 0.2 | Pattern-finding, not inventing |
|
||
| `Importer` | Migration/extraction | 0.2 | Faithful reconstruction, not invention |
|
||
| `StoryReviewer` | Editorial quality review | 0.3 | Constructive critique, report-only |
|
||
| `LineEditor` | Word choice / naturalness | 0.3 | Catch semantic errors grammar misses |
|
||
| `ContinuityEditor` | Fact/consistency check | **0.1** | Hallucination freedom — like a code reviewer |
|
||
| `Proofreader` | Grammar/spelling | 0.1 | Mechanical precision, no restyling |
|
||
| `CopyrightWatchdog` | Copyright-risk check | 0.1 | Flag expression, not ideas; report-only |
|
||
| `StoryRetriever` | Retrieval/search | 0.1 | Accurate lookup, no creativity |
|
||
|
||
**Why this works:** the hot agent invents the prose; the cold agent verifies it
|
||
(catches contradictions — changed eye color, timeline breaks). This is the same
|
||
"generator hot / reviewer cold" split as code agents, applied to fiction.
|
||
|
||
Each agent's temperature lives in its own frontmatter and can be tuned per author.
|
||
|
||
---
|
||
|
||
## 10. Versioning
|
||
|
||
The project directory is a Git repository. Every chapter approval = a commit. This enables rollback and community collaboration.
|