Architecture & Dispatch Flow

Every task flows through the same pipeline: gate → classify → execute → validate → done or escalate.

Escalation Rules

• Maximum 2 escalation hops per task
• Tier 0 → 1 → 2 → 3 (but can skip tiers based on classification)
• Tier 3 failure → NEEDS_USER status, bus message to GM
• Each tier has its own timeout; exceeding it counts as failure

Pre-Dispatch Filters

Classification

The classifier maps (role, task_type) → tier using dispatch/config/classification_table.json. Examples:

Tier 0 — Deterministic Scripts

Free, fast (<5s), no AI. Shell and Python scripts for file operations, status checks, and notifications.

Handler Scripts

Configuration

Tier 1 — Ollama (Local LLMs)

Free inference on local GPUs. Summarization, first-draft content, validation, triage.

Infrastructure

Models

Handlers

Configuration

Tier 2 — Browser AI (Playwright)

Subscription-tier AI via managed Chrome sessions on ubuntu1. Claude.ai, ChatGPT, and Perplexity for production-grade content work.

Browser Instances

Platform Routing

Each task type routes to the best AI platform:

Configuration

Tier 3 — Claude Code CLI

Pro Max plan Claude Code. Last resort for complex multi-step tasks, chunk repair, and orchestration. Rate-limited with a 5-hour rolling window.

Hosts (tried in order)

Rate Limiting

Matches Anthropic's real billing model — a 5-hour rolling window shared across all Claude surfaces.

Prompt Caching (Session Reuse)

Tier 3 supports session reuse via --resume to take advantage of Anthropic's prompt caching (~84% token savings on batch runs). Sessions expire after 4.5 minutes (with a 30-second margin before the 5-minute cache TTL).

Configuration

Infrastructure

Three physical machines on the local network. Services, ports, and roles for each host.

Host Inventory

Port Map

Network Diagram

Systemd Services

Roles

Nine specialized roles, each with their own prompt, expertise, authority boundaries, and bus inbox. All report to the General Manager (except GM, who is top-level).

Role Directory

Reporting Hierarchy

Interactive Mode

Roles are activated via talk.py or by saying their trigger phrase in a Claude Code session. When activated:

1. Role prompt loaded from dispatch/config/roles/{role}.md
2. Startup files read (series bibles, recovery docs, etc.)
3. Bus inbox checked for pending messages
4. Role identity adopted — it discusses, proposes, and pushes back
5. Handoffs create real bus messages to target roles

Role Rate Limits

Bus & Messaging

Filesystem-based inter-role messaging. Roles communicate by dropping JSON files into each other's inboxes. Optional HTTP API for remote clients.

How It Works

Directory Structure

bus/
  bus.py              # Core send/read functions
  api_server.py       # HTTP API (port 8484)
  email_bridge.py     # Email notifications
  templates/          # Email templates
  inboxes/
    {role}/
      new/            # Unprocessed messages
      processed/      # Archive

Message Format

{
  "id": "20260315T143000Z_sender_receiver",
  "from": "codexthewriter",
  "to": "reviewer",
  "type": "READY_FOR_HANDOFF",
  "subject": "Chapter 7 ready for QA",
  "summary": "Completed chunk production for SP04 ch7",
  "refs": ["series/shady_pines/books/04/production/..."],
  "dispatch": {
    "task_type": "manuscript_review",
    "quality_bar": "publication_ready"
  },
  "priority": "normal",
  "timestamp": "2026-03-15T14:30:00Z"
}

Message Types

Bus API (HTTP)

Auth: Bearer token via env BUS_API_TOKEN or secrets/bus_api_token.txt

Batch Queue

Queue up tasks before closing the laptop. The batch runner drains them sequentially on ubuntu — no races, no parallelism.

Architecture

Commands

# Submit a single task
python batch/batch_submit.py codexthewriter chunk_production \
    --subject "Write chapter 7" \
    --refs series/shady_pines/books/04/chunks/ch07.md

# Submit a range of chunks
python batch/batch_submit.py codexthewriter chunk_production \
    --chunks 7-20 --series shady_pines --book 04

# Check queue status
python batch/batch_submit.py --status

# Run queue (one-shot)
python batch/batch_runner.py

# Run as daemon (poll every 60s)
python batch/batch_runner.py --daemon 60

# Monitor health (cron, every 15 min)
python batch/batch_monitor.py --notify

Task States

Safety Features

• File locking — fcntl.flock on queue.lock prevents concurrent access
• Sequential draining — one task at a time, never parallel
• Rate-limit backoff — returns task to pending and sleeps for wait_seconds
• Auth expiry detection — pauses queue and sends CRITICAL to GM
• Stuck task detection — monitor flags tasks running >45 minutes
• Failure rate alerting — monitor flags >50% failure rate

