Add examples/.preflight/ config directory

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.

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.

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"

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

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