Agent-Skills.md

Agent Skills: Session Handoff — Device Portability

|

UncategorizedID: danbrickey/edp-ai-expert-team/handoff

Repository

danbrickey/edp-ai-expert-team
danbrickeyLicense: MIT

Install this agent skill to your local

pnpm dlx add-skill https://github.com/danbrickey/exocortex/tree/HEAD/skills/handoff

Skill Files

Browse the full folder contents for handoff.

Download Skill

Loading file tree…

skills/handoff/SKILL.md

Skill Metadata

Name
handoff
Description
|

Session Handoff — Device Portability

You are running a session handoff for Dan Brickey. Your job is to capture the current session state, update any tracked GitHub issues, and write a portable handoff file so Dan can resume from any device.

Step 1: Gather Session State

Run these commands in parallel to understand what happened this session:

Git state:

git status

git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat

git log --oneline -10

Identify the current repo:

basename "$(git rev-parse --show-toplevel 2>/dev/null)" || echo "not a git repo"

Check for uncommitted work:

git diff --name-only
git diff --cached --name-only

Step 2: Identify GitHub Issues Worked On

Look for GitHub issues that were part of this session. Check multiple sources:

2a. Scan conversation context

Review the conversation history for:

  • Any GitHub issue numbers mentioned (e.g., #42, issue 42, references to issue titles)
  • Any gh issue commands that were run
  • Any issue URLs that were referenced
  • Any tasks or topics that clearly map to an open issue

2b. Check recent commits for issue references

git log --oneline -10 | grep -oE '#[0-9]+' | sort -u

2c. Cross-reference with open issues

For each repo Dan works in that has issues (primarily danbrickey/exocortex), check if any open issues match the work done:

gh issue list --repo danbrickey/exocortex --state open --json number,title --limit 30

Match issue titles against the topics/files worked on in this session. Be conservative — only match issues where the connection is clear.

Step 3: Summarize the Session

Build a mental model of what was accomplished. Categorize the work:

  • Completed: Tasks/changes that are done and committed
  • In Progress: Work started but not finished (uncommitted changes, partial implementations)
  • Decisions Made: Key choices or directions decided during the session
  • Blockers/Questions: Anything unresolved that the next session needs to address
  • Next Steps: What should happen next, in priority order

Step 4: Update GitHub Issues

For each identified issue, add a progress comment. Keep it concise — this is a status update, not a novel.

gh issue comment [NUMBER] \
  --repo danbrickey/exocortex \
  --body "$(cat <<'EOF'
**Session update — [date], [device hint: desktop/laptop]**

**Work done:**
- [bullet points of what was accomplished on this issue]

**Current status:** [In Progress / Blocked / Ready for Review / Done]

**Next steps:**
- [what needs to happen next for this issue]

---
*Auto-generated by `/handoff`*
EOF
)"

If an issue is fully resolved by this session's work, ask Dan before closing it: "Issue #[N] ([title]) looks complete — want me to close it?"

If there are uncommitted changes relevant to an issue, note that in the comment: "Note: there are uncommitted local changes related to this issue."

Step 5: Write the Handoff File

Determine the correct location for the handoff file. Use the current repo's root:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"

