StoryForge: Technical Details

Deutsche Version

← Back to overview

Project structure of a book

Standalone books live under {content_root}/projects/{book-slug}/, volumes of a series under {content_root}/series/{series-slug}/{book-slug}/.

{book-slug}/
├── README.md           # Book metadata (YAML frontmatter)
├── CLAUDE.md           # Book rules, callbacks, linter_mode
├── synopsis.md         # Blurb and long synopsis
├── world-rules.md      # fiction only: canonically fragile facts
├── plot/               # outline.md, acts.md, arcs.md, timeline.md, tone.md, canon-log.md
├── characters/         # INDEX.md and one file per character
├── world/              # setting.md (travel matrix), rules.md, history.md, glossary.md
├── research/           # sources.md and notes/
├── chapters/
│   └── {NN-slug}/
│       ├── README.md   # Chapter metadata, chapter timeline, promises
│       └── draft.md    # the prose
├── cover/              # brief.md, prompts.md, art/
├── promo/              # created on demand
├── export/             # front-matter.md, back-matter.md, blurb.md, output/
└── translations/       # {language}/ with glossary.md and chapters/

With book_category: memoir, people/ replaces characters/, world/ and world-rules.md are omitted, and plot/ contains structure.md and people-log.md instead of acts.md, arcs.md and canon-log.md.

Status model

The book status is derived from the chapters and only ever moves forward:

You set Editing, Export Ready and Published yourself. A higher status you set is never downgraded. rebuild_state() writes the derived status back to the README.

Chapter status aliases are recognised: review and reviewed count as Revision, drafting as Draft, polishing as Polished, done as Final.

Hooks

The plugin registers five hook commands on three events. They run through the wrapper bin/run-server with the virtual environment's Python.

Prose check (validate_chapter)

The hook runs after the write. It only checks files named draft.md below a chapters/ directory, and only when the text has at least 50 words. It locates the book root (the directory containing chapters/ and README.md) and runs these checks:

In strict mode the hook exits with code 2 on a block-level finding. The message goes back to Claude, which has to correct the text. In warn mode (see configuration) blockers are only printed. Warnings never block.

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.

The same rule set is available as the tool validate_chapter.

Character check (validate_character)

The hook acts on .md files under characters/ and people/. INDEX.md is skipped. Also skipped is only the exact path of a series tracker, series/{series}/characters/{file} or series/{series}/people/{file}. Character files of books under series/{series}/{book}/characters/ sit one level deeper and are checked normally.

• Block: missing or invalid YAML frontmatter, missing fields name and status; for characters (not memoir person files) also role.
• Warning: unknown role (valid are protagonist, deuteragonist, antagonist, love-interest, mentor, foil, herald, confidant, supporting, minor).
• Warning: missing recommended sections Want vs. Need, Fatal Flaw, The Ghost (or Backstory) and Motivation Chain (or GMC). Characters with role minor are exempt.
• Memoir person files (with person_category, consent_status or real_name) are checked neither for role nor for the recommended sections.

PreCompact

Before every context compaction the hook reads the transcript, looks in your messages for lines with the prefixes Regel: (also Rule:), Workflow: and Callback: and stores them for the active book (the book from session.last_book in the state cache). No language model is involved, it is plain pattern matching.

• The case of the prefix does not matter.
• The entry must be on a single line.
• An entry longer than 300 characters is silently dropped.
• Messages without a prefix are not stored.
• Without an active book, or without the book's CLAUDE.md, the hook does nothing.

Draft snapshots (snapshot_draft)

hooks/snapshot_draft.py keeps two versions of a fiction chapter. It checks nothing, never blocks, prints nothing and swallows errors. Memoir chapters are skipped.

• Baseline at ~/.storyforge/snapshots/{book-slug}/{chapter-slug}.md (the directory is overridable via the STORYFORGE_SNAPSHOT_DIR environment variable). pre captures the draft right before Claude's write; post merges only Claude's change into the baseline through a paragraph-level three-way merge — so your own edits stay visible as the difference between draft.md and the baseline. get_self_edit_hunks reads this on request; refresh_draft_baseline resets the baseline.
• Raw draft at ~/.storyforge/snapshots/.raw/{book-slug}/{chapter-slug}.md. create_chapter seeds it with the chapter heading (fiction only), after which it only grows through the chapter writer's plain appends. Writes that change existing text (reviewer, humanizer, proofreader, fixer) do not touch it. Readable with list_raw_drafts(book_slug) and read_raw_draft(book_slug, chapter_slug).

