# Best Practices for Modifying BuilderIO/agent-native Root Files: A Complete Guide

> Safely modify BuilderIO/agent-native root files with these best practices. Learn about prep commands, invariant scripting, and Changesets for monorepo management.

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

---

**Always run `pnpm run prep` before committing, encode new invariants in `scripts/guard-*.mjs`, and use Changesets for version management to safely modify root files in the BuilderIO/agent-native monorepo.**

The BuilderIO/agent-native repository is a sophisticated monorepo where root-level configuration files govern the entire workspace ecosystem. Modifying these files requires strict adherence to architectural contracts defined in [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) and validation through the CI pipeline in [`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml). This guide provides actionable steps for editing root files without breaking the shared infrastructure across all templates and packages.

## Understanding the Root Architecture

The root of the Agent-Native repository contains configuration, scripts, and package definitions that form a **four-area contract** (UI, actions, skills, state) described in [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md). These components are tightly coupled and affect every workspace member.

### Central Configuration Files

- **[`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json)** – Defines workspace scripts, dev-dependencies, and the `postinstall` build chain that triggers workspace builds. This is the central entry point for all `pnpm` commands.

- **[`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml)** – Lists all workspace packages and templates, enabling the `workspace:*` version protocol that prevents dangling references.

- **[`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md)** – Contains the canonical "always-on" rules governing branch safety, commit hygiene, and guard philosophy. Any modification must respect these policies.

- **[`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml)** – Runs the CI pipeline executing lint, type-checks, tests, and security guards. Changes introducing failures here block all PRs.

- **`scripts/guard-*.mjs`** – Runtime scripts enforcing invariants like preventing `drizzle-kit push` commands or unscoped credentials. These run automatically via `pnpm guards`.

## Core Principles for Safe Root Modifications

Follow these architectural principles when editing files in the repository root:

- **Never break CI** – The `lint`, `typecheck`, `test`, and `guards` jobs in [`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml) protect the workspace from regressions. Always verify green status locally before pushing.

- **Keep root files declarative** – Avoid embedding application logic in root scripts. The root is shared across all templates; template-specific code belongs in `packages/*` or package-specific scripts.

- **Prefer `workspace:` version ranges** – Every inter-package dependency must resolve to a workspace member using `workspace:*` specifiers. This prevents installation failures caught by the scaffold-e2e job (lines 28-52 in [`ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/ci.yml)).

- **Guard first** – Codify new invariants in `scripts/guard-*.mjs` files. Guards automate the detection of real-world incidents like credential leaks and run automatically on every PR.

- **Version-control via changesets** – Never bump versions manually in [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json). Use the Changeset workflow (`pnpm changeset add`) to generate changelog entries and `pnpm changeset version` to apply them.

- **Never embed secrets** – Hard-coded keys violate the security policy in [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md). Use environment variables and the secrets system documented in [`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md).

## Step-by-Step Workflow for Editing Root Files

Use this checklist workflow to ensure compliance when modifying root configuration:

1. **Review [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md)** – Verify your change complies with "always-on" rules (e.g., no `Co-Authored-By` lines in commits).

2. **Install dependencies** – Run `pnpm install --frozen-lockfile` to ensure lockfile consistency before making changes.

3. **Implement the change** – Edit the target file (e.g., add a script to [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) or a workspace folder to [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml)).

4. **Add guard coverage** – If introducing a new invariant, create a matching `scripts/guard-*.mjs` script following the pattern in `guard-no-drizzle-push.mjs`.

5. **Validate locally** – Execute `pnpm run prep` to run the full verification suite: formatting, linting, type-checking, testing, and guard execution.

6. **Commit correctly** – Write a clear commit message; do not use `Co-Authored-By` metadata per repository rules.

7. **Open PR and verify CI** – Push changes and confirm all GitHub Actions jobs (`lint`, `typecheck`, `test`, `guards`) pass successfully.

8. **Document changes** – If the modification is user-facing, run `pnpm changeset add` to create a changeset entry describing the impact.

## Practical Implementation Examples

### Adding a New Root Script in package.json

When adding utility scripts to the root, keep them declarative and avoid business logic:

```json
{
  "scripts": {
    "my:clean": "rimraf ./tmp && pnpm install --frozen-lockfile"
  }
}

```

This script is safe because it performs cleanup without affecting build order. While no guard is required for simple utilities, always run `pnpm fmt:check` to maintain formatting standards.

### Creating a New Guard Script

Encode policy enforcement by creating `scripts/guard-no-legacy-deps.mjs`:

```javascript
#!/usr/bin/env node
import { readFileSync } from "fs";
import path from "path";

const pkgPath = path.resolve(process.cwd(), "package.json");
const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
let violations = [];

function checkDeps(deps, type) {
  for (const [name, version] of Object.entries(deps || {})) {
    if (typeof version === "string" && version.startsWith("npm:")) {
      violations.push(`${type}.${name}=${version}`);
    }
  }
}

checkDeps(pkg.dependencies, "dependencies");
checkDeps(pkg.devDependencies, "devDependencies");

if (violations.length) {
  console.error("🚨 Legacy npm: protocol dependencies detected:");
  violations.forEach(v => console.error("  -", v));
  process.exit(1);
}

```

Add this guard to the validation suite by ensuring it follows the `guard-*.mjs` naming convention, which `pnpm guards` automatically discovers and executes.

### Extending the Workspace Configuration

To add a new workspace folder in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml):

