`api` specifications

The specifications of api describe what api/ does:

Each specification is in its own directory NNN-<feature>/. The principles in constitution.md apply to all changes in api/. A change in behavior updates the matching specification in the same pull request. api/specification.md gives the design of the wire surface, with the reasons and the alternatives, and the specifications refer to it. The OpenAPI and AsyncAPI documents that api serves give the fields of each call.

A specification describes concepts and behavior: what a part does, for whom, why, which guarantees it gives and how it fails. It does not repeat option names, file paths, environment variables, default values or the names of tests. These are in the code, in the descriptions of the options and in the generated documentation. Thus a change of a name or of a default does not change a specification, but a change of a behavior does.

The specifications are plain Markdown. You can read and change them without other tools.

If you want to use an agent to write them, the development shell of api/ contains Spec Kit. To add the agent commands (for example /speckit-specify) for your agent, run these commands in api/:

specify init --here --integration <agent> --script sh --force
ln -sf ../../specs/constitution.md .specify/memory/constitution.md

The first command writes templates and scripts to api/.specify/, and the agent commands to the directory of your agent (for example api/.claude/). The second command replaces the template constitution with a link to the constitution of api/, so that the agent commands read and change it. Git ignores api/.specify/. Do not commit the agent commands.