kami
c0d61a71a4
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>
95 lines
3.4 KiB
Markdown
95 lines
3.4 KiB
Markdown
---
|
|
name: wrap
|
|
description: 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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```markdown
|
|
# 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.
|