ShallGraph

Track requirements as YAML in git, and trace them to the code.

ShallGraph checks each requirement file against a schema, links it to the implementation and the verification, and writes HTML and Markdown reports from those files.

Sign up Log in

Requirements drift away from the code

A requirement kept in a tracker, a wiki, or a shared document is a second copy of what the code is supposed to do. The branch moves and the tests change, while that copy stays where someone pasted it. A review then has to reconstruct which sentence still applies, and an agent asked to do the work has to recover the intent from chat. ShallGraph keeps the statement in the repository with the files it governs, so the requirement has the same history as the change.

How it works

  1. Each requirement is one file ending in .req.yml or .req.yaml. It has a stable id, a short title, and a single Shall, Should, or May statement. From the project root, shallgraph bootstrap adds shallgraph.yaml and a requirements/ directory. Optional fields record rationale, parameters, and links to other requirements.

  2. The file names the evidence. satisfied_by and verified_by list the paths or URLs that implement or check the requirement. In Rust, #[shallgraph::implements] and #[shallgraph::verifies] mark functions and tests in source, and those items are collected beside the YAML entries. shallgraph validate checks the files against the schema, and shallgraph format rewrites them into a canonical layout so a diff shows the edit.

  3. You read the same files. shallgraph html and shallgraph markdown write a static report, and a GitHub origin turns paths into links at HEAD. After you sign in, the hosted app opens a repository you can access. The editor preview shows one requirement in that report's shape. The YAML file remains the source.

Features

  • Git compatible

    Requirements are files in the project. They branch, review, and merge with the code around them. When the origin is GitHub, a report links each path to the blob at the commit you generated it from.

  • LLM agent friendly

    The schema is small and the ids are stable, so an agent can edit a requirement file directly. It runs shallgraph validate and shallgraph format, the same checks a person runs. The /require and /implement skills draft the requirement and the code that satisfies it.

  • Portable text

    The source is YAML. The reports are HTML and Markdown. Any editor can open them, diff them, and archive them. The hosted application reads those files. It is not where they are stored.

  • Output reports

    The HTML and Markdown reports list each requirement with what satisfies it and what verifies it. YAML entries appear under By comment. Tagged Rust items appear under Rust, with the file, the kind of item, and the line range.