Repository navigation
Closed
Description
Problem
When multiple developers work on a feature branch with a shared squad, handing over context to the next developer requires manually telling the squad to "prep for handover." Without this prompt, the incoming developer gets no proactive briefing — they have to remember to ask "catch me up" or re-explain the project state to the squad.
The data to support handover already exists (Scribe commits session logs, decisions, and agent histories to the branch), but nobody synthesizes it into a handover-ready format, and the coordinator does not deep-read it when a new developer arrives.
Root Cause (5 interconnected gaps)
- Session catch-up is intentionally lazy — the coordinator is told "Do NOT scan logs on every session start" and only does a shallow 2-3 sentence summary even when it detects a different user.
now.mdis never updated at session end — it is read at session start but the Scribe has no task to write handover state back. It goes stale immediately after init.now.mdlacks handover fields — the template only hasfocus_areaandactive_issues. No space for what was done, what is in progress, what is pending, blockers, or per-agent status.- No proactive handover detection — detecting a different user existed but the response was the same shallow catch-up as an explicit ask.
- No routing trigger for manual handover prep — developers had to explain the concept of handover in natural language every time.
Proposed Solution
- Enhanced
now.mdtemplate — Addlast_user,session_count, a full "Last Session Summary" section (done/in-progress/pending/decisions/blockers), and an "Agent Last Touched" table. - Scribe session-end update — New Scribe task that updates
now.mdwith comprehensive handover state after every batch of agent work. This becomes the primary handover artifact. - Deep handover briefing on user change — Split session catch-up: same user gets lazy summary, different user gets automatic deep briefing from
now.md(proactive, no prompt needed). - Manual handover routing trigger — Routing entries for "prep for handover", "wrap up", "I am done for today", "session done".
Files Changed
| File | Change |
|---|---|
templates/identity/now.md |
Enhanced template with handover fields |
index.js |
Updated inline now.md scaffold to match |
.github/agents/squad.agent.md |
Handover Protocol section, routing trigger, Scribe task |
templates/scribe-charter.md |
Added task 5: write handover state to now.md |
docs/guide.md |
Added identity layer to directory tree, handover subsection |
docs/features/memory.md |
Added "Developer Handover" section |
docs/tour-first-session.md |
Added handover to tips and next steps |
docs/sample-prompts.md |
Added "Developer Handover" prompt section |
docs/whatsnew.md |
Updated identity layer description |
CHANGELOG.md |
Updated identity layer description |
test/init-flow.test.js |
Updated tests for new now.md fields |
.squad/identity/now.md |
Updated live file to match new template |
Testing
All 95 tests pass (npm test).
Metadata
Metadata
Assignees
Labels
No labels
Activity
docs: CHANGELOG and SquadUI integration guide for P0 changes
docs: McManus learnings — Epic #181 P0 documentation
docs(ai-team): Epic #181 completion — session log + decision merge
bradygaster commentedon Mar 5, 2026
Great idea — thank you! 🎯
This is actually being tracked in #180, where we're discussing the same "Automatic developer handover via identity/now.md" feature. Head over there to see the ongoing discussion and add your thoughts.
We really appreciate early-stage feedback like this. Keep it coming! 💙