Skip to content
CS Capstone Handbook

Team Working Agreement

Your team has just formed, or it has worked together long enough that a habit nobody chose is starting to grate: pull requests that sit unreviewed for a week, a decision made in a private message, a teammate who goes quiet from Friday to Monday. This page covers the working agreement (sometimes called a team charter): what it settles, how to write one together, and how to keep it current. It doesn’t cover how to confront a teammate who isn’t contributing, or the branch and review rules for the code, which belong in CONTRIBUTING.md.

A working agreement is a document the team writes together to make its operating model explicit: how decisions get made, how people communicate, what “done” means, and what happens when something isn’t working. Every team develops those habits anyway. With an agreement, the team forms them on purpose instead of by accident and has something to point at when one person’s expectation and another’s habit disagree.

Why Working Agreements Matter

Section titled “Why Working Agreements Matter”

Write the agreement before the first technical argument, because a team of strong developers can still stall on process: which branching strategy to use, who breaks a tie, what “finished” means. Those questions are cheaper to settle in the abstract, before anyone’s code or pride depends on the answer.

Google’s Project Aristotle is the best-known attempt to measure which of these actually matters; it’s an internal study of 180 Google teams, published on Google’s re:Work site rather than in a journal. Google found that who was on the team mattered less than how the team operated, and that psychological safety ranked first of the five dynamics Google identified: whether members believed they could take an interpersonal risk, such as admitting a mistake or asking a question, without being penalized for it. Use the agreement to build psychological safety: decide in it what happens when someone says they’re stuck, so the person saying it knows the response before they speak.

Edmondson (1999) defined team psychological safety and, in a study of 51 work teams in a manufacturing company, found it associated with the team’s learning behavior. She built that study on her earlier work with hospital patient-care teams, where members of some teams openly acknowledged a medication error and discussed how to avoid a repeat, while members of others kept it to themselves (Edmondson, 1999). The hospital study found that the teams differed not only in how often errors happened but in how likely an error was to be detected and learned from (Edmondson, 1996).

Aaron et al. (2014) compared business-student teams under several charter conditions and found that introducing a charter improved communication, effort, mutual support, cohesion, and member satisfaction. Mathieu and Rapp (2009) followed 32 MBA teams through a business simulation: the quality of a team’s performance strategy, its plan for the task, predicted its performance, and the teams that sustained the highest performance had both a high-quality charter and a high-quality strategy. Write the agreement alongside your project plan, then, rather than in place of one.

What Effective Agreements Cover

Section titled “What Effective Agreements Cover”

No single template fits every team, but effective agreements settle the same few areas. Treat them as conversations to have early rather than sections to fill in.

Roles and Ownership

Section titled “Roles and Ownership”

Make sure everyone knows who to go to for what, because a question with no obvious owner goes to whoever answers first, or to nobody. This doesn’t mean rigid hierarchy: the useful unit is the concern rather than the job title. Three concerns need an owner on almost any team: the schedule and the partner relationship, the shared AI configuration and the confidentiality rule, and the Definition of Done and the state of the build. Call the owners a Project Manager, an AI Coordinator, and a Quality Owner if you want labels, and name them once rather than letting a second informal set grow alongside.

Count owners per concern, not per person. A concern with two owners has none, because each will assume the other is handling it. A team of two has one person holding two concerns and should say which; a larger team has people holding none of the three, who should own something else nameable instead: a subsystem, the test suite, the deployment. Coordination work the three don’t cover, such as keeping documentation current and facilitating stand-ups and retrospectives, is what those additional areas are for, and assigning it explicitly stops it falling on whoever notices first.

Decision-Making

Section titled “Decision-Making”

Not every decision needs a team meeting. A useful agreement distinguishes three levels:

  • Individual decisions: implementation details within your own work.
  • Team decisions: anything that affects others’ work, the architecture, or the project’s direction. Discuss these (in a stand-up, the team channel, or a dedicated meeting) before acting.
  • Escalated decisions: blockers, pivots, or changes that affect the project partner. These involve the partner, and whoever supervises the team.

A default rule for silence keeps team decisions moving. The Apache Software Foundation calls it lazy consensus: state your intent in the shared channel, wait a set time for objections (Apache usually waits 72 hours), and treat silence as consent. A 24-hour window suits a small team that talks daily, for low-stakes, easy-to-reverse choices; a hard-to-reverse decision deserves an explicit yes from everyone it affects.

Communication

Section titled “Communication”

