This runbook operates the recurring session-and-release cycle of the 📝Git Agent Protocol: an AI coding agent claims a task, works it in an isolated 📝worktree, opens and merges a 📝pull request, and periodically a batch of merged work ships to production. Each run consumes whatever work is next and produces a merged PR or a shipped release; the process improves itself through the Change Log at the bottom of this document.

Modes

Feedback loop: immediate — correctness is established inside each Run: tests pass or they don't, the merge lands or GitHub rejects it, a release deploys or the deploy platform halts it. There is no delayed unknown to check later against this runbook's own scope. Delayed effects outside that scope — whether a shipped change causes a production issue days later — are owned by whatever monitoring, alerting, or incident process you already run, not by this runbook. Ships Run-only; no separate Verify pass.

Run — execute one complete pass: either a Session Pass (claim a task, work it, merge it) or a Release Pass (ship everything merged since the last release), ending by writing a Run Log with its in-run verification outcomes recorded.

The agent determines which pass based on available work: a task waiting in the tracker means a Session Pass; commits merged to staging but not yet released means a Release Pass. A run is complete the moment its Run Log is written and its verification outcomes — tests passed, merge confirmed, or deploy confirmed — are recorded in it.

Parameters

These map directly to .agent-config, created by the Buildbook below — swap this table's values per repo; the procedures never reference an instance value directly.

Preconditions

Tooling — the procedures below call the shell functions new-agent-worktree, kickoff-prompt, ship, and cleanup-worktree, plus the gh CLI. If these aren't available in your shell, halt and run 📝Onboarding a Repo to the Git Agent Protocol — Agent Buildbook first — it installs all of them and is safe to re-run.
Command center clean — git status in the repo's command-center checkout shows nothing, and it's on BASE_BRANCH. Failing: resolve before running new-agent-worktree; a dirty command center is refused by design.
.agent-config populated — OPERATING_CONTEXT_ID is set, and for a Session Pass either DEFAULT_TASK_ID is set or an explicit task ID is passed to kickoff-prompt. Failing: the Buildbook creates the file but doesn't populate repo-specific values — fill them in before the first run.

Reference

Environment Model

Three environments, three gates, three risk levels.

Branch Protection

Strict status checks are on for staging (multiple agents merge there concurrently — GitHub rejects a merge if another agent merged ahead of this one, forcing a re-sync and CI re-run, which is how parallel agents self-serialize without a lock file) and off for main (staging→main is always sequential — only one release PR is ever in flight). The exact target settings and the gh api payloads that produce them live in the Buildbook's Reference and Exact Commands & Payloads sections — this runbook operates against a repo already converged to that state.

Forbidden Operations

