When AI Starts Writing Your System, Who Tells It What 'Done' Means?

You hand AI a task: build a booking system. Users pick a time slot, submit a reservation, and an admin can cancel it.

Fast enough. The page exists. The endpoint exists. The database table exists. Each piece looks right in isolation.

Then you connect them. The frontend treats the timestamp as local time. The backend stores UTC. The cancel endpoint returns 200, but the booking list still shows "reserved." The same slot gets booked twice.

AI generates a lot of code quickly. But if the definition of correct only exists across a few chat turns, every module develops its own interpretation of it.

AI coding needs a shared reference both sides can check

An OpenAPI Specification (OAS) describes endpoints, parameters, responses, and auth in a structured format. People can read it. Tools can read it.

In Powerduck, you start from a business request and ask the AI to propose a design against the existing spec. Something like:

Design the booking create and cancel endpoints. Pin down the timezone format, the booking status lifecycle, and the error response when a slot is already taken. List the rules the requirement does not make obvious.

What matters next is not how much the AI wrote. It is what it proposes to change in the API: are the field meanings unambiguous? Is the status model consistent? Do the failure cases cover what the frontend actually needs to render?

You review the diff, apply it, and save it to the local OAS file. The discussion that would otherwise vanish into chat history becomes a durable artifact the project can keep using.

One file, through the whole AI workflow

The OAS does not have to stop at "design output." In a Powerduck workflow, it continues to feed the later stages:

• Design: the AI proposes endpoint and schema changes against existing definitions.
• Implementation: a local MCP server gives the coding assistant the concrete contract, not a pasted PDF.
• Waiting on dependencies: a mock answers from the spec's examples and schemas, so the frontend can proceed.
• Verification: the agent sends real requests, runs contract checks, and walks scenario tests.
• Delivery: docs render from the same file, and an MCP endpoint can be published on demand.

The shift: the AI's context no longer depends on someone copy-pasting it in every turn. The spec enters the flow at design time and stays the source of truth for every tool downstream.

"AI-native" has to mean feedback loops

After the booking endpoint exists, you can have the AI query the contract over MCP and send a request to the test service. A mismatch in parameters, a missing response field, or a scenario that breaks halfway becomes the concrete signal for the next iteration.

Compared to a "done" from the model, real responses and assertion results are worth interrogating: which step passed? Which field did not match the contract? What rule is still missing?

An OAS has limits. It will not, by itself, express race conditions on slot booking, cross-service transactions, or every business invariant. Those need scenarios, assertions, and implementation-level tests. The point of a tool like Powerduck is to put the structured parts of the contract into a feedback loop that catches the gaps early.

Local first means the consensus belongs to the project

The spec lives as a local file. It goes into version control, code review, and rollback alongside the code. When the team switches from one AI client to another, the contract survives the switch — no need to reconstruct the requirements from an old chat thread.

Local-first does not mean offline-only. When you use a cloud model, the context you hand it still gets transmitted. What it means is that the file and the daily workflow are yours, not locked inside a vendor's chat window.

Powerduck is built around a development pattern that is becoming normal: the human sets the goal and the boundaries, the AI participates in design and implementation, and the tools provide verification evidence. In that loop, a local OAS can be the thing that connects all three.

Before the AI starts writing, make sure "what we are building" and "how we know it is right" have one shared place to land.