Standards

Reference~5 min

Coding conventions for Catalyst projects. Clarity over cleverness.

Read this when you start coding or before your first PR.
These conventions help both humans and AI write consistent, maintainable code.

Philosophy

Catalyst prioritises clarity over cleverness. Code should be simple, explicit, and easy for both humans and AI to read and modify. No over-abstraction. No premature optimisation.

Core Rules

Keep it simple

No over-abstraction or over-engineering. Prefer straightforward solutions.

Be explicit

Avoid implicit behavior. Name things clearly. Make types explicit.

Document the why

Comments explain WHY, not what. Let the code speak for itself.

Use consistent patterns

Same patterns throughout. Inconsistency confuses humans and AI.

AI-Friendly Code

Patterns that help AI agents understand and modify your code correctly.

AI works best with predictable, well-structured code.

Simple is better

Prefer straightforward solutions. AI struggles with clever abstractions and indirection.

Minimal abstraction

Only abstract when there's clear repetition. Don't preemptively abstract 'just in case'.

Good file structure

One concept per file. Clear naming. Logical folder organisation.

Explicit types

TypeScript types help AI understand intent. Avoid 'any' and implicit types.

File Headers

Every new file should include a header comment.

/**
 * CATALYST - {File Purpose}
 *
 * Brief description of what this file does.
 */

UI components in components/ui/ include source tracking:

/**
 * CATALYST - Button Component
 *
 * @source shadcn/ui v3.6.2 + @base-ui/react v1.0.0
 * @customised No — stock component
 */

Configuration

Key files that control app behavior.

lib/config.ts

App name, feature flags, external links. Never hardcode.

lib/navigation.ts

Navigation items for all layouts. Data, not JSX.

AGENTS.md

AI agent conventions. Point your agents here.

.env.local

Environment variables. Copy from .env.example.

Review Expectations

POC stage

  • • Lightweight review
  • • Focus on "does it work?"
  • • No blocking on style issues

MVP+ stages

  • • Full code review required
  • • Check for security issues
  • • Verify test coverage
  • • Enforce coding standards

What NOT to Do

Common mistakes to avoid.

  • ✗Over-abstract or over-engineer
  • ✗Add defensive fallbacks without need
  • ✗Invent scope beyond provided docs
  • ✗Duplicate config values
  • ✗Hardcode URLs — use config.links
  • ✗Create new UI when components exist

For AI Agents

See AGENTS.md in the repo root for the complete AI agent reference with all conventions, guardrails, and examples.

Next Steps

Where to go from here:

Code & Testing Audit

Stage-specific quality expectations and detailed checklists.

Helpers

Built-in utilities, hooks, and shared components.

Setup

Get your environment running if you haven't already.

Core Components

Stack, Row, Grid, Text, Title — the primitives you'll use everywhere.