pluviobyte/contractspec

ContractSpec is a workflow add-on for teams building software with AI coding assistants. It addresses a specific problem: when you let an AI write code for a full-stack application (one that has both a frontend and a backend), the AI tends to invent details that were never agreed on. The frontend might ask for fields the backend never sends. Error messages might be formatted differently on each layer. Tests might get written after the implementation and simply confirm what the code already does rather than checking what the product actually requires. ContractSpec is designed to prevent that drift by requiring all layers to be defined in shared contract documents before any code is written. The tool builds on top of OpenSpec, an existing AI coding workflow system. ContractSpec adds a schema bundle and a validator on top of OpenSpec's lifecycle. Before implementation starts, you define a set of contracts covering the product intent, the data model, the API endpoints, the error formats, the UI states, and the tests. A "bindings" file then maps each contract to the actual code artifacts it governs: which TypeScript types, which API routes, which test files, which generated clients. The validator can check that all these pieces exist and align with each other. The workflow enforces a specific order: write contracts first, then write failing tests from those contracts, then implement the feature, then verify against the evidence. AI agents working in this workflow are given explicit rules: do not invent API fields, do not invent UI states, do not change error formats silently, and do not write tests that simply mirror the implementation you just wrote. If the implementation reveals that a contract was incomplete, the agent is expected to update the contracts first before continuing. A command-line validator checks that all required contract files exist, that each section covers the expected concepts (loading states, error codes, auth requirements, and so on), and that tasks are written as vertical slices with checkbox tracking. Running the validator gives developers a structured audit of whether the change folder is complete before code is applied. The project is in alpha and MIT-licensed. The README recommends pairing it with executable schemas, shared types, and CI checks before using it in production.