Why SysMARA Exists

AI agents see files, not architecture. That is the root of the problem.

The Problem: Hidden Architecture

In a conventional codebase, architecture lives in the heads of senior engineers. It is encoded in naming conventions, directory structures, code review norms, wiki pages that drift out of date, and tribal knowledge passed down through pairing sessions. Humans absorb these patterns over weeks and months. AI agents do not.

When an AI agent works on a traditional codebase, it sees files. It can parse syntax, resolve imports, and trace function calls. What it cannot see:

• Which modules are allowed to depend on which other modules
• Which state transitions are legal for a domain object
• Which business rules must hold across the entire system, not just within a single function
• Which fields are safe to change and which are load-bearing contracts consumed by external systems
• What the downstream impact of a schema change will be across module boundaries

The result is predictable: AI-generated code that compiles, passes type checks, and violates business rules. The code is syntactically correct but architecturally wrong. It introduces a subscription state that the billing module cannot handle. It adds a field that breaks an invariant enforced three modules away. It creates a circular dependency between services that were deliberately kept separate.

The Cost of Implicit Conventions

Implicit architecture was manageable when humans wrote all the code and reviewed every change. It becomes a liability when AI agents generate or modify significant portions of a codebase.

Consider what happens today when an AI agent is asked to "add a trial period to subscriptions":

1. The agent finds the Subscription model and adds a trial_ends_at field
2. It updates the creation flow to set the field
3. It misses the billing module's assumption that all active subscriptions have a valid payment method
4. It does not know that the analytics pipeline expects status transitions to follow a specific state machine
5. It does not update the cancellation capability's preconditions, which now have an unhandled state
6. The code compiles. Tests pass (because the tests also do not encode these constraints). The bug ships.

This is not an AI failure. It is an architecture failure. The architecture did not make its constraints available in a form the agent could consume.

What Changes with Explicit Architecture

SysMARA inverts the problem. Instead of architecture living implicitly in code and conventions, it is declared explicitly in machine-readable YAML specs. Every entity, capability, policy, invariant, module boundary, and cross-module flow is a formal declaration that both humans and AI agents can read, query, and reason about.

With SysMARA, the same "add a trial period" task looks different:

1. The agent reads the Subscription entity spec and sees the status field has a closed enum: [active, paused, cancelled, past_due]. Adding a trial state means updating this enum.
2. It runs sysmara impact Subscription.status and sees every capability, policy, and flow that depends on this field.
3. It reads the billing module boundary spec and sees that Subscription is owned by billing, so any changes require checking billing-specific invariants.
4. It reads the CancelSubscription capability's preconditions and knows it needs to handle the new trial state.
5. It runs sysmara validate after making changes and catches any spec violations before generating a single line of implementation code.

The architecture is no longer a gate that only humans can pass through. It is data that any consumer — human or machine — can query.

The AI System Graph

At the center of SysMARA is the AI System Graph: a directed, queryable graph where entities are nodes and capabilities, policies, and flows are edges. This graph is the single source of truth for your system's architecture.

The graph answers questions that are impossible to answer by reading source code alone:

• What touches this entity? Every capability that reads or writes it, every policy that constrains it, every flow that includes it.
• What breaks if this field changes? The full downstream impact, across module boundaries, including capabilities with preconditions that reference the field.
• What are the legal state transitions? Derived from the enum declarations and the preconditions/postconditions of every capability that modifies the field.
• Where are the module boundaries? Which entities and capabilities belong to which modules, and which cross-module dependencies are explicitly allowed.

The graph is generated from your specs by sysmara graph and is available in JSON format (--json) for programmatic consumption. AI agents read the graph to understand your architecture before generating or modifying any code.

The Three Pillars

SysMARA is built on three mechanisms that work together:

1. AI System Graph

The graph is the queryable representation of your architecture. Entities, capabilities, policies, invariants, modules, and flows are all nodes and edges in a single connected structure. The graph is deterministic: the same specs always produce the same graph. It is the contract between your architecture and any consumer of that architecture.

2. Capability Compiler

The compiler reads your capability specs and produces implementation scaffolds that structurally match the declared contracts. Preconditions become guard clauses. Postconditions become assertions. Error cases become typed error variants. The compiler does not generate business logic — that is where human judgment (or supervised AI generation) belongs. It generates the structural envelope that ensures the implementation cannot violate the declared contract.

3. Change Protocol

The change protocol governs how specs evolve over time. When you modify a spec, the protocol requires impact analysis (sysmara impact), change planning (sysmara plan create), boundary checking (sysmara check boundaries), and validation (sysmara validate). This is not optional process — it is enforced by the toolchain. Every spec change has a traceable, validated path from intent to implementation.

What SysMARA Is Not

SysMARA is not a code generator that writes your application for you. It does not replace your runtime framework, your database, or your deployment pipeline. It sits upstream of all of those. SysMARA defines what your system does and what constraints it must satisfy. The implementation of how it does those things is still your domain — SysMARA just ensures that the how never violates the what.

SysMARA is also not an AI product in the marketing sense. It does not use LLMs internally. It does not call an API. It is a deterministic toolchain that produces machine-readable architecture artifacts. The "AI-native" in its positioning means that the architecture is designed to be consumed by AI agents, not that AI is used to produce it.

Next Steps

Read the Philosophy page to understand the design principles behind these decisions, or jump to the Quick Start to build a working system in five minutes.