Write the handoff file to .claude/handoff.md within the repo (create .claude/ if it doesn't exist):

mkdir -p "$REPO_ROOT/.claude"

Handoff file format:

# Session Handoff

**Date:** [YYYY-MM-DD]
**Device:** [desktop / laptop — infer from hostname or ask if unclear]
**Repo:** [repo name]

## What Was Done
- [concise bullets of completed work]

## In Progress
- [anything started but not finished, with enough context to resume]
- [include file paths and line numbers where relevant]

## Commit
- [short hash] — [commit subject line]
- [list key files changed]

## Decisions Made
- [any direction choices, architecture decisions, or conclusions reached]

## Open Questions / Blockers
- [anything unresolved that needs attention]

## GitHub Issues Updated
- [#N — title — status] (for each issue touched)

## Next Steps (Priority Order)
1. [most important next action]
2. [second priority]
3. [etc.]

## Context Notes
[Any additional context that would help resume — e.g., "was debugging X and found Y",
"waiting on response from Z", "the approach in file.py:42 needs rethinking because..."]

Write this file using the Write tool.

Step 6: Commit All Changes and Push

The handoff always commits and pushes everything — that's the whole point. Don't ask whether to commit; just do it. The only exception is files that look like they contain secrets (.env, credentials, tokens) — warn Dan and exclude those.

6a. Stage all work changes

Review git status output from Step 1. Stage all modified, added, and deleted files that represent session work:

git add -A

Before staging, check for sensitive files:

git status --porcelain | grep -iE '\.(env|secret|key|credential|token)' || true

If any sensitive files appear, exclude them:

git reset HEAD [sensitive-file]

And warn Dan: "Excluded [file] from commit — looks like it may contain secrets."

6b. Generate a proper commit message

Analyze the staged changes to write a meaningful commit message. Run:

git diff --cached --stat
git diff --cached

Follow conventional commit format. Categorize the changes:

  • feat: New features or functionality added
  • fix: Bug fixes
  • docs: Documentation, specs, or planning files
  • refactor: Code restructuring without behavior change
  • chore: Maintenance, config, tooling, or housekeeping
  • wip: Genuinely incomplete work that will be continued next session

Commit message rules:

  • Use imperative mood ("add", not "added")
  • Subject line under 72 characters
  • If changes span multiple categories, use the dominant one and note others in the body
  • If changes relate to a GitHub issue, reference it in the footer (e.g., Relates to #42)
  • Include a body when the changes are non-trivial — explain the "what" and "why"
  • If the work is genuinely incomplete (mid-implementation), use wip: prefix and describe what's in progress so the next session has context from the commit message itself

Example — completed work:

docs: add CES provider organization business vault spec

Define grain, business keys, and satellite structure for the
provider-organization link in the business vault.

Relates to #15

Example — work in progress:

wip: provider organization satellite — hub references done, sats pending

Hub-to-hub link and hash key logic complete. Still need:
- effectiveness satellite with temporal logic
- curation view for downstream star schema

Relates to #15

6c. Commit the work changes + handoff file together

Stage the handoff file and commit everything in a single commit:

git add .claude/handoff.md
git commit -m "$(cat <<'EOF'
[generated commit message here]

Session handoff: [date]
EOF
)"

If the changes are large or mixed enough to warrant separate commits (e.g., completed feature work + unrelated WIP), split into two commits:

  1. First commit: the completed/coherent work with a proper commit message
  2. Second commit: chore: session handoff [date] for the handoff file and any remaining WIP

Use your judgment — one commit is fine for most sessions. Only split when it would be confusing to lump unrelated changes together.

6d. Push

git push

If the branch has no upstream yet:

git push -u origin "$(git branch --show-current)"

If the push fails for other reasons (auth, network), tell Dan the commit is local and he'll need to push manually. The handoff file is still written and committed locally, so git push on the other device after a git pull will still work once the issue is resolved.

Step 7: Confirm

Display a clean summary:

## Handoff Complete — [Date]

**Repo:** [name]
**Branch:** [branch name]
**Commit:** [short hash] — [commit subject line]
**Pushed:** [yes/no]

**Issues Updated:**
- #[N] — [title] — [status]
- ...

**Files committed:** [count] files changed
**Handoff file:** .claude/handoff.md

You're good to switch devices. On your next machine:
  git pull
  # Claude Code will read .claude/handoff.md automatically

Resuming on Another Device

When starting a new session on a different device, Claude Code should automatically read .claude/handoff.md if it exists in the repo. If Dan says "pick up where I left off" or "resume", read the handoff file and use it to orient the session:

  1. Read .claude/handoff.md
  2. Summarize what the last session accomplished
  3. Present the next steps
  4. Ask Dan which item to tackle first

Edge Cases

  • Not a git repo: Write the handoff to ~/handoff.md instead and warn that it won't sync automatically.
  • No GitHub issues found: Skip Step 4. Not every session involves tracked issues.
  • Multiple repos touched in one session: Write a handoff file to each repo that had changes. Update issues from whichever repo is relevant.
  • Dan says "quick handoff": Skip the detailed summary. Just update issues, write a minimal handoff file (What Was Done + Next Steps only), commit, and push.
  • gh CLI not authenticated: Skip issue updates, warn Dan, and proceed with the file-based handoff only.
  • No changes this session (pure research/discussion): Still write the handoff if there were decisions or next steps worth capturing. Skip the commit/push if there's truly nothing to commit.