Skip to content
CS Capstone Handbook

Team Working Agreement

Read this before your team charter, and when a norm nobody agreed on starts causing friction; it gives you what the agreement covers and how to revise it.

Every team develops habits: how decisions get made, how conflicts get handled, how people communicate, what “done” means. The question is whether those habits form intentionally or by accident. A working agreement (sometimes called a team charter) makes the team’s operating model explicit. Without one:

  • Disagreements about process derail technical discussions.
  • Contribution expectations drift until resentment builds.
  • Critical decisions get made inconsistently, or by whoever speaks loudest.
  • Bringing someone up to speed (a new member, or a teammate returning after a break) is painful because nothing is written down.

A working agreement is not a set of rules imposed from above. It is a document your team writes together, revisits regularly, and updates as the project evolves. Its value comes not from the act of writing it, but from the conversations it forces and the clarity it creates.

Why Working Agreements Matter

Section titled “Why Working Agreements Matter”

Software teams fail far more often from coordination problems than from technical ones. A team of strong individual developers can still produce poor results if they cannot agree on branching strategy, cannot resolve disagreements constructively, or cannot maintain a shared understanding of what “finished” means.

Google’s Project Aristotle is the best-known attempt to measure which of these actually matters. Studying its own teams, Google found that who was on the team mattered less than how the team operated, and that the strongest single predictor was psychological safety: whether members believed they could take an interpersonal risk, such as admitting a mistake or asking an obvious question, without being penalized for it. The term comes from Amy Edmondson’s research on hospital teams, where she found that the better teams reported more errors, not fewer, because they were willing to. A working agreement is one of the few levers a student team has on that variable, because it decides in advance what happens when someone says they are stuck.

A working agreement addresses this by making implicit expectations explicit. When a team member says “I thought we agreed to review PRs within a day,” the agreement is where that expectation is either confirmed or revealed as an assumption that was never actually shared.

This is especially important in Capstone, where teams form quickly, members may not know each other well, and there is no manager to set norms. The team has to define its own operating model, or one will emerge by default (and it usually will not be one anyone chose).

What Effective Agreements Cover

Section titled “What Effective Agreements Cover”

There is no single template that works for every team, but effective agreements tend to address a few recurring areas. Think of these less as required sections and more as conversations your team should have early.

Roles and Ownership

Section titled “Roles and Ownership”

Teams work better when everyone knows who to go to for what. This does not mean rigid hierarchy; it means clarity, and 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. Name them 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 do not cover, such as documentation currency and facilitating stand-ups and retrospectives, is exactly what those additional areas are for, and assigning it explicitly is what stops it falling on whoever notices first.

Decision-Making

Section titled “Decision-Making”

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

  • Individual decisions: implementation details within your own work.
  • Team decisions: anything that affects others’ work, the architecture, or project direction. These should be discussed (in a stand-up, async channel, or dedicated meeting) before acting.
  • Escalated decisions: blockers, pivots, or changes that affect the project partner. These should involve the partner and/or instructor.

A default async policy helps keep decisions moving: “if no one objects within 24 hours, the proposal is accepted” works well for low-stakes choices.

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.
  • Response time. “Acknowledge messages within 24 hours on weekdays” is a norm. “Respond promptly” is not.
  • Meeting cadence. When do stand-ups, sprint reviews, and retrospectives happen?
  • Escalation. How does someone flag something urgent?

The tool matters less than the shared commitment to use it consistently. A team that checks Discord daily will outperform a team with five communication channels and no habits.

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, where the Scrum Guide makes it a formal commitment attached to the increment rather than a team preference, and the reason it is a commitment is that without one an increment cannot be inspected.

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 is deployed, reviewed, and documented. This mismatch creates friction at integration time and during sprint reviews.

A DoD does not need to be elaborate, but it does need to be written down and agreed upon. It typically evolves as the project matures: early sprints might only require a reviewed PR and passing tests, while later sprints might add deployment and documentation requirements.

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 experiences disagreement. The working agreement should define how to address it before tensions arise, not in the middle of a dispute.

A simple escalation path:

  1. Direct conversation between the people involved.
  2. Team discussion in a retrospective or dedicated meeting.
  3. Escalation to a Teaching Assistant (TA) or instructor.

The agreement should make clear that escalation is a tool, not a failure. Teams that escalate early recover faster than those that let issues fester. The conflict guide owns the performance conversation and the escalation path in detail; what the agreement contributes is the part decided in advance, when nobody is angry yet.

Inclusion

Section titled “Inclusion”

Agree explicitly on how the team ensures every member’s voice is heard, especially during design discussions, code reviews, and retrospectives. Practical approaches include:

  • Rotating who facilitates meetings.
  • Using async proposals to give everyone time to think before a decision is made.
  • Explicitly inviting quieter members to share their perspective before closing a discussion.

These norms are easy to write and hard to maintain, and they are the concrete form of the psychological safety finding above: a rotating facilitator and an explicit invitation to speak are mechanisms, where “we value everyone’s input” is a sentiment. Atlassian’s working agreements play is a usable one-hour format for producing them as a team rather than having one person draft them. The retrospective is where the team checks whether they are actually being followed.

