Make a change in an unfamiliar codebase

You've been handed a codebase you didn't write. The change itself is probably small. The hard part is finding out where it goes and what else it breaks, and that's exactly the part an agent does badly if grep is the only tool it has.

The code map fixes that.

The whole thing, first

cd the-repo
stella init                                         # index the codebase
stella search "what imports src/db/schema.ts"       # what am I about to break?
stella run --pipeline my-verifier --test-command "pnpm test orders" \
  "add a nullable `archived_at` column to orders and thread it through the API"

1. Index the repository

stella init

stella init does three things worth knowing about. It builds a domain map at .stella/domains.toml (the labels memories and code-map nodes use), builds the code map at .stella/private/codegraph.db, and picks up any commands, skills, and agents already sitting in .claude/ or .agents/ folders as symlinks.

It works offline, using a fallback method, so it succeeds even with no provider key set up — useful on a machine where you haven't set up your keys yet.

2. Ask the questions you'd otherwise guess at

This is the step people skip, and it's the one that pays off. Before deciding how to make a change, find out what depends on the thing you're about to touch.

# Where is this defined — and is it defined exactly once?
stella search "where is resolveOrderTotal defined"

# Who calls it? This is the review surface for a signature change.
stella search "what calls resolveOrderTotal"

# Blast radius: who imports the file I am about to edit?
stella search "what imports src/db/schema.ts"

# What does this file depend on — what do I need to understand first?
stella search "what does src/api/orders.ts import"

# The neighborhood, both directions at once.
stella search "the graph neighborhood of src/api/orders.ts"

Every one of these reads the local index, and with no embedding model configured, makes no model calls and needs no API key. So it costs nothing, and you can afford to be thorough. Ask five questions before you write a prompt.

Two of these are worth turning into habits:

3. Make the change, with a real check

Now the actual work. In an unfamiliar codebase, the single most valuable thing you can supply is a test command, and what turns it into real proof is an installed verification plugin, attached to the run with --pipeline <variant>:

stella run --pipeline my-verifier --test-command "pnpm test orders" \
  "add a nullable archived_at column to orders and thread it through the API"

--test-command arms that plugin's fail-then-pass check: the command has to fail before the change and pass after it. A suite that was already passing can't be used as proof, which is what makes this check meaningful instead of just for show. stella grades what the plugin reports against the rule the plugin set up when it was installed. It doesn't re-run the check itself. Without --pipeline, this flag is rejected — a plain stella run has no way to check the result and makes no claim of proof.

Don't know the test command in a repo you've never read? Ask the repo itself:

stella scripts list          # canonical verbs — install/build/check/test/lint/format

stella scripts finds them by reading the project files (cargo, npm, uv, go, make, just, and so on). It's offline and needs no API key.

If you can't turn "done" into a test

Then the check has to come from the plugin instead. A verification plugin may spend one model call on a witness step — a separate model, never the one doing the work — that writes a small, failing test describing the intended behavior, and checks the fail-then-pass rule against that instead. Whether it does this, and whether it watches those test files for tampering, is up to that plugin. stella grades the evidence it reports against its own declared rule and doesn't re-run anything itself. stella plugin list shows what you have installed.

--keep-witness and --require-verified were flags for the built-in staged pipeline. That pipeline is gone, and both flags are now rejected on every path. A plugin that turns a witness into a real committed test does so on its own terms.

4. Review what actually changed

stella search "what imports src/db/schema.ts"   # re-ask: did the blast radius move?
git diff

In the Command Deck, /diff and /files give you the same review from inside the session.

export STELLA_TRUST_PROJECT=1   # scope it per-repo with direnv or a shell guard

When the repository already documents itself

Most codebases you inherit already contain the instructions an agent needs — AGENTS.md, CLAUDE.md, a CONTRIBUTING.md, architecture notes. They're just written for people, scattered around, and partly out of date.

stella ingest                    # what steering does this repo already contain?
stella ingest AGENTS.md          # extract it into reviewable claims
stella context review            # read what was proposed, and its probe verdict
stella context keep a1b2c3       # publish the ones that are actually true

stella ingest pulls that writing into individual claims, each one tracking where it came from and each one checked against the actual code for staleness. That check matters most in an inherited repo, where the README confidently describes a build system that was swapped out two years ago. Nothing changes stella's behavior until you keep a claim. stella context is where you review them.

Next