Writing long-form fiction books with Spec Kit preset "Fiction Book Writing"

[adaumann]

Dear all,

I would like to present a community-preset I wrote for Spec Kit. It uses Spec Kit for fictional book writing, utilizing best practices story telling elements. Spec Kit helps you to build a long-form fiction book with a full plot structure, character voices, world buiding. It solves the most structural problems writing a long-form book. You can even plan for full book series and have single POV and multi POV elements.
At the end you can let AI write your prose or just make a outline to start writing on yourself.

The preset is now available as community-preset: specify init --preset fiction-book-writing

Documentation: https://github.com/adaumann/speckit-preset-fiction-book-writing/blob/main/fiction-book-writing/README.md

It would me nice to share your ideas, there already some addressed for the next version:

• Translation pipeline
• Cover builder
• Audiobook support
• Illustrations
• Timeline and other visualisations
• The export is currently beta, and need to be adjusted to have template designs

For this I'm think I need to write a extension.

Please let me know if you have further ideas...

---

Here are some technical details:

1. The Core Mapping: SDD --> Fiction Craft

The preset does not bolt creative writing onto Spec Kit. It remaps the full SDD vocabulary:

Spec Kit Concept	Fiction Equivalent	File
Memory / Project constitution	Story Bible	.specify/memory/constitution.md
Feature	Story (slug-named)	.specify/features/<story-slug>/
Spec	Story brief (logline, arcs, scene beats)	spec.md
Plan	Story structure (acts, chapters, beats)	plan.md
Tasks	Scene-by-scene writing tasks	tasks.md
Checklist	Prose quality gates	checklists/<ID>-checklist.md

Key insight for authors: every rule that governs when speckit.implement may proceed, when speckit.revise can change something, and what speckit.continuity flags as CRITICAL derives from a single versioned document — constitution.md. The constitution is not advisory. It is a hard constraint enforced at command level.

---

2. Architecture Overview: The Gate System

The pipeline enforces two classes of gates that advanced users need to understand before pushing into large projects:

2a. Checklist Gate (Quality)

speckit.implement scans checklists/ before every drafting run. If any checklist file contains incomplete items (- [ ]), it stops with a table showing all incomplete gates. The user must explicitly say "proceed despite incomplete checklists" to override. This mirrors a failing CI pipeline — you cannot merge into draft without passing quality gates.

2b. Outline Gate (Authorial Control)

For each chapter, speckit.implement checks for a matching file at outlines/<CHAPTER_ID>_<Title>-outline.md and reads its status field:

status: DRAFT     → stop, ask author to review and set APPROVED or SKIP
status: APPROVED  → draft from this outline (overrides plan.md)
status: SKIP      → mark task done, no prose generated, advance
(no file)         → fall back to plan.md directly (legacy path)

This gives authors a per-scene switch between AI-written and author-written prose without forking the workflow.

---

3. The Constitution: Versioned Governing Authority

constitution.md is semantically versioned and governs every downstream command.

Version increment rules

Change	Bump
Plot structure, POV strategy, or POV strand count changed	MAJOR
New principles, style rules, or Anti-AI phrases added	MINOR
Typos, clarifications, minor refinements	PATCH

Why this matters

Every drafted chapter embeds a constitution_version in its YAML frontmatter. When speckit.continuity runs, it cross-references each draft's version against the current constitution and flags any draft with a stale version as STALE CONSTITUTION. It then reads the ## Change Log and runs targeted violation checks on those specific passages — not a full re-read.

Sync Impact Report

Every constitution update writes an HTML comment at the top of the file:

<!-- SYNC IMPACT: v1.0.0 → v1.1.0
     Changed: Added 3 prohibited phrases, updated theme statement
     Affected templates: spec-template.md, tasks-template.md
     Action required: Re-run /speckit.continuity if scenes have been drafted -->

This is the equivalent of a breaking-change migration note in a software library.

---

4. The Planning Pipeline: Strict Dependency Chain

speckit.constitution  →  speckit.specify  →  speckit.clarify  →  speckit.plan  →  speckit.tasks  →  speckit.outline