Be specific about how the team stays in touch:

  • Where conversations happen. Pick one primary channel (Slack, Discord, Teams) and commit to it.
  • How fast a message gets answered, in hours.
  • When the team meets: stand-ups, sprint reviews, and retrospectives, each with a day and a time.
  • How someone flags something urgent.

Choose the channel your team already opens every day. A response-time norm only works on messages people see, and each extra channel is one more place a message can sit unread.

Definition of Done

Section titled “Definition of Done”

The Definition of Done (DoD) answers one question: what does it mean for a task to be finished? It comes from Scrum. The Scrum Guide makes it the commitment attached to the increment, “a formal description of the state of the Increment when it meets the quality measures required for the product”, and says that an item that doesn’t meet it can’t be released or even presented at the sprint review.

Without a shared DoD, “done” means different things to different people. One person considers a feature done when it works on their machine. Another considers it done when it’s deployed, reviewed, and documented. The mismatch surfaces at integration time and during sprint reviews, when the gap is most expensive to close.

A DoD doesn’t need to be elaborate, but it does need to be written down and agreed on. It usually grows as the project matures: early sprints might require only a reviewed PR and passing tests, while later sprints add deployment and documentation. The team agrees on it together, as part of the working agreement, and writes it down in CONTRIBUTING.md, because the people and AI tools that merge code read that file and never see the agreement.

SprintsThe Definition of Done is used every sprint to determine when work is complete. See example DoD checklists for software and research projects.

Conflict Resolution

Section titled “Conflict Resolution”

Every team disagrees. Define how the team handles it before tensions arise, while nobody is angry yet. A simple escalation path:

  1. A direct conversation between the people involved.
  2. A team discussion, in a retrospective or a dedicated meeting.
  3. Escalation to someone outside the team with authority over it, such as a manager or an advisor.

Write escalation into the agreement as an ordinary step, because a team that treats it as a failure tends to wait until the problem can no longer be fixed. The conflict guide owns the performance conversation and the escalation path in detail; the agreement holds only the part decided in advance.

Inclusion

Section titled “Inclusion”

Agree explicitly on how the team makes sure every member is heard, especially in design discussions, code reviews, and retrospectives. Practical approaches include:

  • Rotating who facilitates meetings.
  • Posting proposals in writing before a decision, so everyone has time to think.
  • Inviting quieter members to give their view before closing a discussion.

A rotating facilitator and an explicit invitation to speak are mechanisms anyone can check, where “we value everyone’s input” is a sentiment nobody can. Check at each retrospective whether they’re still happening, because nothing breaks visibly when they lapse.

AI Tool Usage

Section titled “AI Tool Usage”

Your team will probably use AI coding assistants: in the Stack Overflow (2025) developer survey, an industry report with a self-selected sample, 84% of the roughly 34,000 who answered the question said they use or plan to use AI tools in their development process.

Settle four questions early, because teammates who each prompt their own assistant their own way can leave the codebase with inconsistent patterns, conflicting abstractions, and code nobody on the team fully understands:

  • Which configuration does the team share? Agree on one AGENTS.md checked into the repository, so every teammate’s agent gets the same architectural context whichever model it runs.
  • Which tools may see your material? Teammates may bring different models to the same repository, so the confidentiality rule names the tools, and the model providers behind them, that each kind of material may go into.
  • What review does AI-generated code get? A reasonable default is the same review as human-written code. The author is responsible for understanding and defending what they commit, whoever (or whatever) wrote the first draft.
  • How does the team handle an architectural change an AI tool suggests? Treat it like any design change: discuss it, check it against the design document, and write an ADR if the team adopts it. Nobody merges a structural change just because an assistant proposed it.

These norms apply differently depending on the phase of work. During early exploration, prototypes, and spikes, let the team experiment loosely with AI tools: a prototype exists to learn fast and be thrown away, and requiring full design compliance and rigorous review for throwaway code slows down the experiments that lead to better design decisions. The norms above matter most for code meant to last: anything merged into the main branch, deployed, or built on by others.

These norms belong in the working agreement because they’re about how the team coordinates rather than about the tools. The technical side (which architectural constraints to encode, how to keep AI output consistent with the design) is in the technical design guide.

Technical Design in the Age of AIHow design documents help coordinate teams where everyone uses AI coding tools.

From Agreement to Repository

Section titled “From Agreement to Repository”

A working agreement captures how the team operates. A CONTRIBUTING.md file in your repository captures how someone contributes to the codebase. The two are related but serve different readers.

