Team onboarding and adoption, loop by loop

Team adoption of coding agents is the spread of one working practice from a few engineers to the team, one loop at a time. Each loop has an owner who onboards teammates at the loop’s current autonomy level. Adoption is measured as effective use: eligible engineers who complete the loop at its evidence boundary while change failures stay at baseline.

This page is for the tech lead who owns the rollout, and for the CTO who asks whether it worked. You gave twelve engineers access in the spring. Two of them run dependency bumps through an agent every week, a senior stopped after one bad pull request, and the rest use it for completions. In the last retro someone said the early adopters “ship much faster”, and nobody could say how it was measured, or what it cost the review queue.

What this loop-by-loop rollout gives you

• A rule for choosing the first loop the team adopts, and a named loop owner instead of a “champion network”.
• A shared harness every engineer’s agent reads, kept in sync across Claude Code, Codex and Cursor.
• An onboarding sequence that takes one engineer from access to a counted completion in two real tasks.
• Separate rules for spreading a loop to more people and climbing it to the next ladder level, with who signs each.
• The effective-use measure, with a prompt that computes it from merged pull requests, and the failure modes that make adoption numbers lie.

Why adopt by loop instead of by adoption curve?

Usage no longer tells teams apart. DORA’s 2025 report found that “90% of survey respondents report using AI at work” (Google Cloud, 23 September 2025). The same report’s central finding is the reason to stop counting users: “AI doesn’t fix a team; it amplifies what’s already there.” A team that spreads agent use without tests, review limits and shared context gets more unreviewed change, not more delivery.

A level also belongs to a loop, not to a person or a team. The one map defines a loop as a repeatable class of change with its own trigger, oracle and stop condition, such as dependency bumps, flaky-test repair or feature work in one service. One engineer can run dependency bumps at L4 and payment-provider work at L2 on the same day, and both are correct.

Translate older rollout schemes, then retire them:

Retired scheme	What it tried to do	What replaces it
Adoption curve (champions, early adopters, majority, laggards)	Pace the rollout by people	Spread one loop at a time, with an owner and an eligibility list per loop
“Phase 0” shared baseline	Stop conventions drifting across tools	The shared harness below, with an exit check
Org-size models (2–10, 10–50, 50+) with fixed weeks	Size the calendar	Loop count and team count set the pace; pilot design for many teams
Three training tiers	Teach tool features by seniority	Upskilling per ladder transition
Active users, sessions per day	Prove adoption	Effective use per loop, with guardrails

Build one shared harness before anyone onboards

Onboarding fails when each engineer’s agent reads different context. Before the first teammate joins a loop, commit one instructions file generated from the real repository. The project conversion playbook covers the full setup; this is the minimum.

Claude Code

Run claude at the repository root and paste:

Explore this repository and write a CLAUDE.md at the root. Capture our stack,
the exact install, build, typecheck, lint and test commands, our branch and
PR conventions, and the conventions a new engineer most often gets wrong.
Bullet points only, under 60 lines. Then run each command you listed and
report which pass on the default branch. Finally, list which rules an
automated check could enforce, so they move into CI instead of prose.

On a large monolith, add “use subagents to survey each top-level directory” so the exploration does not exhaust the main session’s context. Claude Code also reads AGENTS.md when a project has no CLAUDE.md, from v2.1.277 for first-party sessions and v2.1.281 on Bedrock, Google Cloud, Foundry, LLM gateways or with telemetry off, both on latest and on stable since stable reached v2.1.287 (checked 2026-10-12). Check your engineers’ versions before relying on it.

Codex

Codex reads AGENTS.md before it starts work, and /init in the Codex CLI drafts one. Replace the draft with this prompt’s output:

Read this repository and write an AGENTS.md at the root: stack, the exact
install, build, typecheck, lint and test commands, PR conventions, and the
conventions a new contributor would miss. Keep it under 60 lines. Run each
command you listed and report which pass on the default branch. Then list
the conventions stable enough to enforce in CI.

