devkit:standards

What this skill does

# Standards

Central reference for all technology decisions and coding principles.

## Philosophy

Technology-agnostic meta principles. All reference files inherit from these.

- **Code is the single source of truth** — keep knowledge in code, not in separate documents. Prefer inline comments over external docs. If something needs explaining, put the explanation next to the code it describes
- **Make everything mechanically detectable** — never rely on human review
- **Prefer tests and lint rules over documentation** — tests and lint rules are executable, self-verifying, and fail loudly when wrong. Documentation rots silently and misleads AI agents. See `references/documentation.md`
- **For each new convention, build a lint rule or test first** — approach from type-system, lint, and test angles before writing prose
- **Fail fast** — don't swallow errors. Let them surface immediately
- **Log aggressively, but at the right layer** — see `references/observability.md`
- **No implicit fallbacks** — no default values or silent recovery that hide failures
- **No dummy code or NO-OP implementations** — no empty functions with TODO comments, no validations that always return true
- **Validate all environment variables at startup** — never use `process.env` directly. Validate and type env vars at the module boundary. Missing or invalid vars must crash immediately, not silently produce undefined. Never skip validation — inject dummy values instead when needed in non-production contexts. See `references/coding-standards.md` for the concrete pattern and stack-specific references for tool choice (t3-env or valibot)
- **Audit dependencies in CI** — run the audit command that matches the repository's package manager when it provides real signal. Pin major versions and review upgrades, but do not cargo-cult `pnpm audit` into repos that intentionally use a different toolchain
- **Document intentional deviations in the repo** — if a project intentionally violates a devkit standard, record it in `docs/devkit-intentional-violation.md` with the reason and the review date. Unwritten exceptions do not exist
- **Functional style** — prefer map/filter over array.push
- **No unnecessary options or defaults** — YAGNI

## Project-Specific Overrides

Inject any documented intentional deviations from the current repository before applying the base standards:

!`bun ${CLAUDE_SKILL_DIR}/scripts/expand-intentional-violations.ts .`

## Bundled Resources

<!-- REFERENCES_START — AUTO-GENERATED by inject-references.ts — DO NOT EDIT MANUALLY -->

### References

- **`references/ai-harness.md`** — AI harness engineering — Hook feedback loops, error message design for agents, and AGENTS.md design principles
- **`references/backend.md`** — Backend tech stack — Hono framework, Drizzle ORM, better-auth, awilix, environment validation, and error handling conventions
- **`references/cli.md`** — CLI tech stack and conventions — Bun, citty, Biome, TypeScript conventions, and code quality examples
- **`references/coding-standards.md`** — Cross-stack coding standards — environment variable validation patterns and other concrete conventions that apply to all stacks
- **`references/documentation.md`** — Documentation principles — what to put in a repository, what not to, and why tests/lint beat prose
- **`references/ecosystem.md`** — Foundation ecosystem — Node.js, pnpm, Turborepo, tsx, Bun, mise, and script execution policy
- **`references/observability.md`** — Observability policy — logging, metrics, tracing, error tracking, and AI agent access
- **`references/parallel-dev.md`** — Parallel development with git worktrees — automated setup, environment isolation, and dynamic port allocation
- **`references/quality-automation.md`** — Quality automation tools — oxlint, ESLint custom plugins, oxfmt, steiger, tsgo, knip, lefthook, Renovate, CI required checks, claude-code-action auto-fix, and automation-as-lint policy
- **`references/test.md`** — Test policy — Vitest framework, Storybook visual testing with CSF factories, co-located files, what to test, mocking strategy, and coverage expectations
- **`references/web.md`** — Web stack — Next.js App Router, TanStack Query/Form, shadcn/ui, FSD customization, and dehydrate pattern
<!-- REFERENCES_END -->