BDD Treaties

John Ferguson Smart | Mentor | Author | Speaker - Author of 'BDD in Action'.
Helping teams deliver more valuable software sooner16th April 2018

bdd | cucumber | Xscale |

Better cross-team coordination with collaborative governance and executable specifications

Getting multiple teams to work together effectively on large projects can be tricky. We expect teams to be autonomous and independent. But at the same time we expect them to coordinate with other equally autonomous and independent teams, so that their modules or services mesh seamlessly with the rest of the enterprise architecture.

Do we really have to use big upfront design and cumbersome, command-and-control governance for teams to work together effectively. And can this approach even function at all in today’s fast-paced and changing world?

It turns out, there are better ways.

In this article, we will look at one of these. We will see how combining the governance practices of an ancient people with the executable specifications of the Behaviour Driven Development world gives us a simple but surprisingly effective solution to this problem.

A tale of two teams

Blue Team and Red Team work in a large financial organisation. They are both small, high performing agile teams who are very good at what they do. Blue Team is working on a Data Lake that keeps track of the trades performed by fund managers within the organisation. Their job is to provide enriched trade data to other teams. These other teams then use this data to build analytics, surveillance and reporting applications.

One of these teams is Red Team. Red Team is working on a surveillance application that monitors fund managers. They need to ensure that the trades they perform are in line with the risk profile of the funds they manage. In other words, they need to make sure that Freddy the Fund Manager isn’t investing Grandma’s pension fund in cryptocurrencies.

Tight timelines mean that Red Team cannot wait for Blue Team to finish the Data Lake before they start their work. And Red Team have only a very general idea of the sort of reports they will need to provide. How can Red Team know what services and data Blue Team will be able to provide them. And how can Blue Team incorporate the needs of Red Team (and all the other teams) into their design?

In a more traditional approach, an Enterprise Architect might define a standard data exchange format that Blue Team need to produce and that Red Team can consume. But this approach doesn’t scale well to modern applications with evolving needs and fast turnaround times. It is unrealistic to expect any architect, no matter how experienced, and no matter how much time they have, to come up with a format suitable for all possible current and future usages.

Team Red and Team Blue do not use this top-down, command-and-control strategy. They use a more effective, more human approach.

Conversations, Examples, and Executable Specifications

At the heart of their collaboration strategy is a practice called Behaviour Driven Development, or BDD. BDD helps the teams both to deliver high quality features at a regular, sustainable rate. But, as we will see, it also helps them collaborate with other teams in a flexible and reliable way.

In Behaviour Driven Development, teams have regular structured conversations with product owners and business folk. They explore concrete examples of how users expect to benefit from the application. These conversations help the teams form a deeper understanding about what features they should build, and about the business rules and constraints they need to implement. They are also a great way to uncover uncertainty or incorrect assumptions which would slow down the team later on.

Using BDD, we can formalise these examples into precise, unambiguous acceptance criteria. When we automated these acceptance criteria, they become Executable Specifications which not only test the application, but also document what it should to do.

The Five Steps of BDD

A BDD process has five main steps:

  • Illustrate: In the week preceding a sprint, team members from each team learn about the features slated for this sprint in detail, working through concrete examples with the product owner. They use light-weight requirements discovery practices such as Feature Mapping and Example Mapping to cover a large number of business rules and examples very quickly. The team comes out of these discovery workshops with a clearer understanding of what they need to build, as well as key business rules and concrete examples that illustrate these rules.
  • Formulate: Once they have identified business rules and key examples, it is time to turn these examples into executable specifications. Each example is expressed in the structured, Given..When..Then notation used by popular BDD tools such as Cucumber.
  • Automate: Shortly before development work starts on a feature, the teams make sure they have turned these executable specifications into automated acceptance tests, wiring up the Given..When..Then notation to actual test automation code. Most often a developer and a test automation specialist pair to do this.
  • Validate: The team then implements the feature, aiming first and foremost to make the automated acceptance tests pass. The Automate and Validate steps can happen several times during a sprint, once for each acceptance criteria. When these tests are all green, the feature is ready to demo.
  • Demonstrate: With the acceptance tests passing, the team can demonstrate the new feature to the product owner. If the product owner sits with the team, the team can even demo each new passing acceptance criteria as they complete them. Often a key part of this demonstration is walking the product owner through the living documentation that is generated when the automated acceptance tests run.