Since Codex CLI 0.150.0, an untrusted project does not supply its AGENTS.md, so each engineer marks the repository as trusted once: accept the trust prompt the first time codex runs in the repository, or add the repository’s absolute path to ~/.codex/config.toml as [projects."/path/to/repo"] with trust_level = "trusted" (key checked on Codex CLI 0.157.1). Put that step in the onboarding checklist. To confirm the file loaded, ask the agent to quote the first rule in AGENTS.md.

Cursor

Open the agent in the repository and ask it to draft project Rules from the same facts:

Read the repository structure, package manifest, CI configuration and the
three largest source files. Draft project rules capturing our stack, how
to run tests and lint, our branch and PR conventions, and the three things
a new contributor most often gets wrong. Write imperative rules, not prose,
under 50 lines. Show me the rules before you save them.

Commit the Rules with the repository so every engineer’s agent loads them. Keep one core of conventions and generate the per-tool files from it, as shared agent rules describes.

The exit check for the harness is mechanical: a fresh clone passes typecheck, lint and tests with exactly the commands the instructions file lists. Teams running more than one tool then need the files to stay in agreement.

Copy-paste prompt: keep the team's context files in sync

Compare CLAUDE.md, AGENTS.md and the Cursor project rules committed in this
repository. List every place they disagree about our stack, commands or
conventions, with the file and line for each side. Propose one source of
truth: pick the most complete file, and rewrite the others as thin pointers
to it plus the notes that only apply to that tool. Show me the diffs and
wait for my approval before writing anything.

Run the sync prompt whenever one of the files changes. Shared skills and hooks follow the same rule: one committed copy, reviewed like code (shared skills).

Which loop does the team adopt first?

Pick the loop whose output your code host and CI already judge, so completion is counted by the system, not by the person who ran it.

Criterion	Good first loop	Poor first loop
Volume	At least five merged changes a month, so a 30-day window holds evidence	A quarterly migration
Oracle	A test, type check or contract check decides “done”	“Looks right to the reviewer”
Risk class	Low or medium: tests, internal tooling, dependency patches	Authentication, payments, schema migrations on production data
Blast radius	One service, reversible by revert	Shared libraries every team imports
People	Two or more engineers do this work weekly	One specialist owns it alone

Flaky-test repair, dependency bumps and failing-test fixes usually pass all five. Record the loop, its current level and its owner in the repository’s loops.yaml; the adoption roadmap has the register format.

What does a loop owner do?

A loop owner replaces the old “champion”: accountable for one loop’s evidence, not for evangelizing a tool. Pick someone peers respect who explains well, not the loudest early adopter.

• Runs the loop first and records the rough edges in the loop’s entry.
• Pairs with each teammate on their first task in the loop.
• Curates the shared harness for the loop: instructions, skills and the onboarding task list.
• Reports measured results in team meetings: completions, accepted changes and failures, never anecdotes.
• Carries friction back to the tech lead, classified, so the team fixes the most frequent class first.

Cap the owner’s support time and rotate the role when the loop reaches its next level.

How does a teammate join a loop?

Onboarding is two real tasks from the backlog, not a workshop on a toy project. It ends when the engineer counts toward effective use.

Settle data handling before a loop leaves its first team

Agree data handling, SSO, admin policies and audit logging with your security team, and ship them as managed policy rather than as a wiki page. Privacy and data handling lists what to decide.

1. Access and policy. A managed account, the team’s usage policy accepted, and a working setup that reads the shared harness. In Codex, that includes trusting the repository (accept the prompt on the first codex run there). Nobody on the loop gets production credentials through the agent.

2. Read the loop, not the tool manual. The engineer reads the loop’s loops.yaml entry and its adoption card: which tasks are eligible, what counts as done, and which paths are excluded.

3. First task, paired. The owner and the engineer take one eligible task from the backlog and run it at the loop’s current level. The task ends at the evidence boundary: a merged pull request with required checks green.

4. Second task, solo. The engineer runs a second eligible task alone. The owner reviews the pull request the same way as any other in the loop, not more strictly.

