CanonLoom

View CanonLoom on GitHub ↗

CanonLoom is a command-driven, local workflow for human–AI collaboration on long-form novels. The author launches tasks with short commands, an Agent (Codex / Claude Code / OpenCode, etc.) reads task files and does the creation, Python scripts perform deterministic validation, and the author makes choices and approvals at every key checkpoint.

It is not GUI writing software, nor a black-box tool that “generates an entire novel from one sentence.” The problem it solves is one of the most common failures in long-form novel writing: state drift across chapters — character motivations that become inconsistent, timelines that break, settings the model proposes that quietly become “story facts” without approval, and review feedback that cannot be traced back to concrete revision tasks.

The most essential point of the design: the protocol lives in files, not in the model’s memory. Project state, plans, drafts, reviews, and approvals are all stored as readable files (Markdown / JSON / JSONL), so different Agents can work on the same file protocol and recover from the last valid artifact after an interruption.

Why

The difficulty of long-form novel generation is not in single-chapter quality but in cross-chapter consistency. The usual “prompt + history text” approach hides state in the model context: when something goes wrong in chapter 7, it is hard to answer “what material does this passage rely on,” “was this fact confirmed by the author or just now guessed by the model,” or “has this review finding been addressed.”

CanonLoom models writing as explicit state transitions. A chapter passes through the S0–S6 stage gates, and only after the author approves is it promoted to a formal state. In this way, states, decisions, and validation boundaries are made explicit, and problems can be located to a specific stage.

Core design

File protocol and the first boundary

The project structure generated after init:

canonloom.json                     # 项目状态 + 工作流配置（状态机）
intent/author-setup.json           # 作者确认的题材/受众/视角/边界（作者说了算）
intent/ai-recognition.json         # AI 识别出的候选人物/世界/线索（AI 只能提案）
intent/style-profile.json          # 文风约束
intent/review-policy.md            # 审查政策
memory/narrative-state/            # 可选叙事状态层：事件/知识/揭示
tasks/current.md                   # 当前任务（Agent 的入口）

author-setup.json (author configuration) and ai-recognition.json (AI proposals) are stored separately: author configuration is not mixed with AI inference, and AI inference never automatically enters canon. This is the first boundary of the entire project.

canonloom.json records the current stage, the next action, the S0–S6 stage order, whether settlement requires author approval, the retry limit, and so on. The Agent always reads it and tasks/current.md first, follows next_action, and does not invent its own process.

S0–S6 stage gates

A chapter’s production is split into 7 stages, each with fixed artifacts and write boundaries:

Stages cannot be skipped: without author approval at S6, a draft cannot enter manuscript/; with unresolved BLOCKER/MAJOR review findings, it cannot enter S6; writing directly to canon is never allowed at any stage. Review findings are graded BLOCKER / MAJOR / MINOR / ADVISORY, with the first two blocking promotion.

To emphasize: the hard constraints restrict the state boundaries, not the sentence expression. A chapter contract can require “a certain choice causes an irreversible cost,” but cannot dictate which sentence a character uses to say it.

Chapter contract and context compilation

The chapter contract is not a summary. At minimum it requires:

{
  "id": "chapter-001",
  "objective": "本章目标",
  "viewpoint": "视角",
  "time": "时间",
  "location": "地点",
  "required_changes": ["必须发生的变化"],
  "forbidden_changes": ["禁止发生的变化"],   // 防止过度解决、越权设定
  "exit_state": "章节出口状态"                // 下一章可继承的事实和开放问题
}

It serves simultaneously as generation input, review baseline, and experiment record. Context compilation bundles the material a chapter needs into a bounded package, recording each source file’s SHA-256 fingerprint and the reason for inclusion; “excluded” material is not deleted, but simply should not be read for this task.

Optional narrative state layer

When a work becomes complex enough to need it, three state files can be enabled: events (what happened), knowledge state (who knows what), and reveals and foreshadowing (when who learns what). Three modes are supported — disabled / optional / required — without forcing every project to adopt a complex knowledge graph from the start.

Usage

The author’s daily work only needs a short command set:

./bin/canonloom --root ~/my-novel status       # 现在处于什么阶段？下一步做什么？
./bin/canonloom --root ~/my-novel continue     # 按 next_action 继续（最常用）
./bin/canonloom --root ~/my-novel idea         # 开始创意：2–5 个候选方向
./bin/canonloom --root ~/my-novel planning     # 层级规划
./bin/canonloom --root ~/my-novel work         # 开始一个工作单元（一章）
./bin/canonloom --root ~/my-novel revision     # 问题驱动修订
./bin/canonloom --root ~/my-novel review       # 审查
./bin/canonloom --root ~/my-novel diagnose     # 检查结构和状态（出问题时先跑这个）
./bin/canonloom --root ~/my-novel repair       # 修复白名单内的结构问题

One complete chapter production: idea/work/continue generates tasks/current.md → the Agent produces 2–5 creative options → the author chooses (select / merge / edit / reject / defer) and writes the reasoning → runs through the S0–S6 gates → settles into manuscript/. There are clear fallbacks when something goes wrong: an S4 failure returns to S3 for re-validation, an S5b divergence keeps both reports for a human decision, and reopening an already-settled chapter uses retry S0 to keep the old artifacts and start a new run.

Three work modes are supported — economy / standard / deep — corresponding to different review intensities.

Current status

What is being validated now is “engineering reliability,” not “the generated novel is of higher quality”. Data that has not been measured is not treated as a result.

Already validated:

• 18 Python unit tests pass (commands, protocol, config precedence, state validation, and other core paths);
• the minimal-project smoke passes: the full init → setup → idea → diagnose chain runs end to end;
• local deterministic tooling measured at 183 ms (one chapter draft, 6 tool steps); the Python layer is usually far smaller than one model request;
• every run records a manifest (stage, tool calls, tokens, latency, retries), and the context package and chapter index carry source SHA-256 fingerprints.

Cross-architecture literary-quality comparison must wait for the controlled experiment in section 10 of the paper (fixed model/seed/chapter contract/budget, B0–B5 control groups, A1–A6 ablations). Until then, the positioning is “an auditable narrative production protocol,” not “a verified-superior generation method.”

The complete system design, research boundaries, and evaluation plan are in: CanonLoom 0.2.0 system design paper ↗.

5-minute run

No third-party packages required, Python 3.9+:

git clone https://github.com/Liyuk/canonloom
cd canonloom
./bin/canonloom init ~/my-novel --name "My Novel"
./bin/canonloom --root ~/my-novel setup --confirm   # 确认作者配置
./bin/canonloom --root ~/my-novel idea              # 开始创意
./bin/canonloom --root ~/my-novel continue          # 按 next_action 继续

The complete minimal chain can be run directly via the repo’s bundled example (prints MINIMAL PROJECT SMOKE: OK):

examples/minimal-project/smoke.sh

Project info

• Repository: https://github.com/Liyuk/canonloom
• License: MIT
• Dependencies: Python standard library, no third-party dependencies
• Version: 0.2.1