AI Tool Usage

Section titled “AI Tool Usage”

Most teams will use AI coding assistants during the project. Without a shared understanding of how these tools fit into the workflow, teams run into problems: inconsistent code patterns, duplicated or conflicting abstractions, and code that no one on the team fully understands.

A few questions worth settling early:

  • Which tools and configurations does the team share? If the team uses a tool that supports project-level instructions (such as CLAUDE.md, agent skills, or a shared system prompt), agree on a single configuration checked into the repository. This ensures every team member’s AI assistant gets the same architectural context.
  • What is the review expectation for AI-generated code? A reasonable default: AI-generated code goes through the same review process as human-written code. The author is responsible for understanding and defending what they commit, regardless of who (or what) wrote the first draft.
  • How does the team handle AI-suggested architectural changes? An AI tool might propose restructuring a module or introducing a new pattern. The team should treat these the same way it treats any design change: discuss it, check it against the design document, and write an ADR if the team decides to adopt it. No one should merge a structural change just because an AI suggested it.

One important distinction: these norms apply differently depending on the phase of work. During early exploration, prototyping, and spikes, the team should feel free to experiment loosely with AI tools. The point of a prototype is to learn fast and throw the result away. Requiring full design compliance and rigorous review for throwaway code slows down the exact kind of experimentation that helps the team make better design decisions. The norms above matter most when the code is intended to last: anything that will be merged into the main branch, deployed, or built upon by others.

These norms belong in the working agreement because they are about how the team coordinates, not about the tools themselves. The technical details (what architectural constraints to encode, how to keep AI output consistent with the design) are covered in the technical design guide.

Technical Design in the Age of AIHow design documents help coordinate teams where everyone uses AI coding tools.
Generative AIIndividual guidelines for using AI tools effectively and responsibly.

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 audiences.

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 team members, future contributors, and reviewers. It covers branching strategy, PR requirements, code style, testing expectations, and the Definition of Done.

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

Writing Your Agreement

Section titled “Writing Your Agreement”

The most important thing about writing a working agreement is that you do it together. A document drafted by one person and signed off by the rest is not an agreement; it is a policy.

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. Look for consensus and surface tensions early.
  3. Draft the document collaboratively during the session.
  4. Review the communication cadence and Definition of Done with your project partner.

Name the stage your team is in first: Team Formation Strategies Assessment walks Tuckman’s forming-to-performing ladder, the 1965 model that named the storming phase teams are usually surprised by. A forming team needs explicit roles and response times more than a performing one does, and the agreement should say more where the team knows each other less.

The conversations that happen during this process are often more valuable than the document itself. Tensions about work style, availability, and expectations surface here rather than three weeks into the project when they are harder to address.

The agreement lives in the repository as docs/charter.md. Kept to the conversations above, it fits on a page:

# Team Charter


## Roles (rotate at the start of each term)
| Role | Fall | Owns |
|---|---|---|
| Project Manager | Sam | board, sprint planning, partner liaison |
| AI Coordinator | Priya | AGENTS.md, skills, the confidentiality one-pager |
| Quality Owner | Jordan | CI, test suite, the Definition of Done |


## Decisions
- Individual: anything inside your own task.
- Team: architecture, dependencies, scope, anything on another
  person's plate. Proposed in the channel; silence for 24 h is a yes.
- Escalated: partner-facing changes and blockers over one sprint.


## Communication
- Discord #shift-board. Acknowledge within 24 h on weekdays.
- Stand-up Tue and Thu 17:00, 15 min. Sprint review and retro every
  other Friday after class.
- Availability: 9 h/week each; interview weeks announced a sprint ahead.


## Definition of Done
See CONTRIBUTING.md. Short form: reviewed PR, CI green, deployed to
preview, docs touched if behavior changed.


## When it is not working
1. Direct conversation within a week of noticing.
2. Raise it at the next retrospective.
3. Escalate to our TA. Nobody carries a teammate's work silently.


## AI and confidentiality
Shared config in AGENTS.md. Generated code is reviewed like any other.
Any tool: our code, our docs, synthetic data. Partner-approved tools
only: the partner's API docs. Never: production data, volunteer names
and emails, credentials. Unsure? Ask the AI Coordinator first.

That is what the file looks like when a real team answers the questions rather than filling in a template. The length is the point: an agreement nobody can read in five minutes is one nobody will consult.

Keeping It Alive

Section titled “Keeping It Alive”

A working agreement written in week 2 and never revisited is a wasted artifact. The team that wrote it in fall is not the same team in winter; the project has changed, the dynamics have shifted, and some norms have proven unrealistic.

Revisit it at the natural moments:

  • Start of each term: does it still reflect how the team actually works?
  • After a significant conflict: what process gap allowed this to happen?
  • When the project scope changes: do roles and the DoD still apply?

Version your working agreement in your repository. Being able to see how it evolved over the year is useful context, both for the team and for anyone evaluating how the team operated.

