CLI for validating, querying, and updating Markdown specs

What this project is

This is a Go utility for working structurally with a complex directory of markdown files (a specification), which is described at https://spec-schema.org. The utility has two main tasks:

- validation of a set of markdown files;

- interaction with markdown files (query, add, update, delete).

Validation can be performed both by developers (including in CI) and by agents. At the same time, the commands for querying and modifying markdown files (query, add, update, delete) are intended primarily for the agent (because for a developer it is easier to do this through a code editor).

What problems this solves

Three main problems:

- anxiety that the agent will break the structural integrity of the specification;

- the ability to maintain structurally complex specifications made up of markdown files;

- the fact that the agent has to load too much data into the context window (read the entire specification).

How it works

An approximate usage scenario for the utility:

- you initialize the specification schema with a yaml file according to https://spec-schema.org/ This schema describes the structure of the directory with markdown files and the structure of the markdown files themselves. This stage, of course, can be done with an agent;

- in a new session with the agent, you simply tell it to run `spec-cli help`: with this command it gets an agent-friendly projection of the specification schema, which it then works with;

- now the agent can use spec-cli to validate, update, and query the specification;

- the specification remains convenient for the developer to read, because it is located next to the project and has the structure defined by the developer.

What this project is not

This is not a Spec Driven Development framework like spec-kit/openspec/spec-kitty/etc. It is simply a utility for structurally working with a complex directory of markdown files.

Future plans

Right now I am testing the utility on a real project. In particular, the utility needs to support concurrent work (for example, to avoid errors where markdown files added simultaneously get the same id) and batch operations.

Thank you for reading!