17b6e5bb91
Workspace version bump for the merged `worktree-vm-network-investigation` branch (Lima-style host ← guest port mirroring + per-launch egress policy hole-punching). New AGENTS.md captures the conventions I keep forgetting: - bump workspace version after every feature merge - merge submodule before superproject when both move - don't relocate build output to tmpfs - don't `rm -rf` inline from tool calls (use scripts) - commit-message style on this branch is multi-paragraph Why/How README now points at AGENTS.md alongside PLAN.md / ARCHITECTURE.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.8 KiB
AGENTS.md — conventions for coding agents working on this repo
Things that aren't obvious from the code and that I keep forgetting to tell you. Read once, then act on them silently.
After merging a feature branch, bump the workspace version
Every merge into rewrite-microsandbox ships with a
workspace.package.version bump in the root Cargo.toml and a
follow-up vX.Y.Z: bump for <feature> commit. Skipping this leaves
the next release boundary ambiguous and means downstream
agent-vm --version lies about what's in the binary.
Convention (look at git log --oneline | grep "^[a-f0-9]* v"):
git merge --no-ff <feature-branch> # produces "Merge ...: ..."
$EDITOR Cargo.toml # version = "0.1.N+1"
git commit -am "v0.1.N+1: bump for <one-line feature>"
Cargo.lock will need refreshing — run a build after the bump to
update it, then commit the lock alongside the version bump if it
moved (it always does).
Submodule merges go first
vendor/microsandbox is a submodule with its own branches. When a
worktree changes both the agent-vm code and the vendored microsandbox
code, merge inside the submodule before merging the superproject —
otherwise the superproject merge will conflict on the gitlink and
you'll have to redo the submodule merge anyway. Pattern:
cd vendor/microsandbox && git merge --no-ff <subm-feature-branch>cd ../.. && git add vendor/microsandbox(bumps the gitlink)git merge --no-ff <agent-vm-feature-branch>(resolves the gitlink conflict to the merge SHA from step 1)
If the feature branch lives in a separate git worktree, the
submodule branches in that worktree's .git/modules/... are not
visible from the main worktree. Push them across with
git -C <worktree>/vendor/microsandbox push <main-worktree>/.git/modules/vendor/microsandbox <branch>:<branch>
before attempting the submodule merge.
Don't relocate build output to /tmp or /dev/shm
If a build is too big, slow, or runs out of inodes, fix the root
cause. Don't sidestep by pointing CARGO_TARGET_DIR at tmpfs — that
loses everything on reboot, masks real disk pressure, and the next
agent will spend an hour relinking from cold.
Don't rm -rf state directories from the assistant turn
Claude Code prompts on every rm -rf and it's painful. The repo
ships /tmp/clean-state.sh for state cleanup — use it, or write a
new short script if it doesn't cover your case. Inline rm -rf in
tool calls is a UX papercut for the human, not a safety win.
When in doubt about scope, read the prior commit messages
Commits on this branch use a multi-paragraph "Why / How" style with real examples (often live e2e output). Match the style; don't write single-line commits for non-trivial changes. The commit body is where future-you (or future-me) recovers the reasoning.