Improve .preflight/ example configs with clearer comments and practical defaults

README.md

@@ -12,7 +12,7 @@ A 24-tool MCP server for Claude Code that catches ambiguous instructions before
 [![npm](https://img.shields.io/npm/v/preflight-dev)](https://www.npmjs.com/package/preflight-dev)
 [![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)
 
-[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard)
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Usage Examples](examples/USAGE_EXAMPLES.md) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard)
 
 </div>
 
@@ -406,6 +406,12 @@ This prevents the common failure mode: changing a shared type in one service and
 
 ## Configuration Reference
 
+> **Want a ready-to-use starting point?** Copy the example configs:
+> ```bash
+> cp -r examples/.preflight /path/to/your/project/
+> ```
+> See [`examples/.preflight/README.md`](examples/.preflight/README.md) for details.
+
 ### `.preflight/config.yml`
 
 Drop this in your project root. Every field is optional — defaults are sensible.

examples/.preflight/README.md

@@ -0,0 +1,25 @@
+# `.preflight/` Config Directory
+
+Drop this directory into your project root to customize preflight behavior.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `config.yml` | Profile, related projects, thresholds, embedding provider |
+| `triage.yml` | Triage strictness and keyword rules |
+
+## Setup
+
+```bash
+cp -r examples/.preflight /path/to/your/project/
+```
+
+Edit the YAML files to match your project. All fields are optional — anything you omit uses sensible defaults.
+
+## Tips
+
+- **Commit this directory** to share settings across your team.
+- Add domain-specific keywords to `triage.yml` → `always_check` for areas where mistakes are costly (billing, permissions, migrations).
+- Add quick commands to `skip` so preflight doesn't slow you down on `commit`, `lint`, etc.
+- When working across multiple repos, add them to `related_projects` in `config.yml` for cross-service contract detection.

examples/.preflight/config.yml

@@ -0,0 +1,30 @@
+# .preflight/config.yml
+# Copy this directory to your project root and customize.
+# All fields are optional — defaults are shown below.
+
+# Profile controls how aggressively preflight intervenes:
+#   minimal  — only catch the most obvious vague prompts
+#   standard — balanced (default)
+#   full     — enforce structure on every prompt
+profile: standard
+
+# Related projects for cross-service contract detection.
+# Preflight will scan these for shared types, routes, and schemas.
+related_projects:
+  # - path: ../api-server
+  #   alias: api
+  # - path: ../shared-types
+  #   alias: types
+
+# Thresholds for session management and pattern detection.
+thresholds:
+  session_stale_minutes: 30            # Mark session stale after this long
+  max_tool_calls_before_checkpoint: 100 # Suggest checkpoint after N tool calls
+  correction_pattern_threshold: 3       # Warn after N similar corrections
+
+# Embedding provider for semantic search over session history.
+#   local  — runs entirely offline, no API key needed (default)
+#   openai — higher quality, requires OPENAI_API_KEY in env
+embeddings:
+  provider: local
+  # openai_api_key: sk-...  # or set OPENAI_API_KEY env var

examples/.preflight/contracts/api.yml

@@ -0,0 +1,47 @@
+# .preflight/contracts/api.yml — manual contract definitions
+# These supplement auto-extracted contracts from your codebase.
+# Manual definitions win on name conflicts with auto-extracted ones.
+#
+# Use this when:
+# - You have contracts that aren't in code yet (planned APIs)
+# - Auto-extraction misses something important
+# - You want to document cross-service agreements explicitly
+
+- 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: createdAt
+      type: Date
+      required: true
+
+- name: "POST /api/users"
+  kind: route
+  description: Create a new user account
+  fields:
+    - name: body
+      type: "{ email: string, role: string }"
+      required: true
+    - name: response
+      type: "{ user: User, token: string }"
+      required: true
+
+- name: "GET /api/users/:id"
+  kind: route
+  description: Fetch user by ID
+  fields:
+    - name: params
+      type: "{ id: string }"
+      required: true
+    - name: response
+      type: User
+      required: true

examples/.preflight/triage.yml

@@ -0,0 +1,40 @@
+# .preflight/triage.yml
+# Customize how the triage decision tree classifies your prompts.
+# All fields are optional — defaults are shown below.
+
+# Strictness controls the ambiguity detection sensitivity:
+#   relaxed  — fewer interruptions, only flags very vague prompts
+#   standard — balanced (default)
+#   strict   — flags anything without explicit file refs or scope
+strictness: standard
+
+rules:
+  # Keywords that ALWAYS trigger deeper inspection, even in short prompts.
+  # Add domain-specific terms where mistakes are expensive.
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+    # - billing
+    # - delete
+    # - production
+
+  # Keywords that mark a prompt as trivial (no inspection needed).
+  # These are low-risk commands that don't benefit from preflight checks.
+  skip:
+    - commit
+    - format
+    - lint
+    # - typecheck
+    # - test
+
+  # Keywords that trigger cross-service contract scanning.
+  # When detected, preflight looks for shared types/routes across related_projects.
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+    # - payment
+    # - queue

examples/USAGE_EXAMPLES.md

@@ -0,0 +1,205 @@
+# Usage Examples
+
+Real-world examples of preflight tools in action inside Claude Code.
+
+---
+
+## 1. Catching a Vague Prompt with `preflight_check`
+
+You type this into Claude Code:
+
+```
+fix the login bug
+```
+
+Preflight intercepts and returns:
+
+```
+⚠️ Ambiguity detected — routing to clarify_intent
+
+I found 3 potential login issues:
+  1. JWT token not refreshing on expiry (src/auth/jwt.ts:42)
+  2. OAuth callback returning 404 after redirect (src/auth/oauth.ts:118)
+  3. "Remember me" checkbox not persisting session (src/components/LoginForm.tsx:23)
+
+Which one? Or describe the symptoms and I'll narrow it down.
+```
+
+Instead of Claude guessing and editing the wrong file, you get a targeted question. One round-trip instead of three.
+
+---
+
+## 2. Scoping Work Before Coding with `scope_work`
+
+```
+> scope_work "Add rate limiting to the /api/upload endpoint"
+
+📋 Execution Plan
+─────────────────
+Goal: Add rate limiting to POST /api/upload
+
+Files to touch:
+  - src/api/routes/upload.ts (add middleware)
+  - src/middleware/rateLimit.ts (create)
+  - src/config/limits.ts (add upload limits)
+  - tests/api/upload.test.ts (add rate limit tests)
+
+Dependencies:
+  - Check if express-rate-limit is already installed
+  - Review existing middleware chain in src/api/index.ts
+
+Risks:
+  - Existing upload tests may break if rate limit hits in CI
+  - Need to decide: per-IP or per-user limiting?
+
+Estimated scope: ~120 lines across 4 files
+```
+
+---
+
+## 3. Enriching a Sub-Agent Task with `enrich_agent_task`
+
+You want to spawn a sub-agent for a refactor:
+
+```
+> enrich_agent_task "refactor the database queries to use the new ORM"
+
+📦 Enriched Task Brief
+──────────────────────
+Original: "refactor the database queries to use the new ORM"
+
+Context added:
+  - ORM: Drizzle (see drizzle.config.ts, src/db/schema.ts)
+  - 14 files with raw SQL queries (grep results attached)
+  - Existing patterns: src/db/queries/users.ts uses query builder already
+  - Related contracts: UserRecord, PostRecord types in src/types/db.ts
+  - Test coverage: 8/14 query files have corresponding tests
+
+Suggested task for sub-agent:
+  "Refactor raw SQL queries in src/db/queries/ to use Drizzle ORM.
+   Follow the pattern in src/db/queries/users.ts. Schema is in
+   src/db/schema.ts. Run `npm test -- --grep db` after each file.
+   14 files total — see list below."
+```
+
+The sub-agent gets everything it needs instead of fumbling through the codebase.
+
+---
+
+## 4. Resolving Vague Follow-ups with `sharpen_followup`
+
+After Claude fixes a bug, you say:
+
+```
+> do the same for the others
+```
+
+Without preflight, Claude guesses what "the others" means. With it:
+
+```
+> sharpen_followup "do the same for the others"
+
+🔍 Resolved "the others" from conversation context:
+
+You just fixed a missing null check in src/api/users.ts:34.
+Similar pattern found in 4 other files:
+  1. src/api/posts.ts:28 — same nullable field access
+  2. src/api/comments.ts:41 — same pattern
+  3. src/api/teams.ts:55 — same pattern
+  4. src/api/billing.ts:19 — slightly different (optional chain exists but incomplete)
+
+Shall I apply the fix to all 4?
+```
+
+---
+
+## 5. Checking Session Health with `check_session_health`
+
+```
+> check_session_health
+
+🏥 Session Health
+─────────────────
+⏱  Session duration: 47 min
+📝 Uncommitted files: 8 (⚠️ commit soon)
+🔄 Last commit: 38 min ago (⚠️ overdue)
+💬 Turn count: 23
+📊 Context usage: ~62% (healthy)
+🎯 Focus score: B (2 directory switches)
+
+Recommendation: Commit your current changes before continuing.
+Run `checkpoint` to save state.
+```
+
+---
+
+## 6. Searching Past Sessions with `search_history`
+
+```
+> search_history "how did we handle the Stripe webhook retry logic"
+
+🔍 Found 3 relevant results across 2 sessions:
+
+Session 2024-12-15 (confidence: 0.92)
+  "Implemented exponential backoff for Stripe webhook retries
+   in src/webhooks/stripe.ts. Uses 3 retries with 1s/4s/16s delays.
+   Idempotency key stored in Redis."
+
+Session 2024-11-28 (confidence: 0.78)
+  "Discussed webhook retry strategies. Decided against queue-based
+   approach due to infrastructure complexity. Went with in-process
+   retry with circuit breaker."
+```
+
+Never re-research decisions you already made.
+
+---
+
+## 7. Getting a Scorecard with `generate_scorecard`
+
+```
+> generate_scorecard type=trend period=week
+
+📊 Weekly Trend — Jan 20–26, 2025
+──────────────────────────────────
+Overall: B+ (78/100) ↑ from B (74) last week
+
+Improving:
+  ✅ Clarification: 82 → 89 (+7) — more file refs in prompts
+  ✅ Verification: 65 → 78 (+13) — running tests before done
+
+Declining:
+  ⚠️ Compaction Mgmt: 71 → 58 (-13) — 3 compactions without prior commit
+  ⚠️ Session Lifecycle: 80 → 72 (-8) — longer gaps between commits
+
+Top tip: Run `checkpoint` before long exploratory conversations
+to avoid losing work on compaction.
+```
+
+---
+
+## 8. Quick Prompt Grading with `prompt_score`
+
+```
+> prompt_score "update the thing"
+
+📝 Prompt Score: D (32/100)
+───────────────────────────
+Specificity:    F — no file, function, or component named
+Scope:          F — "the thing" is completely ambiguous
+Actionability:  D — "update" is vague (add? change? remove?)
+Done-condition: F — no way to verify completion
+
+Try: "Update the user avatar upload handler in src/api/users.ts
+to accept WebP format and add a test case"  → A (94/100)
+```
+
+---
+
+## Tips
+
+- **Start every session** with `preflight_check` on your first prompt — it'll route to the right tool automatically
+- **Use `checkpoint`** every 20–30 minutes or before exploring a new direction
+- **Run `search_history`** before implementing something — you may have solved it before
+- **Check `session_stats`** at the end of a session to spot waste patterns
+- **Set up `.preflight/config.yml`** to tune thresholds for your team (see [examples/.preflight/](/.preflight/))