Chronos — Examples & Artifact Generation

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

namespace com.example.onboarding

@kpi(metric: "OnboardingCompletion", target: ">80%")
journey EmailSignup {
    actor: NewUser

    preconditions: [
        "Actor has navigated to signup page"
    ]

    steps: [
        step ProvideEmail {
            action: "Enters email address"
            expectation: "System validates email format and checks for duplicates"
            outcome: TransitionTo(EmailValidated)
        },

        step SetPassword {
            action: "Creates password meeting security requirements"
            expectation: "System validates password strength (min 8 chars, mixed case, number)"
            outcome: TransitionTo(AccountCreated)
        },

        step VerifyEmail {
            action: "Clicks verification link in email"
            expectation: "System marks account as verified and auto-logs user in"
            outcome: TransitionTo(OnboardingComplete)
            telemetry: [UserVerifiedEvent]
        }
    ]

    variants: {
        EmailAlreadyExists: {
            trigger: "Email address is already registered"
            steps: [
                step ShowLoginPrompt {
                    expectation: "System displays 'Account exists, would you like to log in?' message"
                }
            ]
            outcome: TransitionTo(LoginFlow)
        }
    }

    outcomes: {
        success: "User account exists with status VERIFIED and user is authenticated",
        failure: "Signup form redisplayed with error message"
    }
}

Example 3: API Integration Journey

namespace com.example.integrations

@compliance("PCI-DSS")
journey ProcessPayment {
    actor: PaymentService

    preconditions: [
        "Order total has been calculated",
        "Payment token has been generated"
    ]

    steps: [
        step AuthorizePayment {
            @slo(latency: "3s", p99: true)
            action: "Sends authorization request to payment gateway"
            expectation: "Gateway returns authorization code or decline reason"
            telemetry: [PaymentAuthorizationRequestedEvent]
            risk: "Payment gateway timeout (SLA: 99.9% availability)"
        },

        step CapturePayment {
            action: "Sends capture request with authorization code"
            expectation: "Gateway confirms payment captured and returns transaction ID"
            outcome: TransitionTo(PaymentCaptured)
            telemetry: [PaymentCapturedEvent]
        },

        step RecordTransaction {
            action: "Writes transaction record to database"
            expectation: "Transaction record persisted with status CAPTURED"
            outcome: TransitionTo(TransactionRecorded)
        }
    ]

    variants: {
        PaymentDeclined: {
            trigger: "Gateway returns declined status"
            steps: [
                step LogDecline {
                    expectation: "System logs decline reason and notifies customer"
                    telemetry: [PaymentDeclinedEvent]
                }
            ]
            outcome: TransitionTo(PaymentFailed)
        }
    }

    outcomes: {
        success: "Transaction record exists with status CAPTURED",
        failure: "Payment declined and customer notified"
    }
}

Artifact Generation

Chronos generates multiple artifact formats from a single .chronos source.

Work Items & Issues

Chronos maps each journey to a hierarchy of work items via the configured issue tracker plugin. The plugin calls your tracker's API directly—no manual export or import step.

Each journey becomes a top-level container (Epic, Project, Initiative—whatever the tracker calls it), and each step becomes a child work item with acceptance criteria derived from the step's expectation.

Generated fields (tracker-agnostic):

Title (from step name)
Description (from action + expectation)
Acceptance Criteria (from expectation)
Labels / tags (from traits: @compliance, @priority)
Custom fields (KPI metrics from @kpi, owners from @owner)

Example hierarchy (Jira):

Epic: GuestCheckout
├── Story: ProvideShipping
│   ├── Acceptance Criteria
│   └── Definition of Done
├── Story: ChoosePayment
└── Story: PlaceOrder

Example hierarchy (Linear):

Project: GuestCheckout
├── Issue: ProvideShipping
├── Issue: ChoosePayment
└── Issue: PlaceOrder

Product Requirements Documents (PRD)

The prd plugin generates a human-readable requirements document from your .chronos files. Useful for stakeholder review, handoffs, or audit trails—without manually maintaining a separate doc.

Each journey becomes a section in the PRD with its actor, preconditions, step-by-step flow, acceptance criteria, KPIs, compliance tags, and outcomes. The document is generated fresh on every chronos build, so it never drifts from the spec.

Configure it in chronos-build.json under projections:

"prd": {
  "plugin": "prd",
  "output": "./artifacts/docs",
  "config": {
    "format": "markdown",
    "includeKpis": true,
    "includeCompliance": true
  }
}

Test Scaffolding

The tests projection generates acceptance test scaffolding from your journey steps. Each step's action and expectation map directly to test cases—the happy path and each variant become separate scenarios.

