dot•requirements

One source of truth for what your software should do. Readable. Testable. AI-accessible.

Tests prove something works—but nobody is certain it's the right something. Requirements live scattered across docs, issue trackers, and people's heads. They drift out of sync with actual code. And AI assistants can't access them at all.

dot•requirements closes this gap. Write requirements as structured Markdown, reference them directly in tests, and see coverage update automatically. When a requirement changes, the tests that validate it are one click away.

Alpha Software — Under active development. Please report issues to [email protected].

Who Is This For?

• Developers who want tests that prove the right behavior, not just "80% coverage"
• Product managers who want visibility into what's actually being tested
• AI-first builders who want clear requirements for faster, more accurate implementations

Installation

npm install @popoverai/dotrequirements
# or
pnpm add @popoverai/dotrequirements

Note: Examples use dotreq for brevity. The full command dotrequirements also works.

Quick Start

1. Initialize a project

npx dotreq init

This creates a .requirements/ directory with example requirements and configures your project.

2. Write requirements

Create *.requirements.md files in .requirements/ or colocate them with your code:

---
document:
  title: "Authentication Requirements"
---

## User Authentication

```dotrequirements
AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
  0. → When Jamie provides a valid username and password, they are authenticated and brought to their dashboard
  1. → When Jamie provides an incorrect password, they see an error message and remain on the login page
  2. → When Jamie's account has been deactivated, but they provide otherwise correct credentials, they see a message explaining their account status

If your team prefers a structure such as Gherkin, you can add labels:

AUTH-LOGIN-2: A user with two-factor authentication enabled must provide an OTP
  0. Given → Jamie has two-factor authentication enabled on their account
  1. When → Jamie provides valid credentials
  2. Then → Jamie is prompted to enter an OTP before accessing their dashboard

3. Reference requirements in tests

import { requirement } from '@popoverai/dotrequirements/test';

describe(requirement('AUTH-LOGIN-1'), () => {
  it(requirement('AUTH-LOGIN-1.0'), () => {
    // valid credentials → authenticated
  });

  it(requirement('AUTH-LOGIN-1.1'), () => {
    // incorrect password → error message
  });
});

4. Track coverage

After running tests, you'll see a coverage report showing which requirements have been tested.

CLI Commands

dotreq init

Initialize a new project. Creates .requirements/ directory, example files, and configuration.

dotreq init
dotreq init --name my-project
dotreq init --invite abc123xyz

Options:

| Option | Description | |--------|-------------| | --name <name> | Set project name (skips prompt) | | --invite <token> | Join a team using an invite token |

Joining a team via invite:

If a team admin shares an invite command with you, join the team and connect in one step:

npx dotrequirements init --invite abc123xyz

This shows the team name, prompts you to sign in, adds you to the team, and lets you select a project.

dotreq link

Link your local environment to an existing project (when you already have a project in dot•requirements cloud).

dotreq link

dotreq pull

Sync requirements from dot•requirements cloud to local .requirements/ files.

dotreq pull
dotreq pull --project <project-id>
dotreq pull --document <document-id>
dotreq pull --share <token>

First-time setup with a share token:

If a team member shares a pull command with you, you can pull requirements without creating an account:

npx @popoverai/dotrequirements pull --share drt_abc123...

This gives you read-only access to view requirements. To push changes or report coverage, run dotreq link afterward.

dotreq push

Push local requirements to dot•requirements cloud.

dotreq push
dotreq push .requirements/auth.requirements.md
dotreq push --yes  # Skip confirmation

dotreq validate

Validate requirements files against the schema.

dotreq validate
dotreq validate --file .requirements/auth.requirements.md

dotreq search

Search requirements by text or regex across every .requirements.md file. Searches IDs, content, and labels.

dotreq search "login"
dotreq search "AUTH-.*" --regex

dotreq get

Print a requirement (or subtree) by ID, with test references and source locations. Accepts both numeric paths (AUTH-LOGIN-1.0.1) and label paths (AUTH-LOGIN-1.given.and).

dotreq get AUTH-LOGIN-1
dotreq get AUTH-LOGIN-1.0

dotreq list

Summarize requirements in the project. Without flags, lists every root with its child count. With --untested, filters to roots with no requirement() references in any test.

dotreq list
dotreq list --untested

dotreq requirements-for

Show which requirements a test file references, with the line where each requirement() call lives.

dotreq requirements-for src/auth.test.ts

dotreq tests-for

Show which tests reference each requirement in a .requirements.md file. The inverse of requirements-for.

dotreq tests-for .requirements/auth.requirements.md

dotreq acceptance-test

Run browser-based acceptance tests against requirements. Uses AI-powered browser automation to verify that your application behaves as specified.

dotreq acceptance-test LOGIN-1
dotreq acceptance-test LOGIN-1 https://example.com
dotreq acceptance-test LOGIN-1 --json

Options:

| Option | Description | |--------|-------------| | --json | Output results as JSON (for CI/CD integration) |

Configuration required:

Browser testing needs a Stagehand model and the API key for that model's provider in project-settings.json:

{
  "defaultURL": "https://your-app.com",
  "browserTest": {
    "modelName": "gateway/anthropic/claude-haiku-4-5",
    "modelApiKey": "your-api-key"
  }
}

Pick any Stagehand-supported model. Example values: gateway/anthropic/claude-haiku-4-5 (Vercel AI Gateway key), google/gemini-3-flash-preview (Gemini key).

Optional settings: vercelBypassSecret, browserbaseApiKey, browserbaseProjectId. Setting both Browserbase fields switches runs from LOCAL (spawns Playwright on your machine) to BROWSERBASE (managed cloud browsers).

dotreq cts (Alpha)

Generate behavioral requirements from an existing codebase — it plans a behavioral outline, drafts the requirements for each area, converges each through independent review, then reconciles the whole spec in a final cross-area pass, and writes the result to .requirements/.

It runs as a Claude Code skill backed by a dynamic workflow. Install it, then invoke it from Claude Code:

dotreq cts skill-install            # install into this project's .claude/
dotreq cts skill-install --global   # …or into ~/.claude/ for every project

Then, in Claude Code, run /codebase-to-spec (or just ask — e.g. "spec the auth module"). You confirm the scope; the workflow autonomously plans the areas, drafts and reviews each one, reconciles them in a cross-area pass, and writes the result to .requirements/. Requires a Claude Code version with dynamic-workflow support.

Alpha: output quality is prompt-sensitive and varies by codebase. See the Codebase to Spec docs for prerequisites, scoping, and known rough edges. Feedback to [email protected] welcome.

dotreq ai-setup

Configure the MCP server for AI assistants (Claude Code, Cursor, etc.).

dotreq ai-setup

dotreq mcp

Start the MCP server manually (typically not needed—AI assistants start it automatically after ai-setup).

dotreq mcp

dotreq harness prepare

Parse requirements and build a lookup cache for multi-language test tracking. Run before tests in non-JavaScript projects. JavaScript projects don't need this — the test harness calls prepare() automatically.

dotreq harness prepare
dotreq harness prepare --quiet

dotreq harness finalize

Aggregate test tracking data and print a coverage report. Run after tests in non-JavaScript projects.

dotreq harness finalize
dotreq harness finalize --push
dotreq harness finalize --push --context pytest

| Option | Description | |--------|-------------| | --push | Push coverage to dot•requirements cloud | | --quiet | Output only coverage percentage (for scripting) | | --context <label> | Attribution label identifying the reporter (e.g. pytest, Jest) |

dotreq report

View coverage from the most recent local test run, or from the cloud-persisted record.

dotreq report                                       # local cache (default)
dotreq report --source cloud                        # cloud-persisted record
dotreq report --source cloud --branch main          # filter to a branch
dotreq report --source cloud --since 1700000000000  # filter to records after a timestamp
dotreq report --requirement AUTH-LOGIN              # scope to one requirement
dotreq report --format json

| Option | Description | |--------|-------------| | --source <source> | Where to read coverage from: local (default) or cloud | | --format <format> | Output format: console (default), json, markdown | | --requirement <id> | Filter to a specific requirement (and its children for local source) | | --branch <name> | Cloud-only: filter coverage to a specific git branch | | --since <timestamp> | Cloud-only: only show coverage recorded after this Unix-ms timestamp |

--branch and --since only apply with --source cloud; using them with the local source errors out. Cloud queries require running dotreq link first.

dotreq style-check

Get AI feedback on a requirements file or a test file. Works on both *.requirements.md files (catches vagueness, missing preconditions, untestable assertions) and test files (checks semantic alignment with referenced requirements).

dotreq style-check .requirements/auth.requirements.md
dotreq style-check src/auth.test.ts
dotreq style-check .requirements/auth.requirements.md --keys AUTH-LOGIN-1,AUTH-LOGIN-2

| Option | Description | |--------|-------------| | --keys <list> | Comma-separated requirement keys to limit the review (requirements files only) | | --model <name> | Override the AI model used for the review |

When .requirements/STYLE.md exists in your project, its contents are included in the AI's prompt so project-specific style preferences influence the feedback. Requires cloud authentication.

dotreq review-test

AI-powered semantic review of a test file against its referenced requirements. Validates that test setup matches GIVEN conditions, actions match WHEN triggers, and assertions match THEN outcomes.

dotreq review-test src/auth.test.ts

Catches tests that reference a requirement but don't actually validate what the requirement specifies — especially valuable when AI assistants write tests. Requires cloud authentication.

dotreq create-requirement-document

Print a Markdown template demonstrating the requirements file format, with format guidance and style examples. Use it to seed a new .requirements.md file or to prime an AI assistant's context before authoring.

dotreq create-requirement-document
dotreq create-requirement-document .requirements/auth.requirements.md

When a file path is provided, the template references that filename. If .requirements/STYLE.md exists, its contents replace the bundled default style body in the output. The template is printed to stdout.

What Works Locally

The following features work fully offline—no account required:

• Write requirements (.requirements.md files)
• Validate requirements (dotreq validate)
• Search and explore (dotreq search, get, list, requirements-for, tests-for)
• Reference requirements in tests (requirement())
• Local coverage reporting (dotreq report, default --source local)
• Generate a requirements template (dotreq create-requirement-document)
• MCP tools that mirror the offline CLI verbs

The following features require a dot•requirements cloud account:

• Sync requirements (pull / push)
• Cloud coverage queries (dotreq report --source cloud)
• AI-powered style checking and test review (dotreq style-check, dotreq review-test)
• Team collaboration

To enable cloud features, run dotreq link to connect your project to the cloud.

Test Harness

Stop wondering "did we test that?" The test harness tracks which requirements are exercised by your tests and shows gaps instantly.

Setup with Vitest

vitest.config.ts:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globalSetup: './vitest.setup.ts',
  },
});

vitest.setup.ts:

import { prepare, finalize } from '@popoverai/dotrequirements/test';

// Named exports: Vitest calls setup() before tests, teardown() after
export function setup() {
  prepare();
}

export async function teardown() {
  await finalize();
}

Alternatively, you can use the default export pattern that returns a teardown function—see the Vitest globalSetup docs.

Customizing output: finalize() accepts options to control verbosity:

await finalize({ showTestedList: true }); // Include tested requirements
await finalize({ showSummary: false, showUntestedList: false }); // Quiet mode

Attribution: tag cloud coverage rows with the name of the framework that produced them:

await finalize({ context: 'Vitest' });

The Coverage tab uses this label to show which tool produced each result. Any string works — useful when you have multiple test suites ("Vitest — unit", "Vitest — integration").

By default, only untested requirements are shown. See the test harness docs for all options.

Setup with Jest

jest.config.cjs:

module.exports = {
  globalSetup: './jest.setup.cjs',
  globalTeardown: './jest.teardown.cjs',
};

jest.setup.cjs:

const { prepare } = require('@popoverai/dotrequirements/test');

module.exports = async function setup() {
  prepare();
};

jest.teardown.cjs:

const { finalize } = require('@popoverai/dotrequirements/test');

module.exports = async function teardown() {
  await finalize();
};

Note: Jest global setup/teardown files run in a separate process from your tests. If using ES modules, configure Jest's transform option accordingly.

Using requirement() in Tests

The requirement() function returns a formatted string for test descriptions and tracks coverage:

import { requirement } from '@popoverai/dotrequirements/test';

// Reference root requirement
test(requirement('AUTH-LOGIN-1'), () => {
  // Returns: "A registered user, Jamie, can log in to their account"
});

// Reference by numeric path
test(requirement('AUTH-LOGIN-1.0'), () => {
  // Returns: "When Jamie provides a valid username and password..."
});

// Reference by label path (for requirements with labels)
test(requirement('AUTH-LOGIN-2.given'), () => {
  // Returns: "Given: Jamie has two-factor authentication enabled on their account"
});

// Track multiple requirements in one test
test(requirement('AUTH-LOGIN-1', 'AUTH-SECURITY-1'), () => {
  // Both requirements tracked; returns first one's content
});

Path Reference Patterns

| Pattern | Example | Description | |---------|---------|-------------| | Root | AUTH-LOGIN-1 | Root requirement | | Numeric | AUTH-LOGIN-1.0 | First child (position 0) | | Numeric nested | AUTH-LOGIN-1.2.0 | First child of third child | | Label | AUTH-LOGIN-2.given | First "Given" criterion | | Label disambiguated | AUTH-LOGIN-2.given#1 | Second "Given" criterion | | Label nested | AUTH-LOGIN-2.then.and | First "And" under first "Then" |

Coverage Reporting

Coverage isn't just a number—it's a map of which features have been tested and which haven't.

Local Report

After tests complete, a coverage summary prints to the console:

=== Requirements Coverage Report ===

Total Requirements: 12
Tested Requirements: 10
Untested Requirements: 2
Coverage: 83.3%

✓ Tested Requirements:
  - AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
  - AUTH-LOGIN-1.0: When Jamie provides a valid username and password...

✗ Untested Requirements:
  - AUTH-LOGIN-2: A user with two-factor auth must provide an OTP
  - AUTH-SECURITY-1: Session tokens expire after 8 hours

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

Cloud Reporting

With cloud credentials configured, coverage is automatically reported to dot•requirements cloud:

• Historical tracking of when requirements were last tested
• Branch-based coverage (tracks main, feature branches, etc.)
• Query coverage via the MCP server

Run dotreq link to connect your project to the cloud and enable coverage reporting.

Cloud reporting is fire-and-forget—it never blocks or fails your tests.

Requirements File Format

Requirements use Markdown with YAML frontmatter and dotrequirements fenced code blocks.

File Naming

Files must match the pattern *.requirements.md:

.requirements/
  auth.requirements.md
  checkout.requirements.md

src/components/
  Button.requirements.md    # Colocated with implementation
  Button.tsx

Structure

---
document:
  title: "Document Title"
---

# Optional Markdown Content

You can include any Markdown here for context.

## Requirement Heading

```dotrequirements
AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
  0. → When Jamie provides valid credentials, they are authenticated
  1. → When Jamie provides an incorrect password, they see an error
  2. → When Jamie's account is deactivated, they see a status message

