Inngest Brownfield Audit

Inngest Brownfield Audit

Use this skill when the user asks Codex to inspect an existing codebase, add Inngest "where it makes sense", migrate fragile background work, or find durability gaps before making changes.

This is an agent-first workflow. Do the audit from evidence in the repo, name the specific files and call sites that drove each conclusion, and make small integration moves that preserve current behavior.

When to Trigger

Use this skill for requests like:

• "Audit this repo for Inngest opportunities"
• "Add Inngest to this codebase"
• "Make our webhooks / cron jobs / background tasks reliable"
• "Find places where work can be lost on deploy or process crash"
• "Replace fragile polling, delayed jobs, or fire-and-forget promises"
• "Make this AI workflow / agent durable"

If the user is starting from scratch instead of a brownfield repo, use inngest-setup, inngest-durable-functions, inngest-events, inngest-steps, and, for AI workflows, the agent patterns in this skill. Use inngest-agent-evals when the request includes scoring, sessions, experiments, deferred scorers, Insights, or outcome-based evaluation.

Audit Loop

1. Map the project shape.

   • Read package.json, workspace files, app/router structure, server entry points, deployment config, and test scripts.
   • Identify framework: Next.js App Router, Next.js Pages Router, Express, Hono, Fastify, Remix, SvelteKit, Astro, NestJS, worker-only service, or other.
   • Detect package manager and TypeScript conventions before adding files.

2. Find existing Inngest usage.

   • Search for inngest, createFunction, serve(, /api/inngest, INNGEST_, step.run, step.sleep, step.waitForEvent, step.sendEvent, step.invoke, step.ai, inngest.send, and @inngest/realtime.
   • If Inngest exists, inspect version, client config, serve endpoint, registered functions, event naming, env vars, and v3/v4 API shape before changing anything.

3. Find durability gaps.

   • Search for fire-and-forget work: void someAsync(), un-awaited promises, .then( chains, setTimeout, setInterval, detached jobs after HTTP response, and background work in route handlers.
   • Search for cron and schedulers: cron, node-cron, agenda, bull, bullmq, bee-queue, qstash, sqs, temporal, trigger.dev, deployment cron config, and scheduled API routes.
   • Search for webhooks and at-least-once producers: Stripe, Clerk, GitHub, Slack, Shopify, HubSpot, Linear, Svix, and generic webhook.
   • Search for long-running work: PDF generation, exports, video/image processing, embeddings, bulk email, imports, ETL, sync jobs, polling loops, retries, and external API calls.
   • Search for AI agent shapes: tool loops, LLM calls, streaming tokens, human approval, multi-step reasoning, vector search, eval loops, scoring, experiment assignment, user-feedback signals, and provider calls that need rate limits or retry-safe state.

4. Classify each candidate.

   • P0: user-visible loss, duplicate charge/email/action, timeout, missed webhook, or crash-prone workflow.
   • P1: fragile but recoverable background work, manual retry burden, noisy 429s, or poor observability.
   • P2: cleanup, ergonomics, or future migration opportunity.
   • For each candidate, record: file, current trigger, side effects, idempotency key, failure mode, recommended Inngest primitive, migration size, and confidence.

5. Choose the smallest safe integration.

   • Prefer one vertical slice over a wide rewrite.
   • Keep existing domain functions and data models where possible.
   • Add an Inngest client and serve endpoint only once.
   • Move side effects into step.run one boundary at a time.
   • Make event IDs and database writes idempotent before adding retries.
   • Add tests around existing behavior and the new event/function boundary.

Useful Discovery Commands

Run commands that fit the repo. Prefer rg; keep output focused.

rg -n "inngest|createFunction|step\\.|serve\\(|/api/inngest|INNGEST_" .
rg -n "setTimeout|setInterval|Promise\\.all|void [a-zA-Z0-9_]+\\(|\\.then\\(" .
rg -n "cron|node-cron|schedule|bull|bullmq|bee-queue|agenda|qstash|sqs" .
rg -n "webhook|stripe|svix|clerk|github|shopify|slack|hubspot|linear" .
rg -n "retry|backoff|poll|status|timeout|429|rate limit|rate-limit" .
rg -n "openai|anthropic|ai\\.|generateText|streamText|tool|agent|embedding" .

When the repo is large, narrow searches to app source directories and exclude generated/vendor folders.

Brownfield Decision Matrix

Integration Plan Format

Before editing, summarize findings in this compact shape:

Inngest audit:
- Existing Inngest: none / partial / healthy / risky
- Framework: <framework and evidence>
- Best first slice: <file + workflow>
- Why: <loss/timeout/retry/idempotency failure>
- Proposed primitives: <event, steps, flow control, waits, realtime>
- Idempotency key: <source of truth>
- Files likely touched: <short list>
- Tests/checks: <commands or focused cases>

Then implement unless the user asked for audit-only.

Existing Inngest Checklist

If Inngest is already present, verify:

• A single shared client is exported from a stable module.
• The app id is a stable slug and is not derived from deploy-specific data.
• v4 local development uses INNGEST_DEV=1; production uses INNGEST_SIGNING_KEY.
• Serve endpoint path is discoverable, usually /api/inngest.
• The serve handler registers all functions that should sync.
• Side effects and non-deterministic work are inside steps.
• Step IDs are stable and descriptive.
• Event names follow domain/noun.verb.
• Events that may be replayed use deterministic IDs.
• Webhook handlers verify signatures before emitting events.
• Flow control is configured where external APIs have limits.
• Realtime uses v4 native inngest/realtime, not the v3 @inngest/realtime package.