diff --git a/adapters/claude/commands/handoff.md b/adapters/claude/commands/handoff.md new file mode 100644 index 0000000..f82324c --- /dev/null +++ b/adapters/claude/commands/handoff.md @@ -0,0 +1,17 @@ +--- +description: End-of-session handoff — verify work is saved, update AGENTS.md durable knowledge and Current state, propose commit and push +argument-hint: [optional focus notes] +allowed-tools: Bash(git:*), Read, Edit, Write, Grep, Glob +--- + +Run the end-of-session handoff checklist for the repository in the current working +directory. +Optional focus notes from me (may be empty): $ARGUMENTS + +Your complete handoff guide — the close-out checklist, what belongs in durable knowledge +versus Current state, and the final report format — is at: + + ~/Projects/standards/guides/handoff.md + +Read it in full first, then follow it exactly. If you cannot read that file, stop and +report precisely that — do not improvise the handoff. diff --git a/guides/handoff.md b/guides/handoff.md new file mode 100644 index 0000000..b6abdf7 --- /dev/null +++ b/guides/handoff.md @@ -0,0 +1,46 @@ +# Session handoff + +The session is about to end. Run the close-out checklist below. Use judgment — skip any +step that doesn't apply to what was done this session, and tell the user what you skipped +and why. The user may provide optional focus notes; weave them in where relevant. + +## 1. Verify the work is on disk + +- If this is a git repo, run `git status` and report any uncommitted or untracked changes + related to this session's work. +- If meaningful work is uncommitted, propose a commit (or a few logical commits) with clear + messages. Wait for the user's approval before committing — do not commit on your own. + After committing, push if a remote is configured. +- If this is not a git repo, list every file created or modified this session and confirm + each one is actually written to disk, not just discussed in conversation. + +## 2. Update AGENTS.md — durable knowledge only + +- Add or refresh only what every future session will need: architectural decisions made, + conventions or patterns established, gotchas discovered, key commands, dependency or + structure facts learned the hard way. +- Keep it lean. AGENTS.md loads at the start of every future session, so no session + narrative, no play-by-play. If anything in it is now obsolete or contradicted by today's + work, fix or remove it. +- If a piece of guidance is subsystem-specific rather than whole-repo, put it in + docs/guides/.md with paths: frontmatter, symlink it from the harness's rules + directory, and add its one-line index entry in AGENTS.md instead. + +## 3. Update the Current state section — session state + +- Rewrite the `## Current state` section at the bottom of AGENTS.md. It represents current + state, not a running log — overwrite, don't append. Present tense, 15 lines max. Cover: + - What's done and working, including anything finished this session + - What's in progress and exactly where it stands + - Next steps in priority order + - Open questions, risks, or anything the user flagged that wasn't resolved + - Test/build status if worth knowing +- Anything longer-term goes in ROADMAP.md, not here. If Current state is accumulating + history, prune it — history lives in the git log. + +## 4. Final report + +Reply with a short summary: what got committed or pushed, what went into durable knowledge +versus Current state, and anything still unresolved. If everything is clean, say it's safe +to exit. Then, in case the user decides to keep the session alive instead, give them a +one-line `/compact Focus on ...` command tailored to what matters most from this session.