Onboarding a new engineer to code your agents wrote

The new engineer asks who wrote the reconciliation module. You run git blame and every line lands on a squash merge from March, authored by whoever pressed the button, over a body reading "implement reconciliation per spec" and a Co-authored-by trailer naming a model. The person who wrote the prompt left in May.

Onboarding has always run on one instruction: go sit with the author and ask what they tried first. There is nobody to sit with, and the parts that mattered were never written down.

The mirror of this, onboarding an AI agent like a new hire, is about identity and access. This one is about the human arriving after the agents shipped, and most of what they need had to be captured the day you handed the work over.

The commit says nothing and the trailer is not evidence

People trust the trailer more than it deserves. VS Code 1.110 started appending Co-authored-by: Copilot by default in early March 2026, and it fired on commits where Copilot had not been used, after the developer had reviewed the message. Microsoft switched the default back to opt-in in 1.119 on 3 May 2026. So a trailer can name a model that never touched the file, and can be missing from code a model wrote end to end. An accurate one names a tool version, not somebody you can ask.

git log --format='%h %an %(trailers:key=Co-authored-by,valueonly)' \
  -- src/billing/reconcile.ts

One noisy field would be a small problem. Brett Wheeler's The Substrate Collapse, submitted 18 June 2026, makes the larger case: every authorship-based knowledge metric, the truck factor included, rests on the inference that writing code proves you understand it. Generation breaks it. "The same footprint is now compatible with full, partial, or no understanding."

You have not lost a name. Version control can no longer answer the question.

No, having an agent explain the code does not fix this

Search for this and every result points the same way: aim an AI at the repository and let it give the tour. Those tools do work on one class of question: where is auth handled, what calls this function.

They do not touch the question your new engineer actually has, which is always a form of why. Why a durable queue instead of a cron. Why the retry budget is four. That was never in the code to begin with.

The advice also has a measurement problem. Anthropic ran a randomized trial of 52 engineers learning a new library. The AI-assisted group finished in about the same time and scored 17% lower on a comprehension quiz, 50% against 67%. People who asked conceptual questions scored above 65%; people who delegated code generation scored below 40%. The gap opens at delegation, not at reading.

The diagnosis is not mine and it is not new. Addy Osmani published comprehension debt in April 2026, "the growing gap between how much code exists in your system and how much of it any human being genuinely understands." Thoughtworks put codebase cognitive debt in the caution ring of Technology Radar Vol. 34 the same month. What almost nobody writes down is the operational half: which artifact you produce, and when.

Three things a human author gave you that a diff never had

Human onboarding was a transfer of three specific things, none of which live in the source file.

What onboarding relied on	Where it lived	What survives when an agent wrote it
The alternatives tried and rejected	The author's memory, sometimes a design doc	Nothing. The context window is gone.
The constraint that forced the shape	The author's memory, or a chat thread	Nothing, unless the ticket said it
Who to escalate to when it breaks	Team memory, backed by blame	A merge commit and a model name

The rejected alternative is worth the most and dies first. Without it your new engineer spends a sprint cleaning the code back into the shape you ruled out, and an agent asked to simplify the module will re-derive that design and make it look better than what is there.

The constraint is next. Code shaped by a settlement file that lands at an unpredictable time in no fixed order reads as paranoid over-engineering until you know about the file. Then it reads as the minimum. The escalation path looks least important on paper and gets hit first, usually at 3am.

You solve this at delegation time, not at archaeology time

You either solved this the day you wrote the ticket or you did not solve it. There is no second window.

Writing a ticket an agent can finish and writing one a stranger can read six months later are different jobs. The first is about scope, stop conditions, and escalation, which makes the run succeed now. The lines below are the ones the agent does not need and the stranger does.

## Why this shape
Durable queue, not cron: reconcile has to survive a deploy mid run.
Rejected: cron plus an advisory lock. The lock outlived the pod twice in staging.
Constraint: the settlement file lands between 02:10 and 02:40 UTC, unordered.
Ask: @dana

flowchart LR
  A["Constraint is known"] --> B["Ticket records why"] --> C["New engineer reads it"]
  D["Constraint stays in your head"] --> E["Window discarded"] --> F["New engineer guesses"]

Write it while you still know the answer, the only time it is cheap, and put it in the issue template rather than in your own discipline, which loses to a busy week. Repository conventions belong in AGENTS.md, covered in splitting work between coding agents. The ticket carries what is specific to this change.

The trail a decent setup leaves

Our own product now, so read it with the appropriate suspicion. In Taskfolk an agent is a real workspace member with a user row, a membership, and its own API key. That is what makes attribution work without special cases.

The field that answers your new engineer's question is not the session or the diff. It is the owner. Every connected agent has exactly one named human owner, the person who connected it, and that column cannot be null. Disconnecting revokes the key and drops the membership but leaves the history attributed, so a year later a person's name is still attached to work by an agent that no longer exists.

Assigning an issue to an agent creates a pending session before the agent wakes up, carrying a state, a note, the output URL, the model, and agent-reported cost. The activity log records each field change against the agent by name. Connect the repo and commit references land on the ticket too, though the GitHub integration is GitHub only.

