Creating Requirements

The req add command creates new requirements with automatically generated metadata.

Basic Usage

req add <KIND>

This creates a requirement with the next available ID for the specified KIND.

Examples

# Create USR-001
req add USR

# Create USR-002
req add USR

# Create SYS-001
req add SYS

Output:

Added requirement USR-001
Added requirement USR-002
Added requirement SYS-001

Command Options

Specify Parent Requirements

Create a requirement already linked to parents:

req add <KIND> --parents <PARENT1>,<PARENT2>,...

Alias: -p for --parents

Examples

# Create SYS-001 linked to USR-001
req add SYS --parents USR-001

# Create SYS-002 linked to both USR-001 and USR-002
req add SYS --parents USR-001,USR-002

# Using short form
req add SYS -p USR-001,USR-002

Specify Root Directory

By default, req operates in the current directory. Use --root to specify a different directory:

req --root /path/to/requirements add USR

Alias: -r for --root

This is useful when running Requiem from outside the requirements directory:

# Run from project root
req --root ./docs/requirements add USR

# Using short form
req -r ./docs/requirements add USR

Verbosity

Control log output:

req -v add USR      # INFO level
req -vv add USR     # DEBUG level
req -vvv add USR    # TRACE level

More v's = more verbose. Useful for troubleshooting.

Generated Content

When you run req add USR, a file USR-001.md is created with:

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

Generated fields:

• _version: Always '1' (current format version)
• uuid: A random UUIDv4
• created: Current timestamp in ISO 8601 format (UTC)
• # USR-001: First heading with HRID (title text is initially empty)

Empty body: You need to add the requirement title and text yourself.

Adding Content

After creating a requirement, edit it to add content:

req add USR
# Output: Added requirement USR-001

# Edit the file
vim USR-001.md
# or
code USR-001.md

Add your requirement title and text:

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

Users shall be able to export data in CSV format.

## Rationale

CSV is a universally supported format for data interchange.

Note that the HRID (USR-001) is the first token in the heading, followed by the title. Save the file. Your requirement is now complete.

Creating with Parents

When you specify parents, they're included in the frontmatter:

req add SYS --parents USR-001

Creates SYS-001.md:

---
_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

Generated parent fields:

• uuid: Copied from USR-001's UUID
• fingerprint: Computed from USR-001's current content
• hrid: USR-001 (for human readability in frontmatter)

Generated heading:

• # SYS-001: First heading with HRID (you'll add the title text when editing)

Multiple Parents

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

Creates SYS-001.md with three parent entries:

parents:
- uuid: <USR-001 UUID>
  fingerprint: <USR-001 fingerprint>
  hrid: USR-001
- uuid: <USR-002 UUID>
  fingerprint: <USR-002 fingerprint>
  hrid: USR-002
- uuid: <USR-003 UUID>
  fingerprint: <USR-003 fingerprint>
  hrid: USR-003

Using Namespaces

Create requirements with namespaces by including them in the KIND:

# Create AUTH-USR-001
req add AUTH-USR

# Create AUTH-LOGIN-SYS-001
req add AUTH-LOGIN-SYS

# Create PAYMENT-API-SWR-001
req add PAYMENT-API-SWR

The filename matches the full HRID:

AUTH-USR-001.md
AUTH-LOGIN-SYS-001.md
PAYMENT-API-SWR-001.md

Workflow Recommendations

Create High-Level First

Start with user requirements:

req add USR
req add USR
req add USR

Edit them to add content. Then create system requirements that satisfy them:

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

This top-down approach ensures traceability from the start.

Create in Batches

If you know you need five user requirements:

for i in {1..5}; do req add USR; done

This creates USR-001 through USR-005. Then edit each file to add content.

Use Version Control

After creating requirements, commit them:

req add USR
req add USR
git add USR-001.md USR-002.md
git commit -m "Add initial user requirements (placeholders)"

# Edit the files, then commit again
git add USR-001.md USR-002.md
git commit -m "Add content to USR-001 and USR-002"

This creates a clear history of requirement evolution.

Error Conditions

Parent Not Found

req add SYS --parents USR-999

If USR-999.md doesn't exist, you'll get an error:

Error: Failed to load requirement USR-999

Solution: Ensure parent requirements exist before linking to them.

Invalid HRID Format

req add usr-001  # Trying to specify ID manually (not supported)

The KIND should not include the ID. Use:

req add USR  # Correct - ID is auto-assigned

Malformed Parent List

req add SYS --parents USR-001, USR-002  # Space after comma

Don't include spaces in the parent list:

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

Advanced: Scripting Requirement Creation

For bulk creation with structured content, use shell scripts:

#!/bin/bash

# Create and populate multiple user requirements
requirements=(
  "Users shall authenticate via username and password"
  "Users shall reset forgotten passwords via email"
  "Users shall enable two-factor authentication"
)

for i in "${!requirements[@]}"; do
  req add USR
  hrid="USR-$(printf '%03d' $((i+1)))"

  # Append requirement text to the file
  echo "${requirements[$i]}" >> "$hrid.md"
done

This creates USR-001, USR-002, and USR-003 with predefined content.

Next Steps

Once you've created requirements, you'll often need to link them together. Learn how in Linking Requirements.