harness-book-best-practice

# Harness Book Best Practice

Use this skill for changes inside this repository's book system.

## Scope

This repo has two books:

- `book1-claude-code/`
- `book2-comparing/`

Shared build logic lives in:

- `tools/book-kit/book_meta.py`
- `tools/book-kit/build_pandoc_book.py`
- `tools/book-kit/build_print_html.py`
- `tools/book-kit/export_book_pdf.py`
- `tools/book-kit/export_pdf.py`

Prefer changing shared behavior in `tools/book-kit/` rather than reintroducing per-book one-off scripts.

## Release Metadata

Treat book release metadata as structured config, not manuscript text.

- Store the stable public-facing field `release_date` in `book.json`.
- Prefer deriving `revision` automatically from git in shared tooling instead of maintaining a manual version string.
- Render release metadata through shared export templates, not by manually inserting it into `README.md`, chapter files, or cover artwork.
- Preferred placement is the title page / colophon area for PDF and the cover section for print HTML.
- Do not default to volatile build timestamps in final deliverables. Prefer a stable release date so regenerated exports remain reproducible.
- Use `--draft` for internal draft exports when you explicitly want today's date plus git revision in the rendered output.

## Directory Rules

- `assets/` is for source assets only: cover SVG/PDF, hand-maintained source files, reusable static inputs.
- `diagrams/` is for diagram sources and committed generated images used by the books. In this repo, `.puml` is the source of truth and `.png` is the embedded artifact.
- `exported/` is for final deliverables only: `*.pdf`, `*-print.html`.
- `_book/` is a build/cache directory and may be deleted.
- `_debug/` and `_texdebug/` are disposable debug directories and may be deleted.

Do not move exported PDFs into `assets/`. That mixes source inputs with build outputs and makes cleanup/error analysis harder.

## Diagrams (PUML)

`.puml` is the source of truth in `diagrams/`. The committed `.png` next to it is the artifact embedded in the book. Regenerate `.png` with `python3 tools/book-kit/export_pdf.py <book> --clean-generated` (this calls `plantuml -tpng`); never hand-edit a `.png`.

### Pick The Diagram Type By What You Want To Show

These books are about runtime behavior, so default to diagrams that surface behavior, not static structure:

- State diagram (`state`, `[*]`, `<<choice>>`) — for lifecycles, "where state lives," and stateful loops (query loop, thread, budget thresholds).
- Activity diagram (`start`/`stop`, `if/then/else`, `fork`/`fork again`) — for decision ladders and governance flows (recovery paths, compact rebuild, tool batch ordering).
- Sequence diagram (`actor`, `participant`, `->`) — for temporal interactions between distinct actors (coordinator/worker, user/runtime/worker).
- Component / box-and-arrow — only when structure itself is the point. Do not use it as a default layout for behavioral content.

If a diagram does not show a loop, a decision branch, a transition, or a temporal exchange, reconsider whether it is earning its page.

### Comparison Diagrams (book2)

When contrasting Claude Code vs Codex on a single dimension:

- Use `top to bottom direction` and stack the two sides vertically. Do not lay them out side-by-side with `left to right direction`; that invites parallel component lists and makes the contrast hard to read at book width.
- Wrap each side in a bold composite state: `state "<b>Claude Code - assemble then loop</b>" as CC { ... }` and `state "<b>Codex - structure then turn</b>" as CX { ... }`.
- Separate the two composites with a `[hidden]` edge: `CC -[hidden]-> CX`.
- Contrast exactly one behavioral dimension per diagram (control plane, continuity, governance, ...). Use a closing note on each side to name the design lever, not to restate the boxes.

### Titles And Notes

- Title: name the behavior, not the chapter. Use the form `Topic - Behavior Statement`, e.g. `Query Loop Core - One Iteration Of The While Loop`, `Recovery Decision Paths - Cheapest Fix First`, `Tool Batch Ordering - Concurrency Without Context Reordering`. Avoid `Chapter N · Topic` phrasing.
- Notes should explain the invariant, the design lever, or the principle a designer can copy ("concurrency speeds up I/O; contextual cause-and-effect is always replayed in original block order"). Notes that just restate the adjacent boxes are noise.

### Rendering For Book Pages

Target render dimensions of roughly 700-1500 px on each axis so the diagram fits a printed page without forced scaling.

Standard skinparam baseline (default Harness palette):

```
skinparam backgroundColor #FEFEFE      # transparent for book2 comparisons
skinparam shadowing false
skinparam dpi 120                       # 120 for comparison diagrams, 130 for single-book
skinparam defaultFontName Georgia
skinparam defaultFontSize 14
skinparam TitleFontSize 19
skinparam TitleFontColor #161616
skinparam NoteFontSize 12
skinparam ArrowFontSize 12
skinparam ArrowColor #5E5A53
```

Then add only the semantic blocks the diagram actually uses (`skinparam state { ... }`, `skinparam activity { ... }`, `skinparam sequence { ... }`, `skinparam note { ... }`) using the palette below.

Default Harness palette (book1 and Claude-Code-side of book2):

- shape background `#F2E9D9`, border `#1D1D1D`, font `#161616`, arrow `#5E5A53`, start `#8C2721`, end `#161616`
- note background `#F5EBDD`, border `#8C2721`, font `#7B1E1E`
- accent fills for distinguishing roles inside one diagram: `#E8DDD0` (input / source), `#EFE6D8` (runtime / loop), `#F5EBDD` (decision / warning / error)

Codex palette (Codex-side of book2 only, when contrast with the Harness palette is the point):

- shape background `#F8FAFC`, border `#334155`, font `#0F172A`, arrow `#475569`
- note background `#FFF7ED`, border `#C2410C`, font `#7C2D12`

Do not reintroduce these settings, which were removed from the redesigned diagrams because they fight auto-layout or print badly:

- `linetyp