DEV Community

Cover image for SARA: A CLI Tool for Managing Markdown Requirements with Knowledge Graphs
tumf
tumf

Posted on • Originally published at blog.tumf.dev

SARA: A CLI Tool for Managing Markdown Requirements with Knowledge Graphs

#git #github #mermaid

Originally published on 2026-01-26
Original article (Japanese): SARA: Markdown要件を知識グラフで管理するCLI

"Where is the requirements specification?" "Which requirements does this design come from?" "Oh no, this link is broken..."

As teams grow larger, requirements and design documents start to scatter. Tools like Confluence, Notion, Excel, Wiki, and Markdown become disjointed, links break, and no one can grasp the overall picture.

SARA (Solution Architecture Requirement for Alignment) is a CLI tool that addresses this issue using "Markdown + Git + knowledge graphs (a graph structure representing relationships between documents)." By writing requirements in Markdown and defining relationships using YAML front matter (metadata at the beginning of the Markdown), SARA can automatically validate traceability (the ability to trace from requirements to implementation).

What is SARA?

SARA is a CLI (command-line interface) tool developed in Rust for managing requirements and design documents as a knowledge graph. It is available under the Apache 2.0 license.

Key features:

  • Markdown-first: Manage requirements in plain text (reducing vendor lock-in)
  • Multi-repository support: Aggregate documents across teams
  • Traceability validation: Automatically detect broken links, circular dependencies, and orphan items
  • Git integration: Compare differences between branches and validate automatically in PRs
  • Coverage reports: Visualize the status of requirement implementations

What Can You Do?

Main commands provided by SARA:

Command Purpose
sara init <FILE> Add requirement metadata to a Markdown file
sara parse Parse documents and build a knowledge graph
sara validate Detect broken links, circular dependencies, and orphans
sara query <ID> Trace upstream/downstream of requirements
sara report coverage Output implementation coverage
sara report matrix Generate a traceability matrix
sara diff <REF1> <REF2> Compare changes in requirements between Git references

Example: Tracking Requirement Traceability 

# Display all requirements derived from the user login scenario
sara query SCEN-001 --downstream

# Example output:
# SCEN-001: User Login Scenario
# ├── SYSREQ-001: Response Time Requirement
# │   └── SYSARCH-001: Authentication Architecture
# │       └── SWREQ-001: JWT Token Generation
# │           └── SWDD-001: Auth Service Implementation
Enter fullscreen mode Exit fullscreen mode

Example: Detecting Broken Links 

sara validate

# Example output:
# ❌ Broken reference: SYSREQ-999 (referenced by SCEN-001)
# ⚠️  Orphan item: SWDD-042 (no upstream parent)
# ❌ Circular dependency: SYSREQ-010 → SYSREQ-020 → SYSREQ-010
Enter fullscreen mode Exit fullscreen mode

Writing Requirements in Markdown

SARA's requirement documents are Markdown files with YAML front matter. Relationships between documents (such as derives, satisfies, and depends on) are linked by IDs.

---
id: "SYSREQ-001"
type: system_requirement
name: "Authentication Response Time"
derives_from:
  - "SCEN-001"
  - "SCEN-002"
is_satisfied_by:
  - "SYSARCH-001"
depends_on:
  - "SYSREQ-002"
---

## Requirement

The response time for user authentication must be within 500ms.

## Rationale

To meet the user experience defined in SCEN-001.
Enter fullscreen mode Exit fullscreen mode

Hierarchical Structure of Requirements

SARA recognizes nine types of document:

graph TD
    SOL[Solution<br/>Customer Solution]
    UC[Use Case<br/>Customer Needs]
    SCEN[Scenario<br/>System Behavior]
    SYSREQ[System Requirement<br/>System Requirements]
    SYSARCH[System Architecture<br/>Platform Implementation]
    HWREQ[Hardware Requirement<br/>HW Requirements]
    SWREQ[Software Requirement<br/>SW Requirements]
    HWDD[HW Detailed Design<br/>HW Implementation]
    SWDD[SW Detailed Design<br/>SW Implementation]

    SOL --> UC
    UC --> SCEN
    SCEN --> SYSREQ
    SYSREQ --> SYSARCH
    SYSARCH --> HWREQ
    SYSARCH --> SWREQ
    HWREQ --> HWDD
    SWREQ --> SWDD
Enter fullscreen mode Exit fullscreen mode

Types of Relationships

Relationship Direction Purpose
refines / is_refined_by Upstream / Downstream Solution ↔ Use Case ↔ Scenario
derives_from / derives Upstream / Downstream Scenario ↔ System Requirement
satisfies / is_satisfied_by Upstream / Downstream Requirement ↔ Architecture/Design
depends_on / is_required_by Same Level Dependencies between the same type of requirements

You only need to define relationships in one direction. SARA will automatically infer the reverse links.

Practical Usage

0. Try It in 10 Minutes (Minimal Setup)

First, let's create a small set of requirements locally and see it in action.

Prerequisites:

  • Rust must be installed (if not, use rustup)

1. Install SARA 

git clone https://github.com/cledouarec/sara.git
cd sara
cargo install --path sara-cli
sara --version
Enter fullscreen mode Exit fullscreen mode

2. Create Sample Requirements and Validate

In a separate directory, create the requirement Markdown files.

mkdir -p demo-requirements/docs/sara
cd demo-requirements

cat > sara.toml <<'EOF'
[repositories]
paths = [
  "./docs/sara"
]

[validation]
strict_orphans = true
EOF

