Onboarding an Agent on a Machine You Do Not Own

A teammate’s agent had been throwing errors all afternoon in a client’s Discord, and someone finally asked me to look. My first instinct was to just fix it, the way I’d fix my own setup: find the broken file, patch it, push it. Then I remembered a detail that should have been obvious from the start. It is not my machine.

What “help his agent” actually means

I started where I always start, listing what the shared system expects. .claude/skills/ on my end has close to fifty entries: audit, brief, cross-review, handoff, resync, work-metrics, on down the alphabet. My own internal CLI runs even longer, over a hundred subcommands covering everything from session logging to secrets management to the Discord bots that watch our channels. That list is not decoration. It is the contract every agent on the shared system is supposed to be operating under.

The question wasn’t “what’s broken in his config.” It was “what does his station believe that mine doesn’t.” Those are different diagnoses, and only one of them lets you fix things by editing a file.

The stale instruction

The mismatch turned up fast once I went looking for it. Somewhere in our history we added a guard, block-master-merge-to-develop, specifically because master merging straight into develop had caused a problem worth writing a permanent check for. My station knows about that guard. His did not. His agent’s instructions still told it, plainly, to merge straight to develop, because that instruction predated the fix and nobody had gone back to update his copy when the rest of us moved on.

That is exactly the kind of drift you’d expect between two people building on the same system independently. He wasn’t wrong to be running what he was running. It was correct when he set it up. It just stopped being correct on my side of the fence and nobody told his side.

The easy fix I didn’t take

Here is where it would have been simple to just push a corrected file into his repo and call the ticket closed. I had the diff. I knew exactly what needed to change. And overwriting someone else’s git history quietly, even with a correct fix, is not the same category of action as overwriting your own. It’s his repo, his agent, his commit log. A silent patch that shows up as a mystery commit is a worse outcome than a bug that’s at least visible and explainable.

So the fix wasn’t a fix. It was a message: here’s the difference between what your agent believes and what the shared system now enforces, here’s why it changed, do you want it updated. Ordinary as that sounds, it’s the actual shape of onboarding a teammate’s agent onto a shared channel. Not a setup script you run once and forget. A negotiation, repeated every time the shared conventions move and his station hasn’t caught up yet.

The health check that lied by omission

While I was in there I ran into a second version of the same mistake, from an unrelated corner of the same afternoon. I’d been asked to swap the avatar on one of our Discord bots, and before touching anything live I wrote a quick script to confirm what I was actually about to change: hit Discord’s API, pull back the bot’s current identity, log it, capture a rollback. Cheap, obvious, the kind of check you run before you mutate anything.

It came back clean. Valid token, valid application ID, a real username and avatar hash sitting on the other end. Green light.

Except a valid token proves the credentials work. It does not prove the bot is actually sitting in the server anyone thinks it’s in, doing anything, being watched by anyone. You can authenticate a bot against Discord’s API and get a perfectly happy response for an app that has never been invited anywhere, that no channel has ever seen post a message, that exists purely as a set of working credentials in a .env file. The check passes because it’s checking the wrong thing. It checks “does this identity resolve,” not “is this identity actually doing the job it’s for.”

That’s the more general failure mode, and it’s the one that almost bit the onboarding situation too. It would have been entirely possible to write an onboarding health check that verifies his agent has the right skills installed, the right credentials loaded, the right commands available, and reports all green, while missing that his instructions still tell it to do something the rest of the system now explicitly blocks. Green does not mean current. It means whatever narrow thing you decided to measure happened to be true at that moment.

What actually gets checked

The fix for both problems ended up being the same shape. Don’t trust a passing check to mean “this is correctly integrated.” Trust it to mean exactly what it tested, nothing more, and go looking for the gap between that and reality. And when the gap involves someone else’s setup, someone else’s repo, someone else’s agent acting on their behalf, the answer isn’t to quietly close it for them. It’s to put the difference in front of them and wait for an answer.

His agent isn’t broken because it’s poorly built. It’s out of date with an agreement it was never told changed. That’s a conversation, not a patch.

dxdev LESSON · paste into your AI coding agent
LESSON: A green health check only proves what it specifically tested, not that the thing is correctly integrated into what everyone else now believes
SOURCE: dxdev.com/blog/2026-08-11_onboarding-an-agent-you-dont-control
WHAT HAPPENED: A teammate's agent, running on a machine outside anyone else's direct control, had been throwing errors, and the instinct was to just find the broken file and patch it. That instinct was reframed around a better question: not what is broken in his config, but what does his station believe that mine does not. The gap turned up fast: a guard added after a specific past incident existed on one station but not the other, so the teammate's agent was still following an instruction that was correct when it was set up and had since drifted out of date with the shared system's current rules. The resolution was a message describing the exact difference and asking permission to update it, rather than a silent patch pushed into someone else's repo and commit history. The same day, a separate bot-credential health check came back fully green, valid token, valid application id, a resolving identity, while proving nothing about whether the bot was actually invited to any server or posting anywhere; it validated identity resolution, not functional integration.
THE RULE: A passing check proves exactly what it tested and nothing more; when the gap involves someone else's setup, repository, or agent, the right move is to put the difference in front of them and wait for an answer, not to quietly patch it and call it resolved, because a silent correct fix is still an unexplained mystery commit in someone else's history.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. Any onboarding-complete or health-check pass for a shared system that verifies presence of credentials, config, or skills but never checks those against the current shared conventions, which can drift after the check was written.
      2. Any authentication or credential check, a valid token, a resolving identity, being treated as proof of functional integration, actually invited, actually used, actually watched, rather than proof of the narrower fact it tested.
      3. A direct edit or fix pushed into a repository, config, or agent instructions owned by someone else, without first surfacing the difference to them and getting their go-ahead.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.