Chronos Generator Implementation Guide

This document describes how each Chronos generator implements features for specific output formats and tools. It provides transparency about what happens when you generate artifacts from Chronos specifications—including Jira tickets, Gherkin tests, OpenTelemetry schemas, and documentation.

Generator Architecture and SPI

Chronos uses a pluggable generator architecture that separates the universal requirements model from tool-specific implementations. Generators follow a formal Service Provider Interface (SPI) that enables third-party generator development.

Generator Lifecycle

Every generator follows a defined lifecycle with distinct phases:

discover → configure → validate → resolve → generate → post-process → validate-output → publish

1. Discover: Build system finds generators via plugin declarations in chronos-build.json

{
  "projections": {
    "jira": {
      "plugin": "jira-cloud"
    }
  }
}

2. Configure: Generator receives its configuration block

{
  "projections": {
    "jira": {
      "plugin": "jira-cloud",
      "output": "./artifacts/jira",
      "config": {
        "projectKey": "ECOM",
        "issueTypeEpic": "Epic",
        "issueTypeStory": "Story"
      }
    }
  }
}

3. Validate: Generator confirms compatibility and required options

• Checks if authentication credentials are present
• Validates that project key exists
• Confirms required custom fields are available

4. Resolve: Generator resolves the semantic model into its internal representation

• Parses all journeys, actors, entities, policies
• Resolves namespace imports and dependencies
• Builds the complete requirements graph

5. Generate: Generator emits artifacts (tickets, tests, schemas, diagrams)

• Produces JSON import files, feature files, YAML schemas
• Generates diagrams in Mermaid or PlantUML format
• Creates documentation sites with search and navigation

6. Post-process: Applies formatting and validation

• Formats generated code (Prettier for JSON/YAML)
• Validates generated artifacts against target schema
• Injects additional metadata (timestamps, version info)

7. Validate-Output: Ensures generated artifacts are valid

• Validates JSON against Jira import schema
• Validates Gherkin against Cucumber specification
• Checks OpenTelemetry schemas for completeness

8. Publish: Optionally pushes artifacts to external systems

• Imports tickets into Jira Cloud/Server
• Commits Gherkin files to Git repository
• Uploads diagrams to wiki or documentation site

Generator Types

Built-in Generators

Shipped with Chronos and referenced by plugin name:

• jira-cloud - Jira Cloud import format
• jira-server - Jira Server/Data Center format
• cucumber - Gherkin/Cucumber feature files
• specflow - Gherkin for .NET SpecFlow
• behave - Gherkin for Python Behave
• opentelemetry - OpenTelemetry event schemas
• mermaid - Mermaid state/sequence diagrams
• plantuml - PlantUML diagrams
• markdown-docs - Markdown documentation site
• html-docs - HTML documentation with search

External Generators

Third-party generators installed from repositories:

{
  "plugins": {
    "repositories": [
      "https://plugins.chronos-lang.dev"
    ],
    "generators": {
      "com.acme.chronos:generator-azure-boards": "1.0.0",
      "org.chronos:generator-postman": "2.1.0"
    }
  }
}

Local Generators

Proprietary or in-development generators:

{
  "plugins": {
    "local": [
      "./generators/custom-requirement-tracker",
      "./generators/company-standards"
    ]
  }
}

Jira Cloud Generator

Generates JSON import format for Jira Cloud REST API.

Configuration

{
  "projections": {
    "jira": {
      "plugin": "jira-cloud",
      "output": "./artifacts/jira",
      "config": {
        "projectKey": "ECOM",
        "issueTypeEpic": "Epic",
        "issueTypeStory": "Story",
        "issueTypeTask": "Task",
        "customFields": {
          "kpi": "customfield_10001",
          "owner": "customfield_10002",
          "compliance": "customfield_10003"
        },
        "labelPrefix": "chronos-",
        "autoImport": false,
        "credentials": {
          "email": "${JIRA_EMAIL}",
          "apiToken": "${JIRA_API_TOKEN}",
          "baseUrl": "https://yourcompany.atlassian.net"
        }
      }
    }
  }
}

Generated Structure

One Epic per Journey:

{
  "fields": {
    "project": { "key": "ECOM" },
    "summary": "GuestCheckout",
    "description": "Journey: GuestCheckout\nActor: Customer\n\nPreconditions:\n- Cart is not empty\n- Actor is not logged in\n\n...",
    "issuetype": { "name": "Epic" },
    "labels": ["chronos-journey", "chronos-checkout"],
    "customfield_10001": "CheckoutConversion > 75%",
    "customfield_10002": "product-checkout-team"
  }
}

One Story per Step:

{
  "fields": {
    "project": { "key": "ECOM" },
    "summary": "ProvideShipping",
    "description": "Action: Submits shipping address form\n\nExpectation: System validates address and calculates available shipping methods and taxes\n\nOutcome: TransitionTo(ShippingMethodsDisplayed)",
    "issuetype": { "name": "Story" },
    "parent": { "key": "ECOM-123" },
    "labels": ["chronos-step", "chronos-checkout"],
    "acceptance": "- System validates address\n- System calculates shipping methods\n- System calculates taxes\n- State transitions to ShippingMethodsDisplayed"
  }
}

Feature Support

Advanced Features

Parent/Child Relationships:

• Epic contains all stories for a journey
• Variant steps link to main epic

Labels:

• chronos-journey on epics
• chronos-step on stories
• chronos-variant-{name} on variant stories
• Compliance framework labels (e.g., gdpr, pci-dss)

Version Control:

• Generator tracks previously imported tickets
• Updates existing tickets on re-import (based on summary + epic)
• Creates diff report showing changes

Gherkin/Cucumber Generator

Generates .feature files for behavior-driven development (BDD) testing.

Configuration

{
  "projections": {
    "gherkin": {
      "plugin": "cucumber",
      "output": "./features",
      "config": {
        "language": "en",
        "indentSize": 2,
        "includeVariants": true,
        "stepFormat": "imperative",
        "tagging": {
          "journey": true,
          "compliance": true,
          "kpi": false
        }
      }
    }
  }
}

Generated Output

One Feature per Journey:

@journey:GuestCheckout @compliance:pci-dss
Feature: GuestCheckout
  As a Customer
  I want to complete checkout without logging in
  So that I can quickly purchase items

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

  @success @kpi:CheckoutConversion
  Scenario: Successful guest checkout
    When Actor submits shipping address form
    Then System validates address and calculates available shipping methods and taxes
    And System transitions to ShippingMethodsDisplayed

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

    When Actor clicks 'Place Order'
    Then Order is created with status PAID and confirmation email is queued
    And System transitions to OrderConfirmed
    And OrderPlacedEvent is emitted
    And PaymentProcessedEvent is emitted

  @variant:PaymentDeclined
  Scenario: Payment declined during checkout
    Given Actor has provided shipping and payment details
    When Payment gateway returns declined status
    Then System displays payment declined message with retry option
    And System returns to ChoosePayment step

Step Mapping

Feature Support

Customization

Step Formats:

Imperative (default):

When Actor submits shipping address form
Then System validates address

Declarative:

When shipping address is submitted
Then address is validated

Tags:

• @journey:{name} - Journey identifier
• @compliance:{framework} - Compliance framework
• @variant:{name} - Variant identifier
• @success / @failure - Outcome type
• @slo - Performance constraint present

OpenTelemetry Generator

Generates YAML or JSON event schemas for OpenTelemetry instrumentation.

Configuration

{
  "projections": {
    "telemetry": {
      "plugin": "opentelemetry",
      "output": "./schemas/otel",
      "config": {
        "format": "yaml",
        "includeSpans": true,
        "includeMetrics": true,
        "includeTraceContext": true,
        "namingConvention": "snake_case"
      }
    }
  }
}

Generated Output

Event Schemas:

# PaymentMethodSelectedEvent.yaml
event:
  name: payment_method_selected
  description: Emitted when customer selects payment method in checkout
  source_journey: GuestCheckout
  source_step: ChoosePayment

  attributes:
    - name: journey_name
      type: string
      required: true
      value: GuestCheckout
      description: Name of the journey that emitted this event

    - name: step_name
      type: string
      required: true
      value: ChoosePayment
      description: Name of the step that emitted this event

    - name: actor
      type: string
      required: true
      value: Customer
      description: Actor performing the journey

    - name: payment_method
      type: string
      required: true
      description: Selected payment method (e.g., Credit Card, PayPal)

    - name: session_id
      type: string
      required: true
      description: User session identifier

    - name: timestamp
      type: timestamp
      required: true
      description: Event timestamp in ISO 8601 format

  span_context:
    trace_id: required
    span_id: required
    parent_span_id: optional

Span Definitions (when includeSpans: true):

# GuestCheckout_span.yaml
span:
  name: guest_checkout_journey
  description: Traces the complete guest checkout journey
  kind: SERVER

  attributes:
    - name: journey.name
      type: string
      value: GuestCheckout

    - name: journey.actor
      type: string
      value: Customer

    - name: journey.kpi
      type: string
      value: CheckoutConversion

    - name: journey.kpi_target
      type: string
      value: ">75%"

  events:
    - PaymentMethodSelectedEvent
    - OrderPlacedEvent
    - PaymentProcessedEvent

  child_spans:
    - name: provide_shipping_step
      events: []
    - name: choose_payment_step
      events: [PaymentMethodSelectedEvent]
    - name: place_order_step
      events: [OrderPlacedEvent, PaymentProcessedEvent]

Metrics (when includeMetrics: true):

metrics:
  - name: journey_step_duration
    description: Duration of each journey step
    unit: milliseconds
    type: histogram

    attributes:
      - journey_name
      - step_name
      - actor

  - name: journey_completion_rate
    description: Percentage of journeys completed successfully
    unit: percentage
    type: gauge

    attributes:
      - journey_name
      - kpi

  - name: slo_violations
    description: Count of SLO violations by step
    unit: count
    type: counter

    attributes:
      - journey_name
      - step_name
      - slo_latency

Feature Support

Trace Context Propagation

Generated schemas include W3C Trace Context headers:

headers:
  - name: traceparent
    format: "00-{trace-id}-{span-id}-01"
    required: true

  - name: tracestate
    format: "key1=value1,key2=value2"
    required: false

Diagram Generators

Mermaid Generator

Generates Mermaid diagrams for state transitions and sequence flows.

Configuration

{
  "projections": {
    "diagrams": {
      "plugin": "mermaid",
      "output": "./docs/diagrams",
      "config": {
        "theme": "default",
        "diagramTypes": ["stateDiagram", "sequenceDiagram"],
        "includeVariants": true
      }
    }
  }
}

State Diagram Output

stateDiagram-v2
    [*] --> ProvideShipping: Journey Start

    ProvideShipping --> ShippingMethodsDisplayed: Address Validated
    ProvideShipping --> ProvideShipping: Invalid Address

    ShippingMethodsDisplayed --> ChoosePayment: Shipping Selected

    ChoosePayment --> PlaceOrder: Payment Entered
    ChoosePayment --> ChoosePayment: Payment Declined

    PlaceOrder --> OrderConfirmed: Order Created (SLO: 2s p99)

    OrderConfirmed --> [*]: Success

    note right of PlaceOrder
        Risk: Payment gateway timeout
        Telemetry: OrderPlacedEvent, PaymentProcessedEvent
    end note

Sequence Diagram Output

sequenceDiagram
    participant Customer
    participant System
    participant PaymentGateway

    Note over Customer,System: Journey: GuestCheckout

    Customer->>System: Submits shipping address form
    System->>System: Validates address
    System->>System: Calculates shipping methods
    System-->>Customer: ShippingMethodsDisplayed

    Customer->>System: Selects Credit Card
    System->>System: Validates card format
    System->>System: Emits PaymentMethodSelectedEvent

    Customer->>System: Clicks 'Place Order'
    System->>PaymentGateway: Authorize payment
    PaymentGateway-->>System: Authorization code
    System->>System: Create Order (status: PAID)
    System->>System: Emit OrderPlacedEvent
    System-->>Customer: OrderConfirmed

PlantUML Generator

Generates PlantUML diagrams with richer styling options.

