Add a handoff skill and point .cn at it - #2
Merged
Merged
Conversation
.cn described the whole behavior inline in one alias line: "give me a standalone prompt for the next agent to continue this process." That leaves the shape of the document entirely to the model, and what comes back is a session recap — what we covered, what was confirmed, what is next — addressed to nobody in particular. The sections are the fix. A briefing for an agent is operative, not retrospective: what to read and in what order, the state it inherits, its scope and where to stop, the standing constraints, and a definition of done. Constraints are the section that recaps never have and the one that saves the most time, so it is required; if a session produced none, the handoff says so rather than dropping it. Output stays plain prose, but precision is exempted from the prose rule — paths, SHAs, test counts and error strings are reproduced verbatim, because a path the next agent cannot paste is a broken handoff. The old 200-400 word cap is gone; it was forcing exactly the vagueness the skill is meant to prevent. Moves .cn from the command aliases into the prompt aliases, alongside .ip and .um, which is where the skill-backed ones live. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
joshwand
marked this pull request as ready for review
August 3, 2026 01:11
The rewrite in the previous commit was justified by comparing two real handoffs, one useful and one not. That comparison was the whole method, and it was done by hand and thrown away. This keeps it. Prompts regress in a way code doesn't: an edit can leave a skill still producing something fluent and well organised that has quietly stopped being actionable. Nothing fails. You find out two sessions later when an agent starts on the wrong thing. Two layers, because there are two kinds of failure. Format regressions are mechanical, so lint_handoff.py decides them in stdlib Python — the seven sections present and ordered, prose rule held, constraints not empty, something paste-able actually named. Substance regressions need judgment, so rubric.md carries 21 assertions for a model to grade, weighted so that four load-bearing ones cap the score if failed. The calibration pair is the part worth keeping honest. good.md and bad.md are both written from case 01, and the grader scores them before it scores anything real: good must clear 18, bad must stay under 10. A grader that can't separate them is rewarding fluent prose, which is precisely the failure this exists to catch — bad.md is fluent, well organised, and useless, because it is what the skill produced before. Three cases: the hard one with real state and constraints, a planning-only session that tests whether required sections get padded when there's nothing to put in them, and one blocked on a human where two live options have to survive unchosen. Fixtures are synthetic. evals/local/ is gitignored for grading real handoffs without publishing project details. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
joshwand
changed the title
Conflict was in the alias table, which both sides restructured. Main's version wins on everything it touched: the named agreements, .pi and .nd pointing at ProveItToMe and ItsNotDoneUntilItCompletelyWorks, and .nyr moved up beside them. The one thing kept from this branch is .cn's location. Main still had it in the command aliases; here it sits in the prompt aliases next to .ip and .um, because it now expands into a skill rather than a one-line instruction, which is exactly the distinction that block draws. That also fits main's new convention rather than fighting it: the alias table entries point at a name or a skill instead of restating the rule inline, so .cn describing its own output in two lines was the odd one out either way. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The evals aren't ready and shouldn't hold up the skill. Moved to handoff-evals, stacked on this branch, so this PR is just the skill, the .cn wiring, and the README entry. Removed here rather than rewritten out of the history, because this branch is already pushed and under review and a force-push would throw that away. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
joshwand
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
skills/handoff/— the third skill alongsidememory-bankandinteractive-planning— and points.cnat it.The eval suite that was here has moved to #4, stacked on this branch, since it isn't ready.
Why
.cncurrently carries its whole definition in one alias line: "give me a standalone prompt for the next agent to continue this process." That leaves the document's shape to the model, and what comes back is a session recap — what we covered, what was confirmed, what's next — addressed to nobody in particular. Fine to read, not much use to act on.The comparison that motivated this: a handoff written to that shape opens with "This is for Josh, the developer of..." and closes with a suggestion. A good one opens with "You are continuing a multi-session implementation... steps 1-4 are done, committed at 1a0e936" and closes with a checklist. The difference is the sections, not the writing.
What the skill does
Output is written to the agent picking the work up, in the second person, and the sections are operative rather than retrospective:
Standing constraints is required — it's the section recaps never have and the one that saves the most rework. If a session produced none, the handoff says so in a sentence rather than dropping it.
Two deliberate rules. Precision is exempt from the prose rule: output stays plain prose, but paths, SHAs, test counts and error strings are reproduced verbatim, because a path the next agent can't paste is a broken handoff. And the old 200-400 word cap is gone — it was forcing exactly the vagueness the skill exists to prevent.
Notes
.cnmoves from the command aliases into the prompt aliases, where the skill-backed ones (.ip,.um) live..ts: memory is the durable project record, a handoff is a one-shot briefing aimed at a specific next step. The handoff points at memory rather than duplicating it.mainafter Trim ruleset for the Claude 5 generation, and drop the installer #1 landed. The alias-table conflict resolved in main's favour on everything it touched (named agreements,.pi/.nd/.nyr); the only thing kept from this branch is.cn's move into the prompt aliases, which fits main's new convention of alias entries pointing at a name or a skill.Verification
Cold read, plus a check against two real handoffs: every substantive block of a known-good one (ordered read list, inherited state with SHAs and counts, scope-and-stop boundary, protected paths and hook constraints, hand-back instruction, done criteria) has a home in the new format, and a discussion-only planning session still produces something sensible rather than collapsing into empty sections.
Net diff against
mainis three files:AGENTS.md,README.md, and the newskills/handoff/SKILL.md.🤖 Generated with Claude Code