How It Works

Dot•requirements uses a simple flow to keep requirements in sync with tested code: compose requirements, pull them into your codebase, and reference them in tests.

The Big Picture

Requirements flow from product intent to validated software:

1. Compose — Write requirements in the web composer or with an AI coding assistant
2. Sync — Requirements are stored in the cloud (the “remote origin”)
3. Pull — Developers pull requirements into *.requirements.md files
4. Test — Reference requirements in test descriptions with the requirement('REQ-ID') helper function
5. Track — Coverage is calculated automatically and synced to the cloud for team visibility

Requirements are designed to be available and readable wherever you work, whether that’s in a browser, an IDE, or an issue tracker.

Where Requirements Live

In the cloud — Compose and collaborate here. The web composer at app.dotrequirements.io  provides a structured editor with dedicated AI support.

In your codebase — Pull requirements with the CLI. They land as .requirements/*.requirements.md files—human-readable Markdown that works in any editor and renders nicely on GitHub. AI coding assistants can also compose requirements in tools like Claude Code via MCP.

my-project/
├── .requirements/
│   ├── auth.requirements.md
│   └── checkout.requirements.md
├── src/
└── tests/

The Flow

Compose

Create requirements in the web composer or through an AI assistant. Requirements are discrete, testable statements with optional children:

REQ-LOGIN-1: User can log in with email and password
  0. → Accepts valid credentials
  1. → Rejects invalid credentials
  2. → Locks account after 5 failed attempts

Pull

Developers pull requirements into their codebase:

dotreq pull

Requirements land as Markdown files in .requirements/. These are human-readable and version-controlled with your code.

Test

Reference requirements in your tests:

import { requirement } from '@popoverai/dotrequirements/test'
 
describe(requirement('REQ-LOGIN-1'), () => {
  it(requirement('REQ-LOGIN-1.0'), async () => {
    // "Accepts valid credentials"
    await login(validUser)
    expect(page).toHaveURL('/dashboard')
  })
 
  it(requirement('REQ-LOGIN-1.1'), async () => {
    // "Rejects invalid credentials"
    await login(invalidUser)
    expect(page).toHaveText('Invalid email or password')
  })
})

The requirement() function returns the requirement text, so your test descriptions stay in sync with your requirements.

Screenshot placeholder: Test explorer showing “REQ-LOGIN-1: User can log in with email and password” with children “Accepts valid credentials” and “Rejects invalid credentials”

Track Coverage

After tests run, you see which requirements are covered:

=== Requirements Coverage Report ===

Total Requirements: 3
Tested Requirements: 2
Untested Requirements: 1
Coverage: 66%

✓ Tested Requirements:
  - REQ-LOGIN-1: User can log in with email and password
  - REQ-LOGIN-2: User can reset password

✗ Untested Requirements:
  - REQ-CHECKOUT-1: User can complete checkout

====================================

Optionally sync coverage to the cloud for team-wide visibility.

The Pieces

• Web Composer — Structured editor for composing requirements (app.dotrequirements.io )
• AI Assistants — MCP integration for Claude Code, Cursor, and other AI coding tools
• CLI — pull, push, init commands for syncing requirements
• Test Harness — requirement() function and coverage tracking
• Atlassian Add-ons — View requirements in Jira issues and Confluence pages (read-only)

Works With Your Existing Workflow

Dot•requirements isn’t a replacement for your current process—it’s a missing link that makes existing workflows more effective:

• With TDD — Keep writing tests first. Dot•requirements adds a readable “what” layer that you can reference without context switching, and that less-technical team members can understand without reading test code.

• With PRDs and specs — Keep writing product documentation. Dot•requirements makes it available wherever work happens, and gives you automatic traceability so that you can measure test coverage in terms your stakeholders actually care about.

• With BDD — If Gherkin works for you, great: dot•requirements fully supports Given/When/Then syntax. As a bonus, your specification becomes testable from anywhere in your test suite, not just from dedicated integration layers like Cucumber.