fix: use shellRun for non-git shell commands

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/` Example Config
+
+Copy this directory into your project root to configure preflight:
+
+```bash
+cp -r examples/.preflight /path/to/your/project/
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `config.yml` | Main config — profile, related projects, thresholds, embeddings |
+| `triage.yml` | Triage rules — which keywords trigger which classification level |
+| `contracts/*.yml` | Manual contract definitions — supplement auto-extraction |
+
+## Quick Setup
+
+1. Copy the directory: `cp -r examples/.preflight ./`
+2. Edit `config.yml` — set your `related_projects` paths
+3. Edit `triage.yml` — add your domain-specific keywords to `always_check`
+4. Optionally add contracts in `contracts/` for planned or external APIs
+5. Commit `.preflight/` to your repo so your team shares the same config
+
+All fields are optional. Defaults work well out of the box — only customize what you need.

examples/.preflight/config.yml

@@ -0,0 +1,29 @@
+# .preflight/config.yml — drop this in your project root
+# All fields are optional. Defaults are sensible.
+# See: https://github.com/TerminalGravity/preflight#configuration-reference
+
+# 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 awareness
+# Preflight will search these projects' indexes when your prompt
+# touches shared contracts (types, routes, schemas).
+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"

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,38 @@
+# .preflight/triage.yml — controls the triage classification engine
+# Customize which prompts get flagged, skipped, or escalated.
+
+rules:
+  # Prompts containing these words → always at least AMBIGUOUS
+  # Add domain terms that are too vague without context
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+    # - billing        # uncomment for your domain
+    # - onboarding
+
+  # Prompts containing these words → TRIVIAL (pass through immediately)
+  # Common low-risk commands that don't need analysis
+  skip:
+    - commit
+    - format
+    - lint
+    - "git status"
+    - "git log"
+
+  # Prompts containing these words → CROSS-SERVICE
+  # Triggers search across related_projects defined in config.yml
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+    # - payment
+    # - analytics
+
+# How aggressively to classify
+# "relaxed"  — more prompts pass as clear (faster, less interruption)
+# "standard" — balanced (recommended)
+# "strict"   — more prompts flagged as ambiguous (thorough, more interruptions)
+strictness: standard

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/))