One core, two hosts

OpenSpec Workbench comes in two versions: a Visual Studio Code extension and a standalone web app. Both display the same OpenSpec and Git data and execute the same workflows. To prevent the two versions from becoming separate products, developers chose to write the behavior once and provide a thin adapter for each host. This design allows the shared core to handle execution, OpenSpec and Git integration, security, persistence, and derived state changes.

The web UI and server are separate components, each communicating with the core through a protocol consisting of commands and events. Security is integrated from the start, with all runs restricted to the workspace and command arguments being allowlisted. The core also handles auditing and treats repository contents as data rather than instructions.

Alternative designs were considered but ultimately rejected, including running the server inside the extension, implementing execution separately in each host, and storing change state in a separate .openspec.yaml file. The chosen design offers several benefits, such as a single source of truth for defects, consistent status records across runs, and the ability to add new agents as adapters in the core's registry.

However, the thin adapters still require routing each command, and a command forgotten by one host may be invisible until used. To address this, the core was updated to handle permission requests during chains, and contract tests between the shared UI and server are required before changes are archived. The source code is available on GitHub, and a short tour of the system can be found in the "Supervise agents on OpenSpec changes" document.