5. Counted. Add the engineer to eligible.txt with their onboarding-complete date. They count in the denominator of effective use for this loop in every window that starts on or after that date, and in the numerator for any such window in which they have a completion. Counting from the window start keeps a late joiner from deflating a window they could not have completed, and it means the two onboarding PRs never count as completions. Developer onboarding time turns steps 1–3 into a timed fixture for new hires.

What the newcomer learns depends on the loop’s level, not on their seniority:

Loop level	What the newcomer does	What a human reads before merge	What the owner checks on task one
L2 Paired	Steers the agent live and answers permission prompts	The newcomer reads every edit as it happens	The task stayed inside the eligible paths
L3 Review manager	Starts an unattended run in a worktree or sandbox, then reviews the diff	A reviewer reads every diff	The run used the shared harness and the local tests passed before the PR
L4 Spec manager	Writes or accepts the spec and acceptance criteria, then reads the evidence bundle	The spec and the evidence bundle; code only for high and critical risk classes	Tests and CI files are untouched, and the bundle matches the acceptance criteria

Copy-paste prompt: pick onboarding tasks for one loop

Read loops.yaml and the open issues exported to issues.json. For the loop
"flaky-test-repair", list the eight open issues that best fit its eligible
tasks. Exclude anything touching auth, payments, schema migrations, secrets,
CI configuration or test fixtures shared by other services. For each issue
give: why it is eligible, the test or check that will decide "done", the
files it will probably touch, and an estimate of small, medium or large.
Order them from the easiest first task for a newcomer to the hardest. Edit
no files.

Export the issues first with gh issue list --state open --limit 200 --json number,title,labels,body > issues.json, and change the loop name to yours.

When does a loop spread, and when does it climb?

A loop changes in two independent ways. Spreading adds people at the same level. Climbing moves the loop to the next rung of the ladder. Change one per measurement window, never both, or you cannot tell which change caused a failure.

Change	Go when	Stop or roll back when	Who signs
Spread to the next group of engineers	Effective use among current eligible engineers is stable for one window, and follow-up fixes and change failures are at or below baseline	Time to first review rises past the team’s cap, or follow-up fixes rise above baseline	Tech lead
Climb L2 → L3	Runs finish unattended in isolated checkouts and reviewers can keep up with every diff	Reviewers start approving without reading; the review queue grows week on week	Tech lead
Climb L3 → L4	Protected tests, an evidence bundle on every PR, and a sampled audit that passes	A sampled PR changed its own tests, or the loop’s revert rate rises	Tech lead, with the code owner for the paths involved
Climb L4 → L5	Low-risk classes auto-merge by rule, and the rollback path fired in a drill	Any loop-caused incident in the window	Tech lead and the CTO who owns the risk-class policy

The mechanics of each climb (worktrees, protected tests, evidence gates, auto-merge rules) are on the adoption roadmap. The people side of moving review from diffs to evidence is in trust transfer.

How does the pace change with the number of teams?

Shape	How many loops move at once	What coordinates them
One team	One loop spreading or climbing at a time	The tech lead and one loop owner
Several squads sharing a codebase	One loop per squad, each with its own owner	One shared harness core; per-squad loop entries in loops.yaml
Many teams	Pilot loops on two or three teams against matched teams that continue as before	A signed decision rule from pilot design, then the organization-wide roadmap

Copy-paste prompt: a loop-by-loop rollout plan for several squads

Read loops.yaml. We are 18 engineers in three squads (payments, web,
platform) on TypeScript, Node and Postgres, and each squad has one loop
owner. Draft a rollout plan that moves one loop per squad per 30-day
window. For each window and squad give: the loop, whether it spreads (more
engineers, same level) or climbs (next level), never both; the eligible
engineers as a count; the go rule and the rollback rule; who signs; and
the top risk. Keep payments below L3 for every loop that touches money
movement. Then list three objections our senior engineers will raise and
the check that would answer each. Edit no files.

Change the squads, stack and sizes to yours.

How do you measure adoption without counting seats?

Measure effective use per loop, with the definition from measuring effective workflow use:

effective use (loop, window) = eligible engineers with ≥ 1 completion at the evidence boundary
                               ÷ eligible engineers with access and onboarding completed

The evidence boundary is a merged pull request with required checks green that was not reverted, or fixed by a follow-up change, within 14 days. Pair the number with guardrails from metrics frameworks: the 14-day follow-up fix rate, change failure rate and time to first review, each against the pre-rollout baseline for the same task type. DORA’s 2025 report (Google Cloud, 23 September 2025) is why the guardrail is not optional: “we observe a positive relationship between AI adoption on both software delivery throughput and product performance”, and in the next sentence, “AI adoption does continue to have a negative relationship with software delivery stability.” Report per loop and per team, never per engineer.

To make the count mechanical, label each pull request with its loop (loop:flaky-test-repair) and with agent-assisted from the PR template. The window is the 30 days ending 14 days ago, so every completion has had 14 days to be reverted or fixed. Export 44 days of merged pull requests in a terminal at the repository root:

# GNU date (Linux); on macOS use: date -v-44d +%F
SINCE=$(date -d '44 days ago' +%F)
gh pr list --state merged --search "merged:>=$SINCE" --limit 1000 \
  --json number,title,author,labels,mergedAt,body,statusCheckRollup > merged-prs.json

Save the prompt below as prompts/effective-use.txt, list the eligible engineers in eligible.txt (one login loop onboarded-YYYY-MM-DD line per engineer and loop, since each loop has its own eligibility list), and run it read-only:

Claude Code

claude -p "$(cat prompts/effective-use.txt)" --tools "Read" --strict-mcp-config > effective-use.md

--tools "Read" removes every other built-in tool and --strict-mcp-config skips the project’s MCP servers, so the agent itself has no tool that edits files or runs commands. Hooks in your settings files still run, so add --setting-sources user (or run it in a clean checkout) if the project defines hooks. --setting-sources user still loads your user-level and plugin hooks; --safe-mode also disables hooks, plugins and MCP servers (Claude Code 2.1.283).

Codex

codex exec -c default_permissions=":read-only" -o effective-use.md "$(cat prompts/effective-use.txt)"

The :read-only permission profile is beta in Codex CLI 0.157.1. Do not combine it with --sandbox; the profile and legacy sandbox systems do not compose.

Cursor

Attach merged-prs.json and eligible.txt to the agent, paste the prompt, decline any command or edit it proposes, and save the answer as effective-use.md.

Copy-paste prompt: effective use per loop from merged pull requests

Read merged-prs.json (pull requests merged in the last 44 days) and
eligible.txt (one "login loop onboarded-YYYY-MM-DD" line per engineer and
loop, loop without the "loop:" prefix). Use only labels, authors, titles,
bodies, mergedAt and statusCheckRollup in the JSON. Count a PR only if
every check in its statusCheckRollup concluded SUCCESS, NEUTRAL or SKIPPED;
if the rollup is empty, count the PR as "unknown". The window is the 30 days ending 14 days
before today: count only PRs whose mergedAt is at least 14 days before
today. Count an engineer as eligible for a loop only if their onboarded
date is on or before the window start.

For each loop label (labels starting with "loop:"):
1. Completions: window PRs labelled "agent-assisted" whose author is
   eligible for that loop, excluding any PR that a PR merged within the
   next 14 days reverts (title starts with "Revert" and references it) or
   fixes ("fixes #N", "follow-up to #N").
2. Effective use: engineers eligible for that loop with at least one
   completion, divided by the engineers eligible for that loop. Show
   numerator and denominator.
3. Reverts and follow-up fixes: the PRs excluded in step 1, as a count and
   as a share of the loop's agent-assisted window PRs.
4. Engineers eligible for the loop with no completion: a count only, never
   names.

Output one table per loop, then a list of PRs you could not assign to a loop
and why. Write "unknown" for anything the JSON cannot show. Never estimate.
Edit no files.

To check the output, pick three completions and three excluded PRs at random and confirm each against the code host. If one of the six is wrong, fix the labels or the prompt before you report the number.

Standardize review before the loop spreads