Systemd Service

# Install on ubuntu
bash batch/systemd/install.sh

# Manage
systemctl --user start batch-runner
systemctl --user stop batch-runner
systemctl --user status batch-runner
journalctl --user -u batch-runner -f

Ads System (Amazon Sponsored Products)

34-tool system for Amazon Ads API. Strategy vocabulary, campaign lifecycle, bid optimization, and automated pulse analysis.

Strategy Vocabulary

Per-Series Goals

Safety Guards

Core Modules

Tool Complexity Tiers

Quick Commands

# CLI
python -m ads.tool campaign_status
python -m ads.tool series_strategy --args '{"series_name": "Shady Pines"}'

# HTTP
curl -X POST http://localhost:8484/ads/tool \
  -d '{"tool": "campaign_status"}'

# Python
from ads.tool import AdsTool
AdsTool().call("campaign_status", {})

Scheduling

Cron-based task scheduling. Each scheduled task dispatches through the standard pipeline.

How It Works

# Cron calls the runner script
*/30 * * * * /path/to/scheduling/runner.sh generalmanager_inbox_sweep

# Runner parses schedule.json, calls dispatcher.py
# Dispatcher handles classification, execution, validation

Commands

# Run a specific scheduled task
./scheduling/runner.sh generalmanager_inbox_sweep

# Check which schedules are due
./scheduling/runner.sh --check-schedule

# Generate crontab entries from schedule.json
./scheduling/runner.sh --generate-crontab

# Install the generated crontab
./scheduling/runner.sh --generate-crontab | crontab -

Configuration

Schedules are defined in scheduling/schedule.json. Each entry specifies role, task_type, cron expression, and enabled state. Logs go to logs/cron/.

Key Scheduled Tasks

Monitoring

Health dashboard and cost tracker for understanding system state and tier usage.

Health Dashboard

# Today's health
python monitoring/health_dashboard.py

# Specific date
python monitoring/health_dashboard.py --date 2026-03-10

# Raw JSON output
python monitoring/health_dashboard.py --json

Reports: per-tier task counts, per-role task counts, failure/escalation counts, inbox status, infrastructure health.

Cost Tracker

# Last 7 days
python monitoring/cost_tracker.py

# Last 30 days
python monitoring/cost_tracker.py --days 30

# Raw JSON
python monitoring/cost_tracker.py --json

Tracks tier usage and verifies lower-tier adoption. Tier labels: 0 = Scripts (free), 1 = Ollama (free), 2 = Browser AI (subscription), 3 = Claude Code (Pro Max quota).

Batch Monitor

# Check batch queue health (run from cron every 15 min)
python batch/batch_monitor.py --notify

Detects: paused queue, stuck running tasks (>45 min), high failure rate (>50%), stale pending tasks (>4h). Posts BLOCKER to GM inbox when unhealthy.

Log Locations

Commands Quick Reference

Every command you need, organized by task.

Dispatching

# Dispatch a task
python dispatch/dispatcher.py --role generalmanager --task inbox_sweep

# Process a role's inbox
python dispatch/dispatcher.py --role codexthewriter --inbox

# Dispatch a specific message
python dispatch/dispatcher.py --role reviewer --message path/to/message.json

# Dry run (classify only, don't execute)
python dispatch/dispatcher.py --role adsmanager --task strategy_review --dry-run

Interactive Roles

# Start a role conversation
python talk.py codexthewriter
python talk.py adsmanager --model qwen3-coder:30b

# Ask a one-off question
python ask.py reviewer "Is the QA report for SP04 ready?"

Batch Queue

# Submit task
python batch/batch_submit.py codexthewriter chunk_production \
    --subject "Write chapter 7" \
    --refs series/shady_pines/books/04/chunks/ch07.md

# Submit chunk range
python batch/batch_submit.py codexthewriter chunk_production \
    --chunks 7-20 --series shady_pines --book 04

# Import from JSON file
python batch/batch_submit.py --import tasks.json

# Queue status
python batch/batch_submit.py --status

# Run queue (one-shot or daemon)
python batch/batch_runner.py
python batch/batch_runner.py --daemon 60

Monitoring

python monitoring/health_dashboard.py
python monitoring/health_dashboard.py --date 2026-03-10 --json
python monitoring/cost_tracker.py --days 30
python batch/batch_monitor.py --notify

Scheduling

./scheduling/runner.sh generalmanager_inbox_sweep
./scheduling/runner.sh --check-schedule
./scheduling/runner.sh --generate-crontab | crontab -

Ads

python -m ads.tool campaign_status
python -m ads.tool series_strategy --args '{"series_name": "Shady Pines"}'
python -m ads.tool pull_search_term_report

Infrastructure

# Install batch runner systemd service
bash batch/systemd/install.sh