More Markdown content between requirements...

Another Requirement (with labels)

AUTH-LOGIN-2: A user with two-factor auth must provide an OTP
  0. Given → Jamie has two-factor authentication enabled
  1. When → Jamie provides valid credentials
  2. Then → Jamie is prompted to enter an OTP

### Format Details

- **Frontmatter**: YAML metadata (only `document.title` required for push)
- **Headings**: Optional documentation (not parsed as requirement data)
- **Fenced blocks**: `dotrequirements` blocks contain structured requirement data
- **First line**: `KEY: content` — the requirement identifier and summary
- **Criteria**: `position. → content` or `position. Label → content`
- **Arrow delimiter**: `→` (Unicode) or `->` (ASCII) both work
- **Labels**: Optional — use `Given`, `When`, `Then`, `And` if your team prefers BDD style

See [MARKDOWN_SCHEMA.md](https://github.com/PopoverAI/dotrequirements/blob/main/docs/reference/MARKDOWN_SCHEMA.md) for the complete specification.

---

## MCP Server

AI assistants can read your requirements in context, draft new ones, and verify tests actually validate what they claim to. The MCP server makes this possible through a standard protocol that works with Claude Code, Cursor, and other AI coding assistants.

### Setup

```bash
dotreq ai-setup

Follow the prompts to configure for your AI assistant (Claude Code, Cursor, etc.).

Available Tools

Exploration:

• search_requirements — Search by text or regex
• get_requirement — Get a requirement with its children and coverage
• list_requirements — List all requirements in the project (set untested: true to filter to coverage gaps)
• get_requirements_by_test — Get requirements referenced by a test file
• get_tests_by_requirement — Get tests that reference a requirement

Authoring:

• create_requirement_document — Get a Markdown template with format examples
• validate_requirements — Validate file schema (works offline)
• style_check — AI-powered style feedback on requirements (supports optional requirementKeys filter)
• review_test — Comprehensive test review (style + semantic correctness)

Coverage:

• report_coverage — Coverage from local cache or cloud, with optional requirement / branch / since filters

Cloud:

• push_requirements — Push to dot•requirements cloud

Diagnostic:

• debug_mcp_environment — Debug MCP server configuration

CI/CD Mode

For CI/CD environments (GitHub Actions, etc.), use the --auth-from-env flag to read credentials from environment variables instead of project-settings.json:

node packages/cli/dist/mcp/index.js --auth-from-env

Required environment variables:

• DOTREQ_PROJECT_ID — Your project slug
• DOTREQ_PROJECT_SECRET — Your project secret

Important: Without --auth-from-env, these environment variables are ignored. This explicit opt-in prevents credential conflicts between local and CI environments.

Example MCP config for GitHub Actions:

{
  "mcpServers": {
    "dotrequirements": {
      "command": "node",
      "args": ["packages/cli/dist/mcp/index.js", "--auth-from-env"],
      "env": {
        "DOTREQ_PROJECT_ID": "${DOTREQ_PROJECT_ID}",
        "DOTREQ_PROJECT_SECRET": "${DOTREQ_PROJECT_SECRET}"
      }
    }
  }
}

See the CI/CD Integration docs for complete examples.

Package Exports

// CLI (main entry point)
import '@popoverai/dotrequirements';

// Test harness
import { requirement, prepare, finalize } from '@popoverai/dotrequirements/test';

// Schema utilities
import { parseRequirementsFile, validateRequirementsFile } from '@popoverai/dotrequirements/schema';

// Browser-compatible schema (no Node.js dependencies)
import { parseRequirementBlock } from '@popoverai/dotrequirements/schema/browser';

// MCP server
import '@popoverai/dotrequirements/mcp';

Configuration

The CLI stores project credentials in .requirements/project-settings.json:

{
  "projectId": "your-project-id",
  "projectSecret": "your-project-secret"
}

This file is automatically added to .gitignore during initialization.

Links

• Documentation
• Getting Started Guide
• Support

License

MIT