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

Raw Blame History

name, description

name	description
pickup	Start a work session on a Maven task. Runs task start, reads the brief and the disposable handoff, restates the assumption set, and waits for correction before touching code. Use at the start of any session that continues earlier work, when the user says "pickup", "continue", "resume", or names a Vikunja task id.

Pickup

The point of this skill is the pause in step 5. Every wasted session in this repo started with an agent that inferred the goal instead of stating it back.

0. Get on the branch

task start <vikunja-id>

~/.local/bin/task owns the branch, the identity and the PR. It cuts task/<id>-<slug> off origin/master and sets the commit author to the claude gitea user. It writes TASK.md from the Vikunja task, and pulls any waiting review comments into .task/review-comments.md. Do not hand-roll any of that.

TASK.md is the brief and it is immutable. If it says a PR already exists, this is a review-fix session and not new work. Read the comments first.

1. Read the handoff

HANDOFF.md at the repo root, if it exists. It is gitignored, it belongs to one session, and it holds only what is needed to resume. Treat it as a claim from the previous agent, not as truth. It can be stale or wrong.

If there is no handoff, that is normal. It means the last session closed clean.

2. Read the durable state

In this order, and stop as soon as you have enough:

The Vikunja task, by id. Project Maven is ID 2, MCP at http://localhost:9100/mcp. The task description and its comments hold the goal, the constraints, and the assumption ledger. This outranks the handoff on every conflict.
CLAUDE.md, the section that covers the area you are about to touch.
The one file under docs/ that owns the area. Check its Last verified line. If the sha is behind the code you are reading, say so in step 4 and trust the code.

Do not read the dated files under docs/evals/. They are measurements from one day, never updated. Read one only when you need the number it recorded.

If no task id is known, ask for one before doing anything else. Work without a task is work nobody can resume.

3. Look at the ground

git status, git log --oneline -5, and the diff on the current branch. What the repo says beats what any document says.

4. Restate, then stop

Write at most five bullets and stop. Do not write code, do not open files to "check one thing first", do not start with a small safe change.

Task:        V-359, one line.
Done:        what is already on the branch.
Next:        the one thing this session does.
Constraints: what would make this wrong.
Assuming:    the beliefs that, if false, waste the session.

Then ask: is this right? Wait for the answer.

A corrected assumption goes into the Vikunja task as a comment, not into the handoff. The handoff dies tonight. The task does not.

5. Then begin

Delete HANDOFF.md. It has been consumed and must not outlive this step.
On master, cut the branch: scripts/task-branch.sh <id> <slug>.
One task per session. When context passes roughly half, run /wrap rather than pushing on. A compacted session is a session that forgot why it made a choice.

3.2 KiB Raw Blame History