From 4757ec19dea7c54e158957e0b5e9337c472f8130 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Tue, 3 Mar 2026 09:56:37 -0700 Subject: [PATCH] add .preflight/ config example directory with annotated config, triage, and contract files --- README.md | 2 ++ examples/.preflight/README.md | 27 ++++++++++++++++++ examples/.preflight/config.yml | 30 ++++++++++++++++++++ examples/.preflight/contracts/api.yml | 39 +++++++++++++++++++++++++ examples/.preflight/triage.yml | 41 +++++++++++++++++++++++++++ 5 files changed, 139 insertions(+) create mode 100644 examples/.preflight/README.md create mode 100644 examples/.preflight/config.yml create mode 100644 examples/.preflight/contracts/api.yml create mode 100644 examples/.preflight/triage.yml diff --git a/README.md b/README.md index f60fefa..5c93c22 100644 --- a/README.md +++ b/README.md @@ -406,6 +406,8 @@ This prevents the common failure mode: changing a shared type in one service and ## Configuration Reference +> **Want a ready-to-use starting point?** Copy the [`examples/.preflight/`](examples/.preflight/) directory into your project root and customize it. See [`examples/.preflight/README.md`](examples/.preflight/README.md) for details. + ### `.preflight/config.yml` Drop this in your project root. Every field is optional — defaults are sensible. diff --git a/examples/.preflight/README.md b/examples/.preflight/README.md new file mode 100644 index 0000000..d8602b4 --- /dev/null +++ b/examples/.preflight/README.md @@ -0,0 +1,27 @@ +# Example `.preflight/` Configuration + +Copy this directory into your project root to configure preflight for your team. + +```bash +cp -r examples/.preflight /path/to/your/project/ +``` + +## Files + +| File | Purpose | +|------|---------| +| `config.yml` | Main config — profile, related projects, thresholds, embedding provider | +| `triage.yml` | Triage rules — which keywords trigger which classification level | +| `contracts/*.yml` | Manual contract definitions that supplement auto-extraction | + +## What to customize + +1. **`config.yml`** — Update `related_projects` paths to point at your actual services +2. **`triage.yml`** — Add your domain keywords to `always_check` (e.g. `billing`, `payment`, `deploy`) +3. **`contracts/`** — Add shared types that preflight should always surface + +## Commit it + +The `.preflight/` directory is meant to be committed to your repo. The whole team benefits from shared triage rules and contract definitions. + +Environment variables (`CLAUDE_PROJECT_DIR`, `OPENAI_API_KEY`, etc.) are per-user overrides — they take lower precedence than these files. diff --git a/examples/.preflight/config.yml b/examples/.preflight/config.yml new file mode 100644 index 0000000..64aebbd --- /dev/null +++ b/examples/.preflight/config.yml @@ -0,0 +1,30 @@ +# .preflight/config.yml — Drop this in your project root +# +# Every field is optional. Defaults are sensible. +# This file should be committed to your repo so the whole team shares settings. + +# Profile controls how verbose preflight is: +# "minimal" — only flags ambiguous+, skips clarification detail +# "standard" — default balanced behavior +# "full" — maximum detail on every non-trivial prompt +profile: standard + +# Related projects for cross-service contract awareness. +# When your prompt mentions a keyword from a related project, +# preflight searches that project's LanceDB index and contracts. +related_projects: + - path: /Users/you/Developer/auth-service + alias: auth-service + - path: /Users/you/Developer/shared-types + alias: shared-types + +# Behavioral thresholds +thresholds: + session_stale_minutes: 30 # Warn if no activity for this long + max_tool_calls_before_checkpoint: 100 # Suggest checkpoint after N tool calls + correction_pattern_threshold: 3 # Min corrections before forming a pattern + +# Embedding provider for semantic search +embeddings: + provider: local # "local" (Xenova, zero-config) or "openai" (faster, needs key) + # openai_api_key: sk-... # Only needed if provider is "openai" diff --git a/examples/.preflight/contracts/api.yml b/examples/.preflight/contracts/api.yml new file mode 100644 index 0000000..7b8865a --- /dev/null +++ b/examples/.preflight/contracts/api.yml @@ -0,0 +1,39 @@ +# .preflight/contracts/api.yml — Manual contract definitions +# +# These supplement auto-extracted contracts from your codebase. +# Useful for documenting APIs that preflight can't auto-detect, +# or for pinning definitions that shouldn't drift. +# +# When a prompt touches these contracts, preflight surfaces them +# so Claude has the right types before writing code. + +- name: User + kind: interface + description: Core user model shared across services + fields: + - name: id + type: string + required: true + - name: email + type: string + required: true + - name: role + type: "'admin' | 'member' | 'viewer'" + required: true + - name: teamId + type: string + required: false + +- name: ApiResponse + kind: interface + description: Standard API response wrapper + fields: + - name: success + type: boolean + required: true + - name: data + type: T + required: false + - name: error + type: "{ code: string, message: string }" + required: false diff --git a/examples/.preflight/triage.yml b/examples/.preflight/triage.yml new file mode 100644 index 0000000..b5e512d --- /dev/null +++ b/examples/.preflight/triage.yml @@ -0,0 +1,41 @@ +# .preflight/triage.yml — Controls the triage classification engine +# +# Triage decides how preflight handles each prompt: +# TRIVIAL → pass through (e.g. "commit", "lint") +# CLEAR → looks good, minimal checks +# AMBIGUOUS → needs clarification before proceeding +# MULTI-STEP → complex, needs scoping +# CROSS-SERVICE → touches multiple projects + +rules: + # Prompts containing these words → always at least AMBIGUOUS + # Add domain-specific terms that usually need clarification + always_check: + - rewards + - permissions + - migration + - schema + - billing + - deploy + + # Prompts containing these → TRIVIAL (pass through without checks) + skip: + - commit + - format + - lint + - "git status" + + # Prompts containing these → CROSS-SERVICE + # (triggers search across related_projects from config.yml) + cross_service_keywords: + - auth + - notification + - event + - webhook + - shared-types + +# How aggressively to classify: +# "relaxed" — more prompts pass as clear +# "standard" — balanced +# "strict" — more prompts flagged as ambiguous +strictness: standard