# Navigating the BuilderIO/agent-native Repository: Root Files Explained

> Understand the BuilderIO/agent-native root files. Discover how these files enable an action-centric architecture, sharing business logic across UI, agent, and API.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: internals
- Published: 2026-07-01

---

**The root of the BuilderIO/agent-native repository contains configuration manifests, governance documents, and automation scripts that enforce an action-centric architecture where business logic lives in SQL-backed actions and is shared across UI, agent, and API layers.**

The **agent-native** repository is BuilderIO’s open-source framework that tightly couples AI agents with UI, data, and business logic. Understanding the root-level files is essential for contributors and developers extending the platform, as these files define the monorepo structure, runtime contracts, and automated governance guardrails.

## Core Documentation and Governance

### README.md: Product Overview and Quick Start

The [`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md) serves as the primary entry point, documenting the framework’s philosophy that **actions are the single source of truth**. It contains the canonical `defineAction` example that demonstrates how a single action definition automatically powers UI components, the agent runtime, HTTP endpoints, MCP, A2A, and CLI interfaces.

According to the source code in [`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md) (lines 8-16), a minimal action looks like this:

```typescript
// One action powers UI, agent, HTTP, MCP, A2A, and CLI.
export default defineAction({
  schema: z.object({
    emailId: z.string(),
    body: z.string(),
  }),
  run: async ({ emailId, body }) => {
    await db.insert(replies).values({ emailId, body });
  },
});

```

