From 8f2081a0fd74cbc1234ef1236efff5a1c438d1ce Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Wed, 4 Mar 2026 20:45:14 -0700 Subject: [PATCH] add .preflight/ example config directory with starter configs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README documents .preflight/ config extensively but no example files existed in the repo. Added: - .preflight/config.yml — main config with all options commented - .preflight/triage.yml — triage rules with domain examples - .preflight/contracts/example-api.yml — sample manual contracts - .preflight/README.md — quick setup guide Also added a callout in the main README pointing to the examples. --- .preflight/README.md | 28 ++++++++++++++++++++ .preflight/config.yml | 30 +++++++++++++++++++++ .preflight/contracts/example-api.yml | 39 ++++++++++++++++++++++++++++ .preflight/triage.yml | 36 +++++++++++++++++++++++++ README.md | 2 ++ 5 files changed, 135 insertions(+) create mode 100644 .preflight/README.md create mode 100644 .preflight/config.yml create mode 100644 .preflight/contracts/example-api.yml create mode 100644 .preflight/triage.yml diff --git a/.preflight/README.md b/.preflight/README.md new file mode 100644 index 0000000..39c6ef3 --- /dev/null +++ b/.preflight/README.md @@ -0,0 +1,28 @@ +# `.preflight/` — Project Configuration + +This directory contains example configuration files for preflight. Copy it to your project root and customize. + +## Files + +| File | Purpose | +|------|---------| +| `config.yml` | Main config — profile, related projects, thresholds, embeddings | +| `triage.yml` | Triage rules — keywords that control prompt classification | +| `contracts/*.yml` | Manual contract definitions that supplement auto-extraction | + +## Quick Setup + +```bash +# Copy the example config to your project +cp -r /path/to/preflight/.preflight /path/to/your/project/ + +# Edit to match your setup +$EDITOR your-project/.preflight/config.yml +``` + +## Notes + +- All fields are optional — defaults are sensible +- `.preflight/` config takes precedence over environment variables +- Commit this directory to share settings across your team +- See the main [README](../README.md#configuration-reference) for full docs diff --git a/.preflight/config.yml b/.preflight/config.yml new file mode 100644 index 0000000..1e2a533 --- /dev/null +++ b/.preflight/config.yml @@ -0,0 +1,30 @@ +# .preflight/config.yml — Example configuration +# Copy this directory to your project root and customize. +# Every field is optional — defaults are sensible. + +# Profile controls overall verbosity: +# "minimal" — only flag ambiguous+, skip clarification detail +# "standard" — default behavior +# "full" — maximum detail on every non-trivial prompt +profile: standard + +# Related projects for cross-service contract awareness. +# When a prompt mentions keywords from a related project, +# preflight escalates to cross-service triage and pulls +# relevant types, interfaces, and routes automatically. +related_projects: + # - path: /absolute/path/to/auth-service + # alias: auth-service + # - path: /absolute/path/to/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 configuration +embeddings: + provider: local # "local" (Xenova, zero config) or "openai" + # openai_api_key: sk-... # Only needed if provider is "openai" diff --git a/.preflight/contracts/example-api.yml b/.preflight/contracts/example-api.yml new file mode 100644 index 0000000..96711d3 --- /dev/null +++ b/.preflight/contracts/example-api.yml @@ -0,0 +1,39 @@ +# .preflight/contracts/example-api.yml — Example manual contract +# Define contracts that supplement auto-extraction from code. +# Manual definitions win on name conflicts with auto-extracted ones. +# +# Use this for: +# - External API contracts not in your codebase +# - Shared types that live in a separate repo +# - Business-domain types that aren't in code yet + +- name: User + kind: interface + description: Core user record + fields: + - name: id + type: string + required: true + - name: email + type: string + required: true + - name: role + type: "'admin' | 'member' | 'guest'" + required: true + - name: createdAt + type: Date + required: true + +- name: ApiResponse + kind: interface + description: Standard API response envelope + fields: + - name: success + type: boolean + required: true + - name: data + type: T + required: false + - name: error + type: string + required: false diff --git a/.preflight/triage.yml b/.preflight/triage.yml new file mode 100644 index 0000000..707d6b0 --- /dev/null +++ b/.preflight/triage.yml @@ -0,0 +1,36 @@ +# .preflight/triage.yml — Example triage rules +# Controls how the triage classifier routes prompts. + +rules: + # Prompts containing these words → always at least AMBIGUOUS. + # Add domain-specific terms that are often under-specified. + always_check: + - rewards + - permissions + - migration + - schema + # - billing # uncomment for billing-heavy projects + # - deploy # uncomment if deploys need extra scrutiny + + # Prompts containing these words → TRIVIAL (pass through). + # Safe, well-understood operations that don't need triage. + skip: + - commit + - format + - lint + - prettier + + # Prompts containing these words → CROSS-SERVICE. + # Triggers contract search across related_projects. + cross_service_keywords: + - auth + - notification + - event + - webhook + # - payments # uncomment if you have a payments service + +# How aggressively to classify: +# "relaxed" — more prompts pass as clear +# "standard" — balanced (recommended starting point) +# "strict" — more prompts flagged as ambiguous +strictness: standard diff --git a/README.md b/README.md index f60fefa..e2bfe5b 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 +> **💡 Starter configs included!** Copy the `.preflight/` directory from this repo into your project root for ready-to-customize example configs with inline comments. See [`.preflight/README.md`](.preflight/README.md). + ### `.preflight/config.yml` Drop this in your project root. Every field is optional — defaults are sensible.