Quick Start Tutorial

This 5-minute tutorial introduces Requiem's basic workflow. You'll create a simple set of requirements and link them together.

Creating a Requirements Directory

First, create a directory for your requirements:

mkdir my-requirements
cd my-requirements

Requiem works with any directory - there's no special initialization needed. Requirements are simply markdown files with YAML frontmatter.

Adding Your First Requirement

Let's create a user requirement using the add command:

req add USR

This creates a file named USR-001.md with automatically generated metadata. Output:

Added requirement USR-001

The file contains:

---
_version: '1'
uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a
created: 2025-07-22T12:19:56.950194157Z
---
# USR-001

The YAML frontmatter includes:

• _version: Format version for future compatibility
• uuid: A globally unique, stable identifier
• created: Timestamp of creation

The heading includes:

• # USR-001: The HRID as the first token in the first heading
• Followed by the title text (currently empty)

The body (currently empty) is where you'll write the requirement text.

Editing the Requirement

Open USR-001.md in your text editor and add content:

---
_version: '1'
uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a
created: 2025-07-22T12:19:56.950194157Z
---
# USR-001 Plain Text Requirements

The system shall support plain-text requirements that can be edited with any text editor.

Notice the HRID (USR-001) appears as the first token in the first heading, followed by the title. Save the file. That's it! You've created your first requirement.

Adding More Requirements

Create a few more user requirements:

req add USR  # Creates USR-002
req add USR  # Creates USR-003

Edit these files to add meaningful content. For example:

USR-002.md:

---
_version: '1'
uuid: ...
created: ...
---
# USR-002 Version Control Integration

The system shall integrate with version control systems like Git.

USR-003.md:

---
_version: '1'
uuid: ...
created: ...
---
# USR-003 Requirement Traceability

The system shall support requirement traceability and linkage.

Creating System Requirements

Now let's create system-level requirements that satisfy the user requirements:

req add SYS  # Creates SYS-001

Linking Requirements

Link SYS-001 to its parent USR-001:

req link SYS-001 USR-001

Output:

Linked SYS-001 to USR-001

Now if you open SYS-001.md, you'll see the parent relationship in the frontmatter and the HRID in the heading:

---
_version: '1'
uuid: 81e63bac-4035-47b5-b273-ac13e47a2ff6
created: 2025-07-22T13:14:40.510075462Z
parents:
- uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a
  fingerprint: e533784ff58c16cbf08e436cb06f09e0076880fd707baaf55aa0f45dc4a6ccda
  hrid: USR-001
---
# SYS-001 Markdown File Format

Each requirement shall be stored as a markdown file with YAML frontmatter.

The parents section contains:

• uuid: The stable identifier of the parent
• hrid: The human-readable ID (for your convenience)
• fingerprint: A hash of the parent's content (for change detection)

Creating Requirements with Multiple Parents

You can link a requirement to multiple parents when creating it:

req add SYS --parents USR-001,USR-002

This creates SYS-002 already linked to both USR-001 and USR-002.

Viewing Requirements

Requirements are just markdown files, so you can view them with any tool:

ls *.md
cat USR-001.md

Or use your favorite text editor, IDE, or markdown viewer.

Summary

You've learned the three core commands:

1. req add <KIND> - Create a new requirement
2. req link <CHILD> <PARENT> - Link two requirements
3. req add <KIND> --parents <PARENT1>,<PARENT2> - Create with parents

These commands form the foundation of requirements management with Requiem.

Next Steps

Continue to Your First Requirements Project to build a complete requirement hierarchy and learn more advanced techniques.