| name | novel-write |
| description | Use when writing, free-drafting, fragment-continuing, canon-continuing from a provided excerpt, finishing/resuming an abandoned book, batch-writing, reviewing, or checkpointing long-form novel chapters. Trigger on "free draft", "continue this fragment", "continue canon from here", "finish book intake", "resume abandoned book", "continue", "next chapter", "batch N", "write all", "review", "checkpoint", "续写这段", "按全书设定续写", "从这里接入正文继续", "续写到完结", "不更新状态", "继续", "审阅", "十章检查". |
Novel Write
Prerequisites
Requires novel/context-brief.md (generated by /novel-setup).
If novel/context-brief.md is not found: ask the user:
No novel project found in this directory. Want me to help you create one? Tell me your story idea.
If the user provides an idea → transition to novel-setup Phase 1 flow (ask questions, confirm, generate files), then return to writing.
Modes
| Mode | Trigger | Behavior |
|---|
| Free Draft | "free draft", "draft only", "try a version", "试写", "不更新状态", "跳过记账" | Write without project bookkeeping. Read only context-brief, current outline row, and previous chapter. Do not update state. |
| Fragment Continue | "continue this fragment", "continue from here", "续写这段", "接着这段写", "从这里往下写" | Continue user-provided prose as local voice anchor. Do not update project state or canonical chapter text. |
| Canon Continue | "continue canon from here", "按全书设定续写", "从这里接入正文继续", "作为正式章节继续", "从这段开始继续全书" | Treat the provided fragment as official entry text. Load relevant dynamic state, write canonical prose, create a standard delta, and update state. |
| Standard Writing (default) | "write a chapter", "continue", "next chapter" | Write one chapter, then create a light delta and pause for feedback. |
| Production Lock | "production lock", "严格模式", "稳定推进", batch/full-auto/checkpoint-sensitive work | Full audit, full delta, commit, generated state, and checkpoint guards. |
| Batch | "batch 5", "write 3 chapters", "一口气写5章" | Production Lock unless the user explicitly asks for lighter drafting. |
| Full-Auto | "write all", "all", "一口气写完", "全部写完" | Production Lock only after warning that quality is usually worse; requires explicit confirmation for high-risk runs |
| Finish Book Intake | "finish book intake", "resume abandoned book", "这本书断了，帮我续完", "续写到完结" when direction/state is unclear | Diagnose old/incomplete book, produce intake report and roadmap. Do not write formal chapters yet. |
| Finish Book Run | User confirms intake roadmap | Continue to ending in Production Lock. |
| Review | "review", "审阅", "review chapter N" | Review an existing chapter and offer fixes |
| Checkpoint | "checkpoint", "10-chapter check", "十章检查", "全书检查" | Audit global consistency and payoff health without drafting new prose |
For Batch, Full-Auto, Finish Book, Review, and Checkpoint detailed workflows, read references/modes.md only after that mode is triggered. Do not load mode details during normal Standard Writing.
Reference loading by mode:
| Triggered Mode | Read |
|---|
| Free Draft | references/prose-guide.md only if prose guidance is needed |
| Fragment Continue | references/fragment-continue.md; references/prose-guide.md only if prose guidance is needed |
| Canon Continue | references/prose-guide.md, references/chapter-delta.md; use the fragment to select relevant state rows |
| Standard Writing | references/prose-guide.md, references/chapter-delta.md; read review checklist only for obvious problems |
| Production Lock | references/compression-guide.md, references/scene-blueprint.md, references/prose-guide.md, references/review-checklist.md, references/chapter-delta.md |
| Batch / Full-Auto / Finish Book | references/modes.md, then the mode-specific references it names |
| Review | references/modes.md and references/review-checklist.md |
| Checkpoint | references/modes.md and references/checkpoint-guide.md |
Rule Levels
Hard rules protect the project:
- Do not contradict established core character facts, irreversible events, or world rules.
- Do not drop a promised thread whose payoff is due; pay it off, delay it with a reason, or ask the author.
- Do not mark project state complete without a chapter delta in Standard Writing or Production Lock.
- Do not treat a Canon Continue request as draft-only.
- Do not continue batch/full-auto through P2 continuity problems.
Soft suggestions improve prose but are not red lines:
- Three senses in the first 500 words.
- Dialogue ratio.
- Chapter length relative to average.
- Hook density and closing strategy.
- Extra scene count beyond what the chapter genuinely needs.
Free Draft Flow
Use when the author wants to try prose without bookkeeping.
- Read only
novel/context-brief.md, the current outline row, and previous chapter if available.
- Write the draft freely. Do not run audit, checklist, delta validation, or checkpoint.
- Save only if asked. Prefer
novel/drafts/chapter-{N}-free-draft.md; do not overwrite canonical chapter text unless the author explicitly asks.
- Say clearly: "No project state was updated."
If using the helper script:
python skills/novel-write/scripts/novelflow.py save-free-draft --novel-dir novel --chapter {N} --text-file {draft_file}
Fragment Continue Flow
Use when the author gives a partial scene or paragraph and asks to continue from that exact text.
- Read
references/fragment-continue.md.
- Read
novel/context-brief.md.
- Treat the user-provided fragment as the local voice anchor. If the current chapter is obvious, read only that outline row; otherwise continue from fragment + context-brief.
- Do not run audit, review checklist, delta validation, commit, checkpoint, or generated state updates.
- Return the continuation text and clearly say project state was not updated.
- Save only if asked, preferably as
novel/drafts/fragment-continue-{timestamp}.md or novel/drafts/chapter-{N}-fragment-continue.md.
If using the helper script:
python skills/novel-write/scripts/novelflow.py save-fragment-draft --novel-dir novel --text-file {draft_file}
If the author later says "并入正文", "保存到第 N 章", "把这段作为正式章节的一部分", "按全书设定续写", or "从这里继续全书", switch to Canon Continue. Never promote fragment continuation to canon automatically.
Canon Continue Flow
Use when the author provides a fragment and wants it to become part of the official novel continuation.
This is not draft-only. It uses Standard Writing state discipline for one chapter, and Production Lock if the user also asks to continue in batch/full-auto/to the ending.
- Read
novel/context-brief.md.
- Infer the target chapter from the user instruction, fragment, chapter files, outline status, or next planned chapter in
context-brief.md.
- If the target cannot be inferred, ask one concise question: "这段要接入第几章，还是作为下一章开头？"
- Read the current outline row and adjacent rows.
- Read relevant
novel/story-state.md rows:
- characters appearing in the fragment or target chapter
- current narrative pressure
- relationship shifts touched by the fragment
- open threads touched by the fragment
- continuity locks
- Read relevant
novel/thread-ledger.md rows:
- threads mentioned by the fragment
- threads due in this chapter or next chapter
- high-risk unresolved threads
- Read relevant
novel/characters.md entries and novel/world.md sections only when the fragment touches those facts.
- Read the previous chapter as voice anchor when available; treat the supplied fragment as the immediate local voice anchor.
- Continue the official chapter prose.
- Save or merge into
novel/chapters/chapter-{N}.md.
- Create a
mode: "standard" chapter delta unless the user requested Production Lock, batch/full-auto, or ending run.
- Validate, commit, update generated state, and sync legacy exports as needed.
If the user says "从这里开始一直写到完结" or similar:
- If project state is complete, current chapter is inferable, and the outline contains an ending path, warn that direct full-book continuation is lower quality than supervised batches, then run Finish Book Run in Production Lock.
- If state is missing, stale, contradictory, or the ending direction is unclear, run Finish Book Intake first.
Finish Book Entry
Use when the author asks to resume an abandoned/incomplete book through the ending.
- If project state is missing, stale, contradictory, or the ending direction is unclear, first run Finish Book Intake from
references/modes.md.
- Produce an intake report and continuation roadmap; do not write formal chapter prose or update chapter state before the author confirms the roadmap.
- If the project state is complete and the author explicitly says to follow the existing outline directly to the ending, give the full-auto quality warning, then run Finish Book Run in Production Lock.
- After roadmap confirmation, run Finish Book Run in Production Lock.
Standard Writing Flow
Step 0: Restore State
Only read novel/context-brief.md — the compressed resume entry point for chapter status. Contains premise, character card summaries, writing progress, chapter table with status.
Do NOT read outline.md / characters.md / progress.md / world.md yet. context-brief.md has enough information to determine current state.
Display a welcome message based on completed chapter count, then proceed to Step 1.
Step 1: Assemble Context
Foundation is already in context-brief.md. Now read only what's necessary for this chapter:
In Standard Writing, keep context light. Read context-brief.md, the current outline row, and previous chapter. Use generated context packs if they already exist, but do not run a full audit unless there is a continuity risk. In Canon Continue, use the provided fragment to decide which character rows, relationship shifts, open threads, and world rules are relevant.
In Production Lock, if local file tools are available and at least one chapter delta has been committed, first run:
python skills/novel-write/scripts/novelflow.py audit --novel-dir novel
python skills/novel-write/scripts/novelflow.py assemble-context --novel-dir novel --chapter {C}
Use novel/generated/context-pack-chapter-{C}.md as the default assembled context. If audit reports a chapter newer than its delta, rebuild and commit that chapter's delta before writing later chapters. If audit reports an overdue thread, pay it off, delay it with a reason, or ask the author before continuing. If the script is unavailable or this is Chapter 1, continue with the manual loading rules below.
novel/outline.md — read the table rows for chapters C-1, C, and C+1 to understand immediate narrative context (where we just were, what we're writing now, where we're going next)novel/story-state.md — read current narrative pressure, character state rows for characters in C, open threads relevant to C, and continuity locksnovel/thread-ledger.md — read only threads planted in C, due in C/C+1, mentioned by C's outline row, or high-risk if forgottennovel/reader-promise.md or legacy novel/market-brief.md — read only 2-4 bullets: target reader, core promise, hook, and style contract. Treat legacy market-brief as reader promise, not sales strategy. If missing, continue from context-brief.md.novel/summaries.md — apply pyramid compression per references/compression-guide.md- Previous chapter full text (if any) as Voice Anchor. Skip for Chapter 1.
- If this chapter involves specific world-building rules, read relevant sections of
novel/world.md (not the whole file)
- If this chapter introduces new characters or needs detailed character traits, read that character's entry in
novel/characters.md (not the whole file)
Do NOT blindly read all project files. context-brief.md's compressed character cards are sufficient for most chapters.
Legacy project migration: If novel/story-state.md is missing, create it before writing:
- Use
context-brief.md for premise, completed count, next chapter, and compressed character cards
- Use
outline.md for planned open threads, turning points, milestone chapters, and near-term narrative pressure
- Use
progress.md for existing foreshadowing/revision notes if present
- Keep the initial file concise; mark uncertain fields as
unknown yet instead of inventing facts
- Tell the user it was created as a compatibility migration, then continue
If novel/thread-ledger.md is missing, create it before writing:
- Use
outline.md and progress.md to extract planned mysteries, promises, planted objects, red herrings, relationship payoffs, and delayed consequences
- Use stable IDs (
T01, T02, ...)
- Mark uncertain entries as
planned with unknown yet evidence instead of inventing prose evidence
- Keep the ledger concise; do not add pure mood motifs unless they require future payoff
Step 2: Detect Milestone Chapters
Check the current chapter's Milestone column in novel/outline.md.
If the outline was generated by an older version of novel-setup and has no Milestone column:
- First infer milestones from the
Key Turning Points section and obvious chapter titles/events (death, reunion, revelation, climax, darkest moment, 死亡, 重逢, 告别, 揭示, 真相, 高潮, 至暗).
- If the current chapter can be inferred as a milestone, enforce milestone protection.
- If no inference is possible, warn that the outline needs migration and continue as
normal for this chapter only. Do not silently disable milestone protection for the entire book.
If the value is anything other than normal (or empty), this is a milestone chapter.
Milestone chapters (inciting-incident, midpoint, darkest-moment, climax, death, reunion, revelation, act-break) must receive more scene development, sensory detail, and word budget than the novel's average chapter:
- At least 2 fully-developed scenes (vs. 1 minimum for normal chapters)
- Not shorter than the novel's average chapter length
- Above-average sensory density in the first 500 words
Note this constraint before proceeding to planning.
Step 3: Internal Planning
In Production Lock, read references/scene-blueprint.md now. In Standard Writing, sketch only enough to write the chapter.
Plan this chapter's structure silently. Consider:
- Scene count: Identify at least one fully-developed scene — a specific moment in a specific place with sensory detail, character action, and live dialogue. For milestone chapters, plan 2-3 developed scenes minimum.
- Character beats: What does each character in this chapter want in this moment? What are they hiding?
- State obligations: Which open thread, relationship shift, world fact, or continuity lock from
story-state.md must this chapter preserve or advance?
- Thread obligations: Which
thread-ledger.md entries should be planted, advanced, paid off, reversed, or closed in this chapter?
- Voice matching: Read the first 3 paragraphs of the previous chapter. Match that cadence, sentence rhythm, and sensory density.
- Information reveals: What does the reader learn? What remains hidden?
- Scene vs summary: For each story beat in the outline, decide: will this be a rendered scene or a bridging summary? At least one beat must be a scene.
- Reader promise: Preserve the reader promise and prose contract from
reader-promise.md, legacy market-brief.md, or the context snapshot.
Do not output this plan.
Step 4: Write
Read references/prose-guide.md for writing guidelines. Write a complete chapter.
Format: # Chapter {N}: {title} header, scene breaks with --- on its own line.
Save the drafted chapter to novel/chapters/chapter-{N}.md before delta validation. Treat it as a draft until Step 7 completes.
Craft targets (soft in Standard Writing, enforced in Production Lock from chapter 30 onward):
- Aim for at least one fully-developed scene (specific place + physical experience + real-time + character interaction)
- Prefer rendering emotional beats as live dialogue and action, not summary
- Try for 3 distinct senses in the first 500 words when it serves the scene
- For milestone chapters, give the moment enough space; in Production Lock it must not be shorter than the novel's average chapter
Step 5: Self-Review
Standard Writing: do a light review for hard-rule problems and obvious prose defects. Production Lock: read references/review-checklist.md and run the full checklist.
- P0: Auto-fix immediately (spelling, names, tense, duplicates, placeholders)
- P1: Apply one local revision pass and record in progress.md Review Notes
- P2: Flag for author — do NOT change
One-pass revision loop: Do not run open-ended rewrite cycles. After the checklist, apply P0 fixes and one focused P1 pass. If quality still needs creative judgment or a second structural rewrite, classify it as P2 and pause.
From chapter 30 onward: In Production Lock, pay extra attention to Section 5 (Structural Health). In Standard Writing, treat structural checks as revision suggestions unless they expose a hard-rule problem.
Step 6: Create and Validate Chapter Delta
Read references/chapter-delta.md. Before updating long-term state files, create:
novel/state/deltas/chapter-{N}.json
The delta is the structured handoff between chapter prose and project memory. Standard Writing uses a light delta; Production Lock uses a full delta.
Standard delta must include:
mode: "standard"- Summary fields with a strong first sentence.
- State changes only when the chapter changes characters, threads, world facts, or continuity locks.
- Review findings grouped as P0, P1, and P2; soft craft notes may go in
soft_notes.
Production delta must include:
mode: "production"- Everything in Standard delta.
- Quality metrics: word count, scene count, rendered dialogue blocks, summary bridge count, sensory counts for the first 500 words, emotional turns, and conflict turns.
Run validation when local file tools are available:
python skills/novel-write/scripts/novelflow.py validate-delta --novel-dir novel --chapter {N}
If validation fails, fix the chapter or delta and rerun. If review.p2 is non-empty, stop and ask the author; do not continue batch/full-auto.
After validation passes, commit the delta:
python skills/novel-write/scripts/novelflow.py commit-delta --novel-dir novel --chapter {N}
The commit command updates novel/state/chapter-index.json and renders novel/generated/summaries.md, novel/generated/progress.md, novel/generated/thread-ledger.md, novel/generated/story-state.md, and novel/generated/cards.jsonl.
Do not update legacy summaries.md, progress.md, story-state.md, thread-ledger.md, or context-brief.md until the delta validates and commits. If the runtime cannot execute scripts, manually check the same contract in references/chapter-delta.md, say validation was manual, and avoid batch/full-auto continuation.
Step 7: Update Files
novel/chapters/chapter-{N}.md — keep the validated final chapter textnovel/state/chapter-index.json — committed automatically from the validated delta when tools are availablenovel/generated/summaries.md, novel/generated/progress.md, novel/generated/thread-ledger.md, novel/generated/story-state.md, novel/generated/cards.jsonl — rendered automatically from committed deltasnovel/summaries.md — if this legacy file exists or the project expects it, sync from the generated summary instead of inventing a new summarynovel/progress.md — if this legacy file exists or the project expects it, sync statistics from the generated progress filenovel/story-state.md — if this legacy file exists or the project expects it, sync from novel/generated/story-state.md and the validated delta; do not invent facts outside the chapter text:
- Character State: last seen, current want, hidden pressure, relationship temperature, arc position
- Open Threads: mark planted/advanced/paid off; add new threads only when the chapter clearly creates future obligation
- World Facts: add only facts established in drafted prose that constrain future scenes
- Continuity Locks: add short "must not drift" facts when the chapter creates a hard constraint
- Recent Relationship Shifts: record meaningful changes, not routine conversation
novel/thread-ledger.md — update foreshadowing/payoff lifecycle:
- Add new threads only when the chapter creates a future reader obligation
- Mark planned threads as
planted when they appear in prose and fill Evidence In Text
- Mark active threads as
advanced when the chapter changes their meaning, stakes, or reader interpretation
- Mark threads as
paid-off only when the payoff is explicit enough for readers to recognize
- Move resolved threads to Paid Off / Closed Threads with payoff chapter and payoff form
novel/context-brief.md — update chapter status, writing progress, and State Snapshot. context-brief.md is the resume entry point; chapter text plus validated deltas are the audit trail; story-state.md stores dynamic continuity; progress.md stores detailed stats only.
When updating summaries.md, use the validated delta summary. This summary will be pyramid-compressed for future chapters — its first sentence and first 100 words are especially important.
If the completed chapter count is now a multiple of 10, recommend Checkpoint Mode before continuing. Do not run it automatically unless the user requested batch/full-auto and no guard has paused the run.
Step 8: Pause for Feedback
Display a brief summary (~150-200 words) and ask:
Chapter {N} complete. Continue to the next chapter, or want to adjust anything?
- User says "continue", "next", "go on" → return to Step 0 for chapter N+1
- User gives revision feedback → adjust or rewrite per their direction (do NOT touch other chapters)
- User doesn't respond → wait. Never decide to continue on your own.
Context reminder: If the completed chapter count is a multiple of 5 (5, 10, 15...), append:
{N} chapters written. Conversation context is accumulating. Consider starting a new conversation and running /novel-write — progress is saved in context-brief.md and will resume from chapter {N+1}.
If N is a multiple of 10, also append:
This is a good point for a lightweight checkpoint. Say "checkpoint" / 「十章检查」 to audit continuity, pacing, and payoff health before continuing.
Non-Interactive Modes
For Batch, Full-Auto, Review, and Checkpoint mode details, read references/modes.md after detecting the matching trigger. The mode file defines pre-flight checks, context assembly, guardrails, reports, and action boundaries.