The overall process looks something like this:

Tactical and Strategic BDD

What we have just seen is the most common use of BDD, and is what we could call tactical BDD. For teams using Scrum, the feedback cycles align with the sprints. For teams using Kanban, a cycle lasts as long as it takes to deliver a single feature.

But it turns out, BDD also works at other levels. At a higher level, teams work with product owners to discuss and prioritise higher level features (“epics”, in Scrum terms) and business goals. They use techniques such as Impact Mapping and high level Feature Mapping to understand and re-evaluate business priorities. Jan Molak coined the term Strategic BDD for this level of activity. Team Red and Team Blue run joint strategic BDD workshops with other teams working on related projects every 6 weeks.

Collaborative governance and coordination

But how does all this help our teams coordinate their work? To understand this, we first need to understand how Team Blue works together with other teams that need to use the data lake for their applications.

The teams use a form of collaborative governance promoted by the principles of XSCALE, and which find their inspiration in the traditional governance practices of the Six Nations of the Iroquois Confederacy, the oldest living participatory democracy in the world.

Let's see how this works in practice.

In addition to Team Red, another team, Team Green, relies on the data lake for their application. Every two weeks, towards the middle of the regular sprint cycle, a two delegates from each team get together for a BDD Council Meeting. A few non-team members, such as business folk and DevOps specialists, also attend this meeting.

BDD Council Meetings aim to coordinate activities between the teams, prioritising features and, most importantly from a BDD perspective, identifying integration points where more detailed coordination is required. Wherever their applications interact or exchange information in some way, the teams need to agree on how this interaction will work.

Like the 3-amigos meetings in tactical BDD, Council Meetings thrive on diversity. While there are always members from each team, the attendee list is based on speciality (business analyst, QA/test automation, development, DevOps, and so forth), so that representatives of each speciality are always present. All the teams use a simple roster system to know who should attend these meetings, and rotate every 6 weeks.

We call this agreement a Treaty. Treaties defines acceptance criteria and executable specifications which guide each team when they build their features. Treaties are similar to Consumer Driven Contracts, but with a stronger emphasis on collaborative definition, living documentation and executable specifications that come from BDD.

These treaties are agreed at a high level during the BDD Council sessions. The council identifies in the least high level acceptance criteria and a few key examples. Decisions are made by consensus, following a Leadership-As-A-Service model, which promotes autonomy and self-organisation.

The detailed acceptance criteria would generally take too long to write during this meeting. Working through the details would also waste time for the council members from other teams not involved in that interaction. For this reason, the details are generally elaborated in a separate BDD Treaty Workshop.

BDD Treaty Workshops

Team Red’s backlog contains the following story:

The first acceptance criteria is a simple UI feature. This can be handled entirely within the Surveillance application, so no treaties are needed.

The second, however, needs data from the data lake, using a service that Team Blue is still working on. At the BDD Council, the Team Red delegates put this story on the table. The council discuss it briefly, Team Red and Team Blue agree organise a BDD Treaty workshop. It is in this workshop that they will work through the details together.

A BDD Treaty workshop is like a conventional 3-amigos workshop, except that it involves members of both teams. Delegates from each team meet to agree on how their respective applications will interact. These delegates are generally the team members who will work on the corresponding feature. As with a normal 3-amigos session, the three key perspectives (business, technical, QA) are represented. There may be other people present, such as someone with a DevOps perspective.

The team members who attend a BDD Treaty workshop will vary from meeting to meetings, but they are generally the people who will be working on the feature.

Executable Specifications as Treaties

The aim of the Treaty Workshop is to agree on executable specifications that define how the two applications will interact. This gives the treaties their power. The executable specifications become automated acceptance tests, and these automated tests actively enforce the treaties.

Both Team Red and Team Blue use Cucumber, so they express their treaties in the Given-When-Then Gherkin notation. For Team Red, they agree on a scenario that describes the overall business requirement:


Scenario: Show trade volumes by risk and by fund for each fund manager

  Given the following funds:
   | Fund                  | Fund Manager | Low Risk | Medium Risk | High Risk |
   | Sunshine Pension Fund | Tim          | 70%      | 20%         | 10%       |
   | Lambo Investment Fund | Joe          | 20%      | 50%         | 30%       |
 When the trade volumes for yesterday were:
   | Fund     | Low Risk Trades | Medium Risk Trades | High Risk Trades |
   | Sunshine | 750000          | 150000             | 100000           |
   | Lambo    | 50000           | 50000              | 900000           |
 Then Sally the supervisor should see the following summary:
   | Manager | Fund     | Total   | Low | Low  Δ | Medium | Medium Δ | High | High Δ |
   | Joe     | Sunshine | 1000000 | 5%  | -15%   | 5%     | -45%     | 90%  | +60%   |
   | Tim     | Lambo    | 1000000 | 75% | 5%     | 15%    | -5%      | 10%  | 0%     |


Working through this scenario gives Team Blue a better idea of what they need, and why. The two teams then work together to describe acceptance criteria for the Data Lake service that will support this functionality:

  Scenario: Provide trade volumes by risk and by fund for each fund manager
    Given the following funds:
      | Fund                  | Fund Manager | Low Risk | Medium Risk | High Risk |
      | Sunshine Pension Fund | Tim          | 70%      | 20%         | 10%       |
      | Lambo Investment Fund | Joe          | 20%      | 50%         | 30%       |
    And the following trade volumes for 15/04/2018:
      | Fund     | Low Risk Trades | Medium Risk Trades | High Risk Trades |
      | Sunshine | 750000          | 150000             | 100000           |
      | Lambo    | 50000           | 50000              | 900000           |
    When Sally gets the trade volume summary from end-point /funds/risk-dist?date=2018-04-15
    Then she should receive the following summary:
      | Fund Manager | Fund     | Total   | Low | Low  Δ | Medium | Medium Δ | High | High Δ |
      | Joe          | Sunshine | 1000000 | 5%  | -15%   | 5%     | -45%     | 90%  | +60%   |
      | Tim          | Lambo    | 1000000 | 75% | 5%     | 15%    | -5%      | 10%  | 0%     |


Team Blue agrees to implement a service that respects the contract described in this scenario. And Team Red can use the scenario as the basis for developing the UI feature.

The teams have already established standard JSON conventions, so there is no need to explicitly describe the exchange format here. Some teams prefer to include JSON in these acceptance criteria for more precision, though large JSON structures can reduce readability.

But it is not enough for the delegates to simply agree on a treaty. Everyone involved needs to be happy with the agreement. Like diplomatic treaties, BDD treaties go through several phases:

  • Codify: During the BDD Treaty Workshop, the treaty is turned into executable specifications, as clear and unambiguous as possible.
  • Ratify: Since the whole team was not involved in the treaty negotiation process, they need to be given the opportunity to provide their feedback. The team delegates present the treaty specifications to their team. The delegates share modifications with the delegates from the other team and agree on a definitive version of the treaty.
  • Enact: Once everyone is happy with the treaty, both teams implement the corresponding executable specifications for their own code. Each team implements these executable specifications in a way that verifies that their part of the system respects the treaty.

The Enact phase is particularly important. Team Blue will write an automated test that shows how data is processed and retrieved from the data lake. And Team Red will write a UI test that demonstrates how the Surveillance application displays this data. Team Red can count on the fact that they will receive data from the data lake in the correct format.


BDD Treaties are a simple but powerful approach. They allow teams to work independently, knowing that their code will integrate seamlessly with the other application. The automated tests reduce the risk of integration errors substantially. In addition, as these treaties become part of each application’s living documentation. This makes them are a great way for other teams to see when a feature is ready to integrate.

Further Reading

You can learn more about Leadership as a Service and other XSCALE patterns in this article. And for a fun way to understand some of the XSCALE collaborative governance practices, take a look at the Game Without Thrones.

© 2019 John Ferguson Smart