Working Agreement Generator
Generate a working agreement your team will actually keep. Toggle eight proven clauses - PR size, review turnaround, focus time - edit the numbers, and download the markdown.
A working agreement is a short, written list of the defaults an engineering team holds itself to - how big PRs get, how fast reviews happen, when it is fine to interrupt someone in a focus block. It is not policy handed down from above. It is the team writing down the norms it already argues about, so the argument only has to happen once.
Most teams run on unwritten rules, and unwritten rules fall apart under pressure. The new hire does not know them, the loudest voice redefines them mid-sprint, and nobody can point at anything when a 2,000-line PR sits unreviewed for a week. Writing the norms down turns 'that is just how we do things here' into something a teammate can read, question, and improve.
This generator gives you eight clauses covering the disagreements most teams have on repeat. Toggle the ones you want, set your own numbers, and download a markdown file you can commit next to the code. Nothing you type leaves your browser.
Build Your Agreement
8 of 8 clauses selected. Five or fewer is a good first version.
Preview
# Team Working Agreement _Drafted 2026-07-18_ How we work: these are the defaults we hold each other to, written down so nobody has to guess. ## PR size limit PRs stay under 400 changed lines; larger changes get split or a pre-agreed exception. ## Time to first review First review within 24 working hours of a PR leaving draft. ## Review coverage Every PR gets 2 reviewers; rubber-stamp approvals (under 1 minute on a 300+ line diff) are a smell we discuss, not a metric we punish. ## Work in progress No more than 2 open PRs per person; finish before starting. ## Draft PR etiquette Open PRs as drafts early; ready-for-review means CI is green and the description says what changed and why. ## Focus time Two meeting-free deep-work blocks per week, on the calendar, respected by default. ## Async first Questions go to the channel, not DMs; decisions get written down where the team can find them. ## Incident handoff On-call hands off with a written summary; nobody debugs alone for more than 30 minutes before asking. ## Review cadence We revisit this agreement every quarter - agreements that nobody edits are agreements that nobody follows.
Credit where due: Swarmia popularized working agreements as a product feature, and it remains a good choice if you want in-tool enforcement with Slack nudges. If you are weighing it up, see our Swarmia alternative comparison. This generator gets you the agreement itself, no tool required.
Want the measurable clauses watched for you?
Two of these clauses - PR size and time to first review - are checkable straight from GitHub data. CodePulse Alerts can notify the team when a PR breaks the agreed limit, so the agreement gets reviewed by the team instead of policed by a manager. For the full playbook on keeping agreements alive, read our working agreements guide.
How it’s calculated
Each clause below is a norm that shows up, in some form, on most working agreements engineering teams actually keep. The measurable ones - PR size, review turnaround, reviewer count - take a number you can tune to your team. The behavioural ones are worded so they describe a default, not a rule with a punishment attached.
The eight clauses
- PR size limit: a ceiling on changed lines, with a pre-agreed escape hatch for the changes that genuinely cannot be split.
- Time to first review: a shared clock on how long a ready PR waits before someone looks at it.
- Review coverage: how many reviewers each PR gets, and an honest line about rubber stamps.
- Work in progress: a cap on open PRs per person, so finishing beats starting.
- Draft PR etiquette: what ready-for-review actually means.
- Focus time: protected deep-work blocks that exist on the calendar, not just in theory.
- Async first: questions in channels, decisions written down.
- Incident handoff: written summaries and a time limit on debugging alone.
How to run the adoption conversation
- Draft it together in a retro, not in a manager's doc. Norms imposed from above get ignored; norms the team wrote get defended.
- Start with five clauses at most. A one-page agreement gets read; a ten-page one gets filed and forgotten.
- Pick numbers the team can keep this quarter, not aspirational ones. A 24-hour review clock you hit beats a 4-hour one you miss.
- Commit the file to the repo, so the agreement lives where the work lives and changes go through review like everything else.
- Revisit it quarterly. Delete any clause nobody has referenced since the last review - dead clauses teach people to ignore the live ones.
Worked example
A six-person platform team keeps missing its sprint goals because reviews stall. In a retro they draft an agreement with five clauses: PRs under 300 changed lines, first review within 8 working hours, 2 reviewers per PR, no more than 2 open PRs per person, and drafts opened early with ready-for-review meaning green CI plus a real description.
- They set the PR size limit at 300, not 400, because their median PR is already 250 lines - the limit codifies what good already looks like for them.
- They set first review at 8 working hours, not 24, because everyone is in two adjacent time zones and a same-day review is realistic.
- They skip the focus-time and async clauses for now: five clauses is enough to start, and those two were not the current fight.
- The generated markdown goes into the repo root as working-agreement.md, merged through a normal PR that everyone approves.
A quarter later the team revisits the file. Review wait time has dropped, so the clause stays. The WIP limit clause has never come up once - they discuss whether it earned its place, tighten the wording, and merge the change. That edit is the point: the agreement stays alive because the team keeps touching it.
Our Take
An agreement nobody can measure is a wish. The clauses teams actually keep are the ones they can check from real data - PR size and time to first review - reviewed together as a team, never used to grade individuals.
Teams write beautiful values statements and break them within a sprint, because nothing ever surfaces the gap. The working agreements that survive pair two or three observable clauses with a standing retro slot where the team looks at its own aggregate numbers. The moment the same numbers get used to score people, the agreement dies: everyone starts gaming the metric instead of keeping the promise.
Key terms
- Working Agreement
- A short, team-authored list of behavioural defaults - review turnaround, PR size, communication norms - that the team commits to and revisits regularly. Owned by the team, not imposed by management.
- Team Charter
- A broader document covering why the team exists: mission, scope, stakeholders, and success measures. A working agreement covers how the team behaves day to day; a charter covers what it is for.
- Review SLA
- The agreed maximum time a pull request waits for its first review. Usually counted in working hours from the moment the PR leaves draft, so nights and weekends do not count against anyone.
- WIP Limit
- A cap on how much work one person has in flight at once - here, open pull requests per person. Limits force finishing over starting, which cuts the pile of half-done branches going stale.
- Rubber-Stamp Approval
- An approval given too fast to reflect a real read of the change - for example, under a minute on a 300-line diff. A useful smell to discuss as a team, and a terrible metric to punish individuals with.
Frequently Asked Questions
A working agreement is a short, written set of defaults an engineering team commits to - things like maximum PR size, how quickly reviews happen, and how the team communicates. It is drafted by the team itself, usually in a retro, and revisited on a regular cadence. The value is not the document; it is that norms which used to be unwritten and contested become explicit, so new joiners can learn them and anyone can propose changing them.
Want to track this automatically?
CodePulse connects to your GitHub and calculates these metrics in real-time. No more manual data entry or spreadsheets.
Free tier available. No credit card required.
See These Features in Action
Break down cycle time into coding, waiting, review, and merge phases.
Measure review thoroughness and feedback quality across the team.
Learn More
Working Agreements That Actually Work (Template)
Working agreements define how your team collaborates. This guide provides templates, examples, and a process for creating agreements around code review, communication, and availability.
Swarmia vs CodePulse: Which One I'd Pick (And Why) ({{YEAR}})
An honest comparison of Swarmia and CodePulse. Both prioritize team health over surveillance - this guide explains where they differ and when to choose each.
7 Code Review Rules That Actually Get PRs Approved Faster
Learn code review best practices backed by metrics. Covers reviewer guidelines, author guidelines, team practices, and how to measure review effectiveness.
Related Tools
Meeting Cost Calculator
See the true cost of meetings for your engineering team. Calculate how much engineering time and money is spent in meetings.
Cycle Time Calculator
Calculate your PR cycle time breakdown. See where time is spent between coding, waiting for review, in review, and merging.
Code Review Time Estimator
Estimate how long code reviews should take based on PR size and complexity. Set realistic review SLAs for your team.