Surfaces

One internal API, multiple thin ways to invoke it.

A surface translates input, invokes the API, and renders output. It must not invent orchestration policy or duplicate the business operation. racecar itself offers CLI and agent-skill transports, and generates REST and MCP surfaces for adopting repositories rather than hosting those interfaces itself. Surface declarations and implementation are checked for drift.

CLI

The command line is a surface, not the owner of the underlying work. Its verbs are declared and checked against implementation. The CLI contract distinguishes success or nothing to do (exit 0), findings (exit 1), and inability to run (exit 2). Missing required arguments show the relevant verb's help, unknown arguments are named at that verb, and mistyped verbs receive a suggestion.

Agent Skills

Agent skills are an LLM-facing transport over the same internal API as the CLI. They load when invoked and describe how to perform bounded work. A skill should not shell out to the CLI as its own implementation strategy, because that creates unnecessary coupling and risks divergence. Its instructions are useful precisely because the checks and underlying operations have independent authority.

Generated REST & MCP

racecar can generate REST and MCP surfaces for software built with it. It does not itself expose REST or MCP services. Each generated adapter should translate a transport request into a declared API operation and render the result, without adding orchestration policy. Surface conformance checks compare the authored operation and its transport binding so a new entry point does not silently become a new behavior.