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

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 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 (lines 8-16), a minimal action looks like this:

// 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

AGENTS.md: Architecture Contract and Always-On Rules

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 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 (lines 26-33), key development scripts include:

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 defines the workspace glob patterns that PNPM uses to link packages:

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 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 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 policies during CI execution.

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

// 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

The 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) orchestrates linting, testing, and guard execution:

# .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

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 and .oxfmtrc.json: Configure the Oxlint linter and formatter
• .prettierignore: Excludes generated files from formatting
• 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.

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 and AGENTS.md form the governance layer, defining the action-centric philosophy and architecture contracts
• package.json and pnpm-workspace.yaml configure the monorepo structure and dependency management
• agent-native.json and 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 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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}