Each step is write-blocked by the previous one's output. The key non-obvious aspects:

speckit.clarify — the most skipped, the most important

Scans spec.md for [NEEDS CLARIFICATION] markers across:

• Character motivation (why does the protagonist not take the simple path?)
• Timeline (when precisely do act breaks occur?)
• POV clarity (how close is the narrative distance?)
• World-building inconsistencies

It writes resolutions directly back into spec.md. Ambiguities not resolved here become structural holes in plan.md and orphan tasks in tasks.md.

speckit.tasks — blocked tasks as first-class citizens

tasks.md is generated with [BLOCKED] markers on any task whose prerequisite supporting document (characters/[name].md, world-building.md, research.md) does not yet exist. Tasks remain blocked until the author creates those documents. This prevents drafting scenes where character voice or world rules have not been committed.

speckit.outline — the bridge between structure and prose

Each outline file is the last author checkpoint before AI prose is generated. It contains:

• Opening hook — one concrete sentence (not a summary)
• Causal beat sequence — ordered, one sentence per beat, each beat causing the next
• Character beats — want vs. get for every character present
• Dialogue requirements — what must be deflected or left unspoken (not what to say)
• Sensory anchors — drawn from locations.md LOC-blocks
• Thematic work — active motif + delivery method

The outline file is the author's editorial authority over the AI draft.

---

5. The POV Architecture Layer

speckit.pov is a full sub-system sitting between speckit.plan and speckit.tasks. It is optional for single-POV and mandatory for multi-POV projects.

POV Modes Supported (9)

Alternating · Dual · Braided · Ensemble · Mosaic · Frame + Embedded · Chorus · First-Person Multiple · Single

What pov-structure.md contains

Section	Content
POV Configuration	Mode, character count, tense, narrative distance, chapter demarcation
Voice Differentiation Matrix	How each POV character sounds distinct (vocabulary register, sentence length, sensory focus, micro-obsessions)
POV Schedule	Chapter-by-chapter POV assignment
Information Asymmetry Map	What each character knows and when — explicit, scene-by-scene
Convergence Points	Where arc threads intersect
Relay Rules	How POV handoffs between chapters are structured

Sub-commands for advanced audit work

/speckit.pov audit        ← voice differentiation check across all POV characters
/speckit.pov schedule     ← generate or validate chapter-by-chapter POV schedule
/speckit.pov asymmetry    ← enforce information asymmetry: who knows what, when
/speckit.pov relay        ← review handoff transitions between chapters

Any free-text question to speckit.pov is answered without modifying files — useful for design-time decisions:

/speckit.pov Should Elena's POV come before Marcus's in chapter 12?

---

6. Pre-Draft vs. Post-Draft Analysis: Two Distinct Commands

This is the most architecturally important distinction in the preset. They are not interchangeable.

speckit.analyze — pre-draft, strictly read-only

Runs after speckit.tasks, before speckit.implement. Verifies structural consistency across spec.md → plan.md → tasks.md:

• Every spec requirement maps to at least one plan chapter
• Every plan chapter maps to at least one task
• Every Chekhov item has an assigned pay-off scene
• Act proportions are within range for the chosen plot structure
• Subplot beat sheets have all five required beats mapped to chapter IDs
• Series constraints: opening character state matches closing state from previous book

Does not read draft files. Structural problems caught here cost nothing to fix. The same problem caught post-draft costs a full rewrite.

speckit.continuity — post-draft, strictly read-only

Runs after speckit.implement. Verifies drafted prose against the story bible and supporting documents:

• Anti-AI filter violations in prose
• Triple Purpose and Dirt Rule compliance per scene
• Voice homogeneity test: could a CA-1 scene be mistaken for a CA-2 scene?
• Timeline continuity across non-linear structures (fabula vs. syuzhet)
• Location state logs: if locations.md says a location changed at beat X, all drafts set there after X must reflect that change
• Glossary consistency: invented terms spelled, capitalised, and used correctly
• Constitution version currency: drafts written against an old constitution version are flagged with targeted change-impact analysis

---

7. The Quality Loop: Precision, Not Improvement

