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:

1. They read AGENTS.md and immediately understand the entire architecture
2. They follow documented patterns with confidence
3. 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 repo ships Agent Skills under .agents/skills/. The folder is the only content under .agents today: each skill is a subdirectory with a SKILL.md file (YAML frontmatter plus instructions) that the AI applies when your task matches the skill’s description, or when you invoke the workflow explicitly.

Skill	Description
create-component	Scaffolds a UI component with implementation, index, tests, and Storybook stories following PageZERO conventions (packages/ui or feature apps/{feature}/components)
change-theme	Updates the shadcn/ui theme by editing OKLCH CSS custom properties in apps/core/styles/tailwind.css
create-pr	Opens a GitHub pull request with conventional branch naming, creating a branch from main/master when needed, then pushing and creating the PR
merge-pr	Squash-merges the open PR for the current branch after checks pass, then cleans up the branch (no PR number—the skill uses the branch context only)

How to use them:

• Ask in plain language. For example: add a component in packages/ui, tweak light/dark primary colors, open a PR for your changes, or merge the PR for the branch you have checked out. Cursor loads project skills when the workspace opens; the agent picks a skill when your request matches its description.
• Invoke by name. In Agent chat, type /, then search for the skill (e.g. /create-component, /merge-pr) to run that workflow explicitly.

Skills encode structured workflows: gather requirements, follow repo conventions, and produce consistent output.