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). Only the human sets them; an agent records an entry only when the human dictates it.
• 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.
• Agents apply mechanical and requested edits directly and call out any other change to meaning for review; they never weaken a requirement to make code pass.

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, keep the header, and replace the examples with your own — write your goals and non_goals yourself, or ask your agent to set up a new project and it will ask you for them. To vendor it straight from a release:

   curl -O https://raw.githubusercontent.com/andrioid/requirements-yaml/v0.9.1/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.