Standards

Coding conventions for Catalyst projects. Clarity over cleverness.

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.

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

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

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

Quality expectations by stage

Code quality requirements change as you progress from POC to Production. See the Code & Testing Audit for stage-specific expectations and detailed checklists.

Reference

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