Einzelbände liegen unter {content_root}/projects/{buch-slug}/, Bände einer Serie unter {content_root}/series/{serien-slug}/{buch-slug}/.
{buch-slug}/
├── README.md # Buch-Metadaten (YAML-Frontmatter)
├── CLAUDE.md # Buch-Regeln, Callbacks, linter_mode
├── synopsis.md # Klappentext und Langsynopse
├── world-rules.md # nur Fiction: kanonisch heikle Fakten
├── plot/ # outline.md, acts.md, arcs.md, timeline.md, tone.md, canon-log.md
├── characters/ # INDEX.md und eine Datei je Figur
├── world/ # setting.md (Travel Matrix), rules.md, history.md, glossary.md
├── research/ # sources.md und notes/
├── chapters/
│ └── {NN-slug}/
│ ├── README.md # Kapitel-Metadaten, Chapter Timeline, Promises
│ └── draft.md # die Prosa
├── cover/ # brief.md, prompts.md, art/
├── promo/ # bei Bedarf angelegt
├── export/ # front-matter.md, back-matter.md, blurb.md, output/
└── translations/ # {sprache}/ mit glossary.md und chapters/
Bei book_category: memoir ersetzt people/ das Verzeichnis characters/, world/ und world-rules.md entfallen, und plot/ enthält structure.md und people-log.md statt acts.md, arcs.md und canon-log.md.
| Ebene | Reihenfolge |
|---|---|
| Buch | Idea, Concept, Research, Plot Outlined, Characters Created, World Built, Drafting, Revision, Editing, Proofread, Export Ready, Published |
| Kapitel | Outline, Draft, Revision, Polished, Final |
| Figur | Concept, Profile, Backstory, Arc Defined, Final |
| Idee | raw, explored, developed, ready, shelved, promoted |
Der Buchstatus wird aus den Kapiteln abgeleitet und nur nach vorn bewegt:
| Buchstatus | Auslöser |
|---|---|
Drafting |
mindestens ein Kapitel ist über Outline hinaus |
Revision |
alle Kapitel sind mindestens auf Revision-Stufe |
Proofread |
alle Kapitel sind Final |
Editing, Export Ready und Published setzt du selbst. Ein höherer, von dir gesetzter Status wird nie zurückgestuft. rebuild_state() schreibt den abgeleiteten Status in die README zurück.
Als Kapitelstatus werden Aliasse erkannt: review und reviewed zählen als Revision, drafting als Draft, polishing als Polished, done als Final.
Das Plugin registriert fünf Hook-Befehle auf drei Ereignissen. Sie laufen über den Wrapper bin/run-server mit dem Python der virtuellen Umgebung.
| Ereignis | Skript | Wirkung |
|---|---|---|
PostToolUse (Write, Edit, MultiEdit) |
hooks/validate_chapter.py |
Prosa-Prüfung einer draft.md |
PostToolUse (Write, Edit, MultiEdit) |
hooks/validate_character.py |
Struktur-Prüfung von Figuren- und Personendateien |
PostToolUse (Write, Edit, MultiEdit) |
hooks/snapshot_draft.py post |
Führt Claudes Änderung in die Vergleichsfassung ein |
PreToolUse (Write, Edit, MultiEdit) |
hooks/snapshot_draft.py pre |
Hält den Entwurf unmittelbar vor Claudes Schreibvorgang fest |
| PreCompact | hooks/precompact_sync_claudemd.py |
Sichert Regeln, Workflows und Callbacks vor der Kontext-Komprimierung |
validate_chapter)Der Hook läuft nach dem Schreiben. Er prüft nur Dateien namens draft.md unterhalb eines Verzeichnisses chapters/ und nur, wenn der Text mindestens 50 Wörter hat. Er sucht das Buch-Hauptverzeichnis (das Verzeichnis mit chapters/ und README.md) und führt diese Prüfungen aus:
| Prüfung | Stufe | Gegenstand |
|---|---|---|
| Buchregeln | block | Muster aus den Buchregeln und den Verbotsmustern in plot/tone.md, die in Backticks stehen |
| Autoren-Banlist | block oder warn | verbotene Phrasen (Don'ts) und wiederkehrende Tics des Autors, jeweils mit eigener Stufe |
| Meta-Narrative | block | Erzähltext, der über die Buchstruktur spricht, zum Beispiel Ch 5, callback, as established, echoes the earlier, foreshadow, calls back to, parallels the earlier |
| Story-Zeitanker | warn | relative Zeitphrasen wie yesterday oder an hour ago gegen den Kapitelstart |
| AI-Tells und globale Muster | warn | Muster aus reference/craft/anti-ai-patterns.md (nur bei englischer Buchsprache) |
| Satzlängen-Varianz | warn | Standardabweichung der Satzlänge unter 4 Wörtern bei mehr als 10 Sätzen |
| POV-Grenze | warn | Fachvokabular, das die POV-Figur laut knowledge-Profil nicht kennt |
Im Modus strict beendet sich der Hook bei einem Fund der Stufe block mit Exit-Code 2. Die Meldung geht an Claude zurück, das den Text korrigieren muss. Im Modus warn (siehe Konfiguration) werden Blocker nur ausgegeben. Warnungen blocken nie.
StoryForge linter flagged this write as blocking:
[BLOCK] draft.md line 12: Banned phrase from book CLAUDE.md: 'clocked'
Plus 2 non-blocking warnings:
[WARN] draft.md line 8: phrase 'yesterday' implies Mon Dec 23 ~19:30
(chapter starts Tue Dec 24 ~19:30). Verify against plot/timeline.md.
The file was already written but is invalid — fix the blocking issues. Set `linter_mode: warn` in the book's CLAUDE.md frontmatter to override.
Dasselbe Regelwerk steht als Tool validate_chapter zur Verfügung.
validate_character)Der Hook greift bei .md-Dateien unter characters/ und people/. INDEX.md wird übersprungen. Übersprungen wird außerdem nur der exakte Pfad eines Serien-Trackers, series/{serie}/characters/{datei} oder series/{serie}/people/{datei}. Figurendateien von Büchern unter series/{serie}/{buch}/characters/ liegen eine Ebene tiefer und werden normal geprüft.
name und status; bei Figuren (nicht bei Memoir-Personendateien) zusätzlich role.protagonist, deuteragonist, antagonist, love-interest, mentor, foil, herald, confidant, supporting, minor).Want vs. Need, Fatal Flaw, The Ghost (oder Backstory) und Motivation Chain (oder GMC). Figuren mit Rolle minor sind davon ausgenommen.person_category, consent_status oder real_name) werden weder auf die Rolle noch auf die empfohlenen Abschnitte geprüft.Vor jeder Kontext-Komprimierung liest der Hook das Transkript, sucht in deinen Nachrichten Zeilen mit den Präfixen Regel: (auch Rule:), Workflow: und Callback: und speichert sie für das aktive Buch (das Buch aus session.last_book im State-Cache). Dabei wird kein Sprachmodell benutzt, es ist reine Mustersuche.
CLAUDE.md des Buchs tut der Hook nichts.hooks/snapshot_draft.py hält zwei Fassungen eines Fiction-Kapitels fest. Er prüft nichts, blockiert nie, gibt nichts aus und schluckt Fehler. Memoir-Kapitel werden übersprungen.
~/.storyforge/snapshots/{buch-slug}/{kapitel-slug}.md (Verzeichnis per Umgebungsvariable STORYFORGE_SNAPSHOT_DIR änderbar). pre hält den Entwurf unmittelbar vor Claudes Schreibvorgang fest, post führt per Absatz-Dreiwege-Merge nur Claudes Änderung in die Baseline ein — so bleiben deine eigenen Änderungen als Unterschied zwischen draft.md und der Baseline sichtbar. Darauf liest get_self_edit_hunks auf Zuruf; refresh_draft_baseline setzt die Baseline neu.~/.storyforge/snapshots/.raw/{buch-slug}/{kapitel-slug}.md. create_chapter legt sie mit der Kapitelüberschrift an (nur Fiction), danach wächst sie nur durch reine Anhänge des Chapter Writers. Schreibvorgänge, die vorhandenen Text ändern (Reviewer, Humanizer, Proofreader, Fixer), ändern sie nicht. Lesbar mit list_raw_drafts(book_slug) und read_raw_draft(book_slug, chapter_slug).Regeln, Workflows und Callbacks eines Buchs stehen in der Datenbank und werden über append_book_rule, append_book_workflow, append_book_callback oder das Skill /storyforge:register-callback angelegt.
Für den Prosa-Hook zählt nur, was in einer Regel in Backticks steht:
| Schreibweise | Wirkung |
|---|---|
`clocked` |
Hartes Muster. Enthält der Text Regex-Zeichen, wird es als regulärer Ausdruck behandelt, sonst als Text. Eine Ausnahme gilt für eine verschachtelt unbegrenzt quantifizierte Gruppe wie (a+)+ (ReDoS-Risiko): Sie wird stattdessen als Text durchgesetzt. Einfach quantifizierte Gruppen wie (foo)+ oder (?:being){2} bleiben Regex. Groß- und Kleinschreibung ist egal. |
`journey` max 2 per chapter |
Erlaubt bis zu N Treffer je Kapitel. Das Limit wird auf die aktuelle Entwurfslänge im Verhältnis zur Ziel-Wortzahl des Kapitels skaliert. |
Erkannte Limit-Schreibweisen: max N per chapter, maximum N per chapter, limit to N per chapter, ein Bereich max N-M per chapter (die obere Grenze zählt) und per kapitel.
Mit lint_book_rules oder /storyforge:rules-audit prüfst du Regeln auf Formulierungen, die der Scanner nicht erfassen kann.
Der Abschnitt „Banned Prose Patterns" in plot/tone.md eines Buchs wird maschinell gelesen. Die Überschrift darf auf jeder Ebene von ## bis ###### stehen, der Abschnitt läuft bis zur nächsten Überschrift derselben oder einer höheren Ebene. Aufzählungspunkte mit einer Phrase in Backticks sind durchsetzbar, ein Zusatz wie Max. 1 pro Kapitel begrenzt die Treffer je Kapitel genauso wie bei Buchregeln:
## Banned Prose Patterns
- `plötzlich` Max. 1 pro Kapitel
- Vermeide zu viele rhetorische Fragen in Folge.
Im Beispiel ist nur der erste Punkt durchsetzbar. Der zweite trägt keine Backtick-Phrase und bleibt ein reiner Hinweis, den niemand scannt: Reviewer sehen ihn in tonal_rules.banned_prose_unenforced, der Humanizer warnt davor, und im Chapter Writing Brief steht er unter tone_banned_patterns.advisory_unenforced.
Durchsetzbare Tonregeln wirken wie Buchregeln: Der Prosa-Hook blockt sie mit Kapitel-Limit, der Manuscript Checker liest sie als Buchregeln mit, und scan_chapter_ai_tells/check_replacement_text beachten sie. Die Vorlage templates/plot-tone.md setzt die Überschrift auf Ebene 2.
Der globale Katalog (reference/craft/anti-ai-patterns.md, Abschnitt 1 Vokabular und Abschnitt 11 Banned Shapes) gilt nur für Bücher auf Englisch. Die Sprache kommt aus dem Feld language im YAML-Frontmatter der README.md des Buchs (Standard en; en-US zählt als en). Für jede andere Sprache wird eine Datei anti-ai-patterns.<sprache>.md erwartet; es gibt aktuell keine, also entfallen die Katalog-Treffer für solche Bücher komplett, statt englische Muster blind anzuwenden. Betroffen sind die Hook-Kategorien ai_tell und global_shape_violation, beim Manuscript Checker ai_tell_violation und global_shape_violation, sowie der Vorlauf des Humanizers. scan_chapter_ai_tells und check_replacement_text liefern für solche Bücher eine Warnung statt Katalog-Treffer. Buchregeln, Autoren-Verbote, Tics und Tonregeln wirken unabhängig von der Buchsprache weiter.
Die Autoren-Erkenntnisse (verbotene Phrasen, wiederkehrende Tics, Don'ts, Style Principles) liegen in der Datenbank authors.db. Der Prosa-Hook durchsucht davon nur die Don'ts und die wiederkehrenden Tics. Style Principles prüft er nicht. Sie werden von chapter-writer, chapter-reviewer und author-check über get_author bzw. den Chapter Writing Brief gelesen. Die Datei vocabulary.md ist reine Referenz und wird für die Durchsetzung nicht gelesen. Eine neue verbotene Phrase legst du mit write_author_banned_phrase oder add_vocabulary_entry an. create_author legt beim Anlegen zusätzlich 19 verbreitete AI-Tell-Wörter (etwa delve, tapestry, nuanced, resonate, pivotal) als Don'ts in der Datenbank an, sie wirken ab sofort.
Den Autor eines Buchs findet der Hook über die Zeile - **Author:** Name im Abschnitt Book Facts der CLAUDE.md, sonst über das Feld author: im YAML-Frontmatter der README.md des Buchs.
Jedes Kapitel kann in seiner README.md einen Abschnitt ## Chapter Timeline mit Start- und Endzeit der Szenen haben, zum Beispiel **Start:** Tue Dec 24 ~19:30. Aus dem Start berechnet das Plugin, welches Datum relative Phrasen wie yesterday oder tomorrow meinen. Der Prosa-Hook warnt bei jeder solchen Phrase mit dem abgeleiteten Datum, damit du sie gegen plot/timeline.md prüfst. Das Tool get_current_story_anchor liefert die Zuordnung direkt:
{
"available_relative_phrases": {
"yesterday": "Mon Dec 23 ~19:30",
"tomorrow": "Wed Dec 25 ~19:30"
}
}
get_recent_chapter_timelines(book_slug, n) liefert die Zeitraster der letzten N Kapitel, damit neue Kapitel an echten Zeiten statt an erinnerten verankert werden. validate_timeline_consistency prüft die Zeitdrift über das ganze Buch.
get_chapter_writing_brief(book_slug, chapter_slug) ersetzt viele einzelne Lese-Schritte im Skill chapter-writer durch ein JSON mit diesen Teilen:
chapter, pov_characterstory_anchor, recent_chapter_timelines, recent_chapter_endingscharacters_present mit Profil, knowledge, tactical und series_evolution (immer vorhanden, null ohne Serien-Kontext; befüllt bei Serienbänden mit Tracker-Text, für beide Layouts projects/{buch} und series/{serie}/{buch})pov_character_inventory (zuletzt etablierter Besitz der POV-Figur)rules_to_honor, callbacks_in_register, banned_phrasesrecent_simile_count_per_chapter, tone_litmus_questions, tone_banned_patterns (enforced, advisory_unenforced)tactical_constraints (nur bei Kampf- oder Reiseszenen), review_handleerrorsJede Komponente wird einzeln abgesichert. Fällt eine aus, steht sie in errors, und der Brief kommt mit den übrigen Daten trotzdem an. Häufige Ursache sind fehlende world/setting.md oder plot/timeline.md.
verify_tactical_setup prüft Kampf- und Reiseszenen gegen den optionalen Block tactical im Frontmatter einer Figur:
tactical:
protector_role: false
protected_role: true
combat_skill: none # none|low|medium|high|elite|unknown
movement_lead: false
movement_rear: false
vulnerable_to: [daylight, silver]
carries: [knife]
Regeln: Eine geschützte Figur am Ende (R1) oder an der Spitze (R2) der Gruppe warnt. Eine geschützte Figur ohne positionierten Beschützer warnt (R3). Eine Spitzenposition, die nicht zu movement_lead: true passt, warnt (R4). Ohne taktische Daten gibt es nur einen Hinweis (R0). Das Tool liefert außerdem Fragen an den Autor als Checkliste.
Der optionale Block knowledge im Frontmatter einer Figur ordnet Wissensgebiete den Stufen expert, competent, layperson und none zu:
knowledge:
expert: [it, networking]
competent: [photography]
layperson: [history]
none: [forensics, medicine]
Fachvokabular eines Gebiets, das für die POV-Figur none oder layperson ist, erzeugt eine Warnung. Treffer werden als ganze Wörter gesucht. Freie Gebietsnamen zählen als competent. Ohne knowledge-Block wird die Figur nicht geprüft. Mitgelieferte Vokabellisten liegen unter reference/craft/knowledge-domains/: forensics, tactical_combat, medicine, ballistics, automotive_repair.
analyze_plot_logic(book_slug, scope?, chapter_slug?) baut einen Wissensindex aus Canon-Fakten, Timeline und Promises und führt zwei deterministische Prüfungen aus:
| Kategorie | Prüfung | Memoir |
|---|---|---|
causality_inversion |
Ein Kapitel verweist auf einen Fakt, dessen Kapitel später in der Story-Zeit liegt | aktiv |
chekhov_gun |
Eine registrierte Promise ohne Einlösung (nur im Manuskript-Scope) | übersprungen |
Die semantischen Kategorien information_leak, motivation_break, premise_violation und pov_knowledge_boundary bewerten die Skills chapter-reviewer und manuscript-checker mit Hilfe des Wissensindex. premise_violation entfällt im Memoir.
Promises sind Setup-Elemente (Chekhov-Elemente, Rätsel, Callbacks) pro Kapitel. register_chapter_promises schreibt sie in den Abschnitt ## Promises der Kapitel-README, get_chapter_promises liest sie. Für bereits geschriebene Kapitel füllt /storyforge:backfill-promises sie nach. Die Wahrheit bleibt der Canon-Log in der Datenbank (add_canon_fact).
Erkenntnisse wandern über drei Ebenen: Buch, Autor, global. /storyforge:harvest-author-rules ruft harvest_book_rules auf und sortiert die Regeln eines Buchs in banned_phrase, style_principle und world_rule. Pro Kandidat entscheidest du: übernehmen, nur im Buch behalten, verwerfen oder bearbeiten und übernehmen. Übernommene Einträge tragen eine Herkunft wie _(emerged from firelight, 2026-04)_. Taucht dieselbe Erkenntnis in einem späteren Buch wieder auf, kommt eine zweite Herkunft dazu statt eines Duplikats. /storyforge:promote-rule hebt eine einzelne Regel auf Autoren- oder globale Ebene.
Die Abschnitte im Autorenprofil heißen Recurring Tics, Style Principles und Don'ts. chapter-writer und chapter-reviewer laden sie über get_author.
run_pre_export_gates prüft:
| Gate | Blockiert |
|---|---|
Alle Kapitel Final |
ja |
| Mindestens ein Kapitel vorhanden | ja |
| Wortzahl mindestens 80 % des Ziels | nein, nur Warnung |
| Synopsis mit mehr als 50 Wörtern | nein, nur Warnung |
Mit --arc darf export-engineer das Gate „Alle Kapitel Final" übergehen, nach ausdrücklicher Bestätigung. Weitere Regeln des Skills:
check_memoir_consent. Bei FAIL bricht der Export ab, bei WARN fragt das Skill nach.export/front-matter.md (kein Platzhalter [Author Name], Feld author gefüllt).review_handle im Entwurf stoppen den Export.get_cover_image eines liefert. Ohne Cover wird trotzdem exportiert.export/output/{buch-slug}.{epub|pdf|mobi}, bei ARC {buch-slug}-arc.{ext}.Neben den Markdown-Dateien nutzt StoryForge SQLite-Datenbanken unter ~/.storyforge/db/:
| Datei | Inhalt |
|---|---|
storyforge.db |
Session (aktives Buch, Kapitel, Phase) |
authors.db |
Autoren-Erkenntnisse (author_discoveries) und protokolliertes Review-Feedback (review_feedback) |
{serie-oder-buch-slug}.db |
Canon-Fakten, Charakter-Snapshots, Buchregeln und Callbacks, Cover-Verwaltung |
Die Vergleichs- und Rohfassungen der Fiction-Entwürfe unter ~/.storyforge/snapshots/ sind keine Datenbank, sondern einfache Dateien.
Der Umstieg von Markdown-Daten auf die Datenbanken geschieht einmalig mit Skripten im Verzeichnis scripts/ des Plugins. Führe sie mit dem Python der virtuellen Umgebung aus, in dieser Reihenfolge. Alle sind wiederholbar, bereits vorhandene Einträge werden übersprungen.
| Schritt | Skript | Vorschau und Ausführung |
|---|---|---|
1. Buchregeln und Callbacks aus CLAUDE.md |
scripts/migrate_book_rules.py |
--dry-run zeigt nur an. Ohne Flag wird geschrieben. --clear-markers leert danach die Marker-Abschnitte. |
2. Canon-Log (plot/canon-log.md, people-log.md) |
scripts/migrate_canon_log_to_db.py |
Ohne Flag nur Vorschau, --execute schreibt. |
3. Writing Discoveries aus profile.md und Figuren-Snapshots |
scripts/migrate_phase3.py |
--dry-run zeigt nur an. Ohne Flag wird geschrieben. |
4. Verbotene Wörter aus vocabulary.md |
scripts/migrate_vocabulary_to_db.py |
Ohne Flag nur Vorschau, --execute schreibt. |
5. source_genres nachtragen |
Skill /storyforge:migrate-source-genres |
für Autoren, die study-author früher genutzt haben |
Für Bücher mit alten Regeln in Anführungszeichen statt Backticks gibt es python -m tools.claudemd.migrate_to_backticks <buchpfad>. Ohne --apply zeigt es nur die Änderung, mit --apply fragt es vor dem Schreiben nach. Aus dem Plugin-Verzeichnis aufrufen.
Zum Nachfüllen in bestehenden Büchern dienen die Skills /storyforge:backfill-promises und /storyforge:backfill-style-principles.