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 -->