Architecture

The intro flagged the 4 Tiers and multi-book. This section looks at what output files it flows through, where the per-chapter gate sits, and how several books are isolated. Two things are worth watching: Tiers hand off through files rather than chat, and generation and verification loop per chapter.

The 4-Tier flow

When a user utterance comes in, book-orchestrator goes through Phase 0 (context check and book selection) and routes the Tiers. A new concept starts at Tier 1; “rewrite ch3” jumps to Tier 3.

graph TB
  start[User utterance - I want to write this kind of book]
  p0[Phase 0 - check books.json, select book]
  t1[Tier 1 Direction - 01_direction_brief.md]
  t2[Tier 2 Planning - world_building, character_design, plot_architecture]
  t3[Tier 3 Writing - ch draft one at a time]
  t4[Tier 4 Quality - ch ai_check, ch review]
  done[chapter finished]

  start --> p0 --> t1 --> t2 --> t3 --> t4
  t1 -->|user approval| t2
  t2 -->|user approval| t3
  t4 -->|AI-smell pass| done
  t4 -->|fail| t3

There’s a user-approval gate at the end of Tier 1 and Tier 2. A human confirms the direction and the outline before moving on. If the Tier 4 AI-smell gate fails, it goes back to Tier 3 and rewrites that chapter. A single chapter loops here and has to clear the gate to be marked finished.

Agent and output per Tier

Tier	Agent	Reads	Writes
Direction	direction-agent	user concept	01_direction_brief.md
Planning	planning-agent	direction brief	02_world_building.md, 03_character_design.md, 04_plot_architecture.md, 04_chapter_outline.json (all genres)
Writing	writing-agent	planning outputs, consistency index	chapters/ch{NN}_draft.md, chapters/ch{NN}_meta.json
Quality	quality-agent	chapter, consistency index	chapters/ch{NN}_ai_check.md, chapters/ch{NN}_review.md, chapters/ch{NN}_review.json

Agents don’t pass bodies to each other through chat. Each Tier writes a file, and the next Tier reads it. That’s why work survives a session break. progress.md is the source of truth recording every Tier’s progress.

Multi-book folder isolation

You run several books on one channel. Each book is isolated in its own folder, and the root books.json is the index.

graph TB
  idx[_workspace/books.json - index + active_slug]
  idx --> b1[novel-magic-cost-01/]
  idx --> b2[practical-ai-collab/]
  b1 --> b1a[01_direction_brief.md]
  b1 --> b1b[04_chapter_outline.json]
  b1 --> b1c[chapters/]
  b1 --> b1d[consistency_index.json]
  b1 --> b1e[progress.md]
  b2 --> b2a[01_direction_brief.md]
  b2 --> b2b[chapters/]
  b2 --> b2c[progress.md]

books.json holds the book list and the active book (active_slug). Every agent and skill reads this index to decide its working folder. Saying “continue with book X” only changes the active book; the existing work is preserved as is. With a novel’s folder and a technical book’s folder separated, one book’s character setup doesn’t leak into another.

_workspace/
├── books.json                        index + active_slug
└── {book_slug}/
    ├── 01_direction_brief.md         Tier 1
    ├── 02_world_building.md          Tier 2 (all genres, background/world)
    ├── 03_character_design.md        Tier 2 (all genres, characters/persona)
    ├── 04_plot_architecture.md       Tier 2 (structure + outline)
    ├── 04_chapter_outline.json       Tier 2 (machine-readable)
    ├── consistency_index.json        Tier 2–3 accumulated
    ├── chapters/                     Tier 3–4
    │   ├── ch01_draft.md             Tier 3 body
    │   ├── ch01_meta.json            Tier 3 meta
    │   ├── ch01_ai_check.md          Tier 4 AI-smell report
    │   └── ch01_review.md            Tier 4 aggregated review
    └── progress.md                   progress source of truth

Files outside _workspace/ — .claude/, AI_AUTOMATION.md — are not modified or deleted without human approval (S2). Cross-modification between book folders is blocked too.

Slug rules

A slug uses only lowercase letters, digits, and hyphens. It combines genre, concept, and a serial number, like novel-magic-cost-01 or essay-child-raising-01. /start takes it on first book entry, and later books are named explicitly with “new book — with slug X.”

One chapter, one commit

One chapter is one commit (S5). A chapter and its AI-check are sometimes kept as one commit. Because a version is kept per chapter, if Chapter 12 goes wrong while you fix it, you can roll back to the state through Chapter 11.

The automation entry point points at one place

.claude/agents/ and .claude/skills/ are the Claude Code storage location, and AGENTS.md is the Codex entry point. Both read AI_AUTOMATION.md. The 4-Tier definitions, the directory contract, the books.json schema, and the 14 categories live in that one file, so the Tier and output contracts are the same in whichever runtime you work.

Next

The next section is genres. It covers which skill graph book_type turns on, and how fiction, practical, essay, and technical split.