cat > docs/sara/SOL-001.md <<'EOF'
---
id: "SOL-001"
type: solution
name: "Customer Portal"
is_refined_by:
  - "UC-001"
---

# Customer Portal
EOF

cat > docs/sara/UC-001.md <<'EOF'
---
id: "UC-001"
type: use_case
name: "User Authentication"
refines:
  - "SOL-001"
is_refined_by:
  - "SCEN-001"
---

# User Authentication
EOF

cat > docs/sara/SCEN-001.md <<'EOF'
---
id: "SCEN-001"
type: scenario
name: "User Login"
refines:
  - "UC-001"
derives:
  - "SYSREQ-001"
---

# User Login
EOF

cat > docs/sara/SYSREQ-001.md <<'EOF'
---
id: "SYSREQ-001"
type: system_requirement
name: "Authentication Response Time"
derives_from:
  - "SCEN-001"
is_satisfied_by:
  - "SYSARCH-001"
---

# Authentication Response Time
EOF

cat > docs/sara/SYSARCH-001.md <<'EOF'
---
id: "SYSARCH-001"
type: system_architecture
name: "Authentication Architecture"
satisfies:
  - "SYSREQ-001"
---

# Authentication Architecture
EOF

sara validate
sara query SYSREQ-001 --upstream
sara query SYSREQ-001 --downstream
Enter fullscreen mode Exit fullscreen mode

At this point, if there are broken links or circular dependencies, sara validate will fail. Running this in a PR (Pull Request) helps catch document "breaks" early.

1. Project Initialization 

# Create sara.toml
cat > sara.toml <<EOF
[repositories]
paths = [
    "./docs/requirements",
    "../shared-specs"
]

[validation]
strict_orphans = false

[output]
colors = true
emojis = true
EOF
Enter fullscreen mode Exit fullscreen mode

2. Create Requirement Documents 

# Create a new requirement file
sara init docs/requirements/auth-response-time.md

# Input metadata interactively
# ID: SYSREQ-001
# Type: system_requirement
# Name: Authentication Response Time
Enter fullscreen mode Exit fullscreen mode

Generated file:

---
id: "SYSREQ-001"
type: system_requirement
name: "Authentication Response Time"
---

# Authentication Response Time

[Describe the details of the requirement here]
Enter fullscreen mode Exit fullscreen mode

3. Automate Validation in CI/CD

You can automate the integrity checks of requirements in CI/CD (Continuous Integration/Continuous Delivery).

Example with GitHub Actions (making sara validate a requirement in PRs):

name: Validate Requirements

on:
  pull_request:
    paths:
      - 'docs/requirements/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable

      - uses: Swatinem/rust-cache@v2

      - name: Install SARA
        run: |
          cargo install --git https://github.com/cledouarec/sara --tag sara-cli-v0.4.0 --locked sara-cli

      - name: Validate knowledge graph
        run: |
          sara validate --strict

      - name: Generate coverage report
        run: |
          sara report coverage --format json > coverage.json

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage.json
Enter fullscreen mode Exit fullscreen mode

4. Check Differences Before Release 

# Compare changes in requirements between the main branch and the current branch
sara diff main HEAD

# Example output:
# Added:
#   + SWREQ-042: OAuth2 Token Refresh
# Modified:
#   ~ SYSREQ-001: Response time changed (500ms → 300ms)
# Removed:
#   - HWREQ-999: Deprecated sensor requirement
Enter fullscreen mode Exit fullscreen mode

Which Teams Will Benefit?

SARA is particularly effective in the following cases:

✅ Suitable Teams

  • Developing across multiple repositories: Microservices, monorepos, cross-team projects
  • Mature Git practices: PR reviews, branching strategies, and CI/CD are established
  • Traceability is essential: Regulated industries such as medical devices, automotive, aerospace, and finance
  • Documents are in Markdown: Already managing README, ADR (Architecture Decision Record), RFC (Request for Comments) in Markdown

❌ Unsuitable Cases

  • Non-technical stakeholders: Many stakeholders are not familiar with Markdown
  • Not using Git: No version control or using a VCS (Version Control System) other than Git
  • Few requirements: Small projects (fewer than 10 requirements)
  • Real-time collaborative editing needed: Rich editors like Notion or Confluence are essential

Combining with Mermaid

SARA's knowledge graph can be visualized using Mermaid (a syntax for generating diagrams from text).

Currently, there doesn't seem to be a feature to directly output SARA's results to Mermaid (at least as per the README). However, it is feasible to keep a minimal relationship diagram in Mermaid while reviewing the results of sara query.

graph LR
    SCEN001[SCEN-001: User Login]
    SYSREQ001[SYSREQ-001: Response Time]
    SYSARCH001[SYSARCH-001: Auth Architecture]

    SCEN001 -->|derives| SYSREQ001
    SYSREQ001 -->|is_satisfied_by| SYSARCH001
Enter fullscreen mode Exit fullscreen mode

Conclusion

SARA elevates the option of "writing requirements in Markdown" to a practical level.

Reasons to try SARA:

  • No vendor lock-in: Being plain text, you can migrate to other tools at any time
  • Git integration: Seamlessly fits into existing workflows (PRs, reviews, CI/CD)
  • Automatic validation: Mechanically detects broken links and circular dependencies that humans might overlook
  • Cross-team collaboration: Centralized management of requirements across multiple repositories

Next Steps:

  1. Clone the SARA repository
  2. Install with cargo install --path sara-cli
  3. Try the sample project (examples/smart-home)
  4. Run sara init in your own project

If you want to free your requirement management from the "Excel curse," give it a try!

Reference Links

Top comments (0)