claude-novel-writer 0.1.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "name": "claude-novel-writer",
+  "owner": {
+    "name": "mrskwiw"
+  },
+  "plugins": [
+    {
+      "name": "claude-novel-writer",
+      "source": "./",
+      "description": "AI-assisted novel writing for Claude Code — structure, consistency tracking, context assembly, and prose analysis",
+      "author": {
+        "name": "mrskwiw",
+        "email": "mrskwiw@gmail.com"
+      },
+      "keywords": [
+        "novel",
+        "writing",
+        "fiction",
+        "storytelling",
+        "manuscript"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "claude-novel-writer",
+  "version": "0.2.0",
+  "description": "AI-assisted novel writing for Claude Code — structure, consistency tracking, context assembly, and prose analysis",
+  "author": {
+    "name": "claude-novel-writer",
+    "email": "mrskwiw@gmail.com"
+  }
+}

package/CHANGELOG.md

@@ -7,6 +7,183 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-28
+
+### Changed (MCP server — passthrough rewrite)
+- The `novel-tools` MCP server was a parallel, hand-written set of ~40 tools
+  that had drifted badly behind the CLI and was broken against the current
+  schema (it queried a non-existent `projects.project_path` column and a
+  `novel.db` file the app never creates). It is replaced by a **single `novel`
+  passthrough tool** that runs any CLI command in a project and returns its
+  output. The CLI's `CommandRegistry` is now the single source of truth, so the
+  MCP surface can never drift again — the tool's description points callers at
+  `help` / `help <command>` to discover the live command + argument list.
+  (`mcp-server/novel-tools/`: `handlers.ts` + `tools.ts` removed; `index.ts`
+  rewritten; `launch.js` refactored for testability.)
+
+### Fixed (correctness bugs surfaced by coverage work)
+- **`session`, `location`, and `timeline` commands were non-functional** on a
+  real project: each handler built a `NovelWriterExtension` but never resolved
+  the project id, so every DB operation threw "Project ID not set" (timeline was
+  entirely broken; session start/end/stats and progress always failed). All
+  three now call `loadProjectId()`. (BUGS.md CLI-02)
+- **`/novel foreshadow` was unreachable** — the command and its handler existed
+  and were tested, but the command was never registered in the CLI registry.
+  Now registered. (BUGS.md CLI-03)
+- **`check characters` / `check timeline` / `check plot-threads` silently
+  reported no issues** (and `check list` showed `[undefined]` badges) — the
+  handlers read camelCase fields off raw snake_case rows; `getOpenIssues()` now
+  maps to the typed `ConsistencyIssue` shape. (BUGS.md CHECK-01/02)
+- **`generate next-sentence` always failed** — it queried `scenes.content` /
+  `scenes.project_id`, which don't exist; now reads the scene's chapter summary
+  via a valid join. (BUGS.md SQL-04)
+- **`world-rule established` could throw an FK violation** — a chapter *number*
+  was written into the `established_chapter_id` (FK → `chapters.id`); both sync
+  directions now resolve number↔id. (BUGS.md SQL-05)
+- **Character files with a quote in an attribute** (e.g. `height: 5'9"`) produced
+  invalid YAML that broke sync — values are now escaped. (BUGS.md DATA-01)
+- `--tension 0` / `--mood 0` no longer bypass range validation. (BUGS.md VAL-01)
+- `scene-handler` resolves the real project id instead of hardcoding 1. (BUGS.md ROBUST-01)
+
+### Added (v0.2.0 craft features — round 2)
+- **`novel revise <chapter> [--apply <categories>|--all]`** — diff-gated
+  mechanical prose fixes (doubled words, redundant intensifiers, adverb dialogue
+  tags, straight→curly quotes, multiple/trailing whitespace). Dry-run preview by
+  default; applies only the categories you opt into. Distinct from `revision`
+  (snapshots).
+- **`novel structure list|apply <template>|status`** — story-structure beat
+  templates (three-act, Save the Cat, Hero's Journey) mapped to word-count
+  positions; `status` compares the applied plan against drafted word count.
+- **`novel theme add|list|trace`** — register themes + motif words and trace
+  motif density across chapters (sparkline, gaps, spikes). Deterministic.
+- **`novel analyze hook [--chapter N]`** — deterministic opening-line
+  hook-strength scorer (0–100) across six signals with advisory suggestions.
+- **Advisory severity grading** — `analyze prose|sentences|dialogue` now grade
+  flags as info/suggestion/warning relative to `style-targets.yml` (with an
+  optional `allow:` list and softened wording); `--strict` restores hard flagging.
+- **`novel help --json`** — machine-readable JSON schema of the whole CLI (or a
+  single command), so tooling/agents can introspect commands + flags without
+  parsing prose.
+
+### Tests & coverage
+- Removed `tests/e2e/gothic-horror-live.test.ts` (hardcoded to a personal
+  absolute path; unrunnable elsewhere).
+- Coverage scope corrected (excludes built `dist/`, `examples/`, config files).
+- Comprehensive in-process handler tests added: **CLI at 96.6% statements**
+  (every handler ≥90% except session-handler at 88%), **mcp-server at 93.9%**,
+  project total 91.7% — up from a 55.5% project baseline. Suite: 2,445 tests.
+- Six additional latent bugs documented in `BUGS.md` (CHECK-01/02, SQL-04/05,
+  DATA-01, VAL-01, ROBUST-01) for follow-up.
+
+### Fixed (Tier-0 correctness)
+- `create chapter` now syncs the new chapter to the database and auto-numbers it
+  (was: never synced, hardcoded chapter 1) — chapters are immediately visible to
+  analysis/context/consistency.
+- The CLI resolves the real project id from the database instead of hardcoding 1.
+- `context build` is wired to the ContextPolicyEngine (was a stub) — assembles
+  and renders real context blocks.
+- Chapter summaries moved out of the deterministic sync layer (which wrote a
+  placeholder) into the generation layer: `generate summary --chapter N`
+  produces a ≤5-sentence summary via Claude, using the API when
+  `ANTHROPIC_API_KEY` is set and otherwise the Claude Code session (passthrough).
+
+### Added (v0.2.0 craft features)
+- **`novel report`** — one-screen manuscript-health dashboard: tension sparkline,
+  open plot threads, unresolved/overdue promises, scenes missing a purpose,
+  chapters off their style targets, and total `[TK]` markers. Read-only.
+- **`novel readaloud`** — actually speaks a chapter/scene/text via the OS TTS
+  engine (Windows SAPI, macOS `say`, Linux espeak/spd-say); `--out` writes audio.
+- **`novel analyze voice`** — manuscript-wide character-voice analysis: flags
+  voices that sound too alike and voices that drift across chapters.
+- **`novel extract --chapter N`** — discovery-writer path: scans drafted prose
+  for new character/location candidates and proposes ready-to-run create commands.
+- **`novel extract --file <path>`** — runs the same discovery scan over any
+  prose file (e.g. a freeform outline), so a planner can bootstrap structured
+  `characters/` / `plots/` entities before drafting begins.
+- **`novel generate overview`** — summary of the **intended** book, assembled
+  from the planned outline (plot threads + their beats) and the character
+  roster (unlike `synopsis`, which summarizes drafted chapters). Works
+  pre-draft; `--length brief|standard|full`, `--save` writes
+  `export/overview.md`. Uses the API when `ANTHROPIC_API_KEY` is set, otherwise
+  the Claude Code session (passthrough). Emits a guidance warning — pointing at
+  `extract --file` — when no cast or outline exists yet.
+
+## [0.1.1] - 2026-06-26
+
+### Changed
+
+**`init` command — automation-friendly (works in the Claude Code / AI environment)**
+- `init` no longer blocks on interactive `readline` prompts. It now prompts
+  **only** when attached to a real interactive TTY; in the Bash tool, CI, or any
+  non-TTY context it runs non-interactively and never hangs.
+- When `--title`/`--author` are missing in non-interactive mode, they are
+  auto-derived (title from the directory name, author from `git config
+  user.name`, falling back to `"Unknown Author"`) and the chosen values are
+  reported instead of erroring.
+- Added `--json` flag: emits a single machine-readable JSON result on stdout
+  (`status`, `projectId`, `path`, `metadata`, `derived`, `created`,
+  `hasExistingContent`, `nextSteps`). Implies non-interactive.
+- dotenv startup banner is now suppressed (`config({ quiet: true })`) so it can
+  no longer corrupt `--json` output on stdout.
+- `--skip-prompts` is retained as an explicit non-interactive override; it now
+  auto-derives missing fields rather than failing.
+
+**Docs**
+- Clarified in the `/novel` command guide that the `novel-db` MCP server is
+  optional and for power users only. The CLI accesses the SQLite database
+  directly, so the MCP server is not needed for normal use and should not be
+  added during `init` or to "fix" CLI errors. (Previously the wording implied
+  the MCP server was required, which confused agents during setup.)
+
+**CLI help entries**
+- Every command now ships realistic `examples` in its `/novel help <command>`
+  entry. Added `examples` to: `character`, `check`, `export`, `foreshadow`,
+  `generate`, `location`, `plot`, `scene`, `session`, `progress`, `timeline`,
+  `world-rule`.
+- `help <command>` renderer now shows a `Usage:` line, a positional
+  **Arguments** section, and flag **required / choices / default** metadata
+  (previously only name, alias, type, and description were shown).
+- Sharpened name-echo flag descriptions on `character` (`eye-color`,
+  `hair-color`, `height`).
+
+### Added
+
+- **Style-target engine (deterministic).** New `style-targets.yml` declares
+  quantitative prose targets (sentence length, adjective/adverb density, passive
+  %, show/tell, sensory coverage, em-dash/semicolon/ellipsis cadence, fragments,
+  single-sentence paragraphs). New `novel-writer analyze style [--chapter N | --all]`
+  measures a chapter and grades each metric against the targets (✓ / ⚠ low / ⚠ high).
+  Falls back to general-fiction defaults when no file is present.
+- **Starter templates shipped + scaffolded.** New `templates/` directory in the
+  plugin holds starter files: `style-targets.yml`, `STRUCTURAL_STYLE_GUIDE.md`,
+  `COMPOSITIONAL_STYLE_GUIDE.md`, and schema-accurate entity templates
+  (`character.yml`, `location.yml`, `plot.yml`, `world-rule.yml`, `timeline.yml`,
+  `chapter.md`, `README.md`). `init` now **copies** these (instead of embedding
+  strings): the three functional files to the project root, and the entity
+  templates into the project's `templates/` reference dir (kept out of the
+  content dirs so `sync` never imports them). The generated CLAUDE.md documents
+  how to use them. `init` also records an **editing-mode preference**
+  (deterministic | ai) in CLAUDE.md and via `--editing-mode`.
+- **Editor agents now ship with the plugin.** The Copy / Line / Developmental
+  Editor (and other novel) agents moved into `agents/` at the plugin root and
+  their style-guide paths were corrected to project-root-relative (were pointing
+  at the `novel/` sample subdir, so they never resolved in real projects).
+  `package.json` `files` now includes `agents`, `commands`, `skills`,
+  `.claude-plugin`.
+- `NovelWriterExtension.getProjectId()` accessor.
+- **`analyze copy` now consumes the style guide.** It reads canonical character
+  names from `characters/*.yml` (drives the misspelled-name check) and defaults
+  the expected narrative tense from `style-targets.yml` when `--tense` is omitted.
+
+### Fixed
+
+- **`canon show` / `canon promote` now find their `<id>`.** The handlers read the
+  positional id in a dispatch-aware way; previously they looked one slot too far
+  and always reported the id as missing under real CLI dispatch.
+- **MCP `novel-db` server now points at the real database.** The config pointed
+  at `.novel/novel.db`, but the code uses `.novel/data.db` — corrected so the
+  optional MCP server attaches to the actual database.
+
 ## [0.1.0] - 2026-06-09
 
 ### Added
@@ -66,5 +243,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `generate`, `idea`, `knowledge`, `canon`, `promise`, `context`, `graph`
 - `revision`, `draft`, `analyze`, `research`, `beta`, `query`, `series`, `help`
 
-[Unreleased]: https://github.com/mrskwiw/claude-novel-writer/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/mrskwiw/claude-novel-writer/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mrskwiw/claude-novel-writer/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/mrskwiw/claude-novel-writer/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/mrskwiw/claude-novel-writer/releases/tag/v0.1.0

package/README.md

@@ -8,19 +8,36 @@ A [Claude Code](https://claude.ai/code) plugin for AI-assisted novel writing. Ma
 
 ## Installation
 
+Two alternate methods — both install the same plugin globally, so use whichever you prefer:
+
 ```bash
+# via npm
 npm install -g claude-novel-writer
 ```
 
+```bash
+# via Claude Code's plugin manager
+claude plugin install claude-novel-writer
+```
+
 Claude Code detects the extension automatically after installation. Restart Claude Code, then:
 
 ```
 /novel help
 ```
 
+### Local install (development / testing)
+
+```bash
+git clone https://github.com/mrskwiw/claude-novel-writer.git
+cd claude-novel-writer/project
+npm install && npm run build
+claude --plugin-dir .
+```
+
 ## How it works
 
-Once installed, the plugin loads four skills into Claude's context. Claude reads the skill descriptions and **invokes them automatically** based on what you say — you don't need to remember command names.
+Once installed, the plugin loads five skills into Claude's context. Claude reads the skill descriptions and **invokes them automatically** based on what you say — you don't need to remember command names.
 
 - Say *"I want to write a novel"* in a blank folder → Claude initializes the project
 - Say *"check my manuscript for inconsistencies"* → Claude runs consistency checks
@@ -36,23 +53,6 @@ When you want direct control, use the `/novel` slash command or the `novel-write
 - pandoc (optional — for DOCX/EPUB/PDF export)
 - `ANTHROPIC_API_KEY` (required for AI generation commands only)
 
-## Installation
-
-```bash
-claude plugin install claude-novel-writer
-```
-
-Restart Claude Code after installing.
-
-### Local install (development / testing)
-
-```bash
-git clone https://github.com/mrskwiw/claude-novel-writer.git
-cd claude-novel-writer/project
-npm install && npm run build
-claude --plugin-dir .
-```
-
 ## Starting a new novel
 
 Open an empty folder in Claude Code and just say what you want:
@@ -148,8 +148,17 @@ All commands are available as `/novel <command>` (slash command) or `novel-write
 | `analyze pacing` | Tension arc, POV balance, chapter length distribution |
 | `analyze copy` | POV slips, tense shifts, name variant detection |
 | `analyze developmental` | Scene purpose audit, subplot balance, plot holes |
+| `analyze style` | Grade prose against this project's `style-targets.yml` (`--chapter N` / `--all`) |
+| `analyze voice` | Manuscript-wide voice analysis: flag too-similar voices and voices that drift |
+| `analyze hook` | Score a chapter's opening-line hook strength (0–100) across six signals (`--chapter N`) |
+| `revise <chapter>` | Diff-gated mechanical prose fixes — dry-run by default; `--apply <categories>` / `--all` |
+| `structure apply\|status` | Beat templates (three-act / Save the Cat / Hero's Journey) vs word-count positions |
+| `theme add\|list\|trace` | Register themes + motifs and trace motif density across chapters |
+| `report` | One-screen manuscript-health dashboard (tension, threads, promises, `[TK]`s) |
+| `readaloud` | Speak a chapter/scene/text aloud via the OS TTS engine (`--out` writes audio) |
+| `extract --chapter N` | Scan drafted prose for new character/location candidates (or `--file outline.md` to bootstrap from a freeform outline) |
 | `draft scan` | Find `[TK]`, `[TODO]`, `[CHECK]`, `[FIXME]` markers |
-| `draft readaloud` | Rhythm analysis, accidental rhyme detection |
+| `draft readaloud` | Rhythm analysis, accidental rhyme detection (text prep, not audio) |
 
 ### AI generation
 
@@ -165,6 +174,8 @@ Requires `ANTHROPIC_API_KEY`.
 | `generate comps` | Comparable titles |
 | `generate character --id N` | Full character profile |
 | `generate name` | Character or place name suggestions |
+| `generate summary --chapter N` | ≤5-sentence chapter summary (API, or via the Claude Code session) |
+| `generate overview` | Summary of the **intended** book from the planned outline + cast (pre-draft; `--length brief\|standard\|full`) |
 
 ### Research
 

package/agents/README.md

@@ -0,0 +1,327 @@
+# Claude Novel Writer - Subagents
+
+This directory contains specialized subagents for the Claude Novel Writer project. These agents are designed to assist with specific aspects of novel writing while respecting craft principles and author voice.
+
+## Available Subagents
+
+### Creative Writing Agents
+
+#### 1. Novel Writing Assistant
+**File**: `novel-writing-assistant.md`
+**Purpose**: General creative fiction writing assistance
+**Use for**:
+- Generating character profiles and locations
+- Scene continuation suggestions
+- Dialogue enhancement
+- Description expansion
+- Plot brainstorming
+- Writing craft guidance
+
+**Example**:
+```
+@novel-writing-assistant Can you suggest 3 ways to continue this scene?
+[paste scene text]
+```
+
+---
+
+#### 2. Character Developer
+**File**: `character-developer.md`
+**Purpose**: Deep character creation and consistency
+**Use for**:
+- Creating complex character profiles
+- Checking character consistency across chapters
+- Developing character arcs
+- Ensuring distinct character voices
+- Identifying character contradictions
+
+**Example**:
+```
+@character-developer Create a character profile for:
+"A brilliant but isolated astrophysicist who discovers an alien signal"
+```
+
+---
+
+### Analysis & Review Agents
+
+#### 3. Consistency Checker
+**File**: `consistency-checker.md`
+**Purpose**: Detecting contradictions and continuity errors
+**Use for**:
+- Finding character attribute conflicts (eye color, age, etc.)
+- Identifying timeline inconsistencies
+- Catching world rule violations
+- Detecting plot thread issues
+- Distinguishing errors from intentional complexity
+
+**Example**:
+```
+@consistency-checker Review chapters 1-10 for character consistency,
+especially Sarah Chen's physical description and personality traits.
+```
+
+---
+
+#### 4. Plot Analyzer
+**File**: `plot-analyzer.md`
+**Purpose**: Story structure and pacing analysis
+**Use for**:
+- Analyzing story structure (three-act, hero's journey, etc.)
+- Identifying pacing issues
+- Tracking plot threads
+- Checking stakes escalation
+- Suggesting plot improvements
+
+**Example**:
+```
+@plot-analyzer Analyze the pacing and structure of Act 2 (chapters 8-18).
+```
+
+---
+
+### Editing Agents
+
+**Important**: All editing agents consult your project style guides:
+- `COMPOSITIONAL_STYLE_GUIDE.md` - Voice, POV, themes, dialogue style
+- `STRUCTURAL_STYLE_GUIDE.md` - Technical patterns, punctuation, formatting
+
+#### 5. Developmental Editor
+**File**: `developmental-editor.md`
+**Purpose**: Big-picture structural editing
+**Use for**:
+- Story structure analysis
+- Character arc evaluation
+- Pacing assessment
+- Theme integration review
+- POV and narrative voice consistency
+
+**Consults**: Both style guides for author's vision and narrative commitments
+
+**Example**:
+```
+@developmental-editor Analyze chapters 1-10 for:
+- Story structure alignment with three-act format
+- Character arc progress
+- Pacing appropriateness for Act I
+```
+
+---
+
+#### 6. Line Editor
+**File**: `line-editor.md`
+**Purpose**: Sentence-level prose refinement
+**Use for**:
+- Improving sentence clarity and rhythm
+- Strengthening word choice
+- Reducing wordiness
+- Enhancing dialogue
+- Fixing show-vs-tell balance
+
+**Consults**: Both style guides for voice, modifier limits, filter words, etc.
+
+**Example**:
+```
+@line-editor Polish this paragraph while maintaining my voice:
+[paste paragraph]
+```
+
+---
+
+#### 7. Copy Editor
+**File**: `copy-editor.md`
+**Purpose**: Technical correctness and style consistency
+**Use for**:
+- Grammar and spelling errors
+- Punctuation consistency
+- Style guide compliance
+- Typo detection
+- Consistency checks (names, formatting, numbers)
+
+**Consults**: Both style guides for punctuation style, formatting rules, technical preferences
+
+**Example**:
+```
+@copy-editor Check chapter 5 for:
+- Style guide compliance
+- Grammar errors
+- Consistency issues
+```
+
+## How to Use Subagents
+
+### In Claude Code
+
+**Option 1: @ Mention**
+```
+@character-developer [your request]
+```
+
+**Option 2: /agent command**
+```
+/agent character-developer
+```
+
+Then ask your question in the conversation.
+
+### Best Practices
+
+1. **Be Specific**: Give the agent context
+   ```
+   Good: @consistency-checker Check Sarah Chen's eye color across all chapters
+   Bad: @consistency-checker check my character
+   ```
+
+2. **Provide Context**: Share relevant files
+   ```
+   @character-developer Review characters/sarah-chen.yml and suggest
+   improvements to her character arc based on chapters/01-*.md
+   ```
+
+3. **Combine Agents**: Use different agents for different tasks
+   ```
+   # First, develop character
+   @character-developer Create profile for villain
+
+   # Then, check consistency
+   @consistency-checker Verify villain appears consistently in chapters 5,10,15
+   ```
+
+4. **Edit AI Output**: Always review and edit suggestions to match your voice
+
+## When to Use Which Agent
+
+**Starting a new novel?**
+→ `@novel-writing-assistant` for general guidance
+→ `@character-developer` for creating your cast
+
+**Mid-draft?**
+→ `@novel-writing-assistant` when stuck on a scene
+→ `@plot-analyzer` to check story structure
+→ `@consistency-checker` for quick consistency checks
+
+**Revising?**
+→ `@consistency-checker` for full manuscript review
+→ `@character-developer` for character arc review
+→ `@plot-analyzer` for pacing and structure analysis
+
+**Need creative ideas?**
+→ `@novel-writing-assistant` for brainstorming
+→ `@plot-analyzer` for plot development suggestions
+
+## Agent Philosophy
+
+All agents follow these principles:
+
+✅ **Suggest, don't dictate** - Provide options, not mandates
+✅ **Respect author voice** - Match existing style and tone
+✅ **Support discovery writing** - Embrace "pantsing" and exploration
+✅ **Encourage completion** - Progress over perfection
+✅ **Based on master novelist wisdom** - Grounded in craft principles
+
+## Customizing Agents
+
+These agents are project-level (in `.claude/agents/`), so they're specific to this novel writing project.
+
+**To modify an agent:**
+1. Edit the `.md` file
+2. Change the system prompt (below the YAML frontmatter)
+3. Save - changes apply immediately
+
+**To create a new agent:**
+1. Create `agent-name.md` in this directory
+2. Add YAML frontmatter with `name`, `description`, `tools`, `model`
+3. Write the system prompt
+
+See [Claude Code Agent Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents) for details.
+
+## Tools Available to Agents
+
+Each agent has access to specific tools defined in their YAML frontmatter:
+
+- **Read** - Read files from the project
+- **Write** - Create new files
+- **Edit** - Modify existing files
+- **Grep** - Search file contents
+- **Glob** - Find files by pattern
+
+The tools are restricted to what each agent needs for its specialized purpose.
+
+## Example Workflows
+
+### Character Development Workflow
+
+```bash
+# 1. Create character with AI assistance
+@character-developer Create a character: "mysterious government agent"
+
+# 2. Review and edit the generated YAML
+# Edit characters/agent-name.yml
+
+# 3. Sync to database
+/novel sync characters
+
+# 4. Use character in chapters
+# Write your scenes...
+
+# 5. Check consistency after writing several chapters
+@consistency-checker Check Agent Smith's consistency in chapters 5-12
+```
+
+### Writing Session Workflow
+
+```bash
+# 1. Start session
+/novel session start
+
+# 2. Get continuation suggestions
+@novel-writing-assistant Suggest 3 ways to continue chapter 8, scene 2
+[Current text: Sarah stared at the signal pattern...]
+
+# 3. Pick a direction and write
+# [Write in your editor]
+
+# 4. Check pacing
+@plot-analyzer Review the pacing of chapter 8
+
+# 5. End session
+/novel session end --words 734
+```
+
+### Revision Workflow
+
+```bash
+# 1. Character consistency check
+@character-developer Review all characters for consistency
+
+# 2. Plot structure analysis
+@plot-analyzer Analyze overall story structure (chapters 1-24)
+
+# 3. Detailed consistency check
+@consistency-checker Full manuscript consistency check
+
+# 4. Address issues
+# [Fix problems identified]
+
+# 5. Final verification
+@consistency-checker Re-check chapters I just revised
+```
+
+## Tips
+
+- **Don't use agents for every sentence** - Write first, use agents when stuck
+- **Edit everything** - AI suggestions are starting points, not final copy
+- **Combine with CLI tools** - Use `/novel` commands alongside agents
+- **Trust your instincts** - If an agent suggestion feels wrong, ignore it
+- **Experiment** - Try different agents for the same problem
+
+## Support
+
+For issues or questions about agents:
+- See main project documentation in `../README.md`
+- Read [USER_GUIDE.md](../../USER_GUIDE.md) for comprehensive guidance
+- Check [NOVEL_CRAFT_PRINCIPLES.md](../../NOVEL_CRAFT_PRINCIPLES.md) for philosophy
+
+---
+
+**Remember**: Agents are tools to support your writing, not replace it. The story belongs to you. 📖✍️