From e1be849993b5732686ed63e541bcc108a961b5f8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 29 May 2026 08:48:05 +0000 Subject: [PATCH] docs: document the .jarvis/worktrees/ convention Add docs/worktrees.md explaining the isolated per-task worktree convention: what .jarvis/worktrees/ is for, that .jarvis is gitignored, the fix/issue- branch naming used by automated fixers, and how to list and clean up worktrees. Closes #43 https://claude.ai/code/session_01VKRgwRSZhNcTKsknjEPGGg --- docs/worktrees.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/worktrees.md diff --git a/docs/worktrees.md b/docs/worktrees.md new file mode 100644 index 0000000..b189a13 --- /dev/null +++ b/docs/worktrees.md @@ -0,0 +1,37 @@ +# `.jarvis/worktrees/` convention + +Jarvis uses isolated per-task **git worktrees** so that parallel or automated +work (the auto-mode scheduler, subagents, automated issue fixers) never mutates +the main checkout. Each task gets its own working directory on its own branch, +checked out under `.jarvis/worktrees/`. + +The root is configurable via `JARVIS_WORKTREE_ROOT` (default +`.jarvis/worktrees` under the workspace) and the mode via `JARVIS_WORKTREE_MODE` +(`off` / `per_run` / `per_unit`). Auto mode upgrades `off` → `per_run` +automatically so the scheduler always works on an isolated copy. + +## Gitignored + +The entire `.jarvis` directory is gitignored (see `.jarvis` in `.gitignore`), so +worktrees, scratch state, and other runtime artifacts never get committed. + +## Branch naming + +Automated fixers create branches named `fix/issue-` (for example, +`fix/issue-43`) so the branch maps back to the issue it resolves. + +## Listing and cleaning up + +```bash +# List all worktrees and their branches +git worktree list + +# Remove a finished worktree +git worktree remove .jarvis/worktrees/ + +# Prune stale worktree metadata (e.g. after a directory was deleted manually) +git worktree prune +``` + +Stale worktrees are usually cleaned up automatically when a task finishes, but +the commands above let you inspect and remove them by hand.