Book rules

A book's rules, workflows and callbacks live in the database and are created through append_book_rule, append_book_workflow, append_book_callback or the skill /storyforge:register-callback.

For the prose hook only what a rule puts in backticks counts:

Recognised limit notations: max N per chapter, maximum N per chapter, limit to N per chapter, a range max N-M per chapter (the upper bound counts) and per kapitel.

Use lint_book_rules or /storyforge:rules-audit to check rules for wordings the scanner cannot catch.

Banned patterns from plot/tone.md

The "Banned Prose Patterns" section in a book's plot/tone.md is read by the machinery. The heading may sit at any level from ## to ######; the section runs to the next heading of the same or a shallower level. Bullets with a phrase in backticks are enforceable, and an addition such as max 1 per chapter caps hits per chapter exactly like book rules:

## Banned Prose Patterns

- `suddenly` Max 1 per chapter
- Avoid too many rhetorical questions in a row.

In the example only the first bullet is enforceable. The second carries no backtick phrase and stays a plain hint that nothing scans: reviewers see it under tonal_rules.banned_prose_unenforced, the humanizer warns about it, and the chapter writing brief carries it under tone_banned_patterns.advisory_unenforced.

Enforceable tone rules act like book rules: the prose hook blocks them with a per-chapter cap, the manuscript checker reads them in alongside book rules, and scan_chapter_ai_tells/check_replacement_text honor them. The template templates/plot-tone.md sets the heading at level 2.

Book language and the global catalog

The global catalog (reference/craft/anti-ai-patterns.md, section 1 vocabulary and section 11 banned shapes) applies only to books written in English. The language comes from the language field in the book's README.md YAML frontmatter (default en; en-US counts as en). For any other language a file anti-ai-patterns.<language>.md is expected; none exists at present, so the catalog hits are simply dropped for such books rather than applying English patterns blindly. This affects the hook categories ai_tell and global_shape_violation, the manuscript checker's ai_tell_violation and global_shape_violation, and the humanizer's pre-scan. scan_chapter_ai_tells and check_replacement_text return a warning instead of catalog hits for such books. Book rules, author bans, tics and tone rules still apply regardless of the book's language.

Author banlist

The author's discoveries (banned phrases, recurring tics, don'ts, style principles) live in the database authors.db. Of these, the prose hook only scans the don'ts and the recurring tics. It does not scan style principles. chapter-writer, chapter-reviewer and author-check read them through get_author and the chapter writing brief. The file vocabulary.md is reference only and is not read for enforcement. Add a new banned phrase with write_author_banned_phrase or add_vocabulary_entry. create_author also seeds 19 common AI-tell words (such as delve, tapestry, nuanced, resonate, pivotal) into the database as don'ts on creation, and they take effect immediately.

The hook finds a book's author through the line - **Author:** Name in the Book Facts section of the CLAUDE.md, falling back to the author: field in the YAML frontmatter of the book's README.md.

Story-time anchor

Each chapter can have a ## Chapter Timeline section in its README.md with start and end times of the scenes, for example **Start:** Tue Dec 24 ~19:30. From the start the plugin computes which date relative phrases such as yesterday or tomorrow mean. The prose hook warns on every such phrase with the derived date so you check it against plot/timeline.md. The tool get_current_story_anchor returns the mapping directly:

{
  "available_relative_phrases": {
    "yesterday": "Mon Dec 23 ~19:30",
    "tomorrow": "Wed Dec 25 ~19:30"
  }
}

get_recent_chapter_timelines(book_slug, n) returns the time grids of the last N chapters so that new chapters are anchored to real times instead of remembered ones. validate_timeline_consistency checks time drift across the whole book.

Chapter writing brief

get_chapter_writing_brief(book_slug, chapter_slug) replaces many single read steps in the skill chapter-writer with one JSON containing these parts:

• chapter, pov_character
• story_anchor, recent_chapter_timelines, recent_chapter_endings
• characters_present with profile, knowledge, tactical and series_evolution (always present, null without series context; filled for series volumes with tracker text, resolved for both layouts projects/{book} and series/{series}/{book})
• pov_character_inventory (the POV character's last established possessions)
• rules_to_honor, callbacks_in_register, banned_phrases
• recent_simile_count_per_chapter, tone_litmus_questions, tone_banned_patterns (enforced, advisory_unenforced)
• tactical_constraints (only for combat or travel scenes), review_handle
• errors

Each component is guarded individually. If one fails, it appears in errors and the brief still arrives with the remaining data. A frequent cause is a missing world/setting.md or plot/timeline.md.

Tactical check

verify_tactical_setup checks combat and travel scenes against the optional tactical block in a character's frontmatter:

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]

Rules: a protected character at the rear (R1) or at the lead (R2) of the group warns. A protected character present with no protector positioned warns (R3). A lead position that does not match movement_lead: true warns (R4). Without tactical data there is only a note (R0). The tool also returns questions for the author as a checklist.

POV boundary

The optional knowledge block in a character's frontmatter assigns knowledge domains to the tiers expert, competent, layperson and none:

knowledge:
  expert: [it, networking]
  competent: [photography]
  layperson: [history]
  none: [forensics, medicine]

Specialist vocabulary of a domain that is none or layperson for the POV character produces a warning. Matches are searched as whole words. Free-form domain names count as competent. Without a knowledge block the character is not checked. Bundled vocabulary lists live under reference/craft/knowledge-domains/: forensics, tactical_combat, medicine, ballistics, automotive_repair.

Plot logic and chapter promises

analyze_plot_logic(book_slug, scope?, chapter_slug?) builds a knowledge index from canon facts, timeline and promises and runs two deterministic checks:

The semantic categories information_leak, motivation_break, premise_violation and pov_knowledge_boundary are judged by the skills chapter-reviewer and manuscript-checker using the knowledge index. premise_violation does not apply to memoir.

Promises are setup elements (Chekhov elements, mysteries, callbacks) per chapter. register_chapter_promises writes them to the ## Promises section of the chapter README, get_chapter_promises reads them. For chapters already written, /storyforge:backfill-promises fills them in. The source of truth remains the canon log in the database (add_canon_fact).

Author evolution

Discoveries move across three levels: book, author, global. /storyforge:harvest-author-rules calls harvest_book_rules and sorts a book's rules into banned_phrase, style_principle and world_rule. For each candidate you decide: promote, keep in the book only, discard, or edit and promote. Promoted entries carry an origin such as _(emerged from firelight, 2026-04)_. If the same discovery shows up in a later book, a second origin is added instead of a duplicate. /storyforge:promote-rule lifts a single rule to author or global level.

The sections in the author profile are Recurring Tics, Style Principles and Don'ts. chapter-writer and chapter-reviewer load them through get_author.

Pre-export checks

run_pre_export_gates checks:

With --arc, export-engineer may bypass the "All chapters Final" gate after explicit confirmation. Further rules of the skill:

• For memoir, check_memoir_consent runs first. On FAIL the export stops, on WARN the skill asks.
• A non-ARC export needs a filled-in export/front-matter.md (no [Author Name] placeholder, field author set).
• Leftover review comments with the review_handle in the draft stop the export.
• The cover is embedded automatically when get_cover_image returns one. Without a cover the export still runs.
• Output: export/output/{book-slug}.{epub|pdf|mobi}, for an ARC {book-slug}-arc.{ext}.

Databases

Besides the Markdown files, StoryForge uses SQLite databases under ~/.storyforge/db/:

The comparison baselines and raw drafts of fiction chapters under ~/.storyforge/snapshots/ are not a database, just plain files.

Migrating older books

Moving from Markdown data to the databases is a one-time job using scripts in the plugin's scripts/ directory. Run them with the virtual environment's Python, in this order. All are repeatable, entries that already exist are skipped.

For books with old rules in quotation marks instead of backticks there is python -m tools.claudemd.migrate_to_backticks <book-path>. Without --apply it only shows the change, with --apply it asks before writing. Run it from the plugin directory.

To backfill existing books, use the skills /storyforge:backfill-promises and /storyforge:backfill-style-principles.