What the agent does
The agent reads the project as it is. In a repository shaped like dbt-labs/jaffle-shop, dbt_project.yml names the project jaffle_shop at version 3.0.0 with require-dbt-version: ">=2.0.0", sets staging models to views and marts to tables, and gates the jaffle-data seeds behind a load_source_data variable. There is no groups: block and no access or group property on any model. models/staging/__sources.yml declares the ecom source in the raw schema with six tables, six stg_* models each have a YAML file with not_null and unique tests and a dbt_utils.expression_is_true check, and stg_orders.sql reads the source, renames columns and converts cents through the project's own cents_to_dollars macro. models/marts holds customers, orders, order_items, products, locations, supplies and metricflow_time_spine, and orders.yml, customers.yml and order_items.yml carry the semantic layer spec with semantic_model: enabled: true, entities, dimensions and type: simple metrics. packages.yml pins dbt_utils 1.4.1 and dbt-audit-helper from git, .sqlfluff sets the Snowflake dialect with the dbt-cloud templater, and .github/workflows/ci.yml triggers dbt Cloud CI jobs for Snowflake, BigQuery and Postgres on each pull request.
The design follows how dbt enforces access. A private model can be referenced only by models in its own group, a protected model by any model in the same project, and a public model by other projects too. The marts read the staging models, so staging and marts must share a group for staging to be private; the agent therefore adds models/groups.yml with one group, jaffle_shop, whose owner has a name and an email placeholder for the reviewer to fill in, since dbt requires an owner on every group. In dbt_project.yml it adds +group: jaffle_shop under models.jaffle_shop, +access: private under staging and +access: public under marts, so every model inherits its group from the project folder and its access from its layer, and a new staging model is private without anyone remembering to say so. Where a model file already has a YAML entry, it adds nothing, because the folder-level config is the single source; the pull request says so to stop the two from drifting.
Access rules only matter if something checks them, so the agent reads every ref() in models/marts and confirms each one points at a staging model or another mart, all inside the one group. It then writes a deliberate violation, a scratch model assigned to a second scratch group that refs stg_orders, runs dbt parse, keeps the error message that names the private model and the referencing one, and deletes both the scratch model and the scratch group, so the pull request shows what the rules refuse rather than asserting it. Because the repository has no profiles.yml and the sandbox has no warehouse credentials, it installs dbt-core with the Postgres adapter, writes a throwaway profile outside the repository with placeholder values, and runs dbt deps and dbt parse, which read the project and the packages without opening a connection.
It also adds a short section to README.md on what private means for the stg_* models, why marts are public, and how a future second group would need its own staging layer or a protected model to read from, runs sqlfluff lint only if the templater can run without dbt Cloud credentials and otherwise says it skipped it, and then pushes a branch and opens a pull request. The repository's dbt Cloud CI jobs run on the pull request as they do for every change, and a parse error from a wrong group would stop those jobs at the start.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add model groups and access levels to this dbt project. Define one group with an owner in models/groups.yml, assign every model to it in dbt_project.yml, set +access private on the staging folder and +access public on the marts folder, and confirm every ref in marts stays inside the group. Install dbt-core with the Postgres adapter, write a throwaway profile outside the repository, run dbt deps and dbt parse, show that a scratch model in a second group referencing a staging model fails to parse and remove it, add a README section on the group and the access levels, and open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch with three files changed: a new models/groups.yml, a few lines added under models.jaffle_shop in dbt_project.yml, and a README section. The description names the group and its placeholder owner, states that stg_* models are now private to the group and the marts public, and quotes the parse error the deliberate violation produced.
The proof is in the session. The trajectory at GET /o/{org}/sessions/{id}/messages keeps the dbt deps and dbt parse output for the clean project and the error output for the scratch violation, so a reviewer sees dbt enforce the rule rather than a sentence claiming it will. The dbt Cloud CI jobs the repository already runs on each pull request start from the same parse.
Before merging, a reviewer replaces the owner placeholder with the real team and address, confirms that no analysis or downstream project reads a staging model directly, since it no longer can, and decides whether metricflow_time_spine should be public with the other marts or protected. Nothing about the SQL, the tests or the semantic models changes in this pull request.
Run it on every new model layer added
An analytics team that grows the project by folder sends POST /o/{org}/sessions with this prompt when a new layer appears, such as an intermediate folder, naming the folder and the intended access in the prompt and the repository in resources. Each run reads models/groups.yml and the dbt_project.yml config as they are, adds one folder-level block, and checks the refs again with dbt parse.
Give the API key a webhook_url and Rush POSTs run.completed when the turn ends, with session_url to read the pull request from. A request_id that is a UUID v5 of the folder name makes a retried request return the run it already started instead of opening a second pull request.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Groups and access are a small edit that is easy to get wrong in one direction: mark a model private, miss one ref from outside its group, and the whole project stops parsing on the next CI run. On Rush the run reads every ref in its own cloud sandbox, runs dbt parse with a throwaway profile, and provokes the error on purpose so the pull request shows exactly what the rule refuses, while your own profiles.yml and warehouse credentials never leave your machine.
The result is checkable rather than claimed. The pull request is three files, the trajectory keeps the parse output for the clean project and for the violation, and the repository's dbt Cloud jobs run on the pull request as usual. Nothing reaches main until it merges.
Frequently asked questions
Does dbt parse need a warehouse connection?
No. dbt parse reads the project, the packages and the profile and builds the manifest without connecting, which is enough to enforce group and access rules. The agent writes a throwaway profile with placeholder values outside the repository and never receives your credentials.
Why one group rather than one per folder?
Because a private model can only be referenced from its own group, and the marts reference the staging models. Separate staging and marts groups would make every mart fail to parse. One group with private staging and public marts gives the protection most teams want; a second group makes sense when a second domain gets its own staging layer, and the README section the agent adds says so.
Why set group and access in dbt_project.yml rather than in each model's YAML?
The folder-level +group and +access config applies to every model under staging and marts, including ones added later, and keeps one place to read. Per-model properties would work too, and the agent uses them if your prompt asks for a model that differs from its folder.
Who should own the group?
dbt requires a name or email on the group's owner, and the agent cannot know your team, so it writes a placeholder and marks it in the pull request for the reviewer to fill in. A follow-up on the same session can set it from a value you provide.
Does this change any SQL or the semantic models?
No. The models, tests, sources, seeds and the semantic layer YAML are untouched. The pull request adds a groups file, a few lines of project config and a README section, and the trajectory shows the parse output before and after.