Requirements 📋

Requirements live under docs/requirements/ and define what the project must do. Their primary purpose is to drive AI-agent-assisted development: a contributor creates a requirement file and then instructs the agent to iterate by following requirements.md and Compose Loop, continuing until every Acceptance Criterion is fulfilled.

Creating a requirement is not mandatory to work on a task. For normal work items, bugs, or feature requests, use the project tools directly:

Writing a requirement file is RECOMMENDED when you want an AI agent to autonomously implement and validate a feature end to end, because it gives the agent a structured, checkable definition of done.

File Naming

Every requirements file MUST follow the pattern NNN-topic.md, where NNN is a zero-padded three-digit sequence number (e.g. 000-template.md, 001-auth.md).

File Structure

Every requirements file MUST follow this template exactly:

# NNN - Title

## User Story

As a <role>, I want <goal> so that <benefit>.

## Acceptance Criteria

- [ ] Criterion one.
- [ ] Criterion two.

  • The User Story MUST follow the “As a / I want / so that” format.

  • Each Acceptance Criterion MUST be written as a Markdown task list item (- [ ]).

  • Criteria MUST be independently verifiable, with one observable outcome per item.

  • Completed criteria MUST be checked off (- [x]) once the corresponding work is merged.

Cross-linking

  • You MUST cross-link from the requirement to any PR or issue that implements it.

  • You MUST cross-link from the implementing PR template back to the requirement file.

See Also