Novelist Workflow

A maintainable writing system for novels that outgrow a single document.
Plain Markdown for story state; PowerShell for scaffolding, checks, compilation, and offline reading.

English · 简体中文 · Project homepage · Architecture · Privacy boundary · Contributing

Long novels rarely fail for lack of ideas alone. They fail through state drift: who knows which secret, whether an old injury has healed, who owns an object now, and which promise from ten chapters ago is still unpaid.

Novelist Workflow does not write your novel. It separates outlines, manuscript, living character files, timeline, open threads, and chapter reviews so every new chapter inherits traceable facts—and writes its consequences back into the story world.

Explore the project homepage for an interactive chapter loop, copyable setup commands, and writing guides. The site is available in English and 简体中文 on GitHub Pages.

What it brings together

• A four-part chapter workpack: brief, focused context, state_delta, and review.
• Explicit ledgers for knowledge, relationships, injuries, resources, rules, and open threads.
• Human-review prompts for continuity and prose risks, never an automatic literary verdict.
• Small Windows-first PowerShell tools for status, compilation, and an offline mobile reader.
• A privacy-first split: reusable workflow files are public; your manuscript and live story state are ignored by Git.

The chapter loop

flowchart LR
    A["Outline + story state"] --> B["brief<br/>What must change?"]
    B --> C["context<br/>What matters now?"]
    C --> D["manuscript<br/>What happened?"]
    D --> E["state_delta<br/>What changed?"]
    E --> F["review<br/>What needs attention?"]
    F --> A

Loading

The key seam is state_delta.md: it turns “the chapter is drafted” into “the story state is current.”

Start in five minutes

Requirements: Windows, Windows PowerShell 5.1+ or PowerShell 7, and Git.

git clone https://github.com/chenzhiyong1994/novelist-workflow.git
cd novelist-workflow

# Create a private, Git-ignored writing workspace
powershell -ExecutionPolicy Bypass -File .\scripts\init_project.ps1 -Title "My Novel"

# Create volume 1, a character, and the first chapter workpack
powershell -ExecutionPolicy Bypass -File .\scripts\new_volume.ps1 -Volume 1 -StartChapter 1 -EndChapter 30
powershell -ExecutionPolicy Bypass -File .\scripts\new_character.ps1 -Name "Character Name" -FirstChapter ch001 -Role "Protagonist"
powershell -ExecutionPolicy Bypass -File .\scripts\new_chapter.ps1 -Chapter 1 -Volume v01 -Title "Chapter Title"

Fill in novel.yaml, 00_project/, then the chapter's brief.md and context.md before drafting. The daily loop is documented in docs/workflows/daily-writing-loop.md.

Repository map

scaffold/                  Public, story-free private-workspace scaffold
00_project/                🔒 Intent, voice, and publishing plan
01_bible/                  🔒 World, timeline, rules, threads, fact ledger
02_characters/             Public template + 🔒 living character files
03_outline/                Public templates + 🔒 active outlines
04_manuscript/             🔒 Chapter manuscript by volume
05_chapter_workpacks/      Public templates + 🔒 per-chapter workpacks
06_checks/                 Public checklists + 🔒 generated reports
docs/                      Architecture, privacy, and writing workflows
site/                      Public bilingual project homepage
scripts/                   Initialization, checks, compilation, and reader
dist/                      🔒 Compiled manuscript and offline reader

Paths marked 🔒 are created locally and ignored by Git. Run scripts/validate_public_release.ps1 before publishing to detect accidental private paths or common secret signatures. See the full privacy boundary.

Included tools

Script	Purpose
init_project.ps1	Initialize the private workspace without overwriting existing files
new_character.ps1	Create a living character file and update its index
new_volume.ps1	Create a volume outline and manuscript directory
new_chapter.ps1	Create one manuscript chapter plus its four workpack files
check_continuity.ps1	Check chapter-loop completeness and write a report
project_status.ps1	Report chapters, approximate length, placeholders, and missing workpacks
scan_voice.ps1	Flag prose-pattern risks for human review
compile_manuscript.ps1	Merge a volume into one Markdown manuscript
build_reader.ps1	Build an offline mobile-friendly reader with theme and font controls
build_site.ps1	Assemble only public homepage files into dist/site/ for GitHub Pages
validate_public_release.ps1	Guard the public/private repository boundary

Project website

The homepage uses plain HTML, CSS, and JavaScript. Build it locally with powershell -ExecutionPolicy Bypass -File .\scripts\build_site.ps1, then open dist/site/index.html. Only the six explicitly allowed public files are included; private writing and dist/reader/ are excluded.

Changes to the website on main are published by the dedicated Pages workflow. Writing-workflow verification remains local. See website maintenance and deployment for preview, validation, and fork setup.

Design boundaries

• Manuscript evidence outranks outline intent.
• Tools surface risks; the author makes literary decisions.
• Context is narrowed per chapter instead of dumping the whole story bible into every session.
• Core use is local, account-free, and database-free.
• Each script is small enough to replace or bypass manually.

This workflow is most useful for serialized fiction, series, and stories with enough state to outgrow memory. It may feel heavy for one-off short fiction or authors who want a fully visual editor.

Contributing and license

Real failure cases from actual writing are more valuable than feature checklists. Sanitized issues, template improvements, and PowerShell fixes are welcome; please read CONTRIBUTING.md. Report manuscript or credential exposure privately as described in SECURITY.md.

The workflow is available under the MIT License. Your manuscript, setting, and other private writing remain yours.