From d5f0d016aff065ead0401b10d35b29cd29378168 Mon Sep 17 00:00:00 2001
From: Jack Felke <jrinnfelke@gmail.com>
Date: Wed, 18 Mar 2026 13:41:13 -0700
Subject: [PATCH] docs: add example CLAUDE.md for automatic preflight
 integration

Adds a ready-to-use CLAUDE.md template that makes Claude Code
automatically run preflight_check on prompts. Users can copy it
into their project to get preflight working without manual tool calls.

Referenced from Quick Start in README and examples/README.
---
 README.md          | 10 ++++++++++
 examples/CLAUDE.md | 30 ++++++++++++++++++++++++++++++
 examples/README.md | 16 ++++++++++++++++
 3 files changed, 56 insertions(+)
 create mode 100644 examples/CLAUDE.md

diff --git a/README.md b/README.md
index 6d03f5d..7969d58 100644
--- a/README.md
+++ b/README.md
@@ -124,6 +124,16 @@ claude mcp add preflight -- preflight-dev-serve
 
 > **Note:** `preflight-dev` runs the interactive setup wizard. `preflight-dev-serve` starts the MCP server — that's what you want in your Claude Code config.
 
+### Make Claude use preflight automatically
+
+Add preflight rules to your project's `CLAUDE.md` so Claude runs `preflight_check` on every prompt without you asking:
+
+```bash
+cp /path/to/preflight/examples/CLAUDE.md your-project/CLAUDE.md
+```
+
+See [`examples/CLAUDE.md`](examples/CLAUDE.md) for a ready-to-use template with recommended rules for when to preflight, session hygiene, and skip-lists.
+
 ---
 
 ## How It Works
diff --git a/examples/CLAUDE.md b/examples/CLAUDE.md
new file mode 100644
index 0000000..da55f40
--- /dev/null
+++ b/examples/CLAUDE.md
@@ -0,0 +1,30 @@
+# CLAUDE.md — Preflight Integration Example
+#
+# Drop this into your project's CLAUDE.md (or .claude/CLAUDE.md) to make
+# Claude Code automatically use preflight tools during your sessions.
+# Customize the rules below to match your workflow.
+
+## Preflight Rules
+
+Before starting any non-trivial task, run `preflight_check` with my prompt. This catches vague instructions before they waste tokens on wrong→fix cycles.
+
+### When to use preflight tools:
+
+- **Every prompt**: `preflight_check` triages automatically — let it decide what's needed
+- **Before multi-file changes**: Run `scope_work` to get a phased plan
+- **Before sub-agent tasks**: Use `enrich_agent_task` to add context
+- **After making a mistake**: Use `log_correction` so preflight learns the pattern
+- **Before ending a session**: Run `checkpoint` to save state for next time
+- **When I say "fix it" or "do the others"**: Use `sharpen_followup` to resolve what I actually mean
+
+### Session hygiene:
+
+- Run `check_session_health` if we've been going for a while without committing
+- If I ask about something we did before, use `search_history` to find it
+- Before declaring a task done, run `verify_completion` (type check + tests)
+
+### Don't preflight these:
+
+- Simple git commands (commit, push, status)
+- Formatting / linting
+- Reading files I explicitly named
diff --git a/examples/README.md b/examples/README.md
index 778f15d..f2fafc1 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -12,6 +12,22 @@ The `.preflight/` directory contains example configuration files you can copy in
     └── api.yml             # Manual contract definitions for cross-service types
 ```
 
+## `CLAUDE.md` Integration
+
+The `CLAUDE.md` file tells Claude Code how to behave in your project. Adding preflight rules here makes Claude automatically use preflight tools without you having to ask.
+
+```bash
+# Copy the example into your project:
+cp /path/to/preflight/examples/CLAUDE.md my-project/CLAUDE.md
+
+# Or append to your existing CLAUDE.md:
+cat /path/to/preflight/examples/CLAUDE.md >> my-project/CLAUDE.md
+```
+
+This is the **recommended way** to integrate preflight — once it's in your `CLAUDE.md`, every session automatically runs `preflight_check` on your prompts.
+
+---
+
 ### Quick setup
 
 ```bash