Build your first Polyform project: Fizz Buzz

This walkthrough builds a tiny Rust project so you can see the whole idea before applying it to real software. Four small behaviors are specified separately, then coding agents create several interchangeable implementations of each.

1. Start a normal repository

mkdir polyform-fizzbuzz
cd polyform-fizzbuzz
git init
cargo init --bin .
polyform init

polyform init adds polyform.toml and the conventional specification file specs/polyform.toml. For this starter Rust project, the generated configuration already knows to run cargo test; you do not need to configure packaging yet.

2. Describe Fizz Buzz in specs/polyform.toml

Replace the example specification with these four contracts. Divisibility checks, classification, and display are independently swappable, which makes the combinations easy to see.

schema_version = 1
application = "polyform-fizzbuzz"
release = "0.1.0"
purpose = "Print Fizz Buzz for numbers from 1 through 100."
[[function]]
name = "is_divisible_by_three"
purpose = "Decide whether a number is evenly divisible by 3."
signature = "fn(u32) -> bool"
inputs = ["one integer from 1 through 100"]
outputs = ["true exactly when the input is divisible by 3"]
errors = []
requirements = ["Return true if and only if dividing the input by 3 leaves no remainder."]

[[function.examples]]
name = "nine"
given = "the number 9"
expect = "true"

[[function.examples]]
name = "ten"
given = "the number 10"
expect = "false"

[[function]]
name = "is_divisible_by_five"
purpose = "Decide whether a number is evenly divisible by 5."
signature = "fn(u32) -> bool"
inputs = ["one integer from 1 through 100"]
outputs = ["true exactly when the input is divisible by 5"]
errors = []
requirements = ["Return true if and only if dividing the input by 5 leaves no remainder."]

[[function.examples]]
name = "twenty"
given = "the number 20"
expect = "true"

[[function.examples]]
name = "eighteen"
given = "the number 18"
expect = "false"

[[function]]
name = "classify_number"
purpose = "Combine the two divisibility results into a Fizz Buzz classification."
signature = "fn(u32, bool, bool) -> Classification"
inputs = ["the original number, divisible-by-3 result, and divisible-by-5 result"]
outputs = ["FizzBuzz, Fizz, Buzz, or Number"]
errors = []
requirements = [
  "Return FizzBuzz when both supplied results are true.",
  "Return Fizz when only divisible-by-3 is true.",
  "Return Buzz when only divisible-by-5 is true.",
  "Otherwise return Number containing the original number.",
  "Use the supplied results instead of repeating either divisibility test."
]

[[function.examples]]
name = "both"
given = "the number 15 with true and true"
expect = "FizzBuzz"

[[function.examples]]
name = "neither"
given = "the number 7 with false and false"
expect = "Number containing 7"

[[function]]
name = "render_line"
purpose = "Render one classification as user-visible text."
signature = "fn(u32, Classification) -> String"
inputs = ["the original number and its classification"]
outputs = ["one line without a trailing newline"]
errors = []
requirements = [
  "Render FizzBuzz, Fizz, and Buzz exactly with that capitalization.",
  "Render Number as the base-10 input with no padding."
]

[[function.examples]]
name = "buzz"
given = "the number 10 classified as Buzz"
expect = "Buzz"

[[function.examples]]
name = "ordinary number"
given = "the number 7 classified as Number"
expect = "7"

This file describes behavior, not an implementation. Every generated version must satisfy the same requirements and examples.

3. Have coding agents implement it

polyform generate --count 5

Polyform starts Codex as the default coding agent. One agent first turns the specification into shared conformance tests. Implementation agents then request five independently structured candidates for each of the four functions—twenty candidates in all. Each candidate is accepted only after the project checks pass.

4. Check what the agents built

cargo test
polyform check

Read the generated source and tests too. Passing checks mean the implementations agree with this specification; they do not replace human review. The next documentation pages explain the specification format and generation process in more depth.

5. Push the finished source to GitHub

Create an empty public repository on GitHub, then push this project:

git add .
git commit -m "Build Polyform Fizz Buzz"
git branch -M main
git remote add origin https://github.com/YOUR-USERNAME/polyform-fizzbuzz.git
git push -u origin main

The repository is public so users can inspect the specification, tests, and every implementation.

6. Create the project on Polyform

1. Create an account and choose New project.
2. Use your repository URL: https://github.com/YOUR-USERNAME/polyform-fizzbuzz.
3. Keep the specification path as specs/polyform.toml.
4. Create the project. You can edit these details later from its project page.

The specification path is simply the location of the file inside the repository. It is not another URL or a path elsewhere on your computer.

What comes next?

You now have a public project with agent-written implementations that pass one shared contract. Continue to Connect your app to select different combinations at runtime, then check and publish an installable release.