```yaml
packages:
  - "packages/*"
  - "templates/*"
  - "tools/*"   # New folder for shared CLI utilities

```

After modifying workspace definitions, run `pnpm install` and verify the new package appears in `pnpm list` output. The scaffold-e2e job in [`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml) validates that these references resolve correctly.

### Managing Releases with Changesets

For user-facing root modifications that require version bumps:

```bash
pnpm changeset add

```

Follow the interactive prompts to select the change type (e.g., "added") and provide a summary: "Add my:clean helper script for CI pipelines". This creates a markdown file under `.changeset/` that the release pipeline consumes when `pnpm changeset version` runs on merge.

## Summary

- **Root files require strict validation** – Run `pnpm run prep` locally before every PR to verify formatting, linting, type-checking, and guard compliance.

- **Encode policies in guard scripts** – Create `scripts/guard-*.mjs` files to automate enforcement of new invariants rather than relying on documentation alone.

- **Use workspace protocols** – Always reference internal packages with `workspace:*` in [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) dependencies to prevent resolution failures.

- **Automate versioning** – Use `pnpm changeset add` for all user-facing changes; manual version bumps bypass the release pipeline and break the Changeset workflow.

- **Respect the four-area contract** – Ensure modifications to root configuration support the UI, actions, skills, and state architecture defined in [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md).

## Frequently Asked Questions

### What happens if I modify root files without running pnpm run prep?

**CI will fail.** The [`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml) pipeline runs the same checks as `pnpm run prep` (lint, typecheck, tests, and guards). Local execution catches errors before they block your PR and prevents breaking the shared workspace configuration.

### How do I add a new invariant check to the repository?

**Create a `scripts/guard-*.mjs` file.** Copy the pattern from `scripts/guard-no-drizzle-push.mjs`, implement your validation logic using Node.js APIs, and exit with code 1 on failure. The `pnpm guards` command automatically discovers and executes all files matching the `guard-*.mjs` pattern in the scripts directory.

### When should I use workspace:* versus standard version ranges?

**Always use `workspace:*` for internal dependencies.** In [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json), reference other monorepo packages with the `workspace:*` protocol to ensure they resolve to local source rather than npm registry versions. This prevents "dangling workspace refs" that cause `pnpm install` failures and are caught by the scaffold-e2e CI job.

### Why does CI fail after I edit pnpm-workspace.yaml?

**You likely broke workspace resolution.** Adding folders to [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) requires that those directories contain valid [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) files and that cross-references use `workspace:*` specifiers. The scaffold-e2e job (lines 28-52 in [`ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/ci.yml)) validates that all workspace dependencies resolve correctly. Verify locally with `pnpm install` and `pnpm list` before pushing.