Configure the plugin in chronos-build.json to match your test framework:

"tests": {
  "plugin": "cucumber",
  "output": "./features"
}

Swap the plugin to target a different framework without changing your .chronos files.

Example output (cucumber plugin):

Feature: GuestCheckout
  As a Customer
  I want to complete checkout without logging in

  Background:
    Given Cart is not empty
    And Actor is not logged in

  Scenario: Successful guest checkout
    When Actor submits shipping address form
    Then System validates address and calculates available shipping methods and taxes

    When Actor selects Credit Card and enters payment details
    Then System validates card format via Luhn check and calculates final total

    When Actor clicks 'Place Order'
    Then Order is created with status PAID and confirmation email is queued

  Scenario: Payment declined
    Given Actor has provided shipping and payment details
    When Payment gateway returns declined status
    Then System displays payment declined message with retry option

Example output (playwright plugin):

test.describe('GuestCheckout', () => {
  test.beforeEach(async ({ page }) => {
    // Preconditions: Cart is not empty, Actor is not logged in
  });

  test('Successful guest checkout', async ({ page }) => {
    // Step: ProvideShipping
    // Actor submits shipping address form
    // Expected: System validates address and calculates available shipping methods and taxes

    // Step: ChoosePayment
    // Actor selects Credit Card and enters payment details
    // Expected: System validates card format via Luhn check and calculates final total

    // Step: PlaceOrder
    // Actor clicks 'Place Order'
    // Expected: Order is created with status PAID and confirmation email is queued
  });

  test('Payment declined', async ({ page }) => {
    // Variant trigger: Payment gateway returns declined status
    // Expected: System displays payment declined message with retry option
  });
});

State Diagrams

Generated Mermaid diagram:

stateDiagram-v2
    [*] --> ProvideShipping: Journey Start
    ProvideShipping --> ShippingMethodsDisplayed: Address Validated
    ShippingMethodsDisplayed --> ChoosePayment: Shipping Selected
    ChoosePayment --> PlaceOrder: Payment Entered
    PlaceOrder --> OrderConfirmed: Order Created
    OrderConfirmed --> [*]: Success

    ChoosePayment --> ChoosePayment: Payment Declined
    ProvideShipping --> ProvideShipping: Invalid Address

Telemetry Event Contracts

When steps declare a telemetry field, Chronos generates event contract documents—human and machine-readable descriptions of which events should be emitted and where in the journey they belong.

These contracts tell engineers what to instrument. How you instrument it (which OTel SDK, which backend) is up to your implementation. Many journeys won't need this at all—use telemetry only when you need to formally specify observability requirements alongside behavioral ones.

Generated contract for the GuestCheckout journey:

journey: GuestCheckout
events:
  - name: PaymentMethodSelectedEvent
    step: ChoosePayment
    attributes:
      - name: payment_method
        type: string
        required: true

  - name: OrderPlacedEvent
    step: PlaceOrder
    attributes:
      - name: order_id
        type: string
        required: true
      - name: order_total
        type: float
        required: true

Integration with Other Languages

Chronos is the requirements layer in the Genairus Software Factory. It integrates with:

With Capacitor (Data Models)

Import Capacitor entities into Chronos:

namespace com.genairus.commerce.checkout

use com.genairus.data.orders#Order
use com.genairus.data.orders#OrderStatus

journey GuestCheckout {
    steps: [
        step PlaceOrder {
            expectation: "Order entity created with status PAID"
        }
    ]
}

When integrations.capacitor is configured in chronos-build.json, Chronos validates that imported entities exist.

Standalone mode: Define entities inline if Capacitor isn't present:

entity Order {
    id: String
    status: String
}

With Smithy (API Contracts)

Reference Smithy operations in journey steps:

use com.genairus.api.orders#PlaceOrderOperation

journey GuestCheckout {
    steps: [
        step PlaceOrder {
            @operation("com.genairus.api.orders#PlaceOrderOperation")
            action: "Clicks 'Place Order'"
            expectation: "System calls PlaceOrderOperation and receives success response"
        }
    ]
}

With Flux (UI Components)

Link journey steps to Flux components:

journey GuestCheckout {
    steps: [
        step ProvideShipping {
            @component("com.genairus.ui.checkout#ShippingForm")
            action: "Submits shipping address form"
        }
    ]
}

With Fusion (Infrastructure)

Telemetry event contracts generated by Chronos can be referenced alongside Fusion infrastructure definitions, keeping observability requirements co-located with the infrastructure that supports them.

{
  "integrations": {
    "fusion": {
      "infra": "./infrastructure"
    }
  }
}

Full-Stack Example

See /docs/languages for a complete example using all five languages together.