devkit-standards

name

devkit:standards

description

This skill should be used when the user asks to "set up a project", "choose a tech stack", "establish coding standards", "configure linting", "set up tests", "pick a framework", "review code quality", "set up logging", "configure observability", "choose an ORM", "set up auth", "set up Storybook", "write stories", "visual testing", "CSF", "coverage threshold", or discusses any technology choices for a TypeScript project. Also use when starting a new project, setting up CI/CD, choosing between tools (oxlint vs ESLint, pnpm vs npm), configuring environment variables, or when any other devkit skill needs to reference project conventions. This is the central reference for all devkit technology decisions and coding principles.

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

Scripts

• scripts/expand-intentional-violations.ts

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