From ebc227b0afbb778711799c598d883cb4eb8753f1 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Tue, 10 Mar 2026 10:08:13 -0700 Subject: [PATCH] add .preflight.example/ directory with ready-to-copy config templates Includes annotated config.yml, triage.yml, contracts/api.yml, and a README explaining how to use them. The main README now links to the example directory from the Configuration Reference section. --- .preflight.example/README.md | 36 +++++++++++++++++++++++ .preflight.example/config.yml | 36 +++++++++++++++++++++++ .preflight.example/contracts/api.yml | 39 ++++++++++++++++++++++++ .preflight.example/triage.yml | 44 ++++++++++++++++++++++++++++ README.md | 2 ++ 5 files changed, 157 insertions(+) create mode 100644 .preflight.example/README.md create mode 100644 .preflight.example/config.yml create mode 100644 .preflight.example/contracts/api.yml create mode 100644 .preflight.example/triage.yml diff --git a/.preflight.example/README.md b/.preflight.example/README.md new file mode 100644 index 0000000..da0bff1 --- /dev/null +++ b/.preflight.example/README.md @@ -0,0 +1,36 @@ +# `.preflight/` Example Config + +Copy this directory into your project root as `.preflight/`: + +```bash +cp -r .preflight.example /path/to/your/project/.preflight +``` + +Then customize for your project: + +1. **`config.yml`** — Set your profile, related projects, and thresholds +2. **`triage.yml`** — Add domain-specific keywords that control how prompts are classified +3. **`contracts/*.yml`** — Define key types/interfaces preflight should know about + +All files are optional. Preflight uses sensible defaults for anything you don't configure. + +## Quick Setup + +Most projects only need `config.yml` with related projects: + +```yaml +# .preflight/config.yml +profile: standard +related_projects: + - path: /path/to/your/api + alias: api + - path: /path/to/your/shared-types + alias: types +``` + +## Tips + +- **Commit `.preflight/`** to your repo so your whole team benefits +- **Add to `triage.yml`** when you notice preflight missing domain-specific ambiguity +- **Add contracts** for types that span multiple services — this is where cross-service checks shine +- **Start with `standard`** strictness and adjust based on your team's experience level diff --git a/.preflight.example/config.yml b/.preflight.example/config.yml new file mode 100644 index 0000000..eb17627 --- /dev/null +++ b/.preflight.example/config.yml @@ -0,0 +1,36 @@ +# .preflight/config.yml — copy this directory to .preflight/ in your project root +# +# This configures preflight's behavior for your project. +# Every field is optional — defaults are sensible. +# Commit this to your repo so your whole team gets the same experience. + +# Profile controls overall verbosity +# "minimal" — only flag ambiguous+, skip clarification detail +# "standard" — default behavior (recommended) +# "full" — maximum detail on every non-trivial prompt +profile: standard + +# Related projects for cross-service awareness +# Preflight will search these projects' session history and contracts +# when it detects cross-service prompts (e.g. "update the auth flow") +related_projects: + # - path: /absolute/path/to/auth-service + # alias: auth-service + # - path: /absolute/path/to/shared-types + # alias: shared-types + +# Behavioral thresholds +thresholds: + # Warn if no session activity for this many minutes + session_stale_minutes: 30 + # Suggest a checkpoint after this many tool calls + max_tool_calls_before_checkpoint: 100 + # Minimum logged corrections before a pattern is formed + correction_pattern_threshold: 3 + +# Embedding configuration for semantic search +embeddings: + # "local" uses Xenova transformers (no API key needed, runs on CPU) + # "openai" uses OpenAI's embedding API (faster, needs key) + provider: local + # openai_api_key: sk-... # only needed if provider is "openai" diff --git a/.preflight.example/contracts/api.yml b/.preflight.example/contracts/api.yml new file mode 100644 index 0000000..8104614 --- /dev/null +++ b/.preflight.example/contracts/api.yml @@ -0,0 +1,39 @@ +# .preflight/contracts/api.yml — manual contract definitions +# +# Define your project's key types and interfaces here. +# These supplement auto-extracted contracts from your codebase. +# Manual definitions win on name conflicts with auto-extracted ones. +# +# Why? Auto-extraction may miss domain-specific semantics. +# Manual contracts let you annotate what matters to your team. + +- name: User + kind: interface + description: Core user object returned by auth endpoints + fields: + - name: id + type: string + required: true + - name: email + type: string + required: true + - name: role + type: "'admin' | 'member' | 'viewer'" + required: true + - name: createdAt + type: Date + required: true + +# - name: ApiResponse +# kind: interface +# description: Standard API response wrapper +# fields: +# - name: data +# type: T +# required: true +# - name: error +# type: string | null +# required: false +# - name: meta +# type: "{ page: number, total: number }" +# required: false diff --git a/.preflight.example/triage.yml b/.preflight.example/triage.yml new file mode 100644 index 0000000..8f0f941 --- /dev/null +++ b/.preflight.example/triage.yml @@ -0,0 +1,44 @@ +# .preflight/triage.yml — controls the triage classification engine +# +# Customize how preflight classifies your prompts. +# This is where you teach preflight about YOUR project's domain. + +rules: + # Prompts containing these words are ALWAYS flagged as ambiguous. + # Add domain-specific terms that tend to produce vague prompts. + # Example: "fix rewards" is too vague — which rewards? what's broken? + always_check: + - rewards + - permissions + - migration + - schema + # Add your own: + # - billing + # - onboarding + + # Prompts containing these words pass through as TRIVIAL. + # These are safe, well-understood commands that don't need checks. + skip: + - commit + - format + - lint + # Add your own: + # - typecheck + # - prettier + + # Prompts containing these words trigger CROSS-SERVICE checks. + # Preflight will search related projects for relevant contracts. + cross_service_keywords: + - auth + - notification + - event + - webhook + # Add your own: + # - payment + # - analytics + +# How aggressively to classify +# "relaxed" — more prompts pass as clear (experienced users) +# "standard" — balanced (recommended) +# "strict" — more prompts flagged as ambiguous (new team members, complex projects) +strictness: standard diff --git a/README.md b/README.md index f60fefa..10c58e3 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 +> **Quick start:** Copy the [`.preflight.example/`](.preflight.example/) directory into your project as `.preflight/` and customize. All files are optional. + ### `.preflight/config.yml` Drop this in your project root. Every field is optional — defaults are sensible.