Never check out staging or main directly in the command-center checkout. All work happens on feature/* branches inside isolated worktrees. The command center stays on the base branch, stays clean, and is never used to write commits.
Never force-push to any branch. Blocked by protection on staging/main; forbidden by policy on feature branches too.
Never cherry-pick between long-lived branches. Use full merges via PR — cherry-picking silently diverges branch histories, and a later real merge between them produces spurious conflicts.
Never push directly to staging or main. Blocked by protection. Use a PR.
Never approve your own PR to main. Approval comes from a designated reviewer only.
Never delete or rename staging or main. Blocked by protection.
Never delete a feature branch on the remote until its PR has merged. GitHub auto-closes a PR when its head ref is deleted, and a closed PR can't be merged — branch deletion is always the post-merge step (see Troubleshooting).
Never modify branch protection, CI config, or deploy-infra files without human sign-off first.
Never touch another agent's worktree or feature branch. Any feature/* branch you didn't create this session belongs to someone else.

Why Agents Merge via the API, Not `gh pr merge`

The command-center checkout holds staging checked out at all times. gh pr merge --merge does a local merge — it tries to check out staging in the agent's own worktree, which fails immediately because the command center already holds that branch. The fix: merge server-side via the API. The API call never touches the agent's local worktree; GitHub does the merge in its own copy and returns the new commit SHA. Verify "merged":true in the response before deleting the branch, as a separate step.

Procedure — Run Mode

A. Session Pass

Session start — new-agent-worktree <slug>, launch the agent, then kickoff-prompt. The agent reads CONTEXT.md (or your operating-context doc), this runbook, and the task.
Work — commit locally, test locally, iterate.
Pre-PR sync — git fetch origin && git merge origin/staging before opening the PR, to pull in whatever other agents have already merged.
Open the PR — gh pr create --base staging. This is the hand-off event: the task leaves the tracker now.
Wait for CI — required checks must pass.
Merge to staging via the API (Exact Commands & Payloads).
Verify the merge — confirm "merged":true and a commit SHA. Record this as the in-run verification outcome.
Delete the remote feature branch — only after step 7 is confirmed.
Close out — confirm the work landed clean, remove the item from the tracker (harvest any durable learning into the operating context first), and write the Run Log.
Session end — leave the worktree clean.

B. Release Pass

ship — opens a release PR from RELEASE_HEAD to RELEASE_BASE, enumerating every merged PR since the last release.
The PR sits in review-required state.
A designated reviewer approves it.
Merge via the API — same reasoning as a Session Pass.
The deploy platform pauses for manual approval; a human clicks Deploy.
Confirm production updated. Record this as the in-run verification outcome.
If the project is public-facing, write the change-log entry from the release's git diff — never from memory — then write the Run Log for this release pass.

Run Log Format

Title: Git Agent Protocol — Run Log {YYYY-MM-DD} (prefix with the repo name if one library tracks multiple repos). Visibility: private. Tags: run-log plus this repo's tag. In MythOS or your own tracker of choice, following this shape. Required sections:

Scope — for a Session Pass: task, branch, repo. For a Release Pass: the PRs included.
Input Parameters — which Parameters-table values this run used (repo, branches, test command).
Changes Shipped — what the PR or release actually did.
Verification Results — the in-run outcomes: tests passed, merge confirmed (SHA), deploy confirmed. Recorded at Run close, not by a separate Verify pass — this is the immediate-feedback shape.
Learnings & Proposed Process Changes — mandatory every run, regardless of feedback shape. What this run taught, and any concrete proposal for this runbook. This is what feeds the Change Log below.

Run Logs are durable — never deleted; they're the empirical record the Change Log cites.

Troubleshooting

API merge rejected, required check out of date → staging moved while CI ran. Run git fetch origin && git merge origin/staging && git push, wait for CI, retry the merge command. Never delete the branch as part of this retry.
API merge rejected, "merge already in progress" → an earlier merge call is racing this one. Run gh pr view <n> --json state,mergedAt — if already merged, skip to branch deletion; otherwise retry.
gh pr merge fails with a worktree-checkout error → the local-merge command was used instead of the API. Use the API merge command in Exact Commands & Payloads (Buildbook) or the merge reasoning above.
Branch deleted but PR shows closed, not merged → the branch was deleted before the merge was confirmed. Recreate the branch (git push from the last known commit) and re-open the PR (gh pr reopen <n>), then redo the merge.
Divergent-branch error pulling into the command center → a commit landed directly on the command center's local base branch (forbidden — see Forbidden Operations). Preserve it: git branch rescue-<slug> <sha>, then git reset --hard origin/<base> in the command center, then PR the rescued branch in properly.

Change Log

v1.0 — 2026-07-10 — Converted from the original single-document "Implementation Cookbook" into the Buildbook/Runbook split per the Buildbook/Runbook Conversion Initiative: setup content (branch protection payloads, shell functions, .agent-config schema) extracted to the new Onboarding Buildbook; declared an immediate feedback loop and shipped Run-only, with Session Pass and Release Pass as the two flavors of one Run mode. Evidence: cross-agent design review — the Runbook template's Verify Mode was found to conflate recurrence with delayed feedback, and this runbook is the case that exposed it, resulting in the template gaining a conditional Verify Mode.