Velith / rules

---
description: Velith book publishing pipeline — phases, router, agents, quality bar, author checkpoints, and project structure
globs:
  - "**/*.md"
alwaysApply: true
---

# Velith — Books to the Human-Quality Bar

## Overview

Velith produces books a cold reader cannot distinguish from a competent human author's work. Six phases, twelve agents, one standard: `skills/loom/quality-bar.md` (five-axis rubric, the 2026 AI-tell taxonomy, the cold-read protocol). Read it before any writing or editing work.

```
Phase 0: Onboarding → Phase 1: Ideation → Phase 2: Outlining → Phase 3: Drafting → Phase 4: Editing → Phase 5: Publishing
```

## Operating principles

1. **Full-manuscript context.** Writing and editing agents read the entire manuscript so far, not summaries. `bible.md` is an index and ledger, not a substitute.
2. **Sequential drafting for narrative work.** Fiction, screenplay, game, memoir, narrative nonfiction: chapter N only after N-1 exists and its bible ledger is updated. Parallel (max 3) only for technical/reference/academic chapters the outline DAG proves independent.
3. **Voice lock before volume.** No drafting beyond the sample chapter until the author approves the voice; the lock is recorded in `STYLE.md`.
4. **Draft, critique, revise.** Every chapter is cold-critiqued with quoted lines and revised before it is saved. Editing stages rewrite the manuscript in place.
5. **Grounded claims.** Nonfiction, technical, academic: fact-check before line edit. Unverifiable numbers, quotes, studies, citations are removed, not softened.
6. **Reader gate.** Phase 4 ends with a cold read by simulated target readers (`beta-reader`). Publishing requires `verdict: PASS` in `edits/readiness-report.md` or an explicit author override.
7. **One look per book.** `art-bible.md`; prompts compiled by `velith.mjs images compile`; diagrams and drawings code-rendered; vision QA on every image; look lock before volume.
8. **Author checkpoints.** Concept selection, outline approval, voice lock, look lock, developmental restructures, readiness verdict. Everything else runs without asking.

## Phase router

| State | Route |
|-------|-------|
| No `PRD.md` | Phase 0 `/book-init` |
| `PRD.md`, no `ideation.md`/`outline.md` | Phase 1 `/book-ideation` |
| `ideation.md`, outline missing or without `## Approval` | Phase 2 `/book-outline` |
| Approved outline + `bible.md`, no drafts, or `STYLE.md` `## Voice Lock` pending | Phase 3 voice lock, then drafting |
| Drafts incomplete | Phase 3 `/book-draft` (resume) |
| All drafts, no readiness PASS | Phase 4 `/book-edit` |
| Readiness PASS, no `publish/book.epub` | Phase 5 `/book-publish` |

## Agents

| Agent | Phase | Job |
|-------|-------|-----|
| `book-architect` | 2 | Outline + bible, structure chosen and justified, scored validation |
| `scene-generator` | 3 (fiction) | Scene plans per chapter (purpose, turn, subtext, exit); plans, not prose |
| `chapter-writer` | 3, 4 | Drafts one chapter in full context, critiques, revises, updates the bible ledger |
| `continuity-editor` | 3-4 | Contradictions and repetitions across the whole manuscript against the bible |
| `fact-checker` | 4 (nonfiction) | Claim ledger, verification, removal of unverifiable claims |
| `style-doctor` | 4 | Measures (`velith.mjs metrics`) and rewrites tells, rhythm, drift in place |
| `beta-reader` | 4 | Cold read as target readers; readiness verdict |
| `art-director` | 2-5 | Art bible, look lock, vision QA of every image, contact-sheet review |
| `figure-engineer` | 3-5 | Code-rendered diagrams, charts, technical drawings, maps' base layers |
| `illustrator` | 3-5 | Diffusion illustrations from the art bible, compiled prompts, vision QA |
| `cover-designer` | 5 | Cover concepts from the art bible, formats, marketing variants |
| `marketing-expert` | 5 | Positioning, personas, launch calendar |

## Project structure

```
{project-dir}/
├── PRD.md              # Requirements + reader promise
├── STYLE.md            # Voice fingerprint, rules, voice lock
├── ideation.md         # Concepts, comps, chosen concept
├── outline.md          # Approved chapter specs + dependency map
├── bible.md            # Characters/concepts, term rules, timeline, per-chapter ledger
├── art-bible.md        # Visual identity, figure system, look lock
├── sources/            # Reference material + INDEX.md
├── drafts/             # ch{NN}-{slug}.md, ch{NN}-scenes.md; revised in place in Phase 4
├── visuals/            # plan.md, manifest.json, figures/, illustrations/, photos/, ref/, prompts/
├── edits/              # 00-fact-check … 06-readiness-report, readiness-report.md, editorial-report.md
├── publish/            # Outputs, metadata, cover/, illustrations/, marketing
└── .velith/            # status.json, critiques/, snapshots/, metrics.json
```

## Gates

| Phase | Gate |
|-------|------|
| 0 | `PRD.md` with reader promise; `STYLE.md` with voice fingerprint |
| 1 | `ideation.md` with author-chosen concept; ≥5 comps with verification status |
| 2 | `outline.md` with `## Approval`; architect score ≥ 8, no Critical; `bible.md` |
| 3 | All chapters drafted; each critique all axes ≥ 6; ledger per chapter; voice lock |
| 4 | `edits/readiness-report.md` `verdict: PASS` (every axis ≥ 7, mean ≥ 7.5, no put-down in ch 1-3); all chapters `status: final` |
| 5 | EPUB + PDF built, epubcheck clean, metadata, titles, cover concepts, marketing, checklist |