kami/Maven

Files

T

kami c0d61a71a4 session: pickup and wrap around the task flow, one disposable handoff (V-445)

task start and task pr already own the branch, the identity and the PR.
What was missing sat on either side of them.

pickup runs task start, reads TASK.md and any handoff, then restates the
assumption set and stops. That pause is the point: every wasted session
here began with an agent that inferred the goal instead of stating it
back. wrap runs the tests, updates the durable docs, commits in slices,
calls task pr, and records in Vikunja what task pr cannot know.

HANDOFF.md is gitignored and injected by a SessionStart hook. It holds
what the next agent needs to resume and nothing else. TASK.md is the
brief for the branch and does not change. Anything that would still
matter next week goes to Vikunja, CLAUDE.md or docs/.

CLAUDE.md documented none of this, which is why an agent would rebuild
it. It does now, including the two hooks in ~/.claude/hooks.

.claude/ was ignored wholesale. The workflow is now tracked, because how
a session behaves should be reviewed like code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-02 03:22:46 +04:00

3.4 KiB

Raw Blame History

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, and it ends with the Vikunja ref:

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

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.

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.

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>
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.

3.4 KiB Raw Blame History