Root-Level Files in BuilderIO/agent-native: Complete Repository Structure Guide

The BuilderIO/agent-native repository root contains 30+ configuration files, documentation, and directories including package.json, agent-native.json, multiple wrangler-*.toml files, and workspace directories like scripts/ and docs/.

Understanding the root-level files in BuilderIO/agent-native is essential for navigating this monorepo framework. The repository root serves as the command center for the Agent-Native project, containing configuration manifests, Cloudflare Wrangler deployment files, and workspace definitions that bootstrap the entire system according to the source code structure.

Complete Inventory of Root-Level Files

The repository root contains a mix of JSON manifests, TOML configuration files, YAML workspace definitions, Markdown documentation, and essential directories. Here is the complete list of files located directly in the repository root.

Configuration Manifests

• package.json – Defines the monorepo's dependencies, scripts, and metadata
• agent-native.json – Central manifest that tells the CLI which templates, skills, and defaults to use when scaffolding new projects
• app.json – Application configuration for the native mobile build
• eas.json – Expo Application Services configuration for build and submit profiles
• registry.json – Package registry configuration for the framework components
• opencode.json – OpenCode-specific configuration settings
• .cache_meta.json – Metadata cache for build optimization

Cloudflare Wrangler Configurations

The repository includes multiple TOML files for different Cloudflare Workers deployments:

• wrangler-analytics.toml
• wrangler-calendar.toml
• wrangler-calorie-tracker.toml
• wrangler-chat.toml
• wrangler-clips.toml
• wrangler-content.toml
• wrangler-dispatch.toml
• wrangler-forms.toml
• wrangler-mail.toml
• wrangler-slides.toml
• wrangler-videos.toml

Workspace and Package Management

• pnpm-workspace.yaml – Defines the monorepo structure for pnpm, specifying which directories contain workspace packages
• pnpm-lock.yaml – Lock file ensuring reproducible dependency installs across environments

Documentation Files

• README.md – Primary entry point explaining the framework's purpose and quickstart guide
• AGENTS.md – Defines the "always-on" rules, architecture contracts, and high-level workflow guidelines for contributors
• DEVELOPMENT.md – Setup instructions, development workflows, and contribution guidelines

Tooling and Linting Configuration

• .oxlintrc.json – OX Linter configuration for code quality enforcement
• .oxfmtrc.json – OX Formatter configuration for code style consistency
• .prettierignore – Specifies files and directories for Prettier to ignore
• .gitignore – Git ignore patterns for the repository
• .nvmrc – Specifies the Node.js version required for the project

Root-Level Directories

Five key directories live at the repository root:

• scripts/ – Contains helper scripts for CI, development tooling, and repository maintenance
• docs/ – Documentation source files and guides
• .github/ – GitHub Actions workflows, issue templates, and repository configuration
• .changeset/ – Changeset configuration for versioning and changelog generation
• .agents/ – Agent-specific configuration and rule definitions

Key Files for Daily Development

While the repository contains over 30 root-level items, several files serve as the primary interaction points for developers working with the BuilderIO/agent-native codebase.

agent-native.json

The agent-native.json file acts as the central manifest for the framework. Located at the repository root, this file tells the Agent-Native CLI which templates, skills, and default configurations to apply when scaffolding new projects. According to the source code structure, this file is essential for the framework's code generation capabilities.

pnpm-workspace.yaml

The pnpm-workspace.yaml file defines the monorepo boundaries for pnpm. As implemented in BuilderIO/agent-native, this YAML file typically specifies workspace packages using glob patterns like packages/*, enabling the package manager to link dependencies across the monorepo efficiently.

AGENTS.md

Unlike typical documentation, AGENTS.md serves as an architectural contract. This root-level Markdown file defines the "always-on" rules and high-level workflow guidelines that govern how contributors interact with the codebase. It functions as the constitution for the project's development practices.

Working with Root Files Programmatically

When building tooling or automation scripts for the BuilderIO/agent-native repository, you often need to interact with these root-level files programmatically.

Listing Root Files with Node.js

To enumerate all files in the repository root while excluding directories (useful for build scripts or validation tools):

import { readdir } from 'node:fs/promises';
import { join } from 'node:path';

async function listRootFiles() {
  const rootPath = join(import.meta.dirname, '..'); // assumes script lives in a sub-folder
  const entries = await readdir(rootPath, { withFileTypes: true });
  const files = entries
    .filter(e => e.isFile())      // only files (ignore directories)
    .map(e => e.name);
  console.log('Root-level files:');
  console.log(files.join('\n'));
}

listRootFiles().catch(console.error);

This script filters out directories like scripts/ and docs/, returning only the configuration files and documentation at the repository root.

Loading Workspace Configuration

To programmatically read the monorepo structure defined in pnpm-workspace.yaml:

import { readFile } from 'node:fs/promises';
import yaml from 'js-yaml';
import { join } from 'node:path';

async function loadWorkspaceConfig() {
  const path = join(process.cwd(), 'pnpm-workspace.yaml');
  const raw = await readFile(path, 'utf8');
  const config = yaml.load(raw);
  console.log('Workspace packages:', config.packages);
}

loadWorkspaceConfig();

This pattern is essential for custom build tools that need to understand which packages belong to the Agent-Native workspace.

Summary

The root-level files in BuilderIO/agent-native provide the foundation for this monorepo framework:

• 30+ configuration files reside in the repository root, including JSON manifests, TOML deployment configs, and YAML workspace definitions
• Multiple Wrangler configurations (wrangler-*.toml) support different Cloudflare Workers deployments for analytics, chat, calendar, and other services
• Key interaction points include agent-native.json for CLI scaffolding, pnpm-workspace.yaml for monorepo management, and AGENTS.md for development guidelines
• Five root directories (scripts/, docs/, .github/, .changeset/, .agents/) contain nested tooling, documentation, and configuration

Frequently Asked Questions

What is the purpose of agent-native.json in the root directory?

The agent-native.json file serves as the central manifest that configures the Agent-Native CLI. It specifies which templates, skills, and default settings to use when scaffolding new projects within the framework. Located at the repository root, this file is essential for the code generation capabilities and project initialization workflows.

Why are there multiple wrangler-*.toml files in the repository root?

Each wrangler-*.toml file configures a specific Cloudflare Workers deployment for different services in the Agent-Native ecosystem. The repository includes separate TOML files for analytics, calendar, chat, clips, content, dispatch, forms, mail, slides, and videos—allowing each microservice to have independent deployment configurations, environment variables, and routing rules.

How does pnpm-workspace.yaml define the monorepo structure?

The pnpm-workspace.yaml file uses glob patterns (typically packages/*) to tell the pnpm package manager which directories contain workspace packages. This enables the monorepo to link dependencies between internal packages, share node_modules efficiently, and run scripts across the workspace from the repository root.

What information does AGENTS.md contain compared to README.md?

While README.md provides the general project overview and quickstart instructions for users, AGENTS.md defines the architectural contract and "always-on" rules for contributors. It specifies the high-level workflow guidelines, development conventions, and governance rules that maintain consistency across the BuilderIO/agent-native codebase.

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