Codebase-aware, part two: staying in sync with a repo that keeps moving

A while back we wrote about what "codebase-aware" actually means — the difference between importing a repo and understanding it, and the three stages (exploration, code-specialized retrieval, a structured brief) that have to happen before generation can be said to fit a codebase rather than just have access to it.

That post was about a snapshot: at one moment, does the tool understand your repo? But a snapshot is the easy version of the problem. Repos don't hold still. You push code, the understanding goes stale. Your project turns out to span more than one repository. And it isn't only the final generation step that needs to know your architecture — the planning and design steps do too. This is the part-two work: making codebase-aware hold up after the first read.

A one-time read goes stale the moment you push

Here's the failure mode that matters most in practice. You connect a repo, Shipd explores it and builds an Architecture Brief, and everything fits — for about a day. Then you (or a teammate) merge a few PRs, and now the tool's model of your codebase describes a repo that no longer exists. Nothing errors; the output just quietly drifts back toward "close but not quite," because it's reasoning about last week's structure.

So we made the brief aware of its own staleness. Shipd now connects as a proper GitHub App with installation tokens rather than a raw OAuth token, which lets it do two things it couldn't before: receive events from your repo, and push back securely. When you push to a connected repo, a webhook fires and the Architecture Brief is marked stale — so the tool knows its understanding is out of date and can re-explore, instead of silently building against a model that's a week behind. "Freshness" isn't magic real-time comprehension; it's the far more useful property of knowing when it no longer knows.

Real projects aren't one repo

The first version assumed one project, one repository. Actual codebases don't cooperate — a product is a web app and an API and maybe a shared package, across separate repos. So a Shipd project can now connect to more than one repository at a time, and the brief spans them. If the thing you're building touches your frontend repo and your services repo, the tool can be aware of both rather than forcing you to pretend your architecture is smaller than it is.

The loop has to close back to Git

Understanding your repo is only half of it; the output has to get back there cleanly. So the round trip is now first-class. You can create a brand-new repo directly from Shipd and have your app pushed into it (not left as an empty repo you have to populate). For an existing repo, changes come back as a clean delta PR — a reviewable diff against your main, in your conventions, rather than a wholesale rewrite you'd never merge. The point is that "codebase-aware" shouldn't dead-end in the tool. What it understands, it should be able to hand back in the form your team already reviews and merges.

It's not just the generator that needs to read your code

The subtler improvement: in a Shipd Team Mode run, the codebase isn't only visible to the engineer at the end. When you build against a connected repo, the PM, the director, and the designer are all grounded in the Architecture Brief — so the plan is scoped to what your app already is, the design direction respects the system you already have, and the frontend engineer reviews the actual delta against your repo rather than reviewing in a vacuum. An AI team that only lets the last member see your code isn't much better than a single agent with repo access. The understanding has to be shared across the whole pipeline, or the early steps quietly design something that doesn't belong in your codebase.

The honest scope

None of this makes understanding a large codebase a solved problem. Deep monorepos are still hard; a fresh exploration costs time; and "the brief knows it's stale" is a meaningfully lower bar than "the brief is always perfectly current." We shipped the mechanism that makes staleness visible and recoverable, not a guarantee that the model is omniscient about a repo the size of a company. We'd rather tell you that plainly than imply the harder problem is finished.

The test that actually matters

For the first post, the test was whether anything read your code before generation, as opposed to just making it available. The part-two test is narrower and more revealing: does the tool's understanding survive contact with a repo that changes? Push some code and ask whether the tool knows its picture is now out of date. Point it at a project that genuinely spans two repos and see whether it can hold both. Have it make a change and check whether what comes back is a mergeable PR in your conventions or a rewrite you'd throw away. A tool that's codebase-aware only at the moment you connect is a demo. Staying aware as the repo moves is the actual feature.

See how codebase-aware works →