1. Using pandoc to extract raw Markdown from EPUB
2. Creating a structured project directory
3. Planning and executing AI-driven formatting fixes
4. Producing chapter-by-chapter formatted output
5. Generating merged book file with Table of Contents

python3 scripts/convert_book.py "/path/to/book.epub"

1. Verifies EPUB file exists
2. Creates project structure:

   • books/book-name/

     - Main directory

   • books/book-name/raw/

     - Pandoc output

   • books/book-name/chapters/

     - Formatted chapters

   • books/book-name/images/

     - Extracted images
3. Runs pandoc to extract Markdown
4. Copies formatting standards to project directory

books/book-name/raw/book-parsed.md

python3 books/book-name/analyze_structure.py books/book-name

• Extracts all headers with line numbers
• Detects formatting issues by sampling
• Suggests chapter boundaries
• Creates

  STRUCTURE_ANALYSIS.md

  report (~5-10 KB instead of 35k+ lines)

Task(
  subagent_type="general",
  description="Create chapter map and formatting plan",
  prompt="""Create CHAPTER_MAP.md and FORMATTING_PLAN.md:

1. Read books/book-name/STRUCTURE_ANALYSIS.md (concise report with headers and issues)
2. Read books/book-name/references/chapter-map-template.md for format
3. Read books/book-name/references/formatting-plan-template.md for format
4. Create books/book-name/CHAPTER_MAP.md:
   - Use suggested chapter boundaries from analysis
   - Verify line ranges make sense
   - Create proper slugged filenames
5. Create books/book-name/FORMATTING_PLAN.md:
   - Document issues found in analysis
   - Add severity and priority
   - Note book-specific patterns
6. Update books/book-name/progress.md to mark Phase 2 complete

Return: Summary of chapters found and major issues identified."""
)

CHAPTER_MAP.md

FORMATTING_PLAN.md

progress.md

1. Read and follow ALL steps in books/book-name/references/chapter-workflow.md
2. Apply formatting rules from books/book-name/references/formatting-standards.md
3. Use books/book-name/CHAPTER_MAP.md to find line ranges for Chapter 1
4. Read books/book-name/FORMATTING_PLAN.md for known issues to watch for

• Read references/formatting-standards.md
• Read CHAPTER_MAP.md for your chapter's line ranges
• Read FORMATTING_PLAN.md for known issues

• Extract Chapter 1 from raw/book-parsed.md using line ranges

• Headers using bold instead of #
• Shattered code blocks
• Split paragraphs
• Missing code language identifiers
• Emphasis artifacts [word]
• Corrupted footnotes
• Missing image alt text
• Broken links

• Follow the three-pass approach in chapter-workflow.md:
  • First pass: Structure (headers, code blocks)
  • Second pass: Content (paragraphs, emphasis)
  • Third pass: Details (footnotes, images, links)

• Write to books/book-name/chapters/chapter-01-title.md
• Use structure from chapter-workflow.md

• Update books/book-name/progress.md with completion status
• Document fixes applied

• All headers use proper # syntax
• All code blocks have language identifiers
• No shattered code blocks remain
• Text flows naturally without mid-sentence breaks
• All footnotes have [^N] format with definitions
• Images have descriptive alt text

**Important**: 
- Launch subagents in parallel batches (3-5 at a time) for efficiency
- Each subagent must read chapter-workflow.md and formatting-standards.md
- Follow the systematic workflow to ensure consistent quality

**Output**: Formatted chapters in `books/book-name/chapters/`

merge_book.py

python3 books/book-name/merge_book.py books/book-name

1. Read

   CHAPTER_MAP.md

   for chapter order
2. Load all formatted chapters from

   chapters/

3. Extract headers for Table of Contents
4. Fix image paths (relative to final location)
5. Combine all chapters in order
6. Generate comprehensive TOC
7. Output to

   books/book-name-book.md

books/book-name-book.md

1. Read chapter-workflow.md first - Contains the complete step-by-step process
2. Read formatting-standards.md - Contains all formatting rules (678 lines)
3. Follow the workflow systematically - Don't skip steps
4. Use the three-pass approach:
   • First pass: Fix structure (headers, code blocks)
   • Second pass: Fix content (paragraphs, emphasis)
   • Third pass: Fix details (footnotes, images, links)
5. Complete the quality checklist - Verify all items before finishing

• Ensures consistent quality across all chapters
• Prevents common mistakes (skipped issues, inconsistent style)
• Proven process from Clean Code Collection (35k+ lines)
• Each chapter is only formatted once - must be thorough

1. Keep main context clean: Book content is large and pollutes context
2. Enable parallelization: Format multiple chapters simultaneously
3. Isolate formatting work: Each chapter gets fresh context
4. Avoid token limits: Raw content can exceed context windows

subagent_type="general"

• EPUB extracted
• Project structure created

• Chapter map created (15 chapters identified)
• Formatting plan documented

• Front Matter
• Chapter 1: Introduction
• Chapter 2: Getting Started
• Chapter 3: Advanced Topics
• Chapter 4: Best Practices
• Chapter 5: Performance
• ...

• Merge script created
• Final book generated

Update after each subagent completes.

• Headers: Use proper

  #

  syntax, not bold text
• Code Blocks: Include language identifiers, merge shattered blocks
• Text Flow: Join split sentences into natural paragraphs
• Emphasis: Use

  *italic*

  and

  **bold**

  , not

  [brackets]

• Footnotes: Standard

  [^1]

  format with definitions
• Images: Descriptive alt text, not generic filenames
• Links: Clean anchors, no PDF conversion artifacts

"Convert this EPUB to Markdown: /Users/john/Downloads/Effective.Java.3rd.Edition.epub"

1. Run conversion script to extract content
2. Analyze structure and create chapter map
3. Format each chapter using AI subagents
4. Merge into final book with TOC
5. Provide user with

   books/effective-java-final.md

• convert_book.py: Main conversion script (Phase 1) - Extracts EPUB and sets up project
• analyze_structure.py: Structure analyzer (Phase 2) - Extracts headers and detects issues efficiently
• merge_book.py: Reusable merge script (Phase 4) - Combines all chapters into final book

• formatting-standards.md: Complete formatting rules (loaded as needed during formatting)
• chapter-workflow.md: Detailed chapter formatting workflow (loaded as needed)
• progress-template.md: Template for progress tracking file
• chapter-map-template.md: Template for chapter mapping
• formatting-plan-template.md: Template for formatting issue documentation

• High Quality Focus: Manual AI-driven formatting ensures prose flows naturally
• No Automated Scripts: Formatting requires human-like judgment for line joining
• Preserve Content: Never alter meaning or remove content
• Code Accuracy: Ensure code blocks are syntactically complete