Describe the complete behavior before generating code
The specification is the public source of truth for both tests and implementations. A reader—or an agent—should be able to build the software from this document without copying behavioral decisions from existing code.
Cover the whole design
Describe the application’s purpose, outside standards it follows, and every public function that makes up the design. For each function, state its purpose, exact interface, accepted inputs, returned values, allowed errors, security rules, edge cases, and concrete examples. Private helper functions do not belong in the design yet; agents may create those later while implementing it.
A complete function example
schema_version = 1
application = "zip-safe"
release = "0.1.0"
purpose = "List and safely extract supported ZIP archives."
external_references = ["PKWARE APPNOTE 6.3.10, section 4.4.4"]
[[function]]
name = "decode_filename"
purpose = "Decode a ZIP filename without changing its path."
signature = "fn(&[u8], u16) -> Result<String, ZipError>"
inputs = [
"raw filename bytes exactly as stored in the archive",
"the 16-bit ZIP general-purpose flag field"
]
outputs = ["one Unicode string containing the same filename characters"]
errors = ["InvalidEncoding"]
requirements = [
"If flag bit 11 is set, decode with strict UTF-8 and reject every invalid byte sequence.",
"If flag bit 11 is clear, map every byte with IBM Code Page 437.",
"Preserve slash, backslash, dot, and NUL characters; path safety is handled by another function.",
"Do not replace, skip, or guess invalid UTF-8 bytes."
]
[[function.examples]]
name = "declared UTF-8"
given = "bytes 63 61 66 c3 a9 2e 74 78 74 and flags 0x0800"
expect = "Ok(\"café.txt\")"
[[function.examples]]
name = "invalid declared UTF-8"
given = "bytes ff 2e 74 78 74 and flags 0x0800"
expect = "Err(InvalidEncoding)"
What becomes an executable test?
The requirements and function.examples entries are part of the specification. They describe behavior; they are not names of test functions. When you run polyform generate, a test-author agent turns them into one shared conformance suite in your repository’s normal test directory. Every generated implementation must pass that same suite.
purpose
Why the application or function exists and what responsibility it owns.
signature
The exact interface every implementation must provide.
requirements
Precise rules, including edge cases and security behavior. Avoid unexplained words such as “safe” or “correct.”
function.examples
Concrete inputs and expected results that remove ambiguity and become shared test cases.
Check completeness before spending agent time
polyform generate refuses a specification that is missing a purpose, interface, requirements, or behavioral examples. Review the complete document first; generation is the next phase.