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

​
One workflow for every contributor

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

​
4. Run the shared checks

Generated projects provide a standard local verification loop:
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:
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: 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:
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 →