The three commands forming the per-chapter quality loop enforce a surgical scope model — each tool does exactly one thing and refuses to do the others'.

speckit.checklist  →  speckit.revise  →  speckit.polish

speckit.checklist — weighted scoring

Five sections, each scored 1–10, with weights producing a composite score. Gate rules:

• Score ≥ 7 → PASS
• Any single STB (Scene Transformation Block) failure → FAIL regardless of score
• Any SCN-004 (Triple Purpose) failure → FAIL regardless of score

speckit.revise — surgical scope enforcement

Core operating constraint: only rewrites prose that directly causes a flagged failure. Passing content is untouched. If a revision cannot fix the failure without violating the story bible, it stops and reports the conflict rather than silently violating the bible.

The failure scope is fixed at load time and cannot expand during revision. This is the equivalent of a targeted hotfix that must not change unrelated behaviour.

Produces a versioned output file (_v2.md, _v3.md) plus a diff summary.

speckit.polish — linter, not editor

Polish is a surface-level linter. It applies rules mechanically:

• Filter word removal (she noticed, he felt, she saw, he heard)
• Adverb density cap: 1 per 200 words
• Sentence rhythm: alternating short/long, weight moved to line endings
• Paragraph opening variety
• Em-dash and ellipsis cluster reduction

Polish must never be used to fix story bible violations, triple purpose failures, or structural issues. That is speckit.revise's domain. The tool boundary is enforced by the command prompts themselves.

---

8. Style Modes: Two Architecturally Different Paths

author-sample

Prompts for 500–2,000 words of prose. Extracts 8 voice markers into the constitution:

1. POV & Tense
2. Rhythm (sentence length and cadence)
3. Vocabulary Register
4. Sensory Density
5. Tone (emotional temperature, irony level)
6. Dialogue Style (attribution, subtext density)
7. Anti-Patterns (specific phrasings extracted from the sample to avoid)
8. Scene Integrity Rules (structural habits in the sample)

All downstream drafting targets these extracted markers. The Anti-AI filter is populated from the sample, not from a generic wordlist.

humanized-ai: Universal Principles + Prose Profiles

Seven universal principles that cannot be disabled in any profile:

Principle	Rule
Sensory grounding	Minimum one non-visual sense per scene
Character-in-body	Physical reactions precede named emotions
Dialogue subtext	Deflection or misunderstanding in every exchange
Filter word purge	No she noticed, he felt, she saw, he heard
Off-balance ending	Every scene ends in a new instability
Triple purpose	Every scene serves ≥3 narrative functions simultaneously
Dirt Rule	Every environment has at least one flaw or imperfection

Five Prose Profiles tune how those principles are weighted — they do not relax them:

Profile	Sentence Rhythm	Sensory Density	Interiority	Pace Bias	Genre Fit
commercial	Alternating short/long	Medium	Balanced	Scene = Sequel	General fiction, fantasy, romance
literary	Long-dominant; fragments under rupture	High (texture)	Deep, contradictory	Reflection-forward	Literary fiction, character studies
thriller	Short-dominant (1–2 clauses)	Low-medium, functional	Minimal; act before reflect	Action-forward	Thrillers, crime, horror
atmospheric	Long, winding, syntactically embedded	Maximum; environment as character	Deep; inner/outer blur permitted	Atmosphere as plot	Gothic, horror, weird fiction
dark-realist	Clipped, declarative, no ornament	Medium; decay and failure	Cold, selective; rationalisation visible	Consequence-forward	Noir, social realism, gritty literary

Each profile also adds its own set of Anti-AI filter entries beyond the universal list.

---

9. Advanced Document Layer

These documents are optional but unlock deeper automated checking in speckit.analyze and speckit.continuity:

subplots.md

• Per-subplot beat sheets with five required beats: inciting incident, first obstacle, midpoint reversal, darkest moment, resolution
• Convergence map: all chapters with 3+ arc intersections flagged as high-load
• Arc Absence Log: tracks which acts have no subplot scene (two or more consecutive acts → WARNING)
• Resolution Checklist: any Resolved: No row → CRITICAL in speckit.analyze

locations.md

• Per-location sensory anchors (primary sensory detail expected in every scene set there)
• Atmosphere by time of day / weather condition
• Character behavioral tells per location
• State Log: records when a location changes state (e.g., burned down at chapter A2.204). speckit.continuity enforces that all subsequent scenes reflect that state change.

glossary.md

• Invented terms with usage constraints and all variant forms
• Capitalization and spelling rules
• Consistency Log: speckit.continuity and speckit.polish append violations automatically with date, chapter ID, and correct form

series-bible.md

• Series-level canon: world rules, series arc trajectory
• Character State Registry per book: closing state from book N becomes required opening state for book N+1 — checked by speckit.analyze against character profiles
• Known Contradictions log with OPEN/RESOLVED status

---

10. Extension Hook System

The preset checks for .specify/extensions.yml at the start of every command. The hook schema:

hooks:
  before_constitution:
    - type: mandatory
      action: "remind user to check series-bible.md for series position"
  before_implement:
    - type: optional
      action: "load recent research notes from research.md"
  before_checklist:
    - type: mandatory
      action: "confirm chapter has been spell-checked"

Hook types:

• Mandatory: command stops if the hook action has not been completed
• Optional: hook action is suggested but execution proceeds

This allows teams or multi-author projects to enforce custom pre-flight rules project-by-project without modifying the preset commands themselves.

---

11. The Export Pipeline

speckit.export calls a Python/pandoc script (scripts/python/export.py) that:

1. Scans draft/ for all chapter files
2. Applies priority ordering for versioned files: _polished.md → highest _vN.md → base draft
3. Sorts chapters by chapter_id from YAML frontmatter (not filename sort)
4. Assembles into a single manuscript and invokes pandoc

Supported output formats:

Format	Use Case
DOCX	Publisher/agent submission (default)
EPUB	KDP, Draft2Digital, IngramSpark, Kobo
LaTeX	Professional typesetting, print-on-demand

---

12. Demo Walkthrough: What to Show

The most effective demonstration sequence for an advanced audience shows the constraint system in action, not just happy-path generation.

Demo 1 — The constitution version mechanism

1. Create a constitution at v1.0.0, draft one chapter
2. Update constitution to add a prohibited phrase (v1.1.0, MINOR bump)
3. Run speckit.continuity — show the STALE CONSTITUTION flag and targeted violation search

Demo 2 — The gate system

1. Generate two checklist files, leave items incomplete
2. Run speckit.implement — show it stopping with the gate table
3. Complete the checklists, run again — show it proceeding

Demo 3 — The outline gate with per-scene authorial control

1. Generate outlines for three chapters: approve one, skip one, leave one as DRAFT
2. Run speckit.implement — show APPROVED drafted, SKIP passed through, DRAFT blocked

Demo 4 — Surgical revision vs. polish

1. Generate a checklist with two FAIL items
2. Run speckit.revise A1.101 "CHR-002 STB-004" — show only the failing passage changed in the diff
3. Run speckit.polish — show surface-level mechanical changes only, structural content unchanged

Demo 5 — speckit.analyze catching series constraints

1. Set up a series bible with a character closing state in book 1
2. Create a book 2 character profile where opening state contradicts the closing state
3. Run speckit.analyze — show the CRITICAL series constraint violation before a single scene is drafted

---

13. Key Design Principles to Highlight

1. One governing authority: everything derives from constitution.md. No command silently overrides it — conflicts are surfaced as CRITICAL errors, not hidden.

2. Two read-only analysis commands, strictly separated: speckit.analyze (structural, pre-draft) and speckit.continuity (prose, post-draft). Neither modifies files. Neither substitutes for the other.

3. Surgical revision model: speckit.revise has a fixed scope set at load time. Scope creep is architecturally prohibited. This is the same isolation principle that makes a good unit test trustworthy.

4. Version-tracked prose: every drafted file carries a constitution_version header, enabling precise change-impact analysis without re-reading every chapter.

5. Progressive document depth: the template layer (subplots.md, locations.md, glossary.md, series-bible.md) is optional but unlocks deeper automated checking. Projects start simple and grow into full constraint coverage as the story grows.

[mnriem]

Very exciting to see!