add .preflight/ config example directory

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

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.

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

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