---
name: engineering-standards
description:
  "Engineering taste and coding standards for TypeScript/Effect-heavy codebases. Use when reviewing
  or writing code where subjective standards matter: naming, module boundaries, abstractions, type
  safety, tests, comments, exported API documentation, or docs/ADRs. Stack-agnostic taste layer only
  for non-TypeScript code."
---

# Engineering Standards

Use this skill as the cross-cutting standard for what good code should look like. Specialist skills
still own exact framework mechanics; this skill owns the engineering taste layer.

## Operating Rule

Read the repo first. Project `AGENTS.md`, existing code, and framework-specific skills override
generic guidance here when they are current and intentional. When local code is inconsistent, prefer
the rules in this skill unless the inconsistency is clearly a migration state.

## Workflow

1. Map the local surface: package manager, framework, module shape, tests, docs, and current dirty
   changes.
2. Identify the relevant standard area and read only the matching reference. For Effect, resolve the
   consumer's exact installed version before applying API-specific advice.
3. Apply the standard directly in code review or implementation.
4. Separate hard findings from taste calls:
   - **Bug/risk:** correctness, type safety, runtime, security, data loss.
   - **Standards mismatch:** naming, layering, tests, docs, abstraction shape.
   - **Preference question:** a real tradeoff that the repo does not decide.

## Reference Routing

| Situation                                                                    | Read                                                               |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Broad quality posture, exported docs, comments, failure defaults             | [references/principles.md](references/principles.md)               |
| After a change, a sweep, or "does this actually work"                        | [references/prove-it-works.md](references/prove-it-works.md)       |
| Terms where this codebase takes a position (failure split, `_tag`, CF seams) | [references/vocabulary.md](references/vocabulary.md)               |
| TypeScript + Effect module/service/storage/API shape, derivation             | [references/typescript-effect.md](references/typescript-effect.md) |
| Module/interface/adapter/dependency design, deletion test                    | [references/modules.md](references/modules.md)                     |
| Naming functions, modules, files, jobs, queues, routes, constants            | [references/naming.md](references/naming.md)                       |
| Testing strategy, mocks, fakes, runtime boundaries                           | [references/testing.md](references/testing.md)                     |
| Helpers, wrappers, compatibility, duplication, defensive code                | [references/abstractions.md](references/abstractions.md)           |
| `.scratchpad`, durable docs, ADRs, JSDoc policy                              | [references/docs-and-adrs.md](references/docs-and-adrs.md)         |
| Adversarial review posture, finding bar, severity, review lenses             | [references/review-lens.md](references/review-lens.md)             |

## Tech Stack Defaults

When the repo does not already decide:

- TypeScript backend and application code: prefer Effect-first architecture. Use the `effect` skill
  for exact APIs and mechanics.
- Command-line tools: prefer Effect v4 `effect/unstable/cli`. Use `building-clis` for CLI design and
  agent-readiness, and the `effect` skill for the exact API.
- Web apps: prefer TanStack Start for new TypeScript apps. Use `tanstack-start` for framework
  patterns.
- Cloudflare apps: prefer Workers, Queues, Workflows, Durable Objects, KV, R2, Hyperdrive, and
  service bindings where they match the product boundary. Use `cloudflare` for platform details.
- React UI: use direct framework idioms and the existing design system. Use `react-best-practices`,
  `react-composition-patterns`, and `design-engineering` as needed.
- Swift apps: prefer TCA-style feature/reducer organization. Defer Swift/TCA/SpriteKit mechanics to
  `swift-composable-architecture`, `ios-development`, `macos-development`, or
  `spritekit-development`.
- Logging and observability: prefer wide, structured events (canonical log lines) over scattered
  string logs; debuggability is the first decision priority. Use `logging-best-practices` for event
  shape and `observability` for the implementation layer — Pino, request-ID middleware, Axiom,
  redaction, Sentry. For Workers-specific telemetry, use the `cloudflare` skill's observability
  references.
- Exploratory product QA: use `qa`; this skill only supplies engineering review standards.

## Non-Negotiables

- Make the durable domain model obvious.
- Model lifecycle and state explicitly.
- Preserve type information across boundaries.
- Derive literal unions, protocol shapes, and config keys from their canonical schema/model instead
  of restating them.
- Test through the smallest real boundary that proves the behavior.
- Prove the real artifact, not a proxy, a compile, or a self-report.
- Promote durable architecture decisions to tracked docs/ADRs; keep active planning in
  `.scratchpad`.