The archaeology query is one request:

curl -s "https://taskfolk.ai/api/v1/workspaces/acme/agent-sessions?issue_key=WEB-39" \
  -H "Authorization: Bearer tfk_live_a1b2..."

const res = await fetch(
  "https://taskfolk.ai/api/v1/workspaces/acme/agent-sessions?issue_key=WEB-39",
  { headers: { Authorization: "Bearer tfk_live_a1b2..." } },
);
const { data } = await res.json();

import requests

res = requests.get(
    "https://taskfolk.ai/api/v1/workspaces/acme/agent-sessions",
    params={"issue_key": "WEB-39"},
    headers={"Authorization": "Bearer tfk_live_a1b2..."},
)
data = res.json()["data"]

{
  "data": [
    {
      "agent_name": "Dana's Claude Code",
      "state": "done",
      "note": "opened PR 412, ledger diff is zero",
      "external_url": "https://github.com/acme/api/pull/412"
    }
  ]
}

Now the limit, and it changes what you tell your agents. That note is a single column and every update overwrites it. There is no history. What you read on a finished session is the last thing the agent said, not a log of what it did.

So the durable record is the issue comment, which is append-only and carries the agent's name. Tell your agents to comment when they make a call the ticket did not decide, not only at the end. We store what the agent left on the ticket, not its context window or its reasoning. If it wrote nothing down, there is nothing to recover.

We flag a finished session that left no attributed activity or comment on its issue. It is a heuristic, and one comment defeats it. That check and the wider fleet question live in managing a team of AI agents and keeping an audit trail.

Where Linear does this better than we do

Linear shipped coding sessions on 11 June 2026. Its agent writes code with Claude Code and Codex, then returns a diff on the issue for review. It needs a GitHub connection with code access, spends AI credits, and is on the Basic, Business, and Enterprise plans. Linear says the workflow resolves roughly 30% of its own incoming bug reports, mostly first pass.

That record beats ours where it matters here, because the diff itself sits on the ticket. We store a pointer to it. If the pull request is deleted, the repo moves, or your new engineer has no access to that GitHub org, our external_url is a dead link and the note is all that is left. So have your agents put the reasoning in an issue comment, not only in the PR description.

What our shape buys is uniformity. Taskfolk never runs your agent; it delivers the triggers and stores the session while the runtime works on a laptop or in CI. In a feature table that is a hole. In an archaeology dig it means the trail looks the same whether the run happened in Claude Code, in Codex, or in something you wrote yourself.

Taskfolk editor seats are $3 a month on Pro and $6 on Business; Linear lists Basic at $10 and Business at $16 per user per month billed yearly (both checked 27 July 2026). Connected agents do not count as editor seats on our side. I found no published Linear rule on agent billing, so treat that as unknown, not a win.

The code already written with none of this

You are reading this because the code exists and none of it was captured. The honest word for what comes next is salvage.

Gone permanently: the prompt, the plan, the context window, the alternatives the model dropped. Anything sold as recovery is a summary of code you already have.

Usually still there, in rough order of value: the ticket, even a bad one, which gives you the requester and the date; the PR description and review comments, often the only place a human wrote a reason down; the agent's owner; and the tests, which encode acceptance criteria nobody wrote out.

Liu and colleagues tracked 302,600 AI-authored commits across 6,299 GitHub repositories and found 22.7% of the AI-introduced issues still alive at the repo's latest version. Code smells were 89.3% of them, the category a newcomer is most likely to read as deliberate and leave alone.

Do not document the whole codebase. Pick the five files that would hurt most if someone changed them wrongly, sit with whoever is still here, and write the why for those. Put it in a doc linked from the issues, not a wiki nobody opens. Project docs and grounding an agent on your own docs go deeper.

A first week that uses what survives

Do not start the new engineer in the repository. Start them on the board.

sequenceDiagram
    participant E as New engineer
    participant I as Issue
    participant S as Agent session
    participant O as Agent owner
    E->>I: Which ticket produced this file
    I->>E: Scope, constraint, acceptance
    I->>S: Session anchored to the issue
    S->>E: State, output URL, agent name
    E->>O: Ask the named human owner
    O->>E: Why the cron was rejected

Day one, they read the last twenty closed tickets in the area they will own, with the sessions and PRs attached. Day two, they take one live bug there and find the delegation record before opening the implementation. That order feels backwards. Reaching for the trail first is a habit, and habits set in week one.

Day three, they write the ticket for a small change, delegate it themselves, and review what comes back. That is the conceptual inquiry pattern that held up in the Anthropic study.

Somebody still has to answer why, and when the owner has left that answer gets reconstructed rather than retrieved. Somebody still has to sit with the new engineer while they say "this looks insane" about a module that is correct. None of this replaces either job.

One thing to change this week: add a four-line "why this shape" block to your issue template, and tell your agents to comment when they make a call the ticket did not decide. It costs about a minute per ticket, and it is the only part you cannot backfill.