Maven/.claude/skills/wrap/SKILL.md

name, description

name	description
wrap	Close a Maven work session cleanly. Runs the tests, updates the durable docs, commits in reviewable slices with the Vikunja ref, pushes so the PR opens, records state in Vikunja, and leaves a disposable handoff only if work remains. Use when the user says "wrap", "wrap up", "done for now", or when context passes roughly half.

Wrap

Run every step. A partial wrap is worse than none, because the next session trusts the parts that did run.

1. Prove it works

make test. If something fails, fix it or say plainly in the handoff and in Vikunja that it fails, with the output. Never wrap on an untested claim.

2. Update the durable docs

Ask what a future agent would have to learn the hard way, and write that down.

• CLAUDE.md when a fact an agent needs before touching code has changed: routing behaviour, a measured number, a flag default, a constraint. A commit that changed routing or phrasing without touching the matching CLAUDE.md section is a bug. Correct stale text in place. Do not append a new paragraph next to the wrong one.
• AGENTS.md when the recipe to build, run or preview changed.
• The one file under docs/ that owns the area, plus its Last verified: <date> @ <sha> line. Only a doc directly under docs/ carries that line.
• A new dated file under docs/evals/ when you measured something. Never edit an existing dated file. A newer measurement is a new file, and the living doc points at it.

Nothing that must survive tonight goes anywhere else. Not into the handoff, not into a commit message, not into a comment in the code.

3. Commit in slices

Under 300 changed lines per commit in non-markdown files, enforced by .githooks/pre-commit. Markdown is exempt and may land as one batch.

Each commit is one idea, subject in the repo's voice, lowercase area prefix. A Vikunja ref is welcome where a task exists and is required nowhere: the commit-msg hook that demanded it was deleted on 2026-08-25.

router: narrow the single-token rule (V-359)
router: narrow the single-token rule

If a change genuinely cannot split under 300 lines, say why in the commit body before reaching for --no-verify.

4. Land it

task pr

It refuses a dirty tree, pushes, opens or refreshes the PR against the repo default branch, labels the Vikunja task in-review, comments the PR url on it, and pushes an ntfy. Do not push by hand and do not call tea yourself.

task pr needs an id. On a hand-cut branch with no task, push the branch and open the PR by hand, and skip step 5.

5. Record what task pr cannot know

Comment on the Vikunja task: what you measured, what is still open. List every assumption that turned out to be wrong. If the session found new work, create a task for it now rather than describing it in prose.

This step is what makes the handoff disposable. With no task, it cannot run, so the handoff carries that content instead and stops being disposable. Say so in it.

6. Leave the handoff, or leave none

If the task is finished, delete HANDOFF.md and stop. An empty root is the correct end state.

If work remains, write HANDOFF.md with nothing but what the next agent needs to resume, and no history:

# Handoff — <date>

Task: V-359 <one line>, or `unfiled`
Branch: task/359-<slug>, cut from master

## Where I stopped
<two sentences, mid-thought detail that is nowhere else>

## Next action
<the single concrete next step>

## Do not
<the trap I nearly fell into, or the approach already ruled out>

Nothing else goes in it. No summary of what landed, that is in git and Vikunja. No design rationale, that is in docs/. No fact an agent needs on any task, that is in CLAUDE.md. If a line in the handoff would still matter next week, it is in the wrong file.