This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
A centralized reference library: authoritative style, drafting, and writing standards shared across personal, CPA, and investment projects. No project-specific content lives here. Individual project repositories extend what they need.
This file (CLAUDE.md) is the single source of truth for architecture, conventions,
and model selection. AGENTS.md, GEMINI.md, and .github/copilot-instructions.md
are derived pointers for other tools: they carry quick-reference operational facts
and tool-specific guidance only, and defer here for anything normative. When a rule,
table, or version number changes, change it here; do not restate version-sensitive
detail in the derived files, so they cannot drift.
reference-library/
├── legal-style/ # Oregon legal style and drafting rules
│ ├── QUICK-START.md # 80% of daily lookups: start here
│ ├── cross-reference.md # Where the three sources diverge (read this before drafting)
│ ├── appellate-style-manual/ # Oregon Appellate Courts Style Manual (2002)
│ ├── lc-drafting-manual/ # Oregon Legislative Counsel Drafting Manual
│ └── lc-form-style-manual/ # Oregon LC Form and Style Manual
├── writing-style/
│ ├── style-profile.md # Quantified stylometry targets and voice characteristics
│ ├── ai-detection.md # Blacklisted AI terms and rewrite examples
│ ├── tone-voice.md # 8 style palettes with triggers and signals
│ ├── structural-formatting.md # Markdown rules, heading hierarchy, WCAG notes
│ ├── plain-language-guide.md # Federal plain language principles, readability, inclusive language
│ ├── logical-fallacies-guide.md # Common reasoning errors in professional documents
│ ├── transition-words-reference.md # Transition categories, usage rules, AI overuse detection
│ ├── punctuation-preferences.md # Catalog of person-configurable Tier 3 overrides (em-dash, etc.)
│ └── grammar-style/ # EoS + CMS grammar reference (14 files)
│ ├── QUICK-START.md # 80% of grammar questions: start here
│ ├── cross-reference.md # 26 EoS/CMS divergences with resolution
│ ├── index.md # Concept-to-file routing map
│ ├── elements-of-style/ # EoS base rules (Tier 1, drafting baseline)
│ └── chicago-manual/ # CMS rules (Tier 2, editing authority)
├── config/
│ ├── profiles.example.toml # Shipped default profile + starter styles (committed)
│ ├── profiles.toml # Active per-machine config (gitignored; copied from example on first setup)
│ └── profiles/ # Per-person calibration files (gitignored)
├── agents/
│ ├── grammar-composition-editor.md # Stage 1: Grammar, composition, plain language
│ ├── document-validator.md # Stage 2: Factual accuracy, assumptions, bias
│ ├── writing-style-editor.md # Stage 3: Voice, AI detection, stylometry
│ ├── style-analyzer.md # Pre-pipeline: Analyze samples, calibrate profile
│ ├── document-drafter.md # Pre-pipeline: Voice-calibrated first-draft generation
│ ├── audience-reaction-analyzer.md # Post-pipeline: Predict audience comprehension and response
│ └── tone-rewriter.md # Pre-pipeline: Transform register for different audiences
├── samples/
│ ├── before/ # AI-generated before-state samples for pipeline testing
│ └── after/ # Post-pipeline output: per-stage transcripts plus recaps
├── docs/
│ ├── architecture/ # ADRs (writing authority hierarchy, future architecture decisions)
│ ├── compliance-reports/ # Generated audit and badge-prep reports (git-ignored)
│ ├── superpowers/ # Local working directory for plans and scratch notes (git-ignored)
│ ├── known-vulnerabilities.md # CVE log and accepted Scorecard exceptions; 60-day review cycle
│ └── reusable-workflow-jobs.yaml # Workflow inventory for CI-024 freshness check
├── LICENSES/ # REUSE 3.0 licenses (FOUND-025: in lieu of root LICENSE)
└── scripts/
├── extract_legal_pdfs.py # PDF → raw text extraction (pdftotext → pymupdf fallback)
├── generate_before_samples.py # Generate AI-mechanical before-state samples via OpenRouter
├── profile_resolver.py # Resolve person × style profile from config/profiles.toml
└── setup.sh # Install agents and bootstrap config/profiles.toml from example
Agents resolve a person × style profile at invocation time and use it to scope voice, stylometry, punctuation overrides, AI-detection extensions, and legal-source bindings.
| Dimension | Examples | Scope |
|---|---|---|
| Person | default, byron, ariannah |
Voice, stylometry, hedge phrases, analogy domains, tier_3_overrides, domains, AI extensions |
| Style | general, work-email, internal-memo, client-memo, statutory-drafting, court-brief |
Palette, formality, legal source, structural conventions, register-specific punctuation |
Resolution (last writer wins on scalars; lists concat-and-dedupe):
base_defaults -> [person.<p>] -> [style.<s>] -> [overrides."<p>:<s>"]
The --person and --style CLI flags select which person/style layers apply; they
are not themselves an additional override layer.
Config files:
config/profiles.example.toml: committed; defines the shipped[person.default]and 6 starter styles. Always available as a fallback.config/profiles.toml: gitignored; the active per-machine config.scripts/setup.shcopies the example into this path on first run.config/profiles/<person>/<style>.md: gitignored; per-person calibration data written by thestyle-analyzeragent. Referenced bycalibration_sourcein the TOML.
Domain gating: a style with required_domain = "legal:oregon" will not resolve for a
person whose domains list omits that value. The resolver exits with code 7 (DomainMismatch)
and a clear error. Agents must report the error and ask, not silently substitute.
Invocation: every agent accepts person=<key> style=<key> parameters in the prompt. Both
default to the [defaults] block when omitted. The resolver script (scripts/profile_resolver.py)
is called by agents via the Bash tool and emits a flat JSON profile that drives the rest of
the run. See writing-style/punctuation-preferences.md for the Tier 3 override catalog.
The writing-style/grammar-style/ content uses a three-tier authority hierarchy. The tier
governs based on which operation you are performing:
| Operation | Authority |
|---|---|
| Drafting (writing first draft) | Elements of Style (Tier 1 baseline) |
| Editing (reviewing any draft) | Chicago Manual of Style, 17th ed. (Tier 2; overrides EoS) |
| Person-specific preferences | Active profile's tier_3_overrides (Tier 3; overrides CMS) |
Tier 3 is profile-driven, with one universal exception. The active person's profile
carries a tier_3_overrides list that layers person-specific punctuation and usage choices
on top of CMS. One entry, no-em-dash, is a universal house rule rather than an optional
preference: it is enforced repo-wide by the no-em-dash pre-commit hook and restated in
every assistant-instruction file, so it applies to all output regardless of profile, and the
default profile always includes it. Every other Tier 3 override is genuinely optional and may
differ per person. See writing-style/punctuation-preferences.md for the catalog and
scripts/profile_resolver.py for resolution. Beyond the universal no-em-dash rule, never
hardcode a Tier 3 override into agents or reference content; always read the resolved list at
invocation time.
Agent file-loading strategy: Load grammar-style/QUICK-START.md first. For conflicts,
load cross-reference.md. For deeper rules, load only the specific source file. Never
load all grammar-style files at once (full set exceeds 12,000 tokens).
The legal-style/ content comes from three distinct sources with different and sometimes
conflicting rules. The source governs based on what you are writing, not what you are reading:
| Document type | Governing source |
|---|---|
| Court opinions and briefs | Appellate Courts Style Manual |
| Bills and session law | LC Form & Style Manual |
| Statutory language (meaning, construction) | LC Drafting Manual |
Critical divergences (see legal-style/cross-reference.md for the full list):
- Serial comma: LC omits it (
A, B and C); Appellate uses it (A, B, and C) - Quotation mark punctuation: LC puts punctuation outside; Appellate puts it inside
- ORS ranges: LC always uses "to"; Appellate uses " - " (hyphen with spaces) in citation form
- Ellipsis: Appellate uses
* * *; LC uses... - Tense: LC uses present tense throughout; Appellate uses past for facts, present for legal rules
This is a docs-only repository with no production code. Choose the model based on what you are doing, not the size of the task.
| Task type | Model | When |
|---|---|---|
| Complex writing analysis, agent design, ADRs | Opus 4.8 | Reasoning about agent pipeline architecture, deep style analysis |
| Standard edits, CLAUDE.md updates, agent file edits | Sonnet 4.6 | Most authoring and editing work in this repo |
| Read-only exploration of style or legal content | Haiku 4.5 | File scanning, structure mapping, quick lookups |
For subagents invoked from within this repo, set model: haiku for read-only discovery passes and model: sonnet for any subagent that writes or rewrites content.
Global model selection rules and orchestration patterns: see
~/.claude/rules/supervisor.md
RAD tagging applies when editing agent files (agents/) or scripts (scripts/). Tag assumptions that could cause failures using #CRITICAL, #ASSUME, and #EDGE comment markers paired with #VERIFY instructions.
Mandatory categories for this repository:
- External resources: PDF source URLs in
scripts/extract_legal_pdfs.pyand anycurlcommands in CLAUDE.md. URLs rot; tag fetches with#CRITICALif the content is irreplaceable. - Data integrity: Legal text extraction assumptions (character yield thresholds, page-count estimates, encoding). Tag with
#ASSUMEwhere the script guesses at PDF structure.
Keep agent files free of unverified assumptions about file paths, token counts, and model availability. Those are the most common silent failures in this repo.
Full tagging syntax, verification workflow, and examples: see
~/dev/.claude/docs/response-aware-development.md
These global rule files apply to work in this repository:
- Writing rules (em-dash ban, AI pattern blacklist, grammar authority):
~/.claude/rules/writing.md - Git workflow (branch naming, worktrees, conventional commits):
~/.claude/rules/git-workflow.md - Supervisor and agent patterns (model assignment, subagent orchestration):
~/.claude/rules/supervisor.md
The seven agents in agents/ include pre-pipeline generators, a calibration agent,
a sequential three-stage editing pipeline, and a post-pipeline analyzer. No project-specific
content lives in any agent.
| Agent | Scope | Analogy |
|---|---|---|
style-analyzer |
Collect writing samples, compute stylometry, characterize voice, update profile | Tune the instrument |
Run the style analyzer once when a new user adopts the library, or when the user's
writing style has evolved. It analyzes the user's real writing samples and generates
updated targets for style-profile.md plus adjustment notes for the three pipeline agents.
This replaces the repository author's default style profile with one calibrated to the
new user's voice.
Workflow: Provide 3–5 writing samples (2,000+ words total) → analyzer computes stylometry and characterizes voice → review and approve recommendations → updated profile drives all future pipeline runs.
These agents produce text that feeds into the editing pipeline. Both apply style-profile.md
targets and ai-detection.md constraints during generation to minimize downstream corrections.
| Agent | Scope | Analogy |
|---|---|---|
document-drafter |
Generate first drafts from outlines, bullet points, or contextual prompts, calibrated to the author's voice | Write the first draft |
tone-rewriter |
Transform a document's register for a different audience while preserving all factual content | Same message, new audience |
Document drafter accepts outlines, bullet points, prior documents, contextual prompts, emails with reply direction, or topic-plus-audience descriptions. It produces a complete first draft that already sounds like the author, reducing the remediation cycles Stage 3 needs to run.
Tone rewriter takes a finished document and transforms it for a different audience or formality level. A formal tax analysis becomes a client-friendly summary. An internal memo becomes an executive brief. Factual content must survive the transformation; Stage 2 re-verifies semantic preservation after every rewrite.
Both agents tag their output with ai_generated: true metadata, which signals Stage 3 to
apply heightened AI pattern scrutiny.
Generator flow: Input → Generator Agent → Stage 1 → Stage 2 → Stage 3 → Submission
Run the three editing agents in order: Stage 1 → Stage 2 → Stage 3.
| Stage | Agent | Scope | Analogy |
|---|---|---|---|
| 1 | grammar-composition-editor |
Grammar, composition, plain language, AI-mechanical patterns | Fix the bones |
| 2 | document-validator |
Factual accuracy, assumptions, bias, reasoning errors | Verify the truth |
| 3 | writing-style-editor |
Voice, persona fidelity, AI pattern detection, stylometry | Tune the voice |
Pipeline flow: Draft → Stage 1 (grammar) → Stage 2 (facts) → Stage 3 (voice) → Submission
Why this order: Grammar fixes are mechanical and objective. Factual errors are highest-stakes for credibility. Style and persona are final polish on clean, verified text.
Remediation: If Stage 3 rewrites text for voice, those sections flow back through Stage 1 then Stage 2 to verify grammar and semantic preservation. Max 3 remediation cycles before human review.
| Agent | Scope | Analogy |
|---|---|---|
audience-reaction-analyzer |
Predict audience comprehension, persuasion effectiveness, emotional response, and action clarity | Will this land? |
Run the audience reaction analyzer after the editing pipeline passes. It reads the finished document from the perspective of a specified target audience and reports what they will understand, misunderstand, feel, and do.
Workflow: Provide the finished document plus a target audience description and desired outcome → analyzer predicts comprehension gaps, persuasion weaknesses, emotional trajectory, and action clarity → revision recommendations ranked by impact on the desired outcome.
The analyzer does not edit text. If its findings require revision, the document-drafter or tone-rewriter agents can generate updated content, which then re-enters the editing pipeline.
Full workflow: Input → Generator → Stage 1 → Stage 2 → Stage 3 → Audience Analyzer → (revision if needed)
Installing agents: Run bash scripts/setup.sh from the repository root. This installs
all agents to ~/.claude/agents/ with the correct absolute paths substituted. Agents
become globally available across all Claude Code projects with no per-project configuration.
Re-run after moving or recloning the repository.
Extending agents: To add project-specific rules, create a .claude/agents/ file in the
target project with the additional content. The globally installed base agents handle the
standard pipeline; the project file adds domain-specific rules on top.
The three source PDFs are stored in legal-style/source-pdfs/ (git-ignored). Raw text
intermediates in legal-style/source-pdfs/raw-text/ are also git-ignored (reproducible).
To download the source PDFs:
# #CRITICAL: These three URLs are the sole authoritative sources for Oregon
# legal style content. If a URL rots, the extracted text cannot be replaced
# from an equivalent source; keep the downloaded PDFs in a durable backup.
# #VERIFY: Re-test all three URLs annually and after any Oregon court or
# legislature website redesign.
cd legal-style/source-pdfs
curl -O "https://www.courts.oregon.gov/publications/Documents/UpdatedStyleManual2002.pdf"
curl -O "https://www.oregonlegislature.gov/lc/PDFs/draftingmanual.pdf"
curl -O "https://www.oregonlegislature.gov/lc/PDFs/form-stylemanual.pdf"
# Record checksums so future extractions can detect a changed or tampered file.
# #CRITICAL: a silently changed PDF would propagate into drafting guidance.
# #VERIFY: re-run after any intentional source update and re-review the output.
sha256sum *.pdf > checksums.sha256To re-extract text (tries pdftotext first, falls back to pymupdf):
python scripts/extract_legal_pdfs.pyIf a PDF is image-based (low character yield), the script instructs you to use the Claude Code
Read tool in 20-page increments as an OCR fallback.
After running bash scripts/setup.sh, all seven agents (style analyzer, two generators,
three pipeline stages, and the audience analyzer) are globally available in all Claude Code
projects. No per-project configuration is required. New users should run the style-analyzer
agent first to calibrate the style profile before using the generators or editing pipeline.
Point directly to files using the path where you cloned the library. For example, if cloned
to ~/dev/reference-library:
See ~/dev/reference-library/legal-style/QUICK-START.md for citation rules.
See ~/dev/reference-library/writing-style/style-profile.md for style targets.
See ~/dev/reference-library/writing-style/grammar-style/QUICK-START.md for grammar rules.
The library is designed to be referenced in-place, not copied. The installed agents already resolve these paths automatically at setup time.