When AI writes your system, who defines what done means?

Hand an AI a requirement — a booking system where users pick a time slot, submit a reservation, and staff can cancel — and the output arrives fast. Pages, endpoints, database tables. Each piece looks competent on its own.

Then you run the pieces together. The frontend treats times as local while the backend stores UTC. The cancel endpoint returns success, but the reservation list still shows the slot as booked. The same slot can be submitted twice, and both requests are accepted.

An AI can generate a lot of code in an afternoon. When "correct" exists only as the vibe of a chat transcript, every module is free to develop its own understanding of the rules.

AI coding needs a shared reference that can be queried, changed, and verified — by both people and tools.

Turn the requirement into a contract both sides can inspect

The OpenAPI Specification describes operations, parameters, responses, and auth in a structure people can read and tools can consume. In Powerduck the design starts from a business requirement and turns into proposed changes against the current document:

Design reservation create and cancel endpoints. Be explicit about the time zone format, the reservation statuses, and the error response when a slot is already taken. List anything the requirement does not determine instead of assuming it.

The thing worth reading is not how many paragraphs the model produced. It is the shape of the change: are field meanings explicit, are statuses consistent, do the failure cases give the frontend enough to react? You review the patch card, apply it, and save the file. A discussion that would have evaporated with the chat window is now an artifact the project keeps using.

One file, the whole workflow

The specification does not stop being useful once the design conversation ends. The same file keeps doing work at every stage:

The shift is where the context lives. It no longer depends on a person pasting the right snippet into the right window, and documentation is no longer a chore deferred until the code is finished. The contract enters the process at the start and feeds every tool downstream.

"AI-native" has to show up in the feedback loop

After the booking endpoints are written, the agent can query the contract through the dev MCP server and run requests against a test service. A parameter mismatch, a missing response field, or a scenario that breaks at step three becomes concrete evidence for the next fix cycle. Compare that with "the code is complete," which is not evidence of anything.

Ask the questions that keep the loop honest: which step passed, which assertion failed, what rule is still missing? That is also how scenario testing replaces the single 200 as a definition of done.

Know what the contract cannot do

An OpenAPI document will not, on its own, express slot reservation races, cross-service transactions, or every business constraint. Those need scenarios, assertions, and tests at the implementation layer. What the spec does is pull every rule that can be structured into an executable feedback process, so gaps surface while they are still cheap.

Because the file is local, it travels with the code: reviewed, versioned, and rolled back like anything else in the repository. Switch AI clients next quarter and the project keeps its reference instead of replaying an old conversation. (Using a hosted model still means the relevant context is transmitted to that model — local-first describes ownership of the file and the workflow, not air-gapped networking.)

The working pattern behind Powerduck is increasingly common: people set goals and boundaries, AI participates in design and implementation, and the tooling supplies the evidence. Before any of that works, "what we are building" and "how we know it is right" need a place to land together.