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