Your working agreement is for the team. It covers roles, communication, conflict resolution, and norms. Your CONTRIBUTING.md is for anyone who touches the code: current teammates, future contributors, and reviewers. It covers branching strategy, PR requirements, code style, testing expectations, the Definition of Done, and where each kind of work lives.

Think of CONTRIBUTING.md as the technical expression of your working agreement. When the agreement says “all work goes through reviewed pull requests,” CONTRIBUTING.md says what that means in practice: branch naming, review turnaround, merge strategy.

Writing Your Agreement

Section titled “Writing Your Agreement”

Write the agreement together. When one person drafts it and the rest sign off, the others have agreed to read it rather than to the norms in it, and the disagreements the drafting was meant to surface stay hidden until they cost something.

A short working session (45 to 60 minutes) is usually enough:

  1. Each person writes their top three non-negotiables for working well in a team.
  2. Share and discuss them. Look for consensus and surface tensions early.
  3. Draft the document together during the session.
  4. Review the communication cadence and the Definition of Done with your project partner.

Atlassian’s working agreements play is a scripted alternative of about an hour: a lead drafts the communication channels and escalation process in advance, and the team edits them. The cost is that one person frames those two sections before anyone else speaks.

Before the session, name the stage your team is in, and spell out more (explicit roles, response times) the less the team knows each other, because members who haven’t worked together can’t fall back on habits they don’t share yet. Tuckman (1965) reviewed 50 studies of group development and proposed four stages; on the interpersonal side, a group moves from testing and dependence, through conflict and then cohesion, to functional roles. The Team Formation Strategies Assessment walks those stages under their popular labels, forming to performing.

Keep the agreement with the team’s own documents, such as a shared drive or the team wiki, not in the code repository. It is an agreement between the people on the team, while the repository is read by the project partner and inherited by whoever maintains the code next.

Kept to the conversations above, the agreement stays short. Here is one for a three-person team building a shift board, where a nonprofit’s volunteer coordinators post shifts and volunteers claim them:

# Working Agreement


## Roles (rotate at each new phase)
- Project Manager, Sam: board, sprint planning, partner liaison.
- AI Coordinator, Priya: AGENTS.md, skills, the confidentiality rule.
- Quality Owner, Jordan: CI, test suite, the Definition of Done.


## Decisions
- Individual: your own task. Team: architecture, dependencies, scope,
  proposed in the channel; silence for 24 h is a yes.
- Escalated: partner-facing changes, blockers over one sprint.
- Log: team and escalated decisions, on the team drive. The chair
  rotates; each of us chairs at least one team decision a phase.


## Communication
- Discord #shift-board. Acknowledge within 24 h on weekdays.
- Stand-up Tue and Thu 17:00. Review and retro every other Friday.
- Availability: 9 h/week each; interview weeks announced a sprint ahead.
- Meeting notes in the team drive the same day, for whoever missed it.


## Merging
Definition of Done and where work lives: CONTRIBUTING.md.


## Inclusion
Facilitator rotates each meeting; anyone who hasn't spoken is asked
before a decision closes. Accommodation requests go privately to the PM.


## When it isn't working
Triggers: two missed stand-ups in a sprint, or a PR unreviewed for 48 h.
Talk directly within a week; raise it at the next retro; after two
sprints with no change, escalate to our supervisor.


## AI and confidentiality
Shared config in AGENTS.md; generated code is reviewed like any other.
Any tool: our code, docs, synthetic data. Partner-approved tools only:
partner API docs, meeting notes. Never: production data, personal data,
credentials.

Keep yours short enough to read in five minutes, a few pages at most, because the agreement gets consulted in the middle of a disagreement, and nobody reads ten pages to find the clause they need.

Keeping It Alive

Section titled “Keeping It Alive”

An agreement written in the first weeks and never reopened stops describing the team. Luvison and Michel (2025) found that student teams who revised their charter partway through the project showed significantly higher team commitment, team satisfaction, and individual effectiveness than teams who used a one-time charter. The revised-charter teams also received feedback and coaching, so the effect belongs to the three together.

Revisit it at the natural moments:

  • At the start of each new phase of the project: does it still reflect how the team actually works?
  • After a significant conflict: what process gap allowed it?
  • When the project scope changes: do the roles and the DoD still apply?

Keep the agreement’s earlier versions, which the version history of a shared document does for you. Its history shows how the team’s norms changed and when, which is useful to the team and to anyone who later needs to understand how it operated.

When Things Go Wrong

Section titled “When Things Go Wrong”

