diff --git a/README.md b/README.md index 6d03f5d..a00f10c 100644 --- a/README.md +++ b/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) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard) · [Workflow Examples](examples/WORKFLOWS.md) diff --git a/examples/README.md b/examples/README.md index 778f15d..a61e9a4 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,5 +1,11 @@ # Examples +## [Workflow Examples](WORKFLOWS.md) + +Real-world usage patterns showing how preflight tools chain together — vague bug fixes, multi-file refactors, pre-commit checks, onboarding, cost tracking, and more. + +--- + ## `.preflight/` Config Directory The `.preflight/` directory contains example configuration files you can copy into your project root: diff --git a/examples/WORKFLOWS.md b/examples/WORKFLOWS.md new file mode 100644 index 0000000..f386607 --- /dev/null +++ b/examples/WORKFLOWS.md @@ -0,0 +1,183 @@ +# Workflow Examples + +Real-world usage patterns showing how preflight tools chain together in practice. + +--- + +## 1. The Vague Bug Fix + +You type: `fix the auth bug` + +**Without preflight:** Claude guesses which bug, edits the wrong file, you correct it twice. ~12K tokens wasted. + +**With preflight:** + +``` +You: fix the auth bug + +→ preflight_check triages as "ambiguous" (no file path, no specific bug) +→ clarify_intent fires automatically +→ Returns: + + ⚠️ Ambiguous prompt — 3 possible targets: + 1. JWT refresh not triggering on 401 (src/auth/jwt.ts:47) + 2. OAuth callback returning 404 (src/auth/oauth.ts:112) + 3. Session cookie missing SameSite flag (src/middleware/session.ts:23) + + Recent correction history: You fixed #1 last week but it regressed. + Suggestion: "Fix JWT refresh regression in src/auth/jwt.ts — the 401 retry logic from commit a3f2c1 stopped working after the axios upgrade" + +You: [pick option 1, use the sharpened prompt] +→ Done in one pass. ~4K tokens. +``` + +## 2. Multi-File Refactor Planning + +You type: `refactor the API layer to use tRPC instead of REST` + +``` +→ preflight_check triages as "multi-step" +→ scope_work runs: + + 📋 Work Scope Analysis + ────────────────────── + Estimated scope: LARGE (15-25 files, ~3-5 sessions) + + Files involved: + ├── src/pages/api/*.ts (12 REST endpoints → tRPC routers) + ├── src/lib/api-client.ts (fetch calls → tRPC client) + ├── src/types/api.ts (manual types → inferred from routers) + └── tests/api/*.test.ts (all need rewriting) + + Cross-service contracts found: + - mobile-app/src/api.ts imports shared types from @myapp/types + - admin-dashboard/src/hooks/useApi.ts calls 6 of these endpoints + + ⚠️ Breaking changes for 2 downstream consumers. + + Suggested sequence: + 1. Install tRPC, create root router (1 session) + 2. Migrate endpoints one-by-one, keeping REST alive (2-3 sessions) + 3. Switch clients, remove REST layer (1 session) + 4. Update downstream consumers (1 session) + +→ sequence_tasks breaks this into checkpointed steps +``` + +## 3. "Ship It" Without Checking + +You type: `commit and push` + +``` +→ preflight_check triages as "trivial command" but runs verify_completion first: + + 🔍 Pre-push checks: + ├── ✅ TypeScript: no errors + ├── ❌ Tests: 2 failing (auth.test.ts:34, auth.test.ts:67) + ├── ⚠️ Unstaged files: 3 modified files not in this commit + └── ⚠️ No conventional commit message provided + + Recommendation: Fix the 2 test failures before pushing. + Staged files: src/auth/jwt.ts, src/auth/oauth.ts + Unstaged: src/middleware/session.ts, tests/auth.test.ts, README.md + +You: [fix tests first, then push with a proper commit message] +``` + +## 4. New Team Member Onboarding + +Starting work on an unfamiliar codebase: + +``` +You: I just joined this project, help me understand the codebase + +→ onboard_project runs: + + 📖 Project: my-saas-app + ────────────────────── + Stack: Next.js 14 + Prisma + Supabase + Stripe + Structure: App Router, 47 routes, 3 API namespaces + + Key patterns from 512 past sessions: + - Auth uses Supabase Auth with custom JWT claims + - Payments go through src/lib/stripe/ (webhook-driven) + - DB migrations are in prisma/migrations/ (27 total) + - Tests use Vitest + Playwright (not Jest) + + Common pitfalls (from correction history): + - Don't use `getServerSession` in API routes — use `auth()` from next-auth + - Stripe webhooks need raw body parsing (see src/app/api/webhooks/stripe/route.ts) + - The `user` table has soft deletes — always filter by `deleted_at IS NULL` + + Hot files (most edited in last 30 days): + 1. src/app/(dashboard)/settings/page.tsx (23 edits) + 2. src/lib/stripe/subscriptions.ts (18 edits) + 3. prisma/schema.prisma (12 edits) +``` + +## 5. Cost-Conscious Session Management + +Midway through a long session: + +``` +You: how much have I spent on this session? + +→ session_stats + estimate_cost: + + 📊 Session Stats + ──────────────── + Duration: 2h 14m + Messages: 47 (you: 23, Claude: 24) + Tokens: ~180K in, ~95K out + Estimated cost: $4.12 + + Waste analysis: + - 3 correction cycles detected (~$0.90 wasted) + - 2 context compactions (session got too long) + - Suggestion: checkpoint now and start a fresh session + for the remaining work + +→ checkpoint creates a handoff summary for the next session +→ session_handoff generates a paste-ready context block +``` + +## 6. Catching Repeated Mistakes + +You've made the same error three times across sessions: + +``` +You: update the user schema to add a phone field + +→ preflight_check notices a pattern match: + + ⚠️ Correction pattern detected! + You've modified the User schema 3 times in the past week, + and each time forgot to: + 1. Update the Zod validation in src/lib/validations/user.ts + 2. Add the field to the API serializer in src/lib/serializers.ts + 3. Run `npx prisma generate` after migration + + Auto-expanding scope to include all 3 steps. +``` + +--- + +## Tool Chaining Reference + +| Scenario | Tools chained | +|----------|--------------| +| Vague prompt | `preflight_check` → `clarify_intent` → `prompt_score` | +| Big feature | `preflight_check` → `scope_work` → `sequence_tasks` → `search_contracts` | +| Pre-commit | `preflight_check` → `verify_completion` → `token_audit` | +| Debug session | `search_history` → `clarify_intent` → `check_patterns` | +| End of session | `session_stats` → `estimate_cost` → `checkpoint` → `session_handoff` | +| New codebase | `onboard_project` → `timeline_view` → `audit_workspace` | + +--- + +## Tips + +- **Always start with `preflight_check`** — it routes to the right tools automatically. You don't need to call individual tools unless you want to. +- **Set `CLAUDE_PROJECT_DIR`** so tools can find your files, git history, and past sessions. +- **Commit your `.preflight/` directory** — team members get the same triage rules and thresholds. +- **Review `log_correction` output weekly** — it shows recurring mistakes you can prevent with better prompts or project conventions.