Joining a team, then upgrading the way it works with agents

Most of my engagements start the same way: a team already exists, with its code, its habits, its rituals and its blind spots. I never arrive on blank ground, and that is a good thing. A team that ships always has good reasons for doing what it does, even when it has never written them down.

My job is not to replace that way of working with mine. It is to add, sized to the team, what I call agentic work primitives: simple pieces that both humans and agents know how to use, and that stay when I leave. Here is how I go about it, with examples from real projects and from my own workshop.

First, listen to the repository

In the first weeks I read more than I write. The Git history, the tickets, the implicit conventions, how a review goes, what scares the team when it deploys. I ask a lot of questions, often naive ones, because they are the questions an agent would ask if it could.

What I understand, I write down. Not in a report nobody will read, but in a short file at the root of the repository that the team reviews like code: what the project is for, how it is organised, what must not break, where to find the rest. It is the first primitive and the most profitable one. A newcomer saves a week. An agent gets the difference between a plausible change and a correct one.

Write down what the team already knows

The second primitive is the recorded decision. On the after-sales automation I contribute to for Santécie, the repository now carries architecture decisions written one by one, an audit of the flows and a business glossary shared with the users. On the health-insurance card reading benchmark, eleven architecture decisions explain why each option was kept or dropped.

These documents are not bureaucracy. They are what lets you answer, six months later, “why does the system do that?”. And they are what an agent reads before proposing a change, instead of guessing.

In my own workspace I push the logic further: every folder has an instruction file for agents, every project its own page, durable context lives in docs/ and temporary state in a separate folder. An agent knows where it is, what applies here and where to write what it finds. I do not impose that as is on a team; I install the version that serves it.

Turn procedures into skills

Every team has recurring procedures: preparing a release, reviewing a migration, writing a report. When a procedure comes back often enough and has clear verification rules, it becomes a skill: written know-how the agent loads at the right moment, with its steps and its checks.

In my own work, preparing my monthly activity report is one. The agent rebuilds the activity from the Git history and my work sessions, separates projects, checks that every day is covered, then drafts the invoice and the email. It never sends them: it shows them to me.

The right skill is not the most ambitious one. It is the one that takes away a task the team does without pleasure, while keeping the points where its judgement matters.

Move from conversations to workflows

A conversation with an agent is enough for a short task. For a long one it gets fragile: the context runs out, a step is forgotten, nobody knows where things stand. So I describe the work as a graph of steps, with explicit state, possible resumption and human approvals where things commit the company.

That is what two tools I publish are for, pi-graph and Zedflow. In Zedflow, a human approval is a step of the graph, checked on typed data: the amount, the recipient, the period. Not on a “looks fine”.

Proof before trust

An agent that says “done” has proved nothing. So I build verification into the workflow: a build and a type check after every pass, tests that fail before they are fixed, a human review before publication. An agent that cannot show what it verified is not done.

That holds when an agent gets stuck, too. While this site was being built, an agent tasked with generating images hit a limit of its sandbox. It stopped, described the error and proposed two ways to unblock it, instead of switching off the protection on its own. That is exactly the behaviour I want to install: fail clearly rather than succeed in appearance.

What it looks like on a real project: this site

This site was built by several agents, each with an assigned set of files: one for page structure, one for the reading experience, a third for content. They handed each other written contracts: what each had delivered, what it had not touched, what remained open. Every pass ended with a build and a type check.

Not everything went smoothly. A content agent was stopped midway; the next one had to review its partial edits one by one instead of trusting them. That kind of incident is exactly what primitives are for: the state was written down, so were the rules, and resuming was a review, not an investigation.

What I do not install

I do not show up with a stack of tools to adopt wholesale. I do not put an agent on production data without a written boundary. I do not promise productivity gains before measuring them. And I do not ask a team to give up what makes it proud of its craft: agents take the mechanical moves, developers keep the judgement.

Where to start

If you want to try it in your team, three moves are enough to begin:

1. Write the context file for your main repository, one page, and review it as a team.
2. Pick a procedure that comes back every week, write it as a skill with its checks, and hand it to an agent under supervision.
3. Set a proof rule: no agent change is accepted without the build, the tests and a human review.

The rest comes with use. And if you want to do it together, that is precisely the work I offer.