Use the agreement against slow erosion more than against a blowup: a teammate who misses deadlines, posts vague updates, and leaves tasks in progress for a sprint with nothing to show. A blowup forces a conversation on its own; erosion never produces that moment, so the team needs something to point at. When the agreement states availability in hours, says that a blocker is raised at the next stand-up rather than sat on for a week, and the team has a minimum deliverable per person per sprint that the board can show, then “I feel like you’re not contributing” becomes “the board shows no completed tasks from you in the last two sprints”, which is observable and hard to deflect.

How to have that conversation, when a bad week becomes a pattern, and when to escalate are the conflict guide’s subject.

When a Role Goes Unfilled

Section titled “When a Role Goes Unfilled”

Assigning someone a role, such as documentation owner or facilitator, doesn’t guarantee they’ll do it. If the person responsible for a role consistently neglects it, the team has two choices:

  1. Reassign the role to someone willing to do it, and have a direct conversation about why.
  2. Redistribute the work so the role is shared rather than owned by one person.

Quietly picking up someone else’s responsibilities without addressing the gap doesn’t work. The person covering builds resentment, and the rest of the team learns that an assignment in the agreement can be ignored without consequence.

Validation

Section titled “Validation”

Check the agreement against how the team behaves, not against who signed it:

  • Every teammate can say, without looking, where decisions get made and how fast a message gets answered. If the answers differ, the agreement was written but never agreed.
  • Your project partner has seen the communication cadence and the Definition of Done and didn’t object.
  • The first retrospective checked it against what actually happened and changed at least one line. A first draft rarely matches a real sprint, so an untouched agreement usually means nobody compared the two.

Measuring Success

Section titled “Measuring Success”

The agreement is working when it changes behavior, which is harder to see than whether it exists. Each signal below can be checked without asking anyone how the team feels.

  • Time to raise: how long between a norm being broken and someone saying so. One sprint is good; a whole phase of the project is the failure mode.
  • Where decisions happen: a design change that first surfaced in a pull request rather than the channel shows the decision levels aren’t being used.
  • Rotation on schedule: roles changed hands when the agreement said they would, with a written record of who chaired what.

Best Practices

Section titled “Best Practices”
  • Be specific. “Acknowledge within 24 hours on weekdays” is a norm; “respond promptly” isn’t, because nobody can say when it was broken, so enforcing it means arguing about a teammate’s attitude.
  • Include a process for changing it. “Any teammate can propose a change; the team discusses it at the next retrospective” is a reasonable default.
  • Write it in a live session, in person or on a call, because a comment thread lets people skip the disagreement a conversation forces into the open.

Some Truths About Working Agreements

Section titled “Some Truths About Working Agreements”

A working agreement written because someone required one tends to be written once, in the first weeks, and never opened again. Everyone involved can tell this is happening and nobody says so, because the document looks complete and the deadline has passed. Put yours where the team already looks, linked from the board and opened at every retrospective, so re-reading it is part of a meeting the team already holds.

A working agreement can’t fix a team that has a real problem, and it’s sometimes used to avoid having one. Writing “we will communicate respectfully” is easier than telling a teammate their code review comments are hostile, and a team can spend a productive-feeling hour drafting norms to avoid the five-minute conversation it actually needs. Test each clause by asking whether it would change what a specific person does next week, and if none would, have the conversation the drafting was standing in for.

Expect parts of the agreement to be wrong within a few months. The team that wrote it didn’t know how much time the project would take, which tools would stick, or who would turn out to be reliable at what. When a clause is broken often, treat that as a sign the clause may be unrealistic before concluding the team is failing, and use the retrospective to find out which.

Working Agreements in Industry and Academia

Section titled “Working Agreements in Industry and Academia”

In industry, agile teams write working agreements under many names: team charter, team manifesto, team norms, social contract. Large engineering organizations also document norms that apply across every team, such as coding standards, on-call expectations, and incident response; Google’s engineering practices, which set out its code review standards, are a public example.

Basecamp’s How We Communicate shows what a company-scale working agreement looks like in public, and it is far longer than yours needs to be. Read it for the kind of decision it bothers to write down, which is defaults rather than values: which channel is for what, how long a reply may take, what’s a meeting and what’s a document.

A company that writes its norms down can hand them to a new hire on the first day instead of leaving them to be learned from mistakes. Your CONTRIBUTING.md does the same for anyone who joins your project or reviews your work.

For a student team, the agreement is also a record of how the team meant to operate, which gives the team, and whoever supervises it, a starting point when something stops working.

References

Section titled “References”

Additional Readings

Section titled “Additional Readings”

Sources and further reading

Activities that exercise this