Before a loop spreads past its first engineers, agree what a reviewer checks, and make the pull request carry it. At L3 the reviewer still reads every diff; at L4 the reviewer reads the spec and the evidence bundle, and reads code only for high and critical risk classes. Let a review agent run first, against the same standard: /code-review in Claude Code, /review or codex review in Codex, or the Cursor agent with the standard attached. Agent PR review covers wiring it into CI. A human still owns the merge.

Copy-paste prompt: a review standard for this loop's pull requests

Read CLAUDE.md or AGENTS.md, loops.yaml, and the 20 most recent merged pull
requests labelled "loop:flaky-test-repair" (exported to loop-prs.json).
Write a review standard for this loop with at most 10 checks a reviewer can
finish in five minutes. Cover the failure modes specific to agent output:
imports or APIs that do not exist, tests that assert the implementation
instead of the requirement, changes to tests or CI configuration, silent
edits to files outside the task, unvalidated input and secrets in code.
For each check, say whether CI could enforce it instead of a person, and
how. Then write a PR-template section that asks the author for the loop
label, the acceptance result and whether an agent wrote the change.
Edit no files.

Every check the prompt marks as enforceable goes into CI before the loop spreads. A check a person has to remember erodes first.

What do you say when people push back?

Treat each objection as a gap in the loop’s evidence and close it with a check, not an argument.

Objection	The evidence gap behind it	What to do
“I’m faster without it.”	No measured comparison on this person’s tasks	Run a matched pilot on their own tasks; skeptics and seniors has the pilot log and an honest reading of METR’s results
“Agent code is bad.”	The loop has no oracle the agent cannot edit	Put the senior in charge of the loop’s checks; the loop climbs only when those checks hold
“It doesn’t understand our codebase.”	The engineer’s agent is not reading the shared harness	Ask the agent to quote the first rule in CLAUDE.md or AGENTS.md; if it cannot, the file is not loading. In Codex, check that the repository is trusted: its path has trust_level = "trusted" in ~/.codex/config.toml
“Our current way works.”	Nobody has seen both workflows on the same task	Run the old workflow alongside the loop for one window and compare the two on the guardrails
“This will replace my job.”	No stated view of the role	Say what the team’s work becomes, specifying and verifying behavior; see craft and career

Do not mandate the tool on day one. Forced adoption produces sessions that exist to satisfy a dashboard and pollutes the effective-use denominator.

When team adoption stalls

• Adoption stops after the first engineers. The usual cause is a missing harness or no owner in each squad, so every new person starts from zero. Recover by running the harness exit check on a fresh clone and naming one owner per loop.
• Conventions drift across tools. CLAUDE.md, AGENTS.md and the Cursor Rules disagree, so results depend on who drives. Run the sync prompt, make one file the source of truth, and add a CI check that fails when the pointer files change without it.
• One bad agent PR burns credibility. Revert it, add the check that would have caught it to CI, and pause spreading for one window. Do not pause the whole team: the other loops’ evidence is still valid.
• The loop owner becomes a help desk. Answers live in chat, so questions repeat. Move each repeated answer into the instructions file or a shared skill, and rotate the owner.
• The review queue grows. Spreading added authors faster than reviewers. Set a per-team cap on open agent pull requests with the review queue limits and stop spreading until time to first review returns to baseline.
• Numbers nobody measured. “It feels faster”, or a speed-up figure nobody can trace, dies at the first “measured how?”. Reconstruct a 12-week baseline from the code host and report effective use with its guardrails, or report nothing.
• Spread and climb in the same window. Failures rise and nobody can say why. Roll back the climb, keep the spread, and change one thing per window from then on.
• Training content goes stale. Teach the loop’s gates and evidence, which change slowly, and assign someone to track tool changes (keeping current).

Where to go next with team adoption

Start from the team rollout hub if you have not converted the repository yet. The next step after the first loop spreads is the repository roadmap.

Adoption roadmap for one repository Climb one repository's loops up the ladder, with gate evidence and a rollback rule per transition.

Measure effective workflow use The adoption card, the four-layer funnel and the scorecard evidence behind effective use.

Helping the team stop reading every diff Shadow review, sampled review and evidence-only review, loop by loop.

Upskilling a team for agentic engineering A curriculum per ladder transition, built from katas on your own repository.