Novel Agent Workflow

English | 简体中文

A public, reproducible Codex skill for long-form fiction. It coordinates five fixed agent roles, enforces an outline-first workflow, gates every draft through review, and keeps plot and entity knowledge consistent across writing rounds.

Why It Exists

Long-form generation tends to lose continuity when planning, drafting, review, and memory maintenance happen in one unstructured chat. This project turns that process into a file-backed workspace with explicit role boundaries and deterministic flow gates.

Key capabilities:

• outline-first project initialization;
• five reusable agent role slots;
• REVISE / PASS_TO_RAG review gate;
• parallel plot and entity knowledge maintenance after review passes;
• role-scoped context selection instead of loading the full knowledge base;
• repair and backfill scripts for older workspaces;
• no runtime Python dependencies outside the standard library.

Workflow

flowchart LR
    U[User request] --> P1[story_planner<br/>round open]
    P1 --> W[writer<br/>chapter draft]
    W --> R[reviewer]
    R -->|REVISE| W
    R -->|PASS_TO_RAG| KP[plot keeper]
    R -->|PASS_TO_RAG| KE[entity keeper]
    KP --> P2[story_planner<br/>round close]
    KE --> P2
    P2 --> O[Orchestrator summary]

Loading

Role	Responsibility	Write boundary
story_planner	Round-open brief, round-close brief, and replanning	Outline, planning briefs, plot planning files
writer	Draft new chapters	正文/ only
reviewer	Check continuity, motivation, pacing, style, and hooks	Review record only
rag_plot_keeper	Maintain plotlines, timeline, summaries, and foreshadowing	Plot-side knowledge files
rag_entity_keeper	Maintain characters, relationships, places, rules, and continuity	Entity-side knowledge files

Retrieval Model

The legacy role IDs contain rag, but this public version does not claim embedding or vector-database retrieval. Context is stored as structured Markdown files and selected by role-specific JSON rules:

• an always_read minimum context set;
• recent chapter and review windows;
• an on_demand file set;
• a role-specific selection rule.

This makes the context path inspectable and keeps the main orchestrator from loading the entire knowledge base for every chapter.

Quick Start

Requirements: Python 3.10+.

git clone https://github.com/DTSFO/novel-agent-workflow.git
cd novel-agent-workflow

mkdir -p /tmp/novel-demo
python scripts/init_novel_workspace.py \
  --workspace /tmp/novel-demo \
  --name "星港来信" \
  --user-prompt "一部关于深空通信与记忆伦理的悬疑小说"

python scripts/find_novel_projects.py /tmp/novel-demo

To use the full agent workflow, place or symlink this checkout into the skill directory configured by your Coding Agent runtime, then invoke $write-novel from a workspace where novel projects may be created. The role registry is optimized for Codex fixed-subagent semantics; other runtimes can reuse the workspace, templates, scripts, and review gates, but may need an orchestration adapter.

Reproducibility Boundary

Surface	Verification
Workspace initialization, discovery, registry refresh, and repair	Automated on Python 3.10 and 3.12 in GitHub Actions
Public-file safety scan and local documentation links	Automated before release
Templates and flow-gate configuration	Deterministic files committed in this repository
Model-backed five-agent writing round	Requires a compatible Codex runtime and model access; not executed in model-free CI

The repository therefore guarantees reproducible workspace construction and an inspectable orchestration contract. Generated prose remains model- and prompt-dependent.

Verification

python -m compileall -q scripts
python -m unittest discover -s tests -v
python scripts/check_public_safety.py

The tests initialize a temporary workspace, verify project discovery, refresh managed role configurations, confirm that repair operations preserve user-authored content, exercise invalid input paths, and verify that the public safety scanner rejects credential-like content.

Repository Layout

.
├── SKILL.md                    # Agent-facing workflow contract
├── agents/                     # Skill display metadata
├── assets/
│   ├── project-template/       # Workspace, outline, review, and chapter templates
│   └── rag-template/           # Structured plot/entity knowledge templates
├── docs/architecture.md        # Design and data-flow notes
├── examples/README.md          # Safe, model-free demo procedure
├── references/                 # Role guides and orchestration playbook
├── scripts/                    # Initialize, scan, repair, and safety-check tools
└── tests/                      # Standard-library regression tests

Privacy

This repository contains templates and orchestration code only. It intentionally excludes real novels, generated chapters, API credentials, model configuration, agent session IDs, and private workspace data.

License

MIT