The Agent Worktree System is a small set of shell functions that spawn, kick off, ship, and clean up isolated 📝Git 📝worktrees for AI coding agents — one command each for the four moments that used to be manual, error-prone steps. It's the tooling layer that makes the 📝A Git Protocol for Parallel AI Coding Agents actually easy to run day to day: the protocol is the source of truth for the rules, these functions are the ergonomic surface over them.

Four functions, sourced into your shell, replace whatever ad hoc scripts or muscle-memory command sequences you were using before. Because they run in your current shell rather than a subshell, they can cd you straight into a new worktree — no copy-paste hop required. Each function detects the active repo from your current working directory, then reads that repo's own small config file for the values that differ repo to repo: which doc holds the operating context, which branch is the default base, which test command to run, and so on. Onboarding a new repo means adding a config file, never editing the functions themselves.

Prerequisites

• A 📝command-center checkout per repo — every onboarded repo lives at one full checkout path (not a worktree) that always stays on the base branch and always stays clean.
• A per-repo config file at the repo root declaring the repo-specific values below.
• A public changelog target for repos that publish one. There's no staging changelog — the open PR is the staging record. Repos with no public-facing audience (internal tools) need no changelog at all.
• A gh-equivalent CLI, authenticated — required for opening/merging 📝PRs and for the status-monitoring command.
• Whatever knowledge base or docs system your agents read at session start — kickoff prompts reference IDs/URLs that the agent reads before doing anything.
• A clipboard mechanism — prompts are copied to the clipboard locally, or via a remote-clipboard escape sequence over SSH.

Interface

new-agent-worktree <slug>

Creates an isolated worktree on a fresh feature/<slug> branch and moves your shell into it.

Parameters: slug — a short, kebab-case task identifier. Becomes both the worktree folder name and the branch name (feature/<slug>).

Behavior:

• Detects the repo's command center from your current working directory.
• Refuses if the command center has uncommitted changes or isn't on the base branch — a dirty command center is the root cause of most parallel-agent pain, so this is where it gets caught.
• Pulls the latest base branch, then creates the worktree from it.
• Moves your shell into the new worktree; you start your agent there.

kickoff-prompt [task-id]

Generates a session kickoff prompt with the repo's values filled in, and copies it to the clipboard. Run from inside a worktree — the task slug is auto-detected from the branch name.

Parameters: task-id (optional) — the ID of the task/roadmap item for this session. If omitted, falls back to the repo's configured default.

Behavior:

• Errors clearly if run outside a feature/* branch, or if required config values are missing.
• Generates a prompt that tells the agent, in order: read the operating context for this repo, read the Git Protocol (universal across every repo), read the task/roadmap item for this session.
• Tells the agent that the open PR is the staging record, and that once the PR opens, the covered task is removed from wherever it was tracked — no "completed" list to maintain, no box-checking.
• If the repo is configured for a session-close journal step, appends the instruction: log one dense entry at close-out.
• Prints to stdout and copies to clipboard.

ship

Opens a release PR from staging to production with an auto-generated title and body, then generates a follow-up prompt for writing the public change-log entry from the release's git diff. Zero typing required for either step.

Behavior:

• Detects the repo, moves into the command center.
• Errors if the repo has no configured public-changelog target and you try to run this — meant for repos that publish one; skip it for internal-only tools.
• Fetches the latest base + head branches.
• Enumerates every commit — and every merged PR — between the last release and now.
• Generates a title (release: N change(s) — YYYY-MM-DD) and a body listing every merged PR (full URL + title).
• Opens the release PR.
• Builds a ship-time prompt: read the change-log target, derive the entry from the release's git diff (never from memory or from the task tracker), curate it to plain, user-benefit language, write it under the current period, and roll over the prior period's entries to an archive on the first entry of a new one.
• Copies the ship-time prompt to clipboard and prints it.

cleanup-worktree [<slug>]

Removes a worktree and its local feature branch, then refreshes the command center.

Parameters: slug (optional) — task slug to clean. Auto-detected from the current branch if you're inside the worktree being cleaned.

Behavior:

• Refuses if the worktree has uncommitted changes.
• Moves your shell out of the worktree first if you're standing inside it.
• Removes the worktree, deletes the local branch, pulls the latest base branch into the command center.

Per-repo config schema

Each onboarded repo's command center contains a small config file at its root. The functions source it; only the values change between repos.

OPERATING_CONTEXT_ID="..."     # where this repo's operating context lives
DEFAULT_TASK_ID="..."          # default task/roadmap source for this repo
PUBLIC_CHANGELOG_ID="..."      # public-facing change log target (omit if this repo publishes none)
BASE_BRANCH="staging"          # feature branches branch from here
PR_BASE="staging"              # feature PRs target this
RELEASE_HEAD="staging"         # source of release PRs
RELEASE_BASE="main"            # target of release PRs
REPO="org/repo-name"
TEST_CMD="npm test"
JOURNAL_TARGET="..."           # where the close-out log entry goes (omit for no journal step)

The config file is kept out of version control by default (it's local agent identity for the machine, not project source), except for repos that deliberately want it tracked. To replicate on another machine, copy the file directly.

Standard session, end to end

cd ~/repos/my-project             # or any worktree under it
new-agent-worktree sidebar-scroll  # creates the worktree, cd's in
claude                             # launch the agent (or your CLI agent of choice)
kickoff-prompt                     # generates + copies the session prompt
# … agent works, opens a PR to staging, merges it, task leaves the tracker …
cd ~/repos/my-project
ship                               # opens the staging→production release PR
                                    # + copies the ship-time changelog prompt
cleanup-worktree sidebar-scroll    # remove the merged worktree + branch

Any repo onboarded to the system uses identical commands — the active repo is inferred from your current directory. Override the default task with an explicit ID: kickoff-prompt <explicit-id>.

Error Handling

• Repo not onboarded — add the per-repo config file first.
• Missing operating-context value — the repo's config is incomplete; fill it in.
• Missing changelog target on ship — either this repo genuinely publishes no changelog (don't run ship), or the config is incomplete.
• Not on a feature branch — kickoff-prompt and bare cleanup-worktree both auto-detect the slug from the branch and need one to detect.
• Command center has uncommitted changes — new-agent-worktree refuses on purpose; a dirty command center is exactly the failure mode the Git Protocol's command-center invariant exists to prevent.
• No task ID provided and no default configured — pass one explicitly, or set a default in the repo's config.
• Divergent-branch error on the sync pull — this means a commit landed directly on the command center's local base branch while origin moved on, which should never happen. Recovery: preserve the stranded commit on its own branch, hard-reset the command center to match origin, then PR the rescued branch in properly.

Contexts

• 🏷️#ai-agents
• 🏷️#git
• 🏷️#software-development