1) What this project is

This is a Go utility (spec-cli) 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).

2) What problems this solves

- 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).

3) How it works (approximate usage scenario):

- 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, and commands (query/add/update/) description;

- now the agent can use cli utility 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.

4) 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!

Show HN: CLI for validating, querying, and updating Markdown specs