branch-context
Skill954 starsChanged 4 months agoMITView on GitHub
Branch-local durable PR state -- issue brief, decisions log, and session handoffs. Read the brief, decisions, and latest handoff at session start; append decisions as you work; write a handoff only on user request or explicit session turnover.
3 other projects use a version of this, 2 of them edited.
Adopted by
Most recently taken up by
- rohaquinlop/dsh-setupedited, first seen Nov 8, 2026
- axiomantic/spellbooktheir own version, first seen Nov 1, 2026
- pydantic/pydantic-aiedited, first seen Nov 1, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 2
- pydantic/pydantic-ai★ 21k20% same
- rohaquinlop/dsh-setup★ 015% same
Wrote their own version · 1
- axiomantic/spellbook★ 13same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- pydantic-clai2/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adopt-prSkill
- pushing-commits-to-the-repoSkill
- migrating-deep-agents-to-pydantic-ai-harnessSkill
- pydantic-ai-harnessSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 6 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 29
Read issue-brief.md, pr-decisions.md, and handoffs-index.md.
- Very specific: line 30
Read the latest handoff -- the last entry in handoffs-index.md points at its file under handoffs/.
- Distinctive: line 32
If the index has no entries, there is no handoff yet.
- Very specific: line 33
If the brief is still the unfilled template, populate it first: run /adopt-pr when a PR already exists, or write it from the linked issue …
- Distinctive: line 44
Do not write a handoff because the context "feels full" -- that misjudges and primes an early stop.
- Distinctive: line 83
When the decision restates a modal claim (always / never / only if / must / unless), quote that clause verbatim instead of paraphrasing -- …
- Distinctive: line 145
Write the handoff (and any unlogged decisions) when the user turns the session over.
- Distinctive: line 154
Not for research notes or repro scripts -- those belong outside this directory.
- Distinctive: line 156
Not for durable codebase facts that outlive the PR -- those belong in longer-lived project docs or memory.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Branch Context
This directory is the home for durable PR/branch state that outlives a single session. Three surfaces:
| File / dir | Role | Lifetime |
issue-brief.md | Synthesis of the issue(s) this branch addresses | Rewritten only when adopting or re-syncing a branch |
pr-decisions.md | Append-only log of non-obvious PR-shaping decisions | Append forever; supersede, never edit |
handoffs/ + handoffs-index.md | Append-only session handoffs for the next agent | Never overwrite a handoff file; index points at the latest |
The instances (issue-brief.md, pr-decisions.md, handoffs-index.md,
handoffs/) are per-branch and git-ignored. The scaffolding (this file, the
scripts, the *.template.md files) is committed. Instantiate the instances from
the templates, or via /adopt-pr when a PR already exists.
Session defaults
On start, before coding:
- Confirm the branch matches the brief's
branch:field (git rev-parse --abbrev-ref HEAD). - Read
issue-brief.md,pr-decisions.md, andhandoffs-index.md. - Read the latest handoff -- the last entry in
handoffs-index.mdpoints at its file underhandoffs/. That is what the previous session left for you. If the index has no entries, there is no handoff yet; start from the brief. - If the brief is still the unfilled template, populate it first: run
/adopt-prwhen a PR already exists, or write it from the linked issue when starting fresh.
While working -- persist without being asked:
- A non-obvious decision (picking path A over B, a plan deviation, an ambiguous
thread resolution) goes into
pr-decisions.mdviaappend-pr-decision.shin the same turn you make it, not "later". - Disk in this directory is the continuity channel, not chat history. Do not rely on the conversation surviving a context clear or a new session.
- Do not write a handoff because the context "feels full" -- that misjudges and primes an early stop. Write a handoff only when the user asks, or when session turnover is already decided (the user is clearing, switching tools, or ending the sitting).
When to write each surface
issue-brief.md
Rewritten only when adopting a branch (/adopt-pr) or re-syncing after new
issue activity. Do not freestyle-edit it mid-session.
pr-decisions.md
Append whenever you make a decision the issue did not already spell out:
.claude/skills/branch-context/append-pr-decision.sh \
--title "<short title>" \
--decision "<one-line decision>" \
--why "<one-line why>" \
--source "<source url -- mandatory>" \
[--iter N] [--supersedes "<earlier title>"]Named flags are preferred (they resist arg-order mistakes). Positional order is
title decision why source [iter] [supersedes] -- do not pass iter as the
second argument.
Entry shape (the script writes this):
## YYYY-MM-DD · <short title> · iter <N or "-">
- Decision: <one line>
- Why: <one line>
- Source: <link -- mandatory>
- Supersedes: <earlier title, if applicable>When the decision restates a modal claim (always / never / only if / must / unless), quote that clause verbatim instead of paraphrasing -- "always X unless Y" compressed to "always X" is a different instruction.
Handoffs
One handoff per session, newest last. Never overwrite another session's handoff.
.claude/skills/branch-context/append-handoff.sh [--writer <name>] "<one-line summary>" [path-to-body.md]--writer tags the index line with the skill that produced the handoff. If you
omit the body path, the script writes a stub you must fill in via Write/Edit
before stopping; prefer writing the full body first and passing its path. To
revise a handoff you already wrote this session, edit the file in place rather
than appending a second index entry.
Handoff body sections (required):
# Handoff · YYYY-MM-DD · <summary>
## Done
- ...
## Next
- ... (ordered; first item is what the next agent starts on)
## Commitments & constraints carried forward
- ... (verbatim; or "none")
## Key paths
- `path` -- why
## Open questions
- ... (or "none")
## Branch-context pointers
- Brief: issue-brief.md (still valid? yes/no)
- Decisions appended this session: <titles or "none">
- Related plan file (if any): <path>Commitments & constraints is a required check, not an optional extra. Before writing the handoff, sweep the session for two things and quote them verbatim -- do not paraphrase, the modality is the payload:
- Constraints the user stated that are not already in the brief's Constraints section. "Always X unless Y" and "always X" are different instructions, and a one-line paraphrase is where the qualifier gets dropped.
- Promises you made and have not kept -- to the user ("I'll add the regression test next"), or on the record in a PR/review comment ("I'll file a follow-up issue", "I'll re-run this once CI clears"). A promise made to a reviewer and then dropped across a session boundary is the expensive kind: the next agent cannot know it exists, and the reviewer is still waiting.
A longer, accurate handoff beats a short lossy one. Do not compress this section to save space.
Session turnover
Write the handoff (and any unlogged decisions) when the user turns the session
over. If the harness has a plan mode, capture the remaining work as a concrete
plan (next steps, files, verification), persist the handoff, then exit plan mode
so the fresh session inherits it. If the harness has no plan mode, persist the
handoff and tell the user to start a new session in this worktree whose first
action is to read handoffs-index.md and the latest handoff.
Scope boundary
- Not for research notes or repro scripts -- those belong outside this directory.
- Not for durable codebase facts that outlive the PR -- those belong in longer-lived project docs or memory. Rule of thumb: if removing the linked thread would make this PR's diff confusing, it is a decision; if the fact still helps after merge, it belongs elsewhere.
Helpers
.claude/skills/branch-context/status.sh # JSON: brief/decisions/handoffs state
.claude/skills/branch-context/append-pr-decision.sh ...
.claude/skills/branch-context/append-handoff.sh ...Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