Companies that work this way at scale publish their versions, which is the fastest way to see what a mature one looks like. GitLab’s all-remote handbook and Basecamp’s How We Communicate are both public, both opinionated, and both far longer than yours needs to be. Read them for the kind of decision they bother to write down: not values, but defaults. Which channel is for what, how long a reply is allowed to take, what is a meeting and what is a document.

When Things Go Wrong

Section titled “When Things Go Wrong”

A working agreement is only useful if the team is willing to enforce it, and the common failure is not a blowup but slow erosion: a teammate who misses deadlines, posts vague updates, and leaves tasks in progress for a sprint with nothing to show. The agreement’s contribution is to make that conversation concrete. When it states availability in hours, says that a blocker is raised at the next stand-up rather than sat on for a week, and names 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 in the Conflict guide. The short version: privately, early, with the situation and the behavior rather than a motive, and to someone outside the team if a few sprints pass with no change. Escalating early turns a problem into a correction; escalating late turns it into a post-mortem.

When a Role Goes Unfilled

Section titled “When a Role Goes Unfilled”

Assigning someone the role of documentation owner or process facilitator does not guarantee they will actually 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 an honest conversation about why.
  2. Redistribute the work so the role is shared rather than owned by one person.

What does not work: quietly picking up someone else’s responsibilities without addressing the gap. This breeds resentment and teaches the team that accountability is optional.

Validation

Section titled “Validation”

The agreement is validated by use, not by signatures:

  • Every teammate can say, without looking, where decisions get made and how fast a message gets answered. If the answers differ, the agreement has not been agreed.
  • Your project partner has seen the communication cadence and the Definition of Done and did not object.
  • The first retrospective checked it against what actually happened and changed at least one line. An agreement that survives its first retrospective untouched was written to be filed, not followed.

Measuring Success

Section titled “Measuring Success”

The agreement is working when it changes behavior, which is harder to see than whether it exists. The signals below are the observable proxies: each one is something you could check without anyone’s opinion about how the team feels.

  • Time to raise: how long between a norm being broken and someone saying so. One sprint is good; a term is the failure mode.
  • Decisions made where the agreement says: a design change that surfaced in a pull request rather than the channel is a sign the decision levels are not real.
  • Roles that rotated on schedule, with a written record showing who chaired what.
  • Peer evaluation spread: teammates who rate each other very differently usually had a conversation the agreement was supposed to force and did not.

Best Practices

Section titled “Best Practices”
  • Keep it short enough to re-read. A two-page agreement that people actually reference is better than a ten-page one nobody opens.
  • Be specific. “Respond to messages promptly” is not a norm. “Acknowledge within 24 hours on weekdays” is.
  • Distinguish between team norms and project standards. Conflict resolution belongs in the working agreement. Branching strategy belongs in CONTRIBUTING.md.
  • Include a process for updating it. “Any team member can propose a change; the team discusses it at the next retrospective” is a reasonable default.
  • Write it synchronously. Async collaboration does not surface tensions the same way face-to-face conversation does.

Some Truths About Working Agreements

Section titled “Some Truths About Working Agreements”

The honest starting point is that most working agreements are written once, in week two, to satisfy an assignment, and are never opened again. Everyone involved can tell this is happening and nobody says so, because the document looks complete and the deadline has passed. If yours is going to be one of these, the least wasteful version is short: three decisions you will actually reference beats twelve you will not.

A working agreement cannot fix a team that has a real problem, and it is 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 specifically to avoid the five-minute conversation it actually needs. The test is whether any clause in your agreement would change what a specific person does next week. If none would, the document is displacement activity.

The clauses that survive are the ones with an observable trigger. “Be responsive” cannot be violated, because nobody can say when it was. “A pull request gets a review within one working day, and after that the author may merge with a second approval from anyone” can be, which means it can also be enforced without anyone having to characterize a teammate’s attitude. Prefer clauses that describe what happens, not how people should be.

Expect the agreement to be wrong by winter. The team that wrote it did not know how much time the project would take, which tools would stick, or who would turn out to be reliable at what. Frequent violation of a clause is information: it usually means the clause was unrealistic rather than that the team is failing, and the retrospective is where you find out which. A document nobody has amended all year is not stable, it is unread.

Working Agreements in Industry and Academia

Section titled “Working Agreements in Industry and Academia”

In industry, team charters and working agreements are common in Agile teams. They go by many names: team manifesto, team norms, social contract. Large engineering organizations maintain documented engineering norms (coding standards, on-call expectations, incident response protocols) that function as the operational equivalent of a working agreement.

New hires at well-run companies are onboarded to these norms explicitly, not expected to infer them. Your CONTRIBUTING.md serves this same function for anyone who joins your project or reviews your work.

In academia, working agreements give instructors visibility into how the team intended to operate, which is essential context when evaluating teamwork at the end of a term. They also give the team itself a tool for self-correction: when something is not working, the agreement is the starting point for figuring out why.

Additional Readings

Section titled “Additional Readings”

The research on what makes teams work is better than most engineers expect, and it points somewhere slightly unintuitive: the composition of the team matters less than the norms it operates under. The first three entries are that research. The handbooks that follow are what those norms look like when an organization writes them down in public and has to live with them.

Sources and further reading

Activities that exercise this