From 3b3d1681276dd92f3cfc1adb2eb9c45bc9483014 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Wed, 18 Mar 2026 11:19:29 -0700 Subject: [PATCH] add .preflight/ config example directory with documented config.yml and triage.yml The README mentions .preflight/ config support but had no copy-paste example. Added examples/.preflight/ with: - config.yml: all options with comments explaining each field - triage.yml: triage rules with comments on always_check/skip/cross_service - README.md: setup instructions and team sharing guidance Also added a quick-start copy command to the Configuration Reference section. --- README.md | 5 ++++ examples/.preflight/README.md | 37 +++++++++++++++++++++++++++ examples/.preflight/config.yml | 46 ++++++++++++++++------------------ examples/.preflight/triage.yml | 46 +++++++++++++++------------------- 4 files changed, 84 insertions(+), 50 deletions(-) create mode 100644 examples/.preflight/README.md diff --git a/README.md b/README.md index 6d03f5d..12313de 100644 --- a/README.md +++ b/README.md @@ -491,6 +491,11 @@ This prevents the common failure mode: changing a shared type in one service and Drop this in your project root. Every field is optional — defaults are sensible. +> **Quick start:** Copy the example config into your project: +> ```bash +> cp -r /path/to/preflight/examples/.preflight .preflight +> ``` + ```yaml # Profile controls overall verbosity # "minimal" — only flag ambiguous+, skip clarification detail diff --git a/examples/.preflight/README.md b/examples/.preflight/README.md new file mode 100644 index 0000000..12993ad --- /dev/null +++ b/examples/.preflight/README.md @@ -0,0 +1,37 @@ +# `.preflight/` Configuration + +Copy this directory into your project root to configure preflight per-project. + +``` +your-project/ +├── .preflight/ +│ ├── config.yml # Profile, thresholds, embeddings, related projects +│ └── triage.yml # Triage rules and strictness +├── src/ +└── ... +``` + +## Quick setup + +```bash +# From your project root: +cp -r /path/to/preflight/examples/.preflight .preflight +# Edit to taste, then commit — your whole team gets the same config. +``` + +## How it works + +- **Without `.preflight/`**: preflight uses environment variables (`PROMPT_DISCIPLINE_PROFILE`, `PREFLIGHT_RELATED`, etc.) +- **With `.preflight/`**: YAML config takes precedence over env vars +- All fields are optional — omitted values use sensible defaults + +## Files + +| File | Purpose | +|------|---------| +| `config.yml` | Profile level, related projects, thresholds, embedding provider | +| `triage.yml` | Triage strictness and keyword rules (always_check, skip, cross_service) | + +## Team sharing + +Commit `.preflight/` to your repo. Everyone on the team gets the same triage rules and thresholds — no per-developer env var setup needed. diff --git a/examples/.preflight/config.yml b/examples/.preflight/config.yml index f59170f..672f62a 100644 --- a/examples/.preflight/config.yml +++ b/examples/.preflight/config.yml @@ -1,35 +1,33 @@ -# .preflight/config.yml — Drop this in your project root -# -# This is an example config for a typical Next.js + microservices setup. -# Every field is optional — preflight works with sensible defaults out of the box. -# Commit this to your repo so the whole team gets the same preflight behavior. +# .preflight/config.yml +# Drop this directory in your project root to configure preflight. +# All fields are optional — defaults are shown below. -# Profile controls how much detail preflight returns. -# "minimal" — only flags ambiguous+ prompts, skips clarification detail -# "standard" — balanced (default) -# "full" — maximum detail on every non-trivial prompt +# Profile controls how aggressive preflight is: +# minimal — only catches clearly vague prompts +# standard — balanced (recommended for most teams) +# full — checks everything, including cross-service contracts profile: standard -# Related projects for cross-service awareness. -# Preflight will search these for shared types, routes, and contracts -# so it can warn you when a change might break a consumer. +# Related projects for cross-service contract awareness. +# Preflight will scan these for shared types, routes, and schemas. related_projects: - - path: /Users/you/code/auth-service - alias: auth - - path: /Users/you/code/billing-api - alias: billing - - path: /Users/you/code/shared-types + - path: ../api-service + alias: api + - path: ../shared-types alias: types -# Behavioral thresholds — tune these to your workflow +# Tuning knobs thresholds: - session_stale_minutes: 30 # Warn if no activity for this long - max_tool_calls_before_checkpoint: 100 # Suggest a checkpoint after N tool calls - correction_pattern_threshold: 3 # Min corrections before flagging a pattern + # Minutes before a session is considered stale (triggers context refresh) + session_stale_minutes: 30 + # Tool calls before preflight suggests a checkpoint + max_tool_calls_before_checkpoint: 100 + # How many times a correction pattern repeats before warning + correction_pattern_threshold: 3 # Embedding provider for semantic search over session history. -# "local" uses Xenova transformers (no API key needed, runs on CPU). -# "openai" uses text-embedding-3-small (faster, needs OPENAI_API_KEY). +# local — runs entirely on your machine (no API key needed, slower) +# openai — uses OpenAI embeddings (faster, requires OPENAI_API_KEY) embeddings: provider: local - # openai_api_key: sk-... # Uncomment if using openai provider + # openai_api_key: sk-... # or set OPENAI_API_KEY env var diff --git a/examples/.preflight/triage.yml b/examples/.preflight/triage.yml index b3d394e..0888033 100644 --- a/examples/.preflight/triage.yml +++ b/examples/.preflight/triage.yml @@ -1,45 +1,39 @@ -# .preflight/triage.yml — Controls how preflight classifies your prompts -# -# The triage engine routes prompts into categories: -# TRIVIAL → pass through (commit, format, lint) -# CLEAR → well-specified, no intervention needed -# AMBIGUOUS → needs clarification before proceeding -# MULTI-STEP → complex task, preflight suggests a plan -# CROSS-SERVICE → touches multiple projects, pulls in contracts -# -# Customize the keywords below to match your domain. +# .preflight/triage.yml +# Controls how preflight triages and routes prompts. +# Separate from config.yml so teams can share triage rules independently. + +# How strict the triage classifier is: +# relaxed — lets most prompts through, only flags obvious issues +# standard — balanced (default) +# strict — flags anything remotely ambiguous +strictness: standard rules: - # Prompts containing these words are always flagged as AMBIGUOUS. - # Add domain-specific terms that tend to produce vague prompts. + # Keywords that ALWAYS trigger a full preflight check, even if the prompt + # looks clear. Good for high-risk areas of your codebase. always_check: - rewards - permissions - migration - schema - - pricing # example: your billing domain - - onboarding # example: multi-step user flows + - billing + - auth - # Prompts containing these words skip checks entirely (TRIVIAL). - # These are safe, mechanical tasks that don't need guardrails. + # Keywords that SKIP preflight entirely. These are low-risk commands + # that don't benefit from ambiguity checking. skip: - commit - format - lint - prettier - - "git push" - # Prompts containing these words trigger CROSS-SERVICE classification. - # Preflight will search related_projects for relevant types and routes. + # Keywords that trigger cross-service contract scanning. + # When these appear, preflight looks at related_projects for + # shared types and interfaces that might be affected. cross_service_keywords: - auth - notification - event - webhook - - billing # matches the related_project alias - -# How aggressively to classify prompts. -# "relaxed" — more prompts pass as clear (experienced users) -# "standard" — balanced (default) -# "strict" — more prompts flagged as ambiguous (new teams, complex codebases) -strictness: standard + - api + - queue