andri.dk / requirements-yaml
[READ-ONLY] Mirror of https://github.com/andrioid/requirements-yaml. Compact way of describing functional/non-functional requirements
Star 0
Fork 0
Watch
JavaScript 100%
12 1 7
skills
CHANGELOG.md
README.md
requirements.schema.json
requirements.template.yaml
README.md

requirements-yaml #

A compact, hand-editable format for a project's requirements — one file, one line per requirement. The format is the point; the agent skills are an addon.

functional:
  accounts:
    As a user, I can:
      ACC-01: regain account access after losing my sign-in credential; so that I can recover without contacting support.
  • observable capability; so that value. — the whole requirement on one line. Limits, edge cases, and acceptance criteria live outside the requirement.
  • Requirements contain only what ability is needed and why it matters. Technologies, protocols, components, endpoints, data models, algorithms, UI controls, test methods, and other implementation choices stay in design documents, plans, and code.
  • IDs (ACC-01) are stable, so plans, tests, and commits can reference them.
  • Grouped into functional, non_functional, optional deferred, plus any project-specific domain sections.
  • Optional goals and non_goals lists at the top set the project's vision and its boundaries — plain one-liners, not requirements (non_goals is not ever, distinct from deferred's not yet).
  • An optional roles map defines the actors named in As a <role> headings — each role mapped to a one-line description of who they are and their authority.
  • An optional top-level docs map lists supporting material by filename (ubiquitous language, domain model, ADRs), each with a note on what it is and when to read it.
  • Quotes are optional — add them only if a clause contains : or the value starts with a YAML symbol.
  • The file is human-owned: an agent proposes edits and a human approves them — requirements.yaml is never rewritten unilaterally.

The format #

Two files at the repo root define it:

  • requirements.template.yaml — a ready-to-copy starter.
  • requirements.schema.json — an optional, structure-only editor aid; the template's $schema field points at it.

Skills #

Three agent skills under skills/ build on the format, each installable on its own. The @<skill> selector picks one; omit it to install all three:

npx skills add andrioid/requirements-yaml@requirements-yaml
npx skills add andrioid/requirements-yaml@requirements-implement
npx skills add andrioid/requirements-yaml@requirements-discover
  • requirements-yaml — the format: author, edit, and review a requirements.yaml.
  • requirements-implement — build a change from a requirement: turn its capability into a test, implement, and cite the ID.
  • requirements-discover — reverse-engineer a requirements.yaml from an existing codebase.

The workflow skills depend on requirements-yaml. Skills carry instructions and vendor the template and schema from the repo root (pinned to the release tag) rather than bundling them. The requirements-yaml skill additionally ships scripts/check.mjs — a read-only sensor that surfaces duplicate IDs, grammar drift, and (via git grep) which requirements the code does and does not cite. It reports where the file and the code disagree; it never edits either.

Start #

  1. Install the skills (above).
  2. Copy requirements.template.yaml into your repo as requirements.yaml, then edit the header and examples. To vendor it straight from a release:
    curl -O https://raw.githubusercontent.com/andrioid/requirements-yaml/v0.8.0/requirements.template.yaml
  3. (Optional) vendor requirements.schema.json beside it for editor autocomplete — the template's $schema field already points at it.
  4. To review a file, run the sensor (node skills/requirements-yaml/scripts/check.mjs) for the mechanical checks, and ask your agent (which now has the skill) to judge the rest against the format.

The full rules live in the format skill, skills/requirements-yaml/SKILL.md.