CLAUDE.md · diff

git:20260716.3420635 to git:20260923.ae41833

1 added, 1 removed. Audit A to A.

# CLAUDE.md - Claude Code Instructions for Writing Style Library

See `AGENTS.md` for the full multi-agent reference. This file adds Claude Code-specific guidance.

## Quick orientation

This repo is a composable catalog of writing instructions organized into four directories (Voice, Tone, Style, Format):

- **Voice** (`taxonomy/voices/`) - persistent writer identity

- **Tone** (`taxonomy/tones/`) - situational register

- **Style** (`taxonomy/styles/`) - rhetorical and cognitive pattern

- **Format** (`taxonomy/formats/`) - visual/structural container

Each entry lives in its own folder with an `ENTRY.md` file (atomic-folder pattern).

## Key commands

```bash

# Validate all entries (run before every commit)

python tools/validate.py

# Rebuild taxonomy.json (run after adding/editing entries)

python tools/build-indexes.py

# Generate the docs site pages from the catalog (after editing taxonomy/ or examples/)

node scripts/gen-site.mjs

# Build the site locally (runs the generator, then astro build)

cd site && npm run build

```

## Hard rules

- **No em-dashes (U+2014) or en-dashes (U+2013)** anywhere - not in prose, code comments, commit messages, or doc files. Use " - " (space-hyphen-space). This is enforced by a pre-commit hook.

- **`docs/internal/` is a living planning area** (ADRs, release-plan trackers, specs, the backlog) - maintained under direct maintainer direction as work proceeds, not read-only. `docs/internal/_working/` and `_LOCAL/` are frozen historical/research snapshots - read-only, do not modify.

- - **Never set `review_status` to `stable` or `reference-quality`** without maintainer review. New entries start at `draft`. (The 60-entry v0.1.0 seed catalog was reviewed and set to `stable` as the baseline; this rule governs new entries.)

+ - **Never set `review_status` to `stable` or `reference-quality`** without maintainer review. New entries start at `draft`; tooling promotes them to `machine-verified` once every enforced check passes (`python tools/promote.py`), and only the maintainer moves an entry to `stable`, after reading it (`python tools/promote.py --reviewed <id>`). The ladder and its reasons are in ADR 0021.

- **Conventional Commits** format for all commits: `feat(taxonomy): add <entry-id> <axis> entry`.

## When adding an entry

1. Create `taxonomy/<axis>/<kebab-case-id>/ENTRY.md`

2. Follow the frontmatter schema in `schemas/<axis>.schema.json`

3. Cross-references (`pairs_well_with`, `avoid_with`, `confusable_with`) must use IDs that already exist in the catalog

4. Run `python tools/validate.py` - every check must pass

5. Run `python tools/build-indexes.py` to update the indexes

## Schema changes

Require a version bump and a new ADR in `docs/internal/adr/`. See `AGENTS.md` - Schema Safety section.