The repo is the operating model

In a recent AI engineering enablement programme with a large digital engineering organisation, the most valuable thing we shipped in the first month was not a workshop; it was a folder.

Specifically, a set of small files committed to the root of each priority repository. None of those files contained a single line of product code, yet all of them decided whether the same frontier model produced output that matched the team’s standards, or generic output that someone had to rewrite.

We call this the repo onboarding kit. We treat it as the unit of compounding AI capability inside an engineering team.

What the kit looks like

The kit is short, and that is the point. One context file, two small folders, and the review wiring that binds them, most of it shorter than a sprint retrospective. Committed to a repository, it looks like this:

<repo root>/
├── CLAUDE.md            project context, conventions, architecture, the patterns to follow
├── conventions/         the unwritten team rules, made writable
├── commands/            the named workflows the team runs every week
└── .github/             the Action that reviews every pull request

At the root sits a CLAUDE.md that tells any agent joining the repository what the project is, where the code lives, which patterns to follow, which paths are protected, and where to look for more detail. Sanitised, it looks something like this:

# Project: <service name>
# Stack: <language>, <runtime>, <db>

## Where things live
- Application code: src/
- Tests: src/**/*.test.<ext>
- Migrations: db/migrations/ (protected)
- Configuration: config/ (review-only)

## Patterns to follow
- Errors propagate up. Do not swallow inside services.
- Tests sit next to the code they test.
- Public API methods are documented in src/api/README.md.

## Paths Claude must not touch
- db/migrations/
- secrets/
- infra/production/

## Reference
- See conventions/error-handling.md for the team's error policy.
- See commands/ for named workflows.

Next to the root sits a conventions/ folder with the unwritten team rules made writable. Naming, error handling, test structure, and feature flag naming. All the things that used to live in three engineers’ heads and now live in one place.

The commands/ folder holds the named workflows the team runs every week. In this engagement the kit shipped with six of them, each a short markdown file that turns an open-ended prompt into a step the team runs the same way every time. notes-to-jira turns unstructured input into a Jira ticket in the team’s standard format, not just acceptance criteria, and queries the author for anything missing before it writes the ticket.. jira-to-spec reads the ticket and produces a technical specification. spec-to-code takes that specification into a test-driven implementation. jira-to-code is the shortcut that runs the whole chain, from ticket through explore, plan, code, and commit. qa-notes produces a pre-development QA test plan from the ticket and the diff, so QA can validate scope before code is written. release-notes reads recent merges and the linked tickets, produces release notes, and posts them to Confluence.

Finally, a review checklist sits next to a testing rules file. The GitHub Action does the first pass and the human does the architectural call. The testing rules file names the coverage threshold, what gets tested, and what explicitly does not.

Why this is the operating model, not just plumbing

The kit earns that description because of what the discovery found. The same four-week foundation phase that set the investment sequence, which we cover separately in our piece on where to invest in an AI programme first, surfaced two problems the kit was built to answer.

The first was testing. Testing culture was understood and valued, but carried two to three years of accumulated debt, and the AI assistance already tried against it produced mixed results, because the tests were generated against codebases whose conventions the model had never been given. The second was drift. Individual adoption was already ahead of the organisation’s guidance: engineers were using AI daily and getting different output from the same model, because there was no shared context to work from.

Both are context problems, and context is what the kit commits. It standardises the context so the same model produces consistent output across teams, moves the unwritten conventions into the place an agent actually reads, and turns each workflow into a reproducible command. It does not touch the requirements bottleneck, which sits upstream of the repo and is a different piece of work. But it makes that bottleneck visible: once the rest of the pipeline is fast, it is obvious where work backs up.

The first pilot to run the kit was a small platform team replacing an authentication dependency. Spec throughput increased from 2 to 6.4 specs per week, and rework on those specs decreased from 8% to 0% across 5 pull requests covering 9 stories. The first epic reached staging in 11 calendar days, compared with the team’s pre-AI estimate of 10 to 12 sprints. The sample is small, and the conventions were still settling, so read it as an early signal rather than a settled benchmark. It points the right way, and it is a real number rather than a promise.

The discipline tax, named honestly

The kit is not free. Somebody has to maintain it because conventions change, new patterns are adopted, and old commands no longer align with the workflow the team actually uses. If nobody owns the kit, it goes stale in eight weeks and starts producing worse output than no kit at all, because the model is following rules the team no longer follows.

In this engagement, ownership was written into the team’s Definition of Done. Every merged change that touches a convention also updates the convention file. A team lead owns the kit, just as a tech lead owns the CI configuration. Five to ten minutes of maintenance per week, on a senior’s clock.

The rules were also written into the development environment itself. Hooks in .claude/settings.json enforce the team’s standards, running every time an agent edits a file. The pattern most teams adopt first is a `PostToolUse` hook that lints every file the agent touches, the moment it touches it:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

The hook is short. It is the reason a junior engineer running an agent at 7pm on a Friday cannot quietly accumulate 200 lines of code that ignore every convention the team spent 2 years agreeing on.

The honest comparison is with documentation. Most teams already pay a documentation tax, badly. The kit is a documentation tax that pays back because the documentation is read every day by an agent on every pull request.

What engineering leaders should take away

For an engineering leader, the kit turns an AI decision into an ownership decision. A platform you can swap. A convention file that encodes two years of how your team works is harder to rebuild, and more valuable, because it is yours.

That portability is the part most AI procurement cannot match. The same CLAUDE.md and conventions apply to a different frontier model, with two changes to a configuration file, so the knowledge your team encoded as text survives a vendor decision forced on you by a price change or a security review. In every priority repository sits a small set of files that get read on every change, get smaller as the team learns what works, and outlast personnel, model, and vendor changes without losing their value. They are the operating model, made committable.

If your engineering organisation is six months into AI adoption and starting to plateau, the next investment is not a new tool. It is the file you have not committed yet.

The repo kit is part of how we run AI enablement for engineering teams. If you want to see what this looks like inside a live codebase, start with a diagnosis call.