Checking the Codebase Before Planning

Before the Studio plans an intent it can read your connected repository for what already exists, so that the plan changes what is there rather than building it again. On an Auto Pilot run a second AI request then checks the plan against what you asked for, and the plan is revised before anything of it is written.

Why it exists

An intent such as “the views should open as tabs by default” speaks of something that already exists: the work is to change a default, not to build tabs. A planner that cannot see the code may plan the building of it. The codebase check gives the planner a reading of the code, and the planning check asks a second time whether the plan is what was asked for.

Check the codebase

On an intent's page, the Codebase panel sits on the Brief tab, under the brief. Check the codebase asks the server to read the connected repository for this intent. Any member of the studio can run one. It takes a few minutes, and you can leave the page while it runs.

1. The server lists the repository's files and keeps the paths that match the intent's words.
2. An AI request chooses up to 16 of those files to read.
3. The server reads them, at the branch's latest commit, with the connection's own read access, and cuts each to an excerpt.
4. A second AI request reports what already exists (each point with the files that show it), what is missing, the smallest change that would meet the intent, which files that change would touch, and what it could not tell.

The panel names the repository, the branch and the commit that were read, when and who asked, and lists every file read. A file the report cites is one the server really read, but what the report says about that file is not checked: it is an AI's reading and it may be wrong, so check it against the code before you rely on it.

A check is two AI requests on the provider your studio already uses, and nothing is written to your repository. Check again always makes a new check, unless Auto Pilot is running on the intent (it is refused until the run has finished) or the limits below are reached; an Auto Pilot run uses the stored check as it stands, at no cost, when it is still what a new one would say (the same repository, and the code has not changed since). The panel marks a check out of date when the intent's title, description or kind changes, when its repository connection is archived or its branch changed, or after 30 days; Check again replaces it. Disconnecting the repository, or pointing its connection at another one, removes its checks (see below). A check that fails leaves the one before it and says why. A studio can have two checks running at once, and one person can start six in ten minutes. GitHub, GitLab and Bitbucket repositories can be checked. In local mode the codebase is not checked.

What is never read, and what is removed

Files that exist to hold credentials are never listed or read: .env files, private keys and key stores, registry and cloud credential files, Terraform state and variables, kubeconfig, service-account files, and anything under folders such as .ssh, .aws or secrets. Data files (.sql, .csv, database files and dumps), symbolic links, binaries and any file over about a megabyte are not read either.

In what is read, text that matches the patterns of common secrets is removed before an AI sees it, and again from the report before it is stored: provider tokens, private-key blocks, passwords in connection strings and addresses, and lines such as password=, secret=, token= and api_key=.

What planning does with it

While a check is not out of date, the agents that plan work are shown it: the brief, the planner, and the Generate buttons on the intent's Work tab. They are shown it as an AI's reading that may be wrong, and they plan the change to what it says already exists, not the building of it. The Work tab says in one line whether that is so. The planner and the agents that write work packages and work items are also shown your Definition of Ready and Definition of Done, so that the work they shape can meet them; they are told never to say a checklist item is met, and work that only restates an item is flagged.

What the planner leaves out because the check says it already exists is listed, each with the check's own sentence, so that you can check it against the code: a check that is wrong makes a plan too small.

Each work package the planner makes while a check is shown carries an approach, under its scope: a short note on where the change is expected to go, what it builds on and the files it is expected to touch. It is a note, and it may be wrong. Anyone who can edit the scope can change it while the package is a draft or in review; it is frozen with the scope at approval. The agent that writes work items is shown it as a note. The readiness and done reviewers are never shown it. A coding run is given it, as quoted context, only when it runs on the repository the approach is about and that connection still points where it did.

In an Auto Pilot run

A run on an intent, or on one workstream, can start with a Codebase check stage. The dialog shown before the run is sent has a Check the codebase first box naming the repository, ticked whenever one is connected; untick it to leave the check out, and choose which repository when there are several. The run starts the same check as the Codebase panel, as the person who started the run, and waits for it. Its two AI requests count against the run's limit, as does each pass spent waiting. The run then keeps to that one check: every later stage is shown it and no other, and if it is replaced, goes out of date or checks are switched off while the run is going, the later stages are not shown it and the run says so once. A check that fails never fails the run: the run says why in one line and carries on.

When the run plans the intent (or the workstream), the planning check reads the plan before anything of it is written: against what the intent asks for, the codebase check the run used, the Definition of Ready and Done, and the sizing rules. If it questions the plan, the planner revises it, at most twice, and each revision is checked again. Planning may take up to six AI requests: a plan, up to three checks of it and up to two revisions. With a small request limit the last check may not be made.

The planning stage on the run's panel says which round it is on, and then how the check ended:

Whichever way it ends, the run writes the plan once and does not fail because of the check. A work package a revision removed is listed with the reason, beside what the plan left out. The planning check is an AI's review of the plan against the ask: it does not assess readiness, and it read the same codebase check as the planner, so it cannot tell you the codebase check was wrong. Nothing it says is put on a work package.

A run that stops while it holds a plan it has not yet written says so, and until when resuming it takes that plan up. A run that is resumed, or picked up after a fault, writes one plan and does not ask again about a plan it has already started writing.

What happens next depends on the studio's mode. A Semi-Autonomous run leaves every work package it makes a draft: you read the check's points beside the plan on the run, and decide which packages to send for review. A Fully Autonomous run never approves a work package the planning check still questions: it takes the other packages that pass their review on to approval and dispatch under the standing approval, and leaves that one for a person to approve, listed on the run with the reason. A point about the plan as a whole, or about a workstream, leaves every package of the run for a person. A questioned package still goes through Review and Readiness first, so a person also sees what the reviewer agents found. A point raised on an earlier draft follows its package into the plan as written, even if a revision renamed it. A plan written without a check holds nothing back, because nothing questioned it. In the Autonomous loop a run that left packages for a person still finishes, and the loop moves on to its next intent; those packages wait on their own pages.

Switching codebase checks off

The studio owner can switch codebase checks off for the whole studio under Trust Settings → Codebase checks. No codebase check is then started: the Codebase panel says so in place of its button, the Auto Pilot dialog says so in place of its box, and a run plans without checking the codebase. A check made earlier is kept for people to read and is not shown to the agents that plan work; an approach a package already holds stays on its page and is still given to coding runs. Nothing already written from a check is recalled.

It stops codebase checks only. The codebase scan, Describe the pipelines, the Product Manual's import and coding runs also send repository files to the AI provider, and this setting does not stop them. Only the studio owner can change it.

Disconnecting a repository

Disconnecting a repository, or pointing its connection at another repository, removes the codebase checks read from it. It does not remove what was written while a check was shown: briefs, work packages and their approaches stay, and an Auto Pilot run's list of what its plan left out keeps the check's sentence for each item and how many files it named (never a file name) for as long as the run's record is kept, 90 days after it ended. The disconnect dialog says both.