AI-alignment

PageZERO architecture is designed from the ground up for AI-assisted development. Every structure, pattern, and convention exists to help AI coding assistants like Cursor, Copilot, and Claude understand, navigate, and modify code effectively.

Why this matters?

Codebase gives you a well-defined foundation that scales. When AI agents work with PageZERO:

They read AGENTS.md and immediately understand the entire architecture
They follow documented patterns with confidence
They generate code that matches your codebase style - every time

The result: faster iterations, fewer errors, and a codebase that gets better as AI tools improve.

Predictable Structure

The codebase follows a consistent, modular architecture:

Directoryapps/ Feature modules (auth, payments, user, etc.)
- Directoryfeature/
  - index.ts Public exports
  - Directorycomponents/ Feature-specific components
    …
  - Directoryroutes/ Route handlers
    …
  - Directorydb/ Database schema (if needed)
    …
Directorypackages/ Shared, reusable code
- Directoryui/ UI component library
  - …
- Directorydb/ Database utilities
  - …
- Directorytypes/ Shared TypeScript types
  - …

Each feature module is self-contained. AI agents can add new features by following existing module patterns and find related code in predictable locations.

Consistent Patterns

Component structure. Every UI component follows the same four-file pattern:

Directorycomponent-name/
- index.ts Re-exports public API
- component-name.tsx Implementation
- component-name.test.tsx Unit tests
- component-name.stories.tsx Storybook stories

Code generation. The built-in generator creates scaffolds that follow project conventions:

bun run generate component MyComponent packages/ui

Strict TypeScript. Explicit types throughout-component props, route loaders, database schema. AI agents understand function signatures without reading implementations.

TailwindCSS & shadcn/ui. AI models are extensively trained on Tailwind and shadcn patterns. The UI library uses familiar conventions-utility classes, cva for variants, Radix primitives-that AI assistants recognize and generate correctly out of the box.

Auto-formatting & linting. Biome handles both formatting and linting. AI-generated code gets normalized and checked automatically.

AGENTS.md

The project includes an AGENTS.md file at the root-a comprehensive guide written specifically for AI coding agents:

Project overview - tech stack, architecture, and directory structure
Coding conventions - TypeScript patterns, file naming, component structure
Step-by-step guides - how to add features, components, and database tables
Scripts reference - common commands and their usage
Key files - where to find routes, config, schema, and other important files

When an AI agent opens the project, it reads AGENTS.md and immediately understands how to write code that matches your codebase style.

Agent Skills

The project ships Agent Skills under .agents/skills/. Each skill is a folder containing a SKILL.md file with instructions the AI applies when the task matches the skill’s description (or when you ask for that workflow explicitly).

Skill	Description
`create-component`	Creates a new UI component with all four files (implementation, index, test, stories) following PageZERO conventions
`change-theme`	Modifies the shadcn/ui theme by updating CSS custom properties in OKLCH color space

How to use them:

Ask in plain language. Say what you want to do—for example, scaffold a button in packages/ui, or adjust primary colors in light and dark mode. Cursor loads project skills when the workspace opens; the agent picks up a skill when your request matches its description.
Invoke by name. In Agent chat, type /, then search for the skill (e.g. /create-component) to apply that workflow explicitly.

Skills encode the same structured workflows as before-gathering requirements, following conventions, and generating consistent output.