Quick Start

From zero to a validated, graph-connected system in five minutes.

1. Create the Project

Start with a fresh directory and initialize both npm and SysMARA:

mkdir billing-service && cd billing-service
npm init -y
npm install --save-dev @sysmara/core
npx sysmara init

You now have the system/ directory for your specs and sysmara.config.yaml for project configuration.

2. Define an Entity

Entities are the domain objects in your system. Add a subscription entity:

npx sysmara add entity Subscription

Open system/entities/subscription.yaml and define the schema:

entity: Subscription
description: A recurring billing subscription tied to a customer account.
fields:
  id:
    type: uuid
    required: true
  customer_id:
    type: uuid
    required: true
    references: Customer
  plan_id:
    type: uuid
    required: true
    references: Plan
  status:
    type: enum
    values: [active, paused, cancelled, past_due]
    default: active
  current_period_start:
    type: datetime
    required: true
  current_period_end:
    type: datetime
    required: true
  cancelled_at:
    type: datetime
    required: false

This is a full entity declaration. The references field creates edges in the system graph. The enum type with explicit values gives AI agents and the compiler a closed set of valid states to reason about.

3. Add a Capability

Capabilities declare what your system can do. Add one for cancelling subscriptions:

npx sysmara add capability CancelSubscription

Edit system/capabilities/cancel-subscription.yaml:

capability: CancelSubscription
description: Cancel an active subscription with prorated refund calculation.
module: billing

input:
  subscription_id:
    type: uuid
    required: true
  reason:
    type: string
    required: false
  immediate:
    type: boolean
    default: false

output:
  subscription:
    type: Subscription
  refund_amount:
    type: decimal
    nullable: true

preconditions:
  - subscription.status == "active" OR subscription.status == "past_due"
  - subscription exists

postconditions:
  - subscription.status == "cancelled"
  - subscription.cancelled_at != null
  - IF immediate THEN refund_amount >= 0

errors:
  - code: SUBSCRIPTION_NOT_FOUND
    when: subscription does not exist
  - code: ALREADY_CANCELLED
    when: subscription.status == "cancelled"
  - code: REFUND_CALCULATION_FAILED
    when: prorated refund cannot be computed

Notice the structure: preconditions define what must be true before execution, postconditions define what must be true after. Error cases are declared explicitly, not discovered at runtime. An AI agent reading this spec knows exactly what states are legal, what transitions are valid, and what error handling is required.

4. Validate Your Specs

Check that all specs are syntactically valid and internally consistent:

npx sysmara validate

Expected output for valid specs:

Validating specs...
  entities/subscription.yaml .............. OK
  capabilities/cancel-subscription.yaml ... OK

Checking cross-references...
  CancelSubscription -> Subscription ...... OK

0 errors, 0 warnings

If you have a reference to an entity that does not exist (like Customer or Plan above), the validator will warn you about unresolved references. For this quick start, those warnings are expected.

5. Build the System Graph

The system graph connects all your specs into a single queryable structure:

npx sysmara graph

This generates the AI System Graph, a directed graph where entities are nodes and capabilities, policies, and flows are edges. The graph is the primary artifact that AI agents use to understand your system. You can inspect it in JSON format:

npx sysmara graph --json

The JSON output contains nodes (entities), edges (relationships and capabilities), and metadata that an AI agent can parse to answer questions like "what touches the Subscription entity?" or "what are the downstream effects of changing the Plan schema?"

6. Compile Capabilities

The capability compiler translates your declarative specs into implementation scaffolds:

npx sysmara compile

This reads your capability specs, resolves entity references, validates precondition and postcondition consistency, and produces typed implementation stubs in app/. The compiler ensures that the generated code structurally matches your declared contracts.

7. Run Diagnostics

Check the overall health of your spec suite:

npx sysmara doctor

The doctor command checks for:

• Orphaned entities with no capabilities referencing them
• Capabilities with unreachable preconditions
• Circular module dependencies
• Missing error declarations for known failure modes
• Inconsistent field types across entity references

For a two-file project, doctor should report a clean bill of health. As your system grows, this becomes the first command you run after any spec change.

8. Explore Additional Commands

A few more commands worth knowing immediately:

Every command supports --json for machine-readable output. This is how AI agents integrate with SysMARA programmatically.

What You Have Now

In five minutes, you have built a spec-driven system with:

• A typed entity with field-level constraints and explicit state enumeration
• A capability with declared preconditions, postconditions, and error cases
• A validated, cross-referenced specification suite
• A system graph that any AI agent can query
• Compiled implementation scaffolds ready for business logic

Next Steps

For a complete, production-scale example with multiple entities, cross-module flows, and policy enforcement, see the SaaS Billing example.

To understand the principles behind this approach, read Why SysMARA Exists and the Philosophy page.