Non-negotiable rules:

1. Read references/stack.md first to determine the runtime (Node.js or Bun), framework, and locked decisions.
2. Then load only the references needed for the actual task.
3. TypeScript strict mode — no any, no implicit returns, no unchecked index access.
4. All async functions must handle errors — no unhandled promise rejections. Use try/catch or .catch() at every boundary.
5. Input validation at system boundaries — Zod schemas on every external input (request bodies, query params, env vars, CLI args). Never trust req.body.
6. Structured logging via pino — no console.log in production code. JSON to stdout, parsed by log aggregators.
7. Graceful shutdown — handle SIGTERM/SIGINT, drain connections, finish in-flight work, close DB pools.
8. No secrets in code or logs — env vars validated at startup, never logged, never in error responses. </EXTREMELY-IMPORTANT>

nodejs

Inputs

• $request: The backend task, subsystem, bug, or feature being worked on

Goal

Route Node.js/Bun backend work through the project's conventions so implementation follows the established patterns for server architecture, data access, error handling, and deployment.

Step 0: Read the stack contract

Always start with:

• references/stack.md

That establishes: runtime (Node.js or Bun), framework (Express/Fastify/Hono/none), ORM, test runner, package manager, and locked dependency choices.

If bun.lockb or bunfig.toml exists, the runtime is Bun — also load references/bun-runtime.md for native API differences.

Success criteria: The project's runtime, framework, and toolchain choices are explicit before implementation starts.

Step 1: Load only the relevant references

Use the routing table to pick reference files. Do not bulk-load the full reference tree.

Multiple tasks? Read multiple files. The references are self-contained.

Success criteria: Only the task-relevant backend conventions are in play.

Step 2: Implement with the core backend guardrails

Keep these rules active:

• TypeScript strict mode with noUncheckedIndexedAccess
• all external input validated at the boundary (Zod schemas)
• errors are typed, caught, and returned as structured HTTP responses
• logging via pino child loggers with request correlation IDs
• database access through the project's ORM/query builder, not raw SQL strings
• mutations wrapped in transactions where atomicity matters
• graceful shutdown: SIGTERM handler drains server, closes pools, exits cleanly
• env vars validated at startup — fail fast on missing required config
• no any, no as type assertions unless justified with a comment
• if Bun runtime: prefer Bun.serve(), Bun.file(), bun test over Node.js equivalents

Success criteria: The change matches the project's backend architecture instead of generic defaults.

Step 3: Verify the affected surface

Use the narrowest relevant verification:

• unit tests (vitest run, jest, or bun test)
• integration tests with supertest or actual HTTP calls
• type checking (tsc --noEmit)
• linting (eslint .)
• if Docker: build the image and verify it starts

Success criteria: The changed backend surface still builds, type-checks, and passes tests.

Guardrails

• Do not inline the whole Node.js handbook in SKILL.md.
• Do not skip references/stack.md.
• Do not use console.log in production code — use pino.
• Do not bypass input validation at API boundaries.
• Do not leave unhandled promise rejections.
• Do not hardcode secrets, ports, or environment-specific values.
• Do not add disable-model-invocation; this is a normal domain skill.

When To Load References

• references/stack.md Always.

• references/bun-runtime.md When the project uses Bun (detected via bun.lockb or bunfig.toml).

• then only the task-relevant files under references/

Output Contract

Report:

1. which references were loaded
2. the architecture pattern chosen
3. the change made
4. the verification run