Agent Handoff Notes skill for Codex

A handoff note is good when a fresh agent with no transcript can read it in under a minute, verify it against the repo in one command, and take the correct next step without redoing finished work or retrying a dead end. It records facts, not a diary.

When to write or update the note

Trigger	Action
A milestone is verified (tests green, commit made)	Update state and next step
Before /compact, or when /status shows the context window mostly used	Full update first, then compact
A hypothesis is ruled out	Add to dead ends with the evidence
A decision with alternatives is made	Add to decisions with the reason
Before ending a session or switching tasks	Full update
Handing to a person or another agent	Full update plus open questions

Do not wait for the end: interruptions are unplanned.

Where it lives

• Default: notes/handoff/<task-slug>.md in the repo, git-ignored if it holds personal or noisy detail, committed if the team should see it.
• Not under .codex/ or .agents/: those are read-only inside the workspace-write sandbox, so the agent cannot update a note there.
• One note per task. Link it from the PR description when the work becomes a PR.
• /goal objectives are capped at 4,000 characters; for long tasks set the goal to “Follow notes/handoff/<slug>.md” and keep detail in the file.

Template

Keep it under ~80 lines; prune resolved items rather than appending forever.

# Handoff: <task title>
Updated: 2026-10-28 14:10 UTC by <agent/person> | Branch: feat/rate-limit @ 3f2c1ab

## Goal and done-criteria
Add per-tenant rate limiting to the public API. Done = `make test` green,
p95 latency unchanged in `make bench`, docs/api/limits.md updated.

## State
- [x] Token bucket in src/middleware/ratelimit.ts (tests: tests/middleware/ratelimit.test.ts)
- [x] Redis adapter, 12 tests passing
- [ ] Wire into router (src/server.ts L40-75) <- NEXT
- [ ] Docs page

## Verify current state
`git log --oneline -3` shows 3f2c1ab; `npm test -- ratelimit` -> 14 passed

## Decisions
- Token bucket over sliding window: burst tolerance required by spec (issue #482).
- Limits keyed by tenant id, not API key: keys rotate (see #490).

## Dead ends (do not retry)
- ioredis pipelining for refill: race under concurrent requests; reproduced in
  tests/middleware/race.test.ts (skipped, kept as evidence).

## Commands
- Test: `npm test -- ratelimit` | Full: `make test` | Bench: `make bench` (needs Redis on :6379)

## Open questions
- Should internal callers bypass limits? Asked in #482, no answer yet.

## Next step
Register middleware after auth in src/server.ts, add integration test
tests/api/limits.int.test.ts, run `make test`.

Writing rules

• Exact over approximate: file paths with line ranges, commit SHAs, full commands, literal error messages.
• State what is verified and how; mark unverified claims as such.
• Every dead end carries its evidence, or the next agent will try it again.
• One next step, concrete enough to start without reading anything else.
• No secrets, tokens or customer data; reference where they live instead.
• Update in place. Remove finished checklist detail once it is committed and described in the commit message.

Reading protocol for the next agent

- [ ] 1. Read the note completely
- [ ] 2. Run the "Verify current state" command(s)
- [ ] 3. If the repo disagrees with the note, trust the repo; fix the note first
- [ ] 4. Restate goal, state and next step in one message
- [ ] 5. Execute the next step; update the note at the next milestone

Auto-load the note on resume and after compaction

A SessionStart hook whose matcher covers resume and compact can print the note; plain stdout from that hook is added as developer context, and after compaction it is delivered before the next model request.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "resume|compact",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'for f in \"$(git rev-parse --show-toplevel 2>/dev/null)\"/notes/handoff/*.md; do [ -f \"$f\" ] && { echo \"Handoff note $f:\"; head -c 6000 \"$f\"; }; done; true'",
            "statusMessage": "Loading handoff notes",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Put it in ~/.codex/hooks.json (personal) or <repo>/.codex/hooks.json (team; loads only for trusted projects). New or changed hooks must be trusted in /hooks before they run. Keep the output small; hook output beyond roughly 2,500 tokens is saved to a file rather than shown to the model in full.

Codex features that complement the note

Feature	Use
/recap	Summarize the chat; good raw material for the note, not a replacement
/export notes/transcripts/<slug>.md	Full transcript as Markdown for audit
/compact	Frees context; write the note first
codex resume / codex fork	Continue or branch the same session (see codex-session-resume)
Memories (/memories)	Cross-session recall; not reliable for task state, keep that in the note

Gotchas

• Notes written only at the end are lost when the session dies mid-task.
• A note that narrates (“then I tried…”) instead of stating results doubles the reading cost and hides the next step.
• Stale notes are worse than none: the reading protocol’s verify step exists to catch them. Put the commit SHA in the header.
• Several parallel agents should each have their own note; one shared note gets overwritten.
• Compaction summaries drop exact strings first; copy the failing error text into the note before compacting.

Verification

Start a new session with no history, give it only “Continue the task in notes/handoff/<slug>.md”, and check that it runs the verify command, restates the correct next step, and does not retry anything listed under dead ends.