Configuration

{
  "projections": {
    "diagrams": {
      "plugin": "plantuml",
      "output": "./docs/diagrams",
      "config": {
        "skinparam": {
          "backgroundColor": "#FEFEFE",
          "actorBorderColor": "#22D3EE"
        },
        "diagramTypes": ["activity", "sequence", "state"]
      }
    }
  }
}

Activity Diagram Output

@startuml GuestCheckout
start
:Customer navigates to checkout;

if (Cart is not empty?) then (yes)
  if (Actor is not logged in?) then (yes)
    :Submits shipping address form;
    :System validates address;
    :System calculates shipping and taxes;
    :ShippingMethodsDisplayed;

    :Selects Credit Card;
    :System validates card format;
    note right: Emit PaymentMethodSelectedEvent

    :Clicks 'Place Order';
    note right
      SLO: 2s p99
      Risk: Payment gateway timeout
    end note
    :Create Order (status: PAID);
    :Emit OrderPlacedEvent;
    :OrderConfirmed;
    stop
  else (no)
    :Redirect to login;
    stop
  endif
else (no)
  :Display empty cart message;
  stop
endif
@enduml

Documentation Generator

Generates HTML or Markdown documentation sites from Chronos specifications.

Configuration

{
  "projections": {
    "docs": {
      "plugin": "html-docs",
      "output": "./docs/requirements",
      "config": {
        "title": "E-Commerce Requirements",
        "theme": "modern",
        "search": true,
        "includeIndex": true,
        "includeDiagrams": true,
        "includeTraceability": true,
        "tableOfContents": true
      }
    }
  }
}

Generated Site Structure

docs/requirements/
├── index.html                     # Overview with journey index
├── journeys/
│   ├── GuestCheckout.html        # Full journey documentation
│   ├── UserRegistration.html
│   └── ProcessPayment.html
├── actors/
│   ├── Customer.html
│   ├── PaymentGateway.html
│   └── index.html
├── entities/
│   ├── Order.html
│   ├── OrderItem.html
│   └── index.html
├── diagrams/
│   ├── GuestCheckout-state.svg
│   ├── GuestCheckout-sequence.svg
│   └── index.html
├── traceability/
│   ├── kpi-to-journeys.html      # KPI → Journeys mapping
│   ├── compliance-matrix.html    # Compliance requirements coverage
│   └── actor-journey-matrix.html
├── search.js                      # Client-side search index
└── assets/
    ├── styles.css
    └── search-index.json

Journey Page Example

GuestCheckout.html:

• Journey metadata (KPI, owner, compliance tags)
• Actor description
• Preconditions list
• Steps (expandable with action/expectation/telemetry)
• Variants (collapsible sections)
• Outcomes (success/failure)
• State diagram (embedded SVG)
• Sequence diagram (embedded SVG)
• Traceability links (related entities, APIs, components)
• Generated artifacts (links to Jira epic, Gherkin file)

Search Features

• Full-text search across all journeys, actors, entities
• Filter by compliance framework
• Filter by KPI
• Filter by owner/team
• Autocomplete suggestions

Traceability Matrix

KPI → Journeys:

Compliance Coverage:

Custom Generator Development

Generator SPI

Implement the ChronosGenerator interface:

interface ChronosGenerator {
  name: string
  version: string

  validate(config: GeneratorConfig): ValidationResult

  generate(
    model: ChronosSemanticModel,
    config: GeneratorConfig
  ): GeneratedArtifacts

  postProcess?(artifacts: GeneratedArtifacts): GeneratedArtifacts

  publish?(artifacts: GeneratedArtifacts, config: PublishConfig): PublishResult
}

interface ChronosSemanticModel {
  journeys: Journey[]
  actors: Actor[]
  entities: Entity[]
  policies: Policy[]
  imports: Import[]
}

interface GeneratedArtifacts {
  files: GeneratedFile[]
  metadata: ArtifactMetadata
}

interface GeneratedFile {
  path: string
  content: string
  encoding: 'utf-8' | 'base64'
}

Example: Custom Confluence Generator

