ShiftLead/agent-cadence

agent-cadence is a working cadence for repos where AI coding agents do work: a rule set for how
concurrent sessions share a checkout, track what they defer, keep the person informed and get changes merged,
plus the hooks, checks and CLI helpers that enforce or detect each rule. It is for a developer running one or
more agent sessions (currently Claude Code, Codex, Gemini CLI, with more coming) on a repo who has lost work that only existed in a chat,
merged a PR nobody reviewed, or found two sessions committing on one checkout.
The goal is that different agent tools can work the same repo, or a set of repos, side by side, with every
piece of work tracked and nothing lost between sessions. That lets someone who understands how LLM agents work
get the most out of them: run several at once, hand work from one tool to another, and step away without
losing the thread.
None of the tooling is copied into your repo, which holds only the files it owns. A repo names a commit of this repo in docs/cadence.toml (a pin), and a
one-file launcher, agent-cadence, runs the pinned tree's tools from a per-machine cache. Everything in the tree
is stdlib-only Python 3 or bash, so an agent session can read, run and patch any of it on the spot. Claude Code is
wired through one SessionStart hook line and skills; Codex and Gemini CLI get the same rules and procedures
through AGENTS.md and .agents/skills/.
The rules are files/docs/cadence.md, numbered so any one is citable; the reasoning
behind each is files/docs/cadence-rationale.md. The rest of this file is what
the tooling gives you and how to adopt it.
## What you get
Each rule ships with the tool that enforces it, or the check that notices when it is broken.
One session per checkout (cadence.md §1). The first session in a checkout keeps it (the anchor); every
other concurrent session works in a git worktree, so no two sessions share a HEAD, index or working files. A
SessionStart hook, checkanchor.py, reads the live sessions of every tool it can see (Claude Code, Codex,
Gemini CLI), says so when a tool the repo lists in its agents setting cannot be seen, and warns a second
session into a worktree.
hydrateworktree.sh completes a worktree with what git does not track, reapworktrees.sh removes those
whose work has landed, and checkbase.py tells a resumed session when its branch has already merged.
A ledger of deferred work (§2). Anything found and not fixed gets a TD-NNN (technical debt) entry, with a Why and a
Fix, in docs/technicaldebt.md or, split, one file per entry under docs/ledger/. ledger.py --check
validates entries and --pickable prints what is ready to work, in order; ledgernextid.py takes ids from a
counter branch on origin so two sessions never take the same number; forge.py in-flight TD-NNN says whether
a PR or branch already has an entry.
Never strand work (§3). Anything that needs the person goes on a board, docs/userattention.md, as an
item with a due date. The SessionStart hook prints what is due; /attention is the full report; the
/stranded-work sweep hunts for work left in worktrees, branches, stashes and closed sessions' transcripts.
Convention changes are announced in an append-only cadence-changes.md, which the hook prints once per