# Manage batch runner
systemctl --user start batch-runner
systemctl --user status batch-runner
journalctl --user -u batch-runner -f

Entry Points

The main executable files and what they do.

Root-Level Scripts

Series & Book Data

All book data lives in series/. Each series has its own directory with manuscripts, production files, covers, and QA reports.

Active Series

Per-Series File Structure

series/{name}/
  SERIES_BIBLE.md           # Genre, timeline, character bibles
  metadata.json             # Publication dates, ISBNs
  MASTER_TIMELINE.md        # Character/event chronology
  latest/                   # Latest master manuscripts
    01_{title}__manuscript.md
    02_{title}__manuscript.md
  books/
    {num}_{title}/
      {title}.md            # Full manuscript
      production/           # Production files
      output/               # Chunk breakdown (chunk_01.md, ...)
      cover/                # COVER_BRIEF.md, images
      QA_REPORT.md
  archive/                  # Historical versions

QA System

25-pass QA system (from V3) at qa system/. Latest version: manuscript_qa_system_v7/. Covers continuity, truth checking, fact verification, beat analysis, word count gates, and structural validation.

Templates

Production templates at templates/ — BEAT_WRITING_GUIDE, CHUNK_HANDOFF_TEMPLATE, PRODUCTION_TEMPLATE, COVER_TEMPLATE, MARKETING_BIBLE_TEMPLATE, MYSTERY_DESIGN_TEMPLATE, KDP_A_PLUS_TEMPLATE, etc.

Scripts & Tools

100+ scripts in scripts/. Key utilities organized by function.

Ads Management

Book Production

KDP & Publishing

Browser Automation

QA & Validation

Git Operations

Other Utilities

Directory Map

Complete directory layout of AutoBook V4.

autobookv4/
│
├── CLAUDE.md                    # Project instructions (V4 dispatch)
├── README.md                    # Quick-start guide
├── V4_RECOVERY.md               # Recovery state for roles
├── talk.py                      # Interactive role conversations
├── ask.py                       # One-off role questions
│
├── dispatch/                    # Central dispatch engine
│   ├── dispatcher.py            # Main dispatcher
│   ├── classifier.py            # (role, task_type) → tier
│   ├── validator.py             # Output quality validation
│   ├── filters/                 # Pre-dispatch gates
│   │   ├── deduplicator.py
│   │   ├── substrate_checker.py
│   │   └── dependency_checker.py
│   └── config/                  # All configuration
│       ├── tier_config.json     # Tier definitions
│       ├── classification_table.json  # Task → tier mapping
│       ├── rate_limits.json     # Per-role rate limits
│       └── roles/               # 9 role prompt files
│
├── tiers/
│   ├── tier0/                   # Deterministic scripts
│   ├── tier1/                   # Ollama client + handlers
│   ├── tier2/                   # Browser AI (Playwright)
│   └── tier3/                   # Claude Code dispatch
│       └── claude_code_dispatch.py
│
├── bus/                         # Inter-role messaging
│   ├── bus.py                   # Core functions
│   ├── api_server.py            # HTTP API (:8484)
│   ├── email_bridge.py          # Email notifications
│   ├── templates/               # Email templates
│   └── inboxes/                 # Per-role message queues
│       └── {role}/new/
│
├── batch/                       # Autonomous task queue
│   ├── batch_submit.py          # Queue tasks
│   ├── batch_runner.py          # Process queue
│   ├── batch_monitor.py         # Health monitoring
│   └── systemd/                 # Service files
│
├── ads/                         # Amazon Ads (34 tools)
│   ├── tool.py                  # Unified dispatcher
│   ├── config.json              # Campaign config
│   ├── strategy.md              # Decision framework
│   ├── client.py                # API wrapper
│   ├── scanner.py               # Analysis
│   ├── decider.py               # Action classification
│   ├── applier.py               # Action execution
│   └── pulse.py                 # Periodic analysis
│
├── scheduling/                  # Cron scheduling
│   ├── runner.sh                # Cron entry point
│   └── schedule.json            # Schedule definitions
│
├── monitoring/                  # Health & cost tracking
│   ├── health_dashboard.py
│   └── cost_tracker.py
│
├── series/                      # All book data (12+ series)
│   └── {series_name}/
│       ├── SERIES_BIBLE.md
│       ├── latest/
│       └── books/
│
├── templates/                   # Production templates
├── qa system/                   # 25-pass QA system
├── scripts/                     # 100+ utility scripts
├── tracking/                    # Coordination state
├── models/                      # Ollama model definitions
├── tools/                       # Integration tools
├── logs/                        # All logs
│   ├── dispatch/
│   ├── tier3/
│   ├── batch/
│   └── cron/
└── docs/                        # This documentation