export class ConfluenceGenerator implements ChronosGenerator {
  name = 'confluence-pages'
  version = '1.0.0'

  validate(config: GeneratorConfig): ValidationResult {
    const required = ['spaceKey', 'parentPageId', 'credentials']
    const missing = required.filter(key => !(key in config))

    if (missing.length > 0) {
      return {
        valid: false,
        errors: [`Missing required config: ${missing.join(', ')}`]
      }
    }

    return { valid: true }
  }

  generate(
    model: ChronosSemanticModel,
    config: GeneratorConfig
  ): GeneratedArtifacts {
    const files: GeneratedFile[] = []

    for (const journey of model.journeys) {
      const html = this.generateJourneyPage(journey, model)

      files.push({
        path: `${journey.name}.html`,
        content: html,
        encoding: 'utf-8'
      })
    }

    return {
      files,
      metadata: {
        generator: this.name,
        version: this.version,
        timestamp: new Date().toISOString()
      }
    }
  }

  private generateJourneyPage(
    journey: Journey,
    model: ChronosSemanticModel
  ): string {
    const actorData = model.actors.find(a => a.name === journey.actor)

    // Returns HTML string with journey details
    return htmlTemplate
  }

  async publish(
    artifacts: GeneratedArtifacts,
    config: PublishConfig
  ): Promise<PublishResult> {
    const confluence = new ConfluenceClient(config.credentials)

    for (const file of artifacts.files) {
      await confluence.createPage({
        spaceKey: config.spaceKey,
        parentId: config.parentPageId,
        title: file.path.replace('.html', ''),
        body: file.content
      })
    }

    return {
      success: true,
      publishedCount: artifacts.files.length
    }
  }
}

Registering Custom Generators

Via npm package:

{
  "name": "@acme/chronos-generator-confluence",
  "main": "dist/index.js",
  "chronos": {
    "generatorClass": "ConfluenceGenerator"
  }
}

Via local path:

{
  "plugins": {
    "local": ["./generators/confluence-generator"]
  },
  "projections": {
    "confluence": {
      "plugin": "local:confluence-generator",
      "config": { /* ... */ }
    }
  }
}

Feature Support Matrix

Legend:

• ✅ Full support
• ⚠️ Partial support (via annotations or notes)
• ❌ Not supported

Best Practices

Multi-Target Generation

Generate multiple formats simultaneously for complete coverage:

{
  "projections": {
    "jira": { "plugin": "jira-cloud", /* ... */ },
    "gherkin": { "plugin": "cucumber", /* ... */ },
    "telemetry": { "plugin": "opentelemetry", /* ... */ },
    "diagrams": { "plugin": "mermaid", /* ... */ },
    "docs": { "plugin": "html-docs", /* ... */ }
  }
}

Version Control Artifacts

Commit generated artifacts to Git for traceability:

chronosc build
git add artifacts/ features/ docs/
git commit -m "chore: regenerate artifacts from Chronos specs"

CI/CD Integration

GitHub Actions:

name: Generate Chronos Artifacts
on:
  push:
    paths:
      - 'requirements/**/*.chronos'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g @genairus/chronos-cli
      - run: chronosc build
      - run: git add artifacts/ features/
      - run: git commit -m "chore: regenerate from Chronos"
      - run: git push

Troubleshooting

Issue: Generator fails with "missing required config"

Solution: Check chronos-build.json for required fields:

{
  "projections": {
    "jira": {
      "config": {
        "projectKey": "REQUIRED",
        "issueTypeEpic": "REQUIRED"
      }
    }
  }
}

Issue: Generated Gherkin fails Cucumber validation

Solution: Ensure all steps follow Given/When/Then pattern:

• Preconditions → Given
• Actions → When
• Expectations → Then

Issue: OpenTelemetry events not appearing in traces

Solution: Verify instrumentation code emits events with exact names from generated schemas:

// Generated schema: PaymentMethodSelectedEvent
span.addEvent('payment_method_selected', {
  journey_name: 'GuestCheckout',
  step_name: 'ChoosePayment',
  payment_method: 'Credit Card'
})

For more information, see:

• Chronos Documentation
• Generator SPI Reference
• Community Generators