From d47ec15ec83b953fbd84b4e9bbc847a1b7d3972e Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Tue, 10 Mar 2026 10:36:48 -0700 Subject: [PATCH] docs: add example .preflight/ config directory with ready-to-use templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README documents .preflight/ config extensively but there were no actual example files to copy. Adds: - examples/.preflight/config.yml — profile, related projects, thresholds - examples/.preflight/triage.yml — keyword rules and strictness - examples/.preflight/contracts/api.yml — manual contract definitions - examples/.preflight/README.md — setup instructions and tips - README.md pointer to the examples directory --- README.md | 2 ++ examples/.preflight/README.md | 24 ++++++++++++++++++ examples/.preflight/config.yml | 31 +++++++++++++++++++++++ examples/.preflight/contracts/api.yml | 35 ++++++++++++++++++++++++++ examples/.preflight/triage.yml | 36 +++++++++++++++++++++++++++ 5 files changed, 128 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..7b4b747 100644 --- a/README.md +++ b/README.md @@ -500,6 +500,8 @@ Manual contract definitions that supplement auto-extraction: Environment variables are **fallbacks** — `.preflight/` config takes precedence when present. +> **💡 Ready-to-use example configs:** Copy [`examples/.preflight/`](examples/.preflight/) into your project root to get started quickly. See [`examples/.preflight/README.md`](examples/.preflight/README.md) for details. + --- ## Embedding Providers diff --git a/examples/.preflight/README.md b/examples/.preflight/README.md new file mode 100644 index 0000000..c3ca3b6 --- /dev/null +++ b/examples/.preflight/README.md @@ -0,0 +1,24 @@ +# Example `.preflight/` Config + +Copy this directory into your project root to get started: + +```bash +cp -r examples/.preflight /path/to/your/project/ +``` + +Then edit the files to match your project: + +| File | Purpose | +|------|---------| +| `config.yml` | Profile, related projects, thresholds, embedding provider | +| `triage.yml` | Keyword rules and strictness for prompt classification | +| `contracts/*.yml` | Manual type/interface definitions for cross-service awareness | + +All files are optional — preflight works without any config. These let you tune it for your team and codebase. + +## Tips + +- **Commit `.preflight/` to your repo** so the whole team shares the same rules +- **Start with `strictness: standard`**, then relax or tighten based on your experience +- **Add domain terms to `always_check`** that are frequently ambiguous in your codebase (e.g., "billing", "permissions") +- **Use contracts** for types that live in a separate repo or aren't auto-detected diff --git a/examples/.preflight/config.yml b/examples/.preflight/config.yml new file mode 100644 index 0000000..df4f864 --- /dev/null +++ b/examples/.preflight/config.yml @@ -0,0 +1,31 @@ +# .preflight/config.yml +# Drop this in your project root. Every field is optional. +# See: https://github.com/TerminalGravity/preflight#configuration-reference + +# Profile controls how much detail preflight returns. +# "minimal" — only flags ambiguous+, skips clarification detail +# "standard" — default 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, +# triage escalates to cross-service and searches those projects. +related_projects: + - path: /Users/you/projects/auth-service + alias: auth + - path: /Users/you/projects/shared-types + alias: shared + +# 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 timeline search +# "local" uses Xenova (zero config, runs on-device) +# "openai" uses text-embedding-3-small (faster, needs API key) +embeddings: + provider: local + # 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..154ad5b --- /dev/null +++ b/examples/.preflight/contracts/api.yml @@ -0,0 +1,35 @@ +# .preflight/contracts/api.yml +# Manual contract definitions that supplement auto-extraction. +# Use these when preflight can't auto-detect your shared types, +# or when you want to be explicit about cross-service boundaries. + +- name: User + kind: interface + description: Core user object 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: data + type: T + required: true + - name: error + type: string + required: false + - name: meta + type: "{ page: number, total: number }" + required: false diff --git a/examples/.preflight/triage.yml b/examples/.preflight/triage.yml new file mode 100644 index 0000000..d418ace --- /dev/null +++ b/examples/.preflight/triage.yml @@ -0,0 +1,36 @@ +# .preflight/triage.yml +# Controls the triage classification engine. +# Customize which prompts get flagged, skipped, or escalated. + +rules: + # Prompts containing these words → always at least AMBIGUOUS. + # Add domain terms that are frequently underspecified in your codebase. + always_check: + - rewards + - permissions + - migration + - schema + - billing + + # Prompts containing these words → TRIVIAL (pass through without checks). + # Safe, low-risk operations that don't need guardrails. + skip: + - commit + - format + - lint + - prettier + + # Prompts containing these words → CROSS-SERVICE. + # Triggers a search across related_projects defined in config.yml. + cross_service_keywords: + - auth + - notification + - event + - webhook + - queue + +# How aggressively to classify prompts. +# "relaxed" — more prompts pass as clear (experienced users) +# "standard" — balanced (recommended) +# "strict" — more prompts flagged as ambiguous (teams, onboarding) +strictness: standard