CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is Velith

A Claude Code plugin that produces books to the human-quality bar: a cold reader should not be able to tell the manuscript was machine-drafted. 6-phase pipeline (Onboarding → Ideation → Outlining → Drafting → Editing → Publishing), 18 skills, 12 agents, 7 genre systems + custom, a model-agnostic visual pipeline, and an optional Svelte dashboard. Ships as a plugin with zero npm dependencies at the root.

Architecture

Plugin structure

skills/{skill-name}/SKILL.md    — Skills (slash commands): frontmatter (name, description, argument-hint) + prompt
skills/loom/quality-bar.md      — Shared standard: 5-axis rubric, 2026 AI-tell taxonomy (en/ko/ja), cold-read protocol, visual rules
agents/{agent-name}.md          — Agents: frontmatter (name, description, tools[], effort) + prompt
velith.mjs                      — Unified CLI + HTTP server (scan/agents/stats/words/list/migrate/metrics/snapshot/images/serve)
vendor/sql.js/sql-wasm.js/wasm  — Vendored SQLite WASM binary (no npm install required)
.claude-plugin/plugin.json      — Plugin manifest (skills path, agent list)

Skills are the user-facing entry points. Agents are subagents invoked by skills. loom is the router. quality-bar.md is read by every writing, editing, and reviewing agent; changes there change the whole product.

${CLAUDE_PLUGIN_ROOT} is used in skills and agents (Claude Code substitutes it). Codex TOMLs use {PLUGIN_ROOT} and are generated from agents/*.md; do not hand-edit them.

Operating principles (v0.5, supersede the 2025 design)

• Full-manuscript context. Agents read the whole manuscript, not summaries. bible.md is an index and ledger. (Replaces ADR-005 summary-based context.)
• Sequential drafting for narrative genres; parallel (≤3) only for technical/reference/academic chapters proven independent by the outline DAG. (Amends ADR-003.)
• Voice lock on a sample chapter before drafting volume; recorded in STYLE.md ## Voice Lock.
• Draft → critique → revise inside chapter-writer; critiques saved in .velith/critiques/.
• Editing rewrites in place with snapshots (velith.mjs snapshot) and stage reports; 7 stages (0 fact-check … 6 readiness).
• Readiness gate: beta-reader writes edits/readiness-report.md with YAML verdict: PASS|REVISE, score, axes. Publishing requires PASS or an explicit override.
• One look per book: art-bible.md + .velith/art-bible.json; prompts compiled by velith.mjs images compile; diagrams/charts/drawings are code-rendered by figure-engineer; every image passes vision QA; look lock precedes volume.
• Author checkpoints (required stops): concept, outline approval, voice lock, look lock, developmental restructures, readiness verdict.

Skill → Agent mapping

Agent tool and effort constraints

Each agent has minimal tools by design (style-doctor has Edit but not Write; beta-reader has Write but not Edit; fact-checker has WebSearch/WebFetch). effort is set per agent: max for chapter-writer and beta-reader, xhigh for architect/scene/continuity/style/fact-check/art-director/figure-engineer, high for illustrator/cover/marketing. Model is inherited from the session; do not pin a model in agent frontmatter.

Genre system

7 genre skills + book-genre-creator. Each genre skill is craft guidance (structure options, scene/argument craft, genre-specific AI tells, language notes for en/ko/ja, a Visuals section, and the architect's validation list), not a template. Genres are strings; agents read skills/book-{genre}/SKILL.md or the project's genre-custom.md. Adding a genre: create the skill, update skills/loom/SKILL.md, skills/book-genre-creator/SKILL.md, README.md, dashboard HelpView.svelte, and i18n files.

Book project runtime structure

A book project directory's layout is created by the skills themselves (/book-init onward) — run ls on the project dir. .velith/ holds runtime state; edits/ holds per-stage reports plus readiness-report.md.

CLI (velith.mjs)

Single-file CLI + HTTP server. Run node velith.mjs --help (or read velith.mjs usage strings) for commands: scan, metrics, snapshot, images compile|check|render, agents, serve, list, stats, words, migrate.

Dashboard

See dashboard/CLAUDE.md (loads when working under dashboard/).

Grok Build (xAI) Plugin Support

Grok Build reads skills (skills/) and agents (agents/*.md) natively from the plugin root. Install with grok plugin install epicsagas/Velith --trust; agents spawn as velith:<name>.

Grok also reads the root plugin.json, where the agents field must stay a directory path ("./agents/") or be omitted — a Claude-style file array makes Grok skip spawn registration. Claude Code keeps the file list in .claude-plugin/plugin.json.

Multi-platform support

One platform config set per host — each lives in its own top-level dot-directory (.claude-plugin/, .codex-plugin/, .grok-plugin/, root plugin.json for Agy, .cursor/rules/, .clinerules, CONVENTIONS.md for Aider); ls -d .*/ shows what's active. Codex agent TOMLs are generated (node scripts/gen-codex-agents.mjs) — never hand-edit.

When an agent changes, regenerate the Codex TOMLs and update .clinerules, CONVENTIONS.md, and the Cursor rules if the change affects pipeline semantics.

Conventions

• Commits: Conventional Commits (type(scope): description).
• License: Apache-2.0.
• i18n: all dashboard strings through the i18n system; add keys to all 10 locales.
• Idempotent agents: skip completed work unless --force.
• Agent status: node ${CLAUDE_PLUGIN_ROOT}/velith.mjs agents {id} {running|complete|error} [task] at start and end.
• Prompts are written for frontier models: goals, materials, the bar, and judgment, not step lists. Quote-based critiques. No "delve"-era word lists as the primary tell detector; the taxonomy in quality-bar.md is structural.

Versioning and release

Bump the version in all six locations to the same value before pushing to main: .claude-plugin/plugin.json, .codex-plugin/plugin.json, .grok-plugin/plugin.json, root plugin.json, the README.md badge URL, and UI_VERSION in dashboard/src/App.svelte. Do not bump dashboard/package.json (toolchain version, private). The version badges in docs/i18n/README.*.md are dynamic (shields.io reads version from .claude-plugin/plugin.json) and must not be edited during a bump.

• PATCH: fixes, typos, i18n strings, styling.
• MINOR: new skills, agents, genres, views, i18n keys, feature additions.
• MAJOR: breaking skill/agent interface changes, phase restructuring, removed skills or agents.

Process: bump five locations → cd dashboard && npm run build → regenerate Codex TOMLs → commit → tag v{version} → push with --tags.