NovelCraft

Fully autonomous book authoring — from idea to finished PDF/EPUB.

⚠️ Security Notice: Review SECURITY.md before running, especially for first-time use. Use step-by-step mode initially. Images are disabled by default.

Workflow (Autonomous)

Detailed Chapter Workflow (v3.2)

CRITICAL: Chapters run strictly sequential with proper tracking.

For Each Chapter:

┌─────────────────────────────────────────────────────────────────┐
│  STEP 1: Check Manifest                                         │
│  Read project-manifest.md → chapter_XX.status                   │
└─────────────────┬───────────────────────────────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
pending      writing       approved
    │             │             │
    │             │             └─→ SKIP to next chapter
    │             │
    │             └─→ Check subagent status
    │                   IF running: wait
    │                   IF not: resume/restart decision
    │
    └─→ STEP 2: Acquire Lock
        │
        ▼
    STEP 3: Spawn Subagent
        │
        ├─ Label: NovelCraft-Chapter-XX
        ├─ Mode: run
        ├─ Timeout: 3600s (1 hour)
        ├─ Pre-check: Kill existing Chapter-XX subagents
        │
        ▼
    STEP 4: Update Manifest
        │
        ├─ status: "writing"
        ├─ subagent.session_key: [key]
        ├─ subagent.run_id: [id]
        ├─ subagent.started_at: [timestamp]
        └─ subagent.expected_duration: "1800s"
        │
        ▼
    STEP 5: Wait (Push-Based)
        │
        ├─ DO NOT poll sessions_list
        ├─ DO NOT use sessions_yield
        ├─ Wait for subagent completion event
        │
        ▼
    STEP 6: Handle Result
        │
        ├─ SUCCESS: Validate output → Go to Review
        ├─ TIMEOUT: Check partial draft → Resume or Retry
        └─ ERROR: Log → Retry (max 3)

Subagent Pre-Check (CRITICAL)

Before spawning ANY chapter subagent:

// 1. List active subagents
const active = await subagents({ action: "list" });

// 2. Find existing for this chapter
const existing = active.find(s => 
  s.label === `NovelCraft-Chapter-${chapterNum}`
);

// 3. Kill if exists (prevent duplicates)
if (existing) {
  await subagents({ 
    action: "kill", 
    target: existing.sessionKey 
  });
}

// 4. Verify killed
const verify = await subagents({ action: "list" });
const stillExists = verify.find(s => 
  s.label === `NovelCraft-Chapter-${chapterNum}`
);

if (stillExists) {
  throw new Error(`Failed to kill existing Chapter-${chapterNum}`);
}

// 5. NOW spawn new
await sessions_spawn({
  label: `NovelCraft-Chapter-${chapterNum}`,
  mode: "run",
  runtime: "subagent",
  task: "...",
  runTimeoutSeconds: 3600 // 1 hour minimum
});

Checkpoint System (Progress Tracking)

Subagent MUST write progress header:

<!-- chapter_XX_draft.md -->
<!--
STATUS: writing
WORDS: 650
TARGET: 1000
STARTED: 2026-04-06T19:14:00Z
LAST_UPDATE: 2026-04-06T19:20:00Z
ETA: 10 minutes
-->

# Kapitel XX: Titel

[Content...]

Main Session can check progress:

// Read draft and parse progress
const draft = await read({ file: 'chapter_XX_draft.md' });
const progress = parseProgressHeader(draft);

console.log(`${progress.words}/${progress.target} words`);
console.log(`ETA: ${progress.eta}`);

Timeout Recovery

On subagent timeout:

// 1. Check if partial draft exists
const draft = await read({ file: 'chapter_XX_draft.md' });
const progress = parseProgressHeader(draft);

// 2. Decide action
if (progress.words > 0) {
  // Partial progress → Resume
  await sessions_spawn({
    label: `NovelCraft-Chapter-${chapterNum}-Resume`,
    mode: "run",
    task: `Resume Chapter ${chapterNum} from ${progress.words} words...`,
    runTimeoutSeconds: 3600
  });
} else {
  // No progress → Retry
  const retries = manifest.chapters[chapterNum].retries || 0;
  if (retries < 3) {
    await sessions_spawn({
      label: `NovelCraft-Chapter-${chapterNum}-Retry-${retries + 1}`,
      mode: "run",
      task: `Rewrite Chapter ${chapterNum} (attempt ${retries + 1})...`,
      runTimeoutSeconds: 3600
    });
  } else {
    // Max retries reached → Manual intervention
    await message({
      action: "send",
      message: `Chapter ${chapterNum} failed after 3 retries. Manual review needed.`
    });
  }
}

