Skip to content

feat: Automatic developer handover via identity/now.md #181

Closed

Description

@chrislomonico

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)

  1. 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.
  2. now.md is 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.
  3. now.md lacks handover fields — the template only has focus_area and active_issues. No space for what was done, what is in progress, what is pending, blockers, or per-agent status.
  4. No proactive handover detection — detecting a different user existed but the response was the same shallow catch-up as an explicit ask.
  5. No routing trigger for manual handover prep — developers had to explain the concept of handover in natural language every time.

Proposed Solution

  1. Enhanced now.md template — Add last_user, session_count, a full "Last Session Summary" section (done/in-progress/pending/decisions/blockers), and an "Agent Last Touched" table.
  2. Scribe session-end update — New Scribe task that updates now.md with comprehensive handover state after every batch of agent work. This becomes the primary handover artifact.
  3. 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).
  4. 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).

Activity

  1. bradygaster commented on Mar 5, 2026

    @bradygaster
    Collaborator

    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! 💙

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions