Core Conventions

Reusable, project-agnostic conventions designed to keep codebases scalable and
easy for AI agents to navigate.

When to Use

Use this skill when:

• Starting a new feature and deciding where code should live
• Refactoring to improve maintainability
• Enforcing “one-thing-per-file” discipline
• Establishing naming/layout conventions and boundary rules

Non-Negotiables (MUST)

• Keep many small, focused files with explicit boundaries.
• One exported symbol per file for your own modules
  (component/hook/function/type).
• No barrel/index files (e.g. index.ts) that hide dependencies.
• No inline types outside types/.
• No helper functions inside components or hooks; extract to utils/.
• Avoid adding new dependencies for trivial helpers unless explicitly approved.

Placement / Boundaries

• Route/pages: app/**
• Reusable UI: components/<area>/...
• Orchestration (state/effects): hooks/<area>/useXxx.ts
• Pure logic: utils/<area>/xxx.ts
• External boundaries (network/DB/auth/storage): services/<area>/xxx.ts
• Shared shapes: types/<area>/Xxx.ts

Rules

Core Principles

• core-agent-defaults - Agent behavior defaults (small changes, ask questions,
  avoid dependencies)
• core-code-style - Code style guidelines (English-only, pure functions, avoid
  nesting)
• core-repo-hygiene - Repository hygiene (no barrel files, one responsibility,
  thin handlers)

Boundaries & Placement

• core-boundaries-decision-tree - Decision tree for where code belongs (app,
  components, hooks, utils, services, types)
• core-boundaries-hard-rules - Hard rules for boundaries (one export, no
  inline types, no helpers in components)

Naming & Layout

• core-naming-folder-layout - Folder structure conventions
• core-naming-file-naming - File naming conventions (PascalCase, camelCase,
  kebab-case)
• core-naming-exports - Export conventions (default vs named, Next.js
  exceptions)
• core-naming-imports - Import conventions (no barrel files, relative vs
  aliases)

Services vs Utils

• core-services-vs-utils-contract - When to use services/ vs utils/
• core-services-vs-utils-api - API guidance for services and utils
• core-services-vs-utils-route-handlers - Route handler requirements

Anti-Patterns

• core-anti-patterns-file-structure - File structure anti-patterns (multiple
  exports, barrel files, misc modules)
• core-anti-patterns-types - Type anti-patterns (inline types, huge type
  files)
• core-anti-patterns-react - React anti-patterns (fetching in components,
  helpers in components)
• core-anti-patterns-app-router - App Router anti-patterns (fat handlers,
  unvalidated input)
• core-anti-patterns-dependencies - Dependency anti-patterns (trivial helpers)
• core-anti-patterns-vite-browser - Vite/Browser runtime anti-patterns
  (process.env, Node globals)

Related Skills

• busirocket-typescript-standards - TypeScript-specific standards
• busirocket-react - React component, hook, and state (Zustand) patterns
• busirocket-refactor-workflow - Refactoring workflow

How to Use

Read individual rule files for detailed explanations and code examples:

rules/core-agent-defaults.md
rules/core-boundaries-decision-tree.md
rules/core-naming-folder-layout.md

Each rule file contains:

• Brief explanation of why it matters
• Code examples (correct and incorrect patterns)
• Additional context and best practices