Manifest Status Tracking

Extended chapter entry:

chapters:
  '05':
    status: 'writing'  # pending | writing | reviewing | approved | failed
    subagent:
      session_key: 'agent:opencode:subagent:...'
      run_id: '...'
      started_at: '2026-04-06T19:14:00Z'
      expected_duration: '1800s'
    draft_file: '01-drafts/chapter_05_draft.md'
    review_file: null  # Set after review
    approved_file: '02-chapters/chapter_05.md'
    word_count: 1188
    score: 8.8
    retries: 0
    error: null  # Set if failed

Important Rules

• Autonomous = no intermediate questions
• Never write chapters in parallel — Strictly sequential with tracking
• Kill existing subagents before spawning new ones
• Never block on images — note time, continue
• Publish immediately without images, visuals later
• Max 3 retries per chapter, then manual intervention

Requirements

Before running NovelCraft, ensure you have:

Required Binaries (for PDF/EPUB)

• pandoc — Document conversion
• xelatex (optional, for enhanced PDF)

Check with: which pandoc && which xelatex

Disk Space

• Estimated 5-15 MB per novel project
• Drafts, reviews, revisions, and final outputs

Security

• ⚠️ Review SECURITY.md before first use
• Use step-by-step mode for testing
• Images are disabled by default
• Configure image providers carefully (network calls)

Configuration Schema v3.0

NovelCraft uses a 3-level configuration hierarchy with clear override rules:

Rule: Higher level wins. Only defined fields override lower levels.

Module Configs (Level 2)

Create in ~/.openclaw/workspace/novelcraft/config/:

See: workspace/config/CONFIG-SCHEMA.md for complete schema documentation.

Project Manifest (Level 3)

Path: workspace/Books/projects/{PROJECT}/project-manifest.md

Central status file with:

• Module status tracking (done/pending/rewriting)
• Revision tracking per chapter (status, score, revisions)
• Book-specific overrides (title, chapter_count, has_prolog, etc.)

See: workspace/config/PROJECT-MANIFEST-TEMPLATE.md for template.

Modules

Module Templates

Each module has a template that standardizes subagent calls:

Review Workflow with Scoring

Automatic Decision Based on Score

Scoring Criteria

Revision Rules

• Max 3 revisions per chapter
• After 3 revisions → forced rewrite required
• Review saved as chapter_XX_review.md
• Revision follows the revision template

Error Handling & Recovery (v3.2)

Common Failure Scenarios

Subagent Timeout Recovery

Detection:

// Subagent status: timed_out
{
  status: "timed_out",
  runtime: "6m26s",
  sessionKey: "..."
}

Recovery Steps:

async function handleTimeout(chapterNum) {
  // 1. Check for partial draft
  const draftPath = `01-drafts/chapter_${chapterNum}_draft.md`;
  const draftExists = await fileExists(draftPath);
  
  if (!draftExists) {
    // No draft at all → Full retry
    return await retryChapter(chapterNum, 'no_draft');
  }
  
  // 2. Parse progress from draft header
  const draft = await read({ file: draftPath });
  const progress = parseProgressHeader(draft);
  
  // 3. Decide: Resume vs Retry
  if (progress.words > 0) {
    // Has progress → Resume
    console.log(`Resuming Chapter ${chapterNum} at ${progress.words} words`);
    return await resumeChapter(chapterNum, progress.words);
  } else {
    // No progress → Retry
    console.log(`Retrying Chapter ${chapterNum} from start`);
    return await retryChapter(chapterNum, 'no_progress');
  }
}

async function retryChapter(chapterNum, reason) {
  const manifest = await readManifest();
  const retries = manifest.chapters[chapterNum].retries || 0;
  
  if (retries >= 3) {
    // Max retries → Manual intervention
    await notifyUser(`Chapter ${chapterNum} failed after 3 retries. Reason: ${reason}`);
    return { action: 'manual_intervention', reason };
  }
  
  // Update manifest
  manifest.chapters[chapterNum].retries = retries + 1;
  manifest.chapters[chapterNum].error = reason;
  await saveManifest(manifest);
  
  // Spawn retry subagent
  return await sessions_spawn({
    label: `NovelCraft-Chapter-${chapterNum}-Retry-${retries + 1}`,
    mode: "run",
    runtime: "subagent",
    task: `Rewrite Chapter ${chapterNum} (attempt ${retries + 2}). Previous: ${reason}`,
    runTimeoutSeconds: 3600
  });
}

Duplicate Subagent Prevention

Problem: Multiple subagents for same chapter.

Solution:

async function spawnChapterSafely(chapterNum, task) {
  // 1. List ALL active subagents
  const active = await subagents({ action: "list" });
  
  // 2. Find any for this chapter (fuzzy match)
  const existing = active.filter(s => 
    s.label.includes(`Chapter-${chapterNum}`)
  );
  
  // 3. Kill all existing
  for (const sub of existing) {
    console.log(`Killing existing: ${sub.label} (${sub.sessionKey})`);
    await subagents({ 
      action: "kill", 
      target: sub.sessionKey 
    });
  }
  
  // 4. Wait and verify
  await sleep(1000);
  const verify = await subagents({ action: "list" });
  const stillRunning = verify.filter(s => 
    s.label.includes(`Chapter-${chapterNum}`)
  );
  
  if (stillRunning.length > 0) {
    throw new Error(`Failed to kill ${stillRunning.length} subagents`);
  }
  
  // 5. Safe to spawn
  return await sessions_spawn({
    label: `NovelCraft-Chapter-${chapterNum}`,
    mode: "run",
    runtime: "subagent",
    task,
    runTimeoutSeconds: 3600
  });
}

Wrong Output Validation

Problem: Subagent returns wrong chapter or incomplete data.

Validation:

async function validateChapterOutput(chapterNum, content) {
  const errors = [];
  
  // 1. Check chapter number in content
  const chapterMatch = content.match(/Kapitel\s+(\d+)/i);
  if (chapterMatch && parseInt(chapterMatch[1]) !== chapterNum) {
    errors.push(`Wrong chapter number: expected ${chapterNum}, got ${chapterMatch[1]}`);
  }
  
  // 2. Check word count
  const words = countWords(content);
  const config = await readModuleConfig('chapters');
  if (words < config.min_words || words > config.max_words) {
    errors.push(`Word count ${words} outside range ${config.min_words}-${config.max_words}`);
  }
  
  // 3. Check for required content
  if (!content.includes('#')) {
    errors.push('Missing chapter title (H1)');
  }
  
  // 4. Return result
  return {
    valid: errors.length === 0,
    errors,
    word_count: words
  };
}

// Usage
const result = await validateChapterOutput(5, content);
if (!result.valid) {
  console.error('Validation failed:', result.errors);
  await retryChapter(5, 'validation_failed');
}

Manifest Recovery

Problem: Manifest out of sync with filesystem.

Reconstruction:

async function rebuildManifest(projectPath) {
  const manifest = {
    chapters: {}
  };
  
  // Scan 01-drafts/
  const drafts = await listFiles(`${projectPath}/01-drafts/chapter_*.md`);
  for (const draft of drafts) {
    const num = extractChapterNumber(draft);
    manifest.chapters[num] = manifest.chapters[num] || {};
    manifest.chapters[num].draft_file = draft;
    manifest.chapters[num].status = 'draft';
  }
  
  // Scan 02-chapters/
  const approved = await listFiles(`${projectPath}/02-chapters/chapter_*.md`);
  for (const chapter of approved) {
    const num = extractChapterNumber(chapter);
    manifest.chapters[num] = manifest.chapters[num] || {};
    manifest.chapters[num].approved_file = chapter;
    manifest.chapters[num].status = 'approved';
  }
  
  // Scan reviews
  const reviews = await listFiles(`${projectPath}/01-drafts/chapter_*_review.md`);
  for (const review of reviews) {
    const num = extractChapterNumber(review);
    if (manifest.chapters[num]) {
      manifest.chapters[num].review_file = review;
      if (manifest.chapters[num].status === 'draft') {
        manifest.chapters[num].status = 'reviewing';
      }
    }
  }
  
  await saveManifest(manifest);
  return manifest;
}

Best Practices Summary

1. Always pre-check for existing subagents
2. Always use extended timeout (3600s minimum)
3. Always validate subagent output
4. Always update manifest before and after subagent
5. Always implement retry with max 3 attempts
6. Always notify user on unrecoverable errors

Directory Structure

IMPORTANT: All project data (Books) lives in the workspace, not the skill folder!

Workspace (Project Data)

~/.openclaw/workspace/novelcraft/          ← Workspace (localized)
├── config/
│   ├── CONFIG-SCHEMA.md                  # Schema v3.0 documentation
│   ├── PROJECT-MANIFEST-TEMPLATE.md      # Project template
│   ├── module-concept.md                 # Module: Concept
│   ├── module-writer-extras.md           # Module: Prolog/Epilog
│   ├── module-images.md                  # Module: Images
│   ├── module-chapters.md                # Module: Chapters
│   └── module-publication.md             # Module: Publication
│
└── Books/projects/novel-[TITLE]/
    ├── project-manifest.md                # Central project manifest
    ├── 00-concept/                        # Concept, characters, worldbuilding
    ├── 01-drafts/                         # WIP chapters, reviews, revisions
    │   ├── chapter_01_draft.md
    │   ├── chapter_01_review.md
    │   └── chapter_01_review_v2.md
    ├── 02-chapters/                       # ✅ APPROVED final chapters
    │   ├── chapter_01.md
    │   └── chapter_02.md
    └── 03-final/                          # PDF, EPUB

