// Blog / team workflow
Agent handoff between coding sessions without losing repo context
A useful handoff is not a chat recap. It is a repo-local pointer to what changed, what is trusted, and what must be rechecked.
// direct answer
Short answer
Handoff works when the repository stores the continuation point: routing bundle, handoff summary, trust report, repair queue, changed files, and current source-of-truth rules. The next agent should treat chat recap as advisory and re-read source for critical behavior.
Move work from one coding-agent session to another without losing repo context or trust warnings.
// real failure mode
The failure mode
A session ends with useful context in the agent's answer, but none of it is durable or easy to verify.
The next session starts cold, misses a warning, or repeats the same investigation.
The team thinks it handed off work, but it only handed off prose.
// handoff model
The repo-local fix
A handoff should point to files, trust state, changed areas, and repair items.
The handoff summary is useful only when it routes the next agent to source, tests, and evidence.
After meaningful work, rebuild routing and search so the next session sees the current map.
// concrete example
A safe session restart
The first agent updates docs and finds stale module context, but does not finish repair.
Before ending, it refreshes the routing bundle and leaves a handoff summary that points to the stale module and repair queue item.
The next agent reads those artifacts and rechecks source before continuing instead of trusting the prior conversation.
// repo proof
Repo proof to inspect
.knowledge/maintenance/handoff_summary.json
The next agent needs a compact continuation point with routes, risks, and pending work.
- Session continuation
- Finding recent context
- Skipping source recheck
- Treating chat recap as truth
.knowledge/maintenance/events/
Events preserve maintenance actions across sessions.
- Understanding recent maintenance
- Auditing changes to knowledge state
- Replacing git history
.knowledge/maintenance/repair_queue.json
Unfinished uncertainty should be visible to the next agent.
- Picking up incomplete work
- Prioritizing rechecks
- Blocking unrelated edits
.knowledge/maintenance/routing_bundle.json
The next session should start from the current route, not a stale conversation.
- First read
- Finding module boundaries
- Behavior proof
// command transcript
Commands and expected checks
node .knowledge/tools/build-routing-bundle.js - expected
- The compact routing file is current for the next session.
- inspect next
- .knowledge/maintenance/routing_bundle.json
node .knowledge/tools/build-search-index.js - expected
- Local search reflects current knowledge artifacts.
- inspect next
- .knowledge/search/index.json
node .knowledge/tools/doctor.js - expected
- The next agent sees whether it should use caution.
- inspect next
- .knowledge/maintenance/quality_report.json
From one session to the next
// field guide
Handoff artifacts
| Artifact | Carries | Next agent should |
|---|---|---|
| Handoff summary | Recent context and warnings. | Use it to choose what to inspect. |
| Routing bundle | Current first-read map. | Open target source and tests. |
| Repair queue | Unresolved context debt. | Repair, assign, or document. |
| Events | Maintenance actions. | Audit what changed since last session. |
// guardrails
What the agent should not trust blindly
- Treat handoff prose as advisory until current source confirms it.
- Do not hide unresolved uncertainty in a final chat message.
- After meaningful changes, rebuild routing and search before handoff.
// common mistakes
Common mistakes
- Ending with a long summary but no file-backed route.
- Assuming the next agent will remember a warning from chat.
- Not marking stale context discovered during the session.
// quick FAQ
FAQ
Is a chat summary still useful?
Yes, but it should point to repo-local artifacts and current source files. It should not become the source of truth.
What should be refreshed before handoff?
At minimum, routing, search, and doctor status after meaningful knowledge or source changes.
// page-specific next step
Use this page before ending a coding-agent session
Refresh the repo-local route, make unresolved repair work visible, and make the next agent re-read source for risky behavior.