> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent-Ready Projects

> Help people and coding agents make safe ACI changes with repository guidance, typed contracts, and shared checks.

A Gradial ACI (Agentic Content Infrastructure) project gives every contributor the same understandable working surface: JSON content, typed component contracts, framework code, familiar commands, and tests. Generated projects also include repository-local guidance that compatible coding agents can load before they make a change.

There is no separate content model for agents. Work produced with Gradial or a coding assistant must satisfy the same contracts and pass the same review, preview, and release process as work produced manually.

## Guidance travels with the project

The starter places its operating guidance under `.agents/`:

```txt theme={null}
.agents/
├── AGENTS.md
└── skills/
    ├── aci/
    │   └── SKILL.md
    ├── authoring/
    │   └── SKILL.md
    └── migration/
        └── SKILL.md
```

| Resource | When to use it |
| - | - |
| `.agents/AGENTS.md` | Repository-wide conventions and routing to more specific guidance |
| `skills/aci/SKILL.md` | ACI project structure, commands, testing, and troubleshooting |
| `skills/authoring/SKILL.md` | Pages, components, contracts, registration, and design tokens |
| `skills/migration/SKILL.md` | Moving an existing site or design into the ACI project shape |

These files are useful to people as well as agents. Keeping them in the repository means the instructions can evolve alongside the code and be reviewed like any other project change.

<Tip>
  Treat the generated guidance as a maintained part of the project. Add your own brand, accessibility, test, and review requirements where contributors will find them before they edit content or components.
</Tip>

## One workflow for every contributor

```mermaid theme={null}
flowchart LR
    A["Read repository guidance"] --> B["Inspect content and contracts"]
    B --> C["Make a scoped change"]
    C --> D["Compile and test"]
    D --> E["Review and preview"]
    E --> F["Approve, promote, and release"]
```

The shared workflow matters more than which tool made the edit. A component prop added by a developer, a page revised with a coding agent, and content produced through Gradial all meet at the same validation boundary.

### 1. Read the local instructions

Before editing, load `.agents/AGENTS.md` and the relevant skill. The task should also identify the page, component, or route in scope and the checks required before handoff.

### 2. Inspect the source of truth

Agents can reason about the project through ordinary files:

* `.content/` contains pages, fragments, overlays, and site configuration;
* `src/cms/contracts/` defines valid component props and layout regions;
* `src/cms/registry.ts` maps contracts to runtime components;
* `src/components/` contains the frontend implementation; and
* `package.json` defines the project's supported development and verification commands.

This makes the correct boundary visible. A copy-only task may change a page document. A new visual treatment may require a contract, runtime component, registry entry, and tests.

### 3. Make a scoped change

Use the normal project tools. Keep stable page and block IDs when updating existing content, and avoid changing generated output under `.aci/`.

For hosted content work, use a named ACI branch so the change remains isolated until it has been reviewed:

```bash theme={null}
aci branch create campaign-refresh --source-ref main
aci content pull --branch campaign-refresh
# Edit the relevant .content files.
aci content diff --branch campaign-refresh
```

For code work, use your repository's normal Git branch and review process. If the ACI content branch needs the new frontend code for preview, build and link the current Git state:

```bash theme={null}
aci code-build --branch campaign-refresh
```

### 4. Run the shared checks

Generated projects provide a standard local verification loop:

```bash theme={null}
npm run content:compile
npm run typecheck
npm test
npm run build
```

These checks verify content structure, component props, contract-to-runtime mappings, TypeScript code, conformance rules, and the production framework build. Add your own accessibility, visual regression, and policy tests to the same loop.

### 5. Review the result

A passing command is necessary, but it is not the whole review. Before approval:

* inspect the file diff for unintended scope;
* confirm that IDs and references were preserved;
* review the branch preview across relevant routes and viewports;
* check base and personalized experiences when overlays changed; and
* follow your team's content, legal, brand, and release approvals.

Agents do not bypass these controls. The same branch, validation, preview, promotion, and release stages apply regardless of who or what prepared the change.

## Write an effective task

A useful agent task names the outcome, source files, constraints, and proof of completion. For example:

```txt theme={null}
Read .agents/AGENTS.md and .agents/skills/authoring/SKILL.md first.

Update the existing home-page hero copy for the fall campaign.
- Change only .content/pages/home/_index.json.
- Preserve the page ID and hero block ID.
- Keep the props valid for the home_hero contract.
- Do not edit generated files under .aci/.

Run npm run content:compile and report the changed file and result.
```

This gives the contributor room to do the work while making scope and verification explicit.

## Guardrails worth keeping in the repository

Add instructions that are specific enough to verify:

| Area | Example guardrail |
| - | - |
| Content scope | Change only the named page and its directly referenced fragment |
| Stable identity | Preserve existing page, block, audience, and experiment IDs |
| Contracts | Update schema, runtime component, registry, content, and tests together |
| Generated output | Never edit `.aci/` by hand |
| Personalization | Keep a complete base experience and verify the fallback |
| Quality | Run compile, type, test, and build commands before handoff |
| Release | Preview and obtain the required approval before landing or promotion |

Prefer rules that describe observable outcomes. A contributor can verify “no raw color values” with a lint rule; “make it polished” leaves the important constraint open to interpretation.

## Use the same CLI safely

Coding agents can invoke the same project scripts and ACI commands available to a developer. Grant only the access required for the task, and keep production activation as an explicit step in your release process.

For a content branch, a safe handoff sequence is:

```bash theme={null}
aci content validate
aci content diff --branch campaign-refresh
aci content push --branch campaign-refresh --dry-run
```

The dry run gives the reviewer a concrete change plan. Applying the push, landing the branch, promoting paths, and activating a release can remain separate approvals based on your team's operating model.

## What stays consistent

Whether a change is made by a person, through Gradial, or with a compatible coding agent, ACI evaluates the resulting project rather than trusting the authoring tool:

* content is structured and reference-aware;
* props are checked against code-owned schemas;
* branches isolate in-progress work;
* previews show the branch's linked content and code; and
* approved content is promoted and released through explicit steps.

That consistency is what makes agent-assisted work practical: the project is easy to understand, and correctness does not depend on a separate agent-only interface.

***

*Next: [Personalization Quickstart →](/aci/personalization/quickstart)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.