~/.openclaw/skills/novelcraft/             ← Skill folder (read-only)
├── SKILL.md                               # This file
├── README.md                              # Quick start
├── CHANGELOG.md                           # Version history
├── CONTRIBUTING.md                        # Contribution guidelines
├── templates/                             # Module templates
│   ├── module-concept-template.md
│   ├── module-writer-extras-template.md
│   ├── module-images-template.md
│   ├── module-chapters-template.md
│   ├── module-review-template.md
│   ├── module-revision-template.md
│   └── module-publication-template.md
└── references/
    └── CONFIG.md                          # Config documentation

Workflow:

1. Drafts in 01-drafts/
2. Review → Revision if needed
3. On APPROVED → Copy to 02-chapters/
4. Publication reads only from 02-chapters/

Books Path: ~/.openclaw/workspace/novelcraft/Books/ (always load from workspace)

Modes

Images (Optional)

Default: DISABLED — Images must be explicitly enabled in module-images.md.

Provider Options

⚠️ Warning: Using api provider sends book content descriptions to external services. Review your provider's privacy policy.

Workflow

• Never block — start generation, proceed to chapters
• After completion: Create separate version with images

See references/CONFIG.md for detailed provider configuration.

Dashboard

Current: No dashboard available. NovelCraft works via command line.

Planned: Web-based dashboard for project monitoring and control.

• Live progress for active projects
• Chapter detail view with scores
• Config editor in browser

See ROADMAP.md for details.

Audio (Planned)

Audiobook generation from completed chapters:

• TTS integration (ElevenLabs, OpenAI, Local)
• Character voices for dialogue
• MP3/WAV export per chapter

See ROADMAP.md for details.

References

Target Audience Profiles (v3.2)

NEW: Select a profile to auto-configure all modules for your intended readers!

Available Profiles

What Auto-Configures?

Usage

Setup: "Start NovelCraft Setup"
→ "Select target audience profile:"
   [1] early-readers (6-8)
   [2] middle-grade (8-12)
   [3] young-adult (12-16)
   [4] new-adult (16-25)
   [5] adult (25+)
   [6] senior (60+)
   [7] custom (manual)
→ User selects: 1
→ All modules auto-configure for 6-8 year olds!

Override Anytime

Keep profile, change one value:

"Change chapter target to 1500 words"
"Enable chapter images"

See setup.md for detailed profile specifications.

Image Configuration (v3.1)

Images are disabled by default (provider: none). When enabled, configure categories:

Image Categories

Critical Image Rules

Prompt Examples

Cover:

Children's book cover illustration, four friendly colorful monsters standing in front of a school building, whimsical and playful style, soft pastel colors, storybook art style, magical atmosphere, no text, no letters, no words, no typography, no writing, no watermark, no signature

Character:

Children's book character portrait, young girl 7 years old, brown hair in pigtails, bright curious eyes, friendly smile, soft pastel colors, storybook illustration style, white background, no text, no letters, no words, no typography, no writing, no watermark, no signature

Setting (NO people):

Children's book illustration, cozy elementary school classroom interior, colorful desks and chairs neatly arranged, sunlight streaming through windows, empty room no children no teacher, warm atmosphere, storybook art style, no text, no letters, no words, no typography, no writing, no people, no characters, no humans, no monsters, no watermark, no signature

Chapter Image:

Children's book illustration, scene from chapter: monsters hiding in school closet, surprised expressions, playful mood, colorful and whimsical, storybook art style, no text, no letters, no words, no typography, no writing, no watermark, no signature

See setup.md for complete prompt guidelines and configuration details.

Quick Start

Project Management (New)

Setup & Configuration

Help & Info

Alternative Syntax

NovelCraft --project              # Create project
NovelCraft --project-list         # List projects
NovelCraft --setup
NovelCraft --setup --module=images
NovelCraft --reconfigure
NovelCraft --help
NovelCraft --status

Full Documentation

Version

Current: 3.2.0 — Target Audience Profiles & Enhanced Image Configuration

Maintained by: Felix (AI) with Ronny (User) 🧠💡