feat(hr-handoff): successor thread title, rotation trigger, boundary and record
hr-handoff now says how to replace a session with a successor thread: the title, when stale guidance is worth a new session, when it is safe, and what the handoff and successor record.
Nothing in rules/ or another skill covered this. I searched rules/ and skills/ for handoff, successor, rotate and rotation. The matches were the low-quota modifier, the plan-files modifier, hr-what-next and the existing thread-move step in hr-handoff, none of which set a title, a trigger or a boundary for replacing a session. hr-agent-guidance-refresh only says a reread does not prove injected context changed. The new text is a reference file in hr-handoff, linked from SKILL.md, so it sits beside the thread-move step it extends. No host tool calls are in it, so any host can use it.
| Part | What it says |
|---|---|
| Title | Keep the base title and end it with v<N>. The first thread counts as v1 and is renamed at the handoff. A trailing v<digits> is parsed and incremented. Threads are found by registry row, project and thread id, never by title. |
| Trigger | Replace for stale injected guidance only when the change is an always-on rule, a safety rule, the catalog entry of a skill the session uses, or a subagent definition. Skill bodies and docs need only the reread. |
| Boundary | Never mid-turn, mid-evaluation that fixed its guidance, or with an external action pending. Only when idle, nothing is running and the ledger is reconciled. |
| Record | The outgoing thread is marked settled with a pointer to the successor. The handoff names open offers by ID, and with more than one open the successor asks which a bare go means. The successor re-points registry rows, scheduled tasks, pull request watches and its messaging name, with read-backs. |
Choices made in passing:
- The section does not authorize starting a thread. It defers to the house rules' § Repository work for that.
- The successor asks which offer a bare
gomeans when several listed offers are open, matching § Offers. - The skill's
descriptionis unchanged, so skill selection should not shift.
Checks on this head: node --test test/*.test.mjs (151 pass, 7 skipped), bun test test/ skills/ (488 pass, 8 skipped, 0 fail), npm run check:package -- --bun, pinned oxfmt check clean, pinned oxlint (one existing warning in test/install-ps1.test.mjs, not touched here), and the plain-prose checker on the new file. Not covered: host adoption, and the host-specific tool steps, which the chief-of-staff Orchestrator writes.
Summary by cubic
Adds successor-thread guidance to hr-handoff for replacing a session when stale injected guidance warrants it, covering the successor title, the rotation trigger, the safe boundary, and what the handoff and successor record. The new reference successor-thread.md is linked from SKILL.md and makes no host tool calls, so any host can use it.
- A successor keeps the base title and ends it with
v<N>; the first thread counts asv1and is renamed at the handoff. Threads are found by registry row, project and thread id, never by title. - A replacement is warranted only for session-critical changes — an always-on rule, a safety rule, a skill's catalog entry, or a subagent definition. Skill bodies and docs need only a reread, and a replacement never happens mid-turn, mid-evaluation, or with an external action pending, only when the session is idle with its ledger reconciled.
- The handoff lists each open offer by its recorded offer ID, and the successor acts on one only when the latest ledger still shows it open, so a bare
goselects only when one listed offer is open. The outgoing thread is marked settled with a pointer to the successor, who re-points registry rows, scheduled tasks, pull request watches and its messaging name; items it cannot bind keep the recorded reason and stay behind.
Summary by CodeRabbit
- Documentation
- Added guidance for handing work from a current thread to a successor, including when a replacement is warranted and how to title it.
- Clarified that handoffs should happen only when the session is idle and its work records are reconciled.
- Added steps for transferring open offers and work items, recording handoff outcomes, and ensuring the successor reviews and updates transferred items before taking on new work.