*Source:* [README.md line 8-16](https://github.com/BuilderIO/agent-native/blob/main/README.md#L8-L16)

### AGENTS.md: Architecture Contract and Always-On Rules

[`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) functions as the constitution of the repository. It mandates the **four-area checklist** (UI, actions, skills, state) and defines the **Always-On Rules** that every contribution must satisfy. The document enforces strict contracts including:

- **SQL-backed state** via Drizzle-compatible databases
- **Action-centric design** prohibiting business logic in UI components
- **Client helpers** for data fetching patterns
- **No unscoped queries** in production code

This file references the exact architectural constraints implemented in the `packages/core` runtime.

## Package Management and Workspace Configuration

### package.json: Scripts and Dependency Overrides

[`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) declares the project metadata and critical dependency overrides. It pins essential packages like **React 19**, **Hono**, and **Kysely** to ensure compatibility across the monorepo.

As defined in [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) (lines 26-33), key development scripts include:

```bash
pnpm dev          # starts the dev server with hot-reload

pnpm dev:desktop  # launches the Electron desktop wrapper

```

The `pnpm` overrides section prevents version drift in shared dependencies across the workspace.

### pnpm-workspace.yaml: Monorepo Structure

[`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) defines the workspace glob patterns that PNPM uses to link packages:

```yaml
packages:
  - 'packages/*'
  - 'templates/*'

```

This configuration enables shared tooling and isolated versioning for framework packages (`packages/core`, `packages/dispatch`, `packages/scheduling`) while keeping template applications (`templates/clips`, `templates/plans`) separately buildable.

## Runtime Configuration Manifests

### agent-native.json: Capabilities Manifest

[`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json) is the runtime manifest describing the application’s capabilities, environment variables, and how the agent interacts with the host system. The core runtime consumes this file during bootstrap to initialize actions, skills, and extensions.

### registry.json: Dynamic Discovery

[`registry.json`](https://github.com/BuilderIO/agent-native/blob/main/registry.json) lists the built-in agents, extensions, and skill registries available to the framework. This manifest drives the **dynamic discovery** mechanism, allowing the runtime to load new capabilities without modifying core source code.

## Automation and CI/CD

### scripts/ Directory: Guard Scripts and Utilities

The `scripts/` folder contains TypeScript and Node.js automation utilities. Files prefixed with `guard-` enforce compliance with [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) policies during CI execution.

For example, `scripts/guard-no-drizzle-push.mjs` prevents accidental database pushes in production:

```javascript
// scripts/guard-no-drizzle-push.mjs
import { execSync } from "child_process";

try {
  execSync("git diff --name-only | grep drizzle-kit", { stdio: "ignore" });
  console.error("❌ Drizzle push detected – aborting build");
  process.exit(1);
} catch {
  // No drizzle-kit changes – safe to continue
}

```

*Source:* [guard-no-drizzle-push.mjs](https://github.com/BuilderIO/agent-native/blob/main/scripts/guard-no-drizzle-push.mjs)

The [`scripts/workspace-run.ts`](https://github.com/BuilderIO/agent-native/blob/main/scripts/workspace-run.ts) file serves as the entry point for executing type-checks, tests, and guards across all workspace packages.

### .github/workflows/: Continuous Integration

The `.github/workflows/` directory contains GitHub Actions pipelines that guarantee every pull request respects the architecture contract. The main CI pipeline ([`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml)) orchestrates linting, testing, and guard execution:

```yaml

# .github/workflows/ci.yml

name: CI
on: [push, pull_request]
jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: pnpm install
      - run: pnpm fmt:check
      - run: pnpm oxlint
      - run: pnpm test
      - run: pnpm guards

```

*Source:* [ci.yml line 1-20](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml)

Additional workflows handle PR visual recaps, Netlify preview deployments, and automated changelog releases via changesets.

## Development Tooling Configuration

Root-level dotfiles configure the development environment:

- **`.nvmrc`**: Pins the Node.js version for consistent builds
- **[`.oxlintrc.json`](https://github.com/BuilderIO/agent-native/blob/main/.oxlintrc.json)** and **[`.oxfmtrc.json`](https://github.com/BuilderIO/agent-native/blob/main/.oxfmtrc.json)**: Configure the Oxlint linter and formatter
- **`.prettierignore`**: Excludes generated files from formatting
- **[`eas.json`](https://github.com/BuilderIO/agent-native/blob/main/eas.json)**: Configures Expo Application Services for mobile builds

These files ensure environmental consistency across developer machines and CI runners.

## Starter Templates

### templates/ Directory: Full-Stack Examples

The `templates/` folder contains ready-to-run SaaS applications demonstrating the framework in production scenarios. Each template (Clips, Plans, Analytics) is a complete full-stack application following the same architectural contracts defined in [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md).

These templates serve as reference implementations for the **action-centric design** and **SQL-backed state** patterns, showing how to structure `actions/` directories and Drizzle schemas in real applications.

## Summary

- **[`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md)** and **[`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md)** form the governance layer, defining the action-centric philosophy and architecture contracts
- **[`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json)** and **[`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml)** configure the monorepo structure and dependency management
- **[`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json)** and **[`registry.json`](https://github.com/BuilderIO/agent-native/blob/main/registry.json)** provide runtime manifests for capability discovery and bootstrap
- **`scripts/`** and **`.github/workflows/`** enforce automated compliance with repository rules through guard scripts and CI pipelines
- **`templates/`** contains production-ready reference applications demonstrating framework patterns

## Frequently Asked Questions

### What is the purpose of AGENTS.md in the BuilderIO/agent-native repository?

[`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) is the repository's constitution that enforces architectural governance. It defines the **Always-On Rules** and **Architecture Contract** requiring SQL-backed state via Drizzle, action-centric business logic, and the four-area checklist (UI, actions, skills, state). Every contribution must comply with these rules, which are automatically enforced by guard scripts in CI.

### How does the monorepo structure work in agent-native?

The monorepo uses PNPM workspaces configured in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) to group `packages/*` (framework core) and `templates/*` (example applications). This structure enables code sharing through internal package dependencies while allowing isolated versioning and publishing via changesets. The [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) at the root provides shared scripts and dependency overrides that apply across all workspaces.

### What are guard scripts and why are they important?

Guard scripts are automation utilities in the `scripts/` directory that enforce [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) policies during continuous integration. For example, `guard-no-drizzle-push.mjs` prevents accidental database schema pushes by scanning git diffs for Drizzle Kit changes. These scripts ensure that architectural constraints are mechanically enforced rather than relying solely on code review.

### How do actions bridge UI and AI agents in this framework?

Actions defined using `defineAction` serve as the single source of truth for business logic. As shown in [`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md) line 8-16, one action definition automatically generates TypeScript types for UI components, API endpoints (HTTP/MCP/A2A), and the AI agent runtime. This eliminates duplication and ensures that UI components and AI agents interact with the database through identical, type-safe operations.