ΒΆ StoryForge - AI Book Writing
ΒΆ Table of Contents
- Overview
- What Makes StoryForge Different
- Key Features
- Writing Modes
- System Requirements
- Installation
- Configuration
- Quick Start
- Project Structure
- Status Model
- MCP Tools Overview
- Hooks
- Persistence: Per-Book CLAUDE.md
- Sub-Pages
- Troubleshooting
- FAQ
ΒΆ Overview
StoryForge is a Claude Code plugin for the complete fiction writing process β from initial brainstorm through concept, plot, characters, world-building, chapter-by-chapter writing, to finished EPUB, PDF, or MOBI. The core is the author profile system: every piece of prose is written in the voice of a defined (or PDF-extracted) author β not generic AI output.
Yes, StoryForge writes prose β via the
chapter-writerskill. But it is not a one-click book generator. You make all creative decisions (plot, characters, theme, turns), every scene runs through your review, and the skill writes only under strict context constraints (author profile, canon, timeline, tonal document, per-book rules). Put differently: the plugin writes the text, but you are the author.
Who StoryForge is for:
- Authors who want to use AI as a tool without sliding into generic AI slop
- Self-publishers who want everything from concept to EPUB in one pipeline
- Series authors with complex multi-book canon management
- Discovery writers (pantsers) who still need timeline/canon/tonal consistency
- Authors who want to extract style DNA from their own past work
Who StoryForge is not for:
- One-click book generators β there is no "write-me-a-novel" button
- Non-fiction, how-to guides, or technical documentation (use VidCraft or other tools)
- Ghost-writing without an author reference β the plugin refuses to write without an author profile
ΒΆ What Makes StoryForge Different
Most AI writing tools produce prose immediately. StoryForge forces you through mandatory context loads before every creative step:
The chapter-writer skill, for example, loads 16 different context sources before writing a single word. Every rule, every character voice, every calendar line is held actively in the prompt context.
ΒΆ The "Never Trust" Rule (Rule #14)
StoryForge is configured to not blindly accept user corrections on prose. If you say "this sentence is wrong," the plugin will quote the text, check context, and push back when you are mistaken. Background: for English-language prose, subtle nuances are often missed by the user.
ΒΆ Simile Discipline
Figurative comparisons (similes, metaphors) are actively counted and checked for redundancy β both within a scene and across chapters. This prevents the classic AI failure mode "every sunset is like liquid gold."
ΒΆ Key Features
ΒΆ Author Profiles β The Anti-AI Engine
- Style parameters: voice, tone, sentence structure, vocabulary
- Banned words / preferred words lists
- PDF/EPUB/DOCX import for style extraction from past work
author_writing_mode: outliner / plantser / discovery- See detail page: Author Profiles
ΒΆ Genre System with Mixing
- 11 base genres: horror, fantasy, sci-fi, thriller, mystery, romance, drama, literary-fiction, historical, contemporary, supernatural
- 1 cross-cutting: lgbtq (always combined with others)
- 2 predefined mixes: dark-fantasy, paranormal-romance
- Free combination: up to 3 genres (e.g., LGBTQ+ Supernatural Mystery)
- Custom genre mixes with
/storyforge:genre-creator - See detail page: Genre System
ΒΆ 8 Plot Methods
| Method | Use Case |
|---|---|
| 3-Act Structure | Universal standard for most novels |
| Hero's Journey | Fantasy, sci-fi, coming-of-age |
| Save the Cat | Plot-driven thrillers, mysteries, commercial fiction |
| Snowflake Method | Complex plots with many POV characters |
| Freytag's Pyramid | Literary fiction, drama |
| Seven-Point Story | Structured action/thriller |
| Story Circle (Dan Harmon) | Character-driven stories, TV pilots |
| KishΕtenketsu | Literary, East-Asian-inspired, conflict-light plots |
ΒΆ 33 Specialized Skills
Split into categories: Core, Author, Creative, Writing, Research, Production, Series, Utility. See Skills Detail Page.
ΒΆ Quality Gates
- Chapter Reviewer: 28-point quality checklist per chapter
- First-Chapter Gate: 13-point check for the opening chapter (stricter)
- Voice Checker: 7-dimension AI-tell scan
- Manuscript Checker: cross-chapter repetition scanner for the whole book
- Continuity Checker: timeline + travel matrix validation
- See detail page: Quality System
ΒΆ Craft Knowledge Base
36+ reference documents (73,000+ words) built in:
- Story structure, plot craft, character arcs
- Pacing, dialog craft, show-don't-tell
- POV, tension & suspense, simile discipline
- Anti-AI patterns, prose style, do's and don'ts
- 10 genre-specific craft guides (e.g., horror-craft, fantasy-craft, mystery-craft)
ΒΆ Writing Modes
StoryForge supports three working styles for authors β based on how much planning you like:
| Mode | For Whom | Pre-Planning | Writing Process |
|---|---|---|---|
| Outliner | Detail planners | Full plot outline with all chapter beats | Chapters follow the plan |
| Plantser | Hybrid authors | 6 key beats (MVO = Minimum Viable Outline) | Scene buffer 3-5 scenes ahead via Rolling Planner |
| Discovery Writer | Pantsers | Only premise + protagonist + core tension | Scene-by-scene with Rolling Planner, no plot |
Detailed comparison with examples: Writing Modes
ΒΆ System Requirements
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.10+ | Recommended: Python 3.12 |
| Claude Code | 1.0+ | CLI, Desktop, or IDE Extension |
| Pandoc | 3.0+ | For EPUB/PDF export |
| Calibre | optional | For MOBI export |
| LaTeX | optional | For PDF via xelatex/pdflatex |
ΒΆ Installation
git clone https://github.com/markus-michalski/storyforge.git ~/projekte/storyforge
- Download from GitHub Releases
- Extract to
~/projekte/storyforge/
ΒΆ Step 2: Install Plugin
claude plugin install ~/projekte/storyforge
ΒΆ Step 3: Run Setup
In Claude Code:
/storyforge:setup
This automatically creates:
- Python venv at
~/.storyforge/venv/ - Dependencies: FastMCP, PyYAML, pdfplumber, python-docx, ebooklib
- Config template at
~/.storyforge/config.yaml - Cache directory
~/.storyforge/cache/ - Authors directory
~/.storyforge/authors/
ΒΆ Step 4: Customize Configuration
nano ~/.storyforge/config.yaml
Most important value: content_root (where your book projects live).
ΒΆ Step 5: Create First Author Profile
/storyforge:create-author
Without an author profile, the plugin refuses to write β by design.
ΒΆ Configuration
ΒΆ config.yaml
# ~/.storyforge/config.yaml
paths:
content_root: "~/projekte/book-projects"
authors_root: "~/.storyforge/authors"
defaults:
language: "en" # "de" for German books
book_type: "novel" # short-story / novelette / novella / novel / epic
export_format: "epub" # epub / pdf / mobi
pdf_engine: "xelatex" # xelatex / pdflatex / wkhtmltopdf
cover_platform: "midjourney" # midjourney / dall-e
review:
handle: "Author" # Name for inline review comments
export:
include_toc: true
include_colophon: true
font_family: "Minion Pro" # PDF only
ΒΆ Word-Length Standards per Book Type
| Type | Words | Chapter Count (typical) |
|---|---|---|
| short-story | 1,000 - 7,500 | 1 (no chapters) |
| novelette | 7,500 - 17,500 | 3-5 |
| novella | 17,500 - 40,000 | 8-15 |
| novel | 40,000 - 120,000 | 15-35 |
| epic | 120,000+ | 35+ |
ΒΆ Paths
| Path | Contents |
|---|---|
~/.storyforge/config.yaml |
User configuration |
~/.storyforge/cache/state.json |
State cache (automatic) |
~/.storyforge/venv/ |
Python virtual environment |
~/.storyforge/authors/{slug}/ |
Author profiles |
{content_root}/projects/{book-slug}/ |
Book projects |
ΒΆ Quick Start
ΒΆ Standard Workflow (Outliner) β with example "The Lighthouse Keeper"
1. /storyforge:create-author
β Creates author profile "maja-sundberg"
β author_writing_mode: outliner
2. /storyforge:new-book
β Title: "The Lighthouse Keeper"
β Type: novel
β Genres: mystery + contemporary + literary-fiction
β Slug: the-lighthouse-keeper
3. /storyforge:book-conceptualizer the-lighthouse-keeper
β 5-phase concept: premise, protagonist, conflict, theme, tone
4. /storyforge:plot-architect the-lighthouse-keeper
β Method: 3-Act Structure
β 18 chapters, 3 beats each
5. /storyforge:character-creator the-lighthouse-keeper
β Protagonist: Arne Kruse (72, former seaman)
β Antagonist: The island itself + his past
β 4 supporting characters with 14 psychology steps each
6. /storyforge:world-builder the-lighthouse-keeper
β Setting: Fictional North Sea island "Kargholm"
β Travel Matrix: 6 locations with travel times
β Canon log initially populated
7. /storyforge:chapter-writer the-lighthouse-keeper 01
β Scene-by-scene mode (recommended)
β 3 scenes at ~900 words each
β Each scene: inline review comments possible
8. /storyforge:chapter-reviewer the-lighthouse-keeper 01
β 28-point check
9. (Repeat chapters 2-18)
10. /storyforge:manuscript-checker the-lighthouse-keeper
β Cross-chapter analysis
β Interactive fix mode
11. /storyforge:voice-checker the-lighthouse-keeper
β 7-dimension AI-tell scan
12. /storyforge:export-engineer the-lighthouse-keeper --format epub
13. /storyforge:promo-writer the-lighthouse-keeper
β Back-cover blurb + social media campaign
Complete worked example: Workflow Example
ΒΆ Project Structure
Every book is its own directory under {content_root}/projects/:
the-lighthouse-keeper/
βββ README.md # Book metadata (YAML frontmatter)
βββ synopsis.md # Back-cover blurb + long synopsis
βββ plot/
β βββ outline.md # Act/beat structure
β βββ timeline.md # Story calendar (day-by-day)
β βββ tone.md # Tonal guard rails + litmus test
β βββ canon-log.md # Story bible (established facts)
β βββ arcs.md # Character arc overview
βββ characters/
β βββ INDEX.md # Character overview
β βββ arne-kruse.md # Individual character files
β βββ inga-holm.md
β βββ pastor-thaden.md
βββ world/
β βββ setting.md # Setting incl. Travel Matrix
β βββ rules.md # World rules (for fantasy: magic system)
β βββ history.md # World history
βββ chapters/
β βββ 01-arrival/
β β βββ README.md # Chapter metadata + outline + Chapter Timeline
β β βββ draft.md # The actual prose
β βββ 02-the-beacon/
β βββ README.md
β βββ draft.md
βββ CLAUDE.md # Per-book rules/workflows/callbacks (auto-sync)
βββ cover/ # brief.md, prompts.md, art/
βββ export/ # front-matter.md, back-matter.md, output/
βββ translations/ # {lang}/ with glossary.md + chapters/
ΒΆ Status Model
ΒΆ Book Status
Derivation happens automatically from chapter aggregates and never moves backward:
Auto-derivation rules:
| Book Tier | Trigger |
|---|---|
Drafting |
Any chapter past Outline |
Revision |
Every chapter at Revision rank or higher |
Proofread |
Every chapter at Final |
Editing, Export Ready, and Published remain explicit β they require qualitative judgment beyond chapter aggregation.
Floor rule: A user-set higher tier (Export Ready, Published) is never silently downgraded.
ΒΆ Chapter Status
Outline β Draft β Revision β Polished β Final
Aliases for ranking (display string preserved):
| Alias | Canonical Rank |
|---|---|
review, reviewed |
Revision |
drafting |
Draft |
polishing |
Polished |
done |
Final |
ΒΆ Character Status
Concept β Profile β Backstory β Arc Defined β Final
ΒΆ Idea Status
raw β explored β developed β ready β promoted (or shelved)
ΒΆ MCP Tools Overview
The MCP server storyforge-mcp provides tools in these categories:
- State Management β Projects, chapters, characters, sessions
- Content Operations β Scaffolding, templates, YAML frontmatter
- Author Tools β Profiles, vocabulary, style analysis
- Analysis β Document parsing (PDF/EPUB/DOCX), voice checks
- Export β EPUB/PDF/MOBI generation
- Reference β Craft docs, genre rules, templates
- Per-Book CLAUDE.md β Read/write the book-specific CLAUDE.md
The complete tool inventory with parameters: see plugin repo at servers/storyforge-server/server.py.
Important: Skills must never parse project files directly. Every state access goes through MCP tools. This is Rule #1 in the CLAUDE.md.
ΒΆ Hooks
StoryForge registers three hooks:
ΒΆ PreCompact Sync (precompact_sync_claudemd.py)
Runs before every session compaction. Extracts messages from the conversation with these prefixes:
Regel:/Rule:β book ruleWorkflow:β process ruleCallback:β callback to weave in (character, object, thread)
These get written to the book's CLAUDE.md so they survive compaction and reload on every chapter.
Example:
User: Rule: Arne Kruse never speaks in complete sentences when he is alone.
β Automatically written to projects/the-lighthouse-keeper/CLAUDE.md and reloaded on /storyforge:chapter-writer.
ΒΆ Chapter Validator (validate_chapter.py)
Runs after every write/edit on chapter files. Checks:
- YAML frontmatter syntax
- Status value against allowed values
- Required fields (number, slug, status)
ΒΆ Character Validator (validate_character.py)
Runs after every write/edit on character files. Checks:
- YAML frontmatter syntax
- Required fields (name, slug, role)
ΒΆ Persistence: Per-Book CLAUDE.md
Each book gets its own CLAUDE.md that acts as memory between sessions:
# The Lighthouse Keeper β Book-Specific Rules
## Rules
- Arne Kruse never speaks in complete sentences when he is alone
- No flashbacks before chapter 5 β rhythm decision
- Island descriptions never longer than 3 sentences at a stretch
## Workflow
- Scene-by-scene writing mandatory for this book
- Chapter Reviewer after each chapter, not batched
## Callbacks
- Lighthouse flashlight (chapter 2 introduced) β must return in chapter 12
- The coin on the mantelpiece (chapter 4) β resolution in chapter 16
- Pastor Thaden limps on his left leg (chapter 3) β keep visual motif
Chapter-writer loads this file before every chapter via get_book_claudemd(book_slug). This makes rules survive Claude compaction and even full session resets.
ΒΆ Sub-Pages
Deeper documentation on separate pages:
- Skills in Detail β All 33 skills with purpose, input, output
- Writing Modes β Outliner, Plantser, Discovery β with examples
- Author Profiles β The anti-AI engine system
- Genre System β 14 genres + mixing + custom mixes
- Quality System β Voice Checker, Manuscript Checker, gates
- Workflow Example β One book from start to finish
ΒΆ Troubleshooting
ΒΆ Problem: Plugin writes generic AI prose
Symptoms: Text sounds flat, interchangeable, full of phrases like "journey", "realm", "tapestry of emotions".
Causes:
- Author profile not created or too vague
vocabulary.mdhas nobanned_wordslist- No personal works imported via
/storyforge:study-author
Solution:
/storyforge:create-author
# Enter detailed parameters
/storyforge:study-author ~/my-previous-book.epub
# Extract style DNA from your own work
/storyforge:voice-checker my-book chapter-01
# 7-dimension scan shows concrete issues
ΒΆ Problem: MCP server not connecting
Symptoms: Skills show errors, no MCP tools available.
Check:
claude plugin list | grep storyforge
ls ~/.storyforge/venv/bin/python3
~/.storyforge/venv/bin/pip list | grep mcp
Solution:
/storyforge:setup
ΒΆ Problem: Chapter contradicts previous chapter
Symptoms: Characters act inconsistently, time references don't match, places are described differently.
Cause: Canon Log or Timeline not loaded or outdated.
Solution:
/storyforge:continuity-checker my-book
This skill reconstructs timeline and travel matrix from all existing chapters and lists conflicts.
ΒΆ Problem: State cache empty
Symptoms: list_books shows nothing despite existing projects.
Solution:
/storyforge:session-start
Rebuild happens automatically from the Markdown files.
ΒΆ Problem: Compaction loses book rules
Symptoms: After Claude compaction, the plugin forgets book-specific rules (e.g., "no flashbacks before chapter 5").
Cause: Rule was not written with Rule: prefix, so it never made it to the per-book CLAUDE.md.
Solution:
User: Rule: No flashbacks before chapter 5.
The PreCompact hook extracts the rule automatically. Verify with:
cat ~/projekte/book-projects/projects/the-lighthouse-keeper/CLAUDE.md
ΒΆ FAQ
Q: Does StoryForge write the book for me?
A: Prose yes β the book no. The chapter-writer skill generates text in the defined author voice. But you make all creative decisions (plot, characters, theme, turns, style). You review every scene inline and correct. Without your reviews and corrections nothing moves forward β the plugin never writes on blindly.
Q: Do I need a previous book of my own to use StoryForge?
A: No, but recommended. You can fill an author profile manually. The study-author skill (PDF/EPUB import) dramatically accelerates style DNA capture.
Q: Which languages are supported?
A: The writing engine is language-neutral. Default is English, but German, Spanish, French, etc. work as long as the author profile is defined in the target language. Craft references are in English but apply to foreign-language text.
Q: Can I manage multiple books of a series?
A: Yes. /storyforge:series-planner creates a series level with overarching canon, arc planning, and character evolution. Each individual book sits below it as a standard project.
Q: What happens with writer's block?
A: /storyforge:unblock diagnoses the block type (fear / perfectionism / procrastination / distraction) and delivers targeted exercises β no generic tips.
Q: Can I write non-fiction too?
A: No, StoryForge is built for fiction. Craft references, plot methods, and the genre system are tailored to fiction.
Q: How good are the exported EPUBs?
A: Production-ready. The export-engineer uses Pandoc with EPUB-3 templates, adds front matter (copyright, dedication), back matter (about author, other books), and supports custom CSS. Testable in Calibre, Apple Books, and Adobe Digital Editions before upload to Amazon KDP / Tolino / Kobo.
Q: Can I use StoryForge for game writing or screenplays?
A: Not directly. Chapter-writer is built for prose. For screenplays I recommend VidCraft (script writing for videos). For game writing you could use StoryForge as a plotting tool and skip the prose generation.
Q: How does the plugin handle sensitivity topics?
A: /storyforge:sensitivity-reader scans for problematic representations (stereotypes, trauma porn, appropriation). For LGBTQ, trauma, or racial content, additional human sensitivity readers are recommended β the skill does not replace that, it supplements.
ΒΆ License
MIT License β GitHub Repository