`core` specifications

The specifications of core describe what core does:

These specifications describe the individual parts that the general specifications above use:

Each specification is in its own directory NNN-<feature>/. A family of parts (for example the resources) has a spec.md for the rules that all parts of the family share, and one file for each part. The principles in constitution.md apply to all changes in core/. A change in behavior updates the matching specification in the same pull request.

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 core contains Spec Kit. To add the agent commands (for example /speckit-specify) for your agent, run these commands in core/:

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 core/.specify/, and the agent commands to the directory of your agent (for example core/.claude/). The second command replaces the template constitution with a link to the constitution of core, so that the agent commands read and change it. Git ignores core/.specify/. Do not commit the agent commands.