Chronos - Universal Requirements Language

Version 1.0 | AI-First Requirements Language

Chronos Documentation: Introduction & Getting Started | Language Reference → | Examples & Artifacts → | CLI Reference →

Introduction

The Problem

Product requirements today live in scattered prose—Confluence pages, Google Docs, Jira epics written in natural language. This creates three fundamental problems:

1. Ambiguity: "The system should respond quickly" means something different to everyone
2. Drift: Requirements become stale the moment they're written
3. Untraceable Outcomes: No formal link between business goals and what gets built

The Solution

Chronos treats product intent as a structured asset. Instead of writing prose that must be interpreted, you author .chronos files that are parsed, validated, and generated into downstream artifacts—work items in your issue tracker of choice, test scaffolding for your test framework, state diagrams, and API stubs.

Chronos doesn't replace conversation. It replaces the output of conversation—the document that becomes your source of truth.

Core Principles

Who Is This For?

• Product Managers: Specify intent without ambiguity
• Engineers: Machine-readable requirements you can validate against
• QA Teams: Auto-generated acceptance criteria and test scaffolding
• Compliance Officers: Traceable policy enforcement across every journey
• AI Systems: Structured, ontologically sound input for reasoning

Getting Started

Installation

The Chronos CLI (chronos) is distributed as self-contained native binaries for each platform. Releases are available on the Genairus GitHub releases page.

macOS

Homebrew (Recommended)

brew tap genairus/tap && brew install chronos-cli

Manual (x86_64 and ARM)

Download the appropriate binary from the releases page, then extract and run the installer:

mkdir -p chronos-install/chronos && \
curl -L https://github.com/genairus/chronos/releases/latest/download/chronos-cli-darwin-$(uname -m).zip \
-o chronos-install/chronos-cli.zip && \
unzip -qo chronos-install/chronos-cli.zip -d chronos-install && \
mv chronos-install/chronos-cli-darwin-*/* chronos-install/chronos
sudo chronos-install/chronos/install

Linux

Manual (x86_64 and ARM)

mkdir -p chronos-install/chronos && \
curl -L https://github.com/genairus/chronos/releases/latest/download/chronos-cli-linux-$(uname -m).zip \
-o chronos-install/chronos-cli.zip && \
unzip -qo chronos-install/chronos-cli.zip -d chronos-install && \
mv chronos-install/chronos-cli-linux-*/* chronos-install/chronos
sudo chronos-install/chronos/install

Windows

Scoop (Recommended)

scoop bucket add genairus https://github.com/genairus/scoop-bucket; `
scoop install genairus/chronos-cli

Manual (x64)

Download chronos-cli-windows-x86_64.zip from the releases page, extract it, then run install.bat as Administrator.

Verify Installation

chronos --version
chronos --help

Your First Journey

Create a file called user-registration.chronos:

namespace com.example.onboarding

@kpi(metric: "RegistrationConversion", target: ">65%")
journey UserRegistration {
    actor: NewUser

    preconditions: [
        "Actor has navigated to the signup page",
        "Actor has a valid email address"
    ]

    steps: [
        step ProvideEmail {
            action: "Enters email address in the signup form"
            expectation: "System validates email format and checks for existing accounts"
            outcome: TransitionTo(EmailValidated)
        },

        step CreatePassword {
            action: "Enters password meeting minimum requirements"
            expectation: "System validates password strength (min 8 chars, 1 uppercase, 1 number)"
            outcome: TransitionTo(AccountCreated)
        },

        step ConfirmEmail {
            @slo(latency: "5s", p99: true)
            action: "Clicks confirmation link in email"
            expectation: "System marks account as verified and logs user in"
            outcome: TransitionTo(RegistrationComplete)
            telemetry: [UserRegistrationCompletedEvent]
        }
    ]

    outcomes: {
        success: "User account exists with status VERIFIED and user is logged in",
        failure: "Signup form displays actionable error message and preserves entered data"
    }
}

Generate Artifacts

Everything Chronos generates is controlled by chronos-build.json in your project root. Each entry in the projections block is a plugin that produces a specific output—issue tracker tickets, test scaffolding, PRDs, state diagrams, telemetry contracts. You enable what you need and skip what you don't.

Run the build locally:

chronos build

Chronos reads chronos-build.json, validates your spec, then executes each configured projection in order.

View Generated Artifacts

ls artifacts/
issues/         # Work items pushed to your configured issue tracker
tests/          # Test scaffolding for your configured test framework
diagrams/       # State diagrams
docs/           # PRDs and other generated documents
telemetry/      # Event contracts (only if telemetry fields declared)

Next Steps

Chronos Documentation: Introduction & Getting Started | Language Reference → | Examples & Artifacts → | CLI Reference →