nightshift/docs/writer-idea.md

Agentic Novel Writing Workflow Idea

NightShift could plausibly support non-coding workflows, especially long-form fiction, because the core abstraction is not actually "write code." It is:

• read task context
• call one or more agents
• produce artifacts
• validate outputs
• update project state
• move to the next task

That maps surprisingly well to writing a novel.

Core Realization

A novel workflow should not ask one model to write the whole book, or even necessarily one whole chapter.

The durable project files would act like the source of truth:

• worldbuilding.md
• characters.md
• plot-state.md
• style-guide.md
• outline.md
• chapters/chapter-001.md
• chapters/chapter-001-scene-001.md
• tasks.md

The task file would drive the work, similar to coding tasks:

- [ ] SCENE-001: Opening scene at the border checkpoint

Description:
Write the opening scene where Mara tries to enter the city under a false work permit.

Acceptance Criteria:
- Introduces Mara's immediate goal
- Shows the checkpoint culture without exposition dump
- Mentions the salt tax conflict indirectly
- Ends with the inspector noticing the forged seal
- 900-1400 words
- Maintains close third-person POV

NightShift would run one scene or section at a time.

What We Already Have

NightShift already has several useful primitives:

• task files for chunking the novel into scenes or chapter sections
• scoped paths so agents only edit allowed writing/project files
• artifact output so drafts, reviews, and notes are preserved
• retry loops for revision
• planner/reviewer/debugger-style roles
• repo context and semantic context retrieval
• command stages that could run deterministic checks
• file-writer stages that can update Markdown files
• lookup_requests so agents can ask to read worldbuilding or prior scenes

That means this may not require a totally new engine. It may mostly need a new template and some writing-specific validation/review stages.

Likely Workflow

One practical pipeline:

plan_scene
gather_context
draft_scene
validate_scene
continuity_review
style_review
update_plot_state
summarize

Possible roles:

• Planner: turns the scene task into a beat plan.
• Context agent: pulls relevant worldbuilding, character, and plot-state excerpts.
• Drafting agent: writes the scene.
• Continuity reviewer: checks contradictions against known state.
• Style reviewer: checks POV, tone, pacing, and prose constraints.
• State updater: updates plot-state.md, characters.md, and maybe timeline.md.

Chunking Strategy

Do not make a task equal to "write chapter 4" unless chapters are short.

Better units:

• scene
• scene fragment
• chapter section
• revision pass for one scene
• continuity update after one scene
• prose polish for one scene

A chapter can be assembled from multiple scene files:

chapters/
  chapter-001/
    scene-001.md
    scene-002.md
    scene-003.md
  chapter-001.md

Then a later command or agent stage can compile chapter-001.md.

Durable State Files

The most important design piece is explicit state.

Recommended files:

story/
  worldbuilding.md
  style-guide.md
  characters.md
  timeline.md
  plot-state.md
  unresolved-threads.md
  continuity-rules.md
  outline.md
  chapters/

plot-state.md should be updated after every completed scene.

It should track:

• current character locations
• known secrets
• promises made to the reader
• unresolved questions
• relationships
• injuries/resources/items
• timeline date/time
• what each POV character currently knows

This is the fiction equivalent of application state.

Validation Ideas

Some checks can be deterministic:

• word count range
• file exists
• only allowed files changed
• Markdown heading format
• no forbidden placeholders like TODO, [insert], or TBD
• no accidental author notes in final prose
• required task terms are present
• output compiles into a chapter file

Some checks need model review:

• continuity with worldbuilding
• character voice consistency
• POV discipline
• pacing
• whether the scene satisfies the beat plan
• whether exposition is too direct
• whether the state update accurately reflects the scene

The key is not to overtrust model review. It should produce actionable retry notes, not silently bless everything.

What Might Be Missing

1. Better Non-Code Templates

This likely needs a dedicated template:

tutorial-deaddrop
tutorial-novel

or:

writer-novel

The template would include:

• starter story files
• writing prompts
• task examples
• validation commands
• allowed paths
• recommended pipeline

2. Better Markdown Patch/File Handling

The current file-writer flow can work, but fiction output may be long. It may be safer to require complete file blocks for one scene file at a time.

The workflow should avoid having an agent rewrite the whole novel or whole plot-state.md unless necessary.

3. Stronger State Update Governance

The risky part is not drafting prose. The risky part is bad state updates.

Example failure:

• the scene says Mara never saw the prince
• the state updater records that Mara recognized the prince
• future scenes build on the wrong state

A state update should probably be reviewed against the actual scene before being applied.

Possible pipeline:

draft_scene -> review_scene -> propose_state_update -> review_state_update -> apply

4. Context Window Management

Worldbuilding documents can get large.

The agent should not receive the entire story bible every time. It should receive:

• the current task
• relevant worldbuilding excerpts
• relevant character entries
• recent scene summaries
• current plot state
• style guide

Semantic search is probably enough for a first version, but a novel template may want a more explicit index:

world-index.md
character-index.md
location-index.md

5. Scene Dependency Tracking

Coding tasks already have dependencies. Fiction tasks would need the same:

Dependencies:
- SCENE-001
- SCENE-002

This prevents writing a later scene before the required earlier story state exists.

6. Revision Workflows

Writing is not only forward generation.

Useful task types:

• draft new scene
• revise scene for pacing
• revise dialogue
• continuity repair
• line edit
• chapter assembly
• chapter-level review
• update outline after discovery writing

NightShift can already represent these as tasks, but the prompts should distinguish them clearly.

7. Output Length Controls

Long fiction output needs explicit limits.

Use:

• scene word count bounds
• num_predict
• task acceptance criteria
• smaller scene files

Do not ask for "write chapter 12" unless the chapter has already been broken into beats.

Suggested First Template

Start with a minimal writer-novel template.

Files:

nightshift.yaml
.nightshift/tasks.md
.nightshift/agents/planner.md
.nightshift/agents/drafter.md
.nightshift/agents/continuity-reviewer.md
.nightshift/agents/style-reviewer.md
.nightshift/agents/state-updater.md
story/worldbuilding.md
story/characters.md
story/style-guide.md
story/plot-state.md
story/timeline.md
story/unresolved-threads.md
story/chapters/.gitkeep

Pipeline:

plan
semantic_context
context
draft
validate_draft
continuity_review
style_review
update_state
validate_state
summarize

Allowed paths:

scoped_paths:
  - story
  - .nightshift/tasks.md

Draft stage allowed paths:

allowed_paths:
  - story/chapters

State update stage allowed paths:

allowed_paths:
  - story/plot-state.md
  - story/characters.md
  - story/timeline.md
  - story/unresolved-threads.md

That separation matters. The drafter should not freely rewrite the world bible, and the state updater should not rewrite the scene prose.

What We Should Not Do First

Do not start with:

• automatic full-plot generation
• full chapter generation
• global rewrites of all prior chapters
• one giant worldbuilding.md dumped into every prompt
• trusting the model to maintain continuity without explicit state files

Those are likely to produce impressive-looking but unstable output.

Practical First Experiment

A good first test:

1. Create a tiny worldbuilding document.
2. Create three characters.
3. Create five scene tasks.
4. Have NightShift draft one scene at a time.
5. After each scene, update plot-state.md.
6. Run continuity review against only the scene, state files, and relevant worldbuilding.
7. Inspect artifacts.

Success criteria:

• scenes land in the right files
• word counts stay bounded
• state updates are accurate
• future scenes use prior state correctly
• reviewers catch obvious contradictions

Bottom Line

Theoretically, NightShift already has many of the needed utilities.

The missing piece is mostly a writing-oriented template with:

• scene-sized tasks
• durable story state files
• strict path separation between prose and state updates
• writing-specific prompts
• lightweight deterministic validators
• continuity/style review stages

This is viable, but it should start as a constrained scene-writing workflow, not an autonomous novel generator.