Software specifications should be portable. A change description should be able to enter through one agent workflow, become structured work, code, tests, and runtime evidence, then leave in a form another person or tool can understand.
That sounds obvious. It is not how most AI-assisted development works.
Today, the important parts of a change are usually split across a chat transcript, a Markdown folder, a task tracker, a pull request, and a developer’s memory. Change the agent, switch editors, or return three weeks later and the intent has already started to decay. The code may still be there. The reason it exists, the behavior it promised, and the proof that it worked are much easier to lose.
This is not an argument against specifications. It is an argument against treating them as files that belong to a particular tool.
A specification is a contract, not a destination
A useful software specification says what must change, what must not change, and how to recognize a correct result. It is the contract between product intent and implementation.
That contract should not be trapped in the tool that first wrote it.
It should be possible to import a proposal, requirements, design decisions, and implementation tasks from an agent-oriented workflow. It should be possible to connect those materials to a product model, a repository, the work that follows, and the evidence that comes back. And it should be possible to export the change again without forcing the next tool to reconstruct its meaning from a pile of prose.
The important distinction is this:
A portable specification preserves intent. A verified specification proves behavior.
You need both. Portability keeps the contract alive across tools. Verification decides whether the contract was actually met. As spec-driven development makes clear, a green build is not enough: acceptance criteria need to be executed against the real result.
The failure mode: context locked inside a workflow
AI coding tools are excellent at creating a local loop:
- Describe a change.
- Let an agent make a plan.
- Apply the plan.
- Keep moving.
The loop breaks when the context has to leave its original home. A new agent cannot see the decisions behind the plan. A teammate sees completed tasks but not the acceptance contract. A future maintainer sees a diff but not why one alternative was rejected. The repository becomes technically correct in pieces while the product becomes harder to reason about as a whole.
That is the same problem behind locally correct, globally incoherent software: each isolated change can make sense while the system loses its shared direction.
Markdown is not the problem. Markdown is a good exchange format. The problem starts when a folder of Markdown is the only representation of the change.
Make the change move without flattening it
PAELLADOC now treats an external specification workflow as an interoperable envelope rather than as a competing destination.
OpenSpec is one practical format that can now enter and leave PAELLADOC. Its familiar proposal, specs, design, and tasks files are useful because they make a change legible outside a single chat. The point is not to replace that format with another silo. The point is to carry it through implementation and return it with the context it gained.
You can bring in a change package: its proposal, requirements, design, and tasks. PAELLADOC turns that material into a living local model of the work: product artifacts, relationships, execution context, and validation expectations. The change can then be taken through the factory, from discovery and planning to agents, code, review, and evidence.
When it is ready to leave, the same change can be exported again. The next agent or tool receives a legible contract, not only a final diff.
This is deliberately not a one-way import. One-way import turns other tools into a migration path. A two-way format turns them into participants in a wider workflow.
What must survive the trip
A portable spec is more than a title and a checklist. At minimum, it needs to carry five things.
1. Intent
What user or business behavior is supposed to change? Without that, a task list can be executed perfectly and still create a feature factory: a record of output with no account of the behavior it was meant to install. Making product is installing a behavior, not accumulating surface.
2. Boundaries
What is explicitly out of scope? What must stay true after the change? The constraints are often more valuable than the happy path, especially when an agent can generate a great deal of plausible code very quickly.
3. Decisions
Why this design instead of another one? Architecture decisions, trade-offs, and known risks should remain attached to the change. They are not ceremony; they are the shortest route to understanding a future diff.
4. Work and provenance
Which tasks, files, components, services, and tests belong to the contract? A portable specification should be able to acquire references to the code that implements it, not merely point at a vague repository.
5. Evidence
What was run? What passed? Against which version of the contract? A completed checkbox is useful status. It is not evidence. The difference matters most when an AI agent produced the implementation and nobody watched every line.
This is why a product knowledge graph matters: it gives the specification a place to attach intent, code, decisions, and proof without reducing all of them to an undifferentiated document.
Interoperability is not vendor lock-in with a nicer import button
There is a common trap in developer tools: call something interoperable because it accepts an import, then make every valuable action depend on a proprietary internal representation.
The test is simpler. Can the work leave with its meaning intact?
If you change agents tomorrow, can the next one understand the proposal, the constraints, the decisions, the tasks, and the result? If a team decides to work in a different editor, can it keep its accepted contracts? If the product changes, can you find the evidence that is now stale rather than trusting an old green status?
Portable specifications are an answer to that test. They let the workflow change without forcing the product’s memory to reset.
Why this matters more with AI agents
The faster an agent writes code, the more expensive it becomes to lose the decision trail around that code.
AI has made producing a diff cheap. It has not made deciding what to build, protecting constraints, or proving behavior cheap. In fact, it raises the bar: when implementation is abundant, durable intent and verification become the scarce parts.
That is why the useful unit is not the prompt, the chat, or even the task. It is the portable contract that can outlive all three.
The local software factory view
PAELLADOC is not trying to own the place where every specification is written. It is building the local factory where a specification can become a maintained piece of software.
Bring the contract in. Connect it to the product and the code. Run the work. Capture the evidence. Send it back out.
The agents will change. Editors will change. Frameworks will change.
The intent, the decisions, and the proof should survive them.
FAQ
Are portable software specifications the same as spec-driven development? Not exactly. Spec-driven development is the practice of defining the acceptance contract before implementation. Portability makes that contract able to move between tools and retain its connection to the code and verification that followed.
Does a portable spec guarantee that the implementation is correct? No. It preserves the contract; runtime validation and acceptance evidence are still what establish correctness.
Why export a spec after implementation? The exported change gives another agent, teammate, or future maintainer the intent, decisions, tasks, and verification context behind the code, instead of forcing them to infer it from a diff.