Roadmap — SysMARA Framework Development Plan

Current status, what exists today, and what is coming next.

Current Status: v0.7.1

SysMARA is in active early-stage development. The core architecture specification, validation system, database adapter layer, flow execution engine, and AI bootstrap workflow are functional and being used in real projects. The API is not yet stable — breaking changes may occur between minor versions.

What Exists Today

The following features are implemented and tested:

Specification System

  • Six spec types: entities, capabilities, policies, invariants, modules, and flows.
  • YAML-based spec files with Zod schema validation.
  • Recursive file discovery — organize specs in flat directories or nested structures.
  • Scaffolding with sysmara add for all spec types.

Validation and Diagnostics

  • Full cross-validation of all inter-spec references.
  • 30+ diagnostic codes covering duplicates, reference resolution, boundary violations, orphans, safety, and consistency.
  • Module boundary enforcement with depends_on and forbidden_deps.
  • Comprehensive health check via sysmara doctor (9 sections).

Graph and Analysis

  • System graph generation with full relationship mapping.
  • System map generation for AI agent discovery.
  • Impact analysis with BFS traversal (depth 3, bidirectional).
  • Change plan creation and rendering (terminal, markdown, JSON).
  • Capability explanation with sysmara explain.

Runtime

  • Minimal built-in HTTP server (SysmaraServer).
  • Route registration mapping HTTP endpoints to capabilities.
  • Actor extraction and policy enforcement.
  • Built-in /health and /_sysmara/routes endpoints.
  • Structured error hierarchy (SysmaraError, ValidationError, PolicyError, InvariantError).

CLI

  • Full command set: init, add, validate, build, graph, compile, doctor, explain, impact, plan create, plan show, check boundaries.
  • JSON output mode on all commands for tooling integration.

Database Adapter System (v0.3.0)

A pluggable adapter system for connecting entity specs to database backends. Supports multiple ORMs and includes a built-in AI-first ORM.

  • Adapter interface and registry: A DatabaseAdapter interface with generateSchema(), generateMigration(), and generateRepository() methods. Adapters are registered and looked up by name through the adapter registry.
  • Prisma adapter: Generates schema.prisma files from entity specs with model definitions, relation detection, and typed repository classes per capability.
  • Drizzle adapter: Generates TypeScript-first schema.ts table definitions with provider-specific column mappings (PostgreSQL, MySQL, SQLite) and typed repositories.
  • TypeORM adapter: Generates @Entity() decorated TypeScript classes with @Column, @ManyToOne, @PrimaryGeneratedColumn decorators and typed repositories.
  • SysMARA ORM: An AI-first ORM where schema is the system graph, every query is scoped to a capability, invariants are enforced as DB constraints, every operation is logged as structured JSON, and migrations are impact-aware with risk classification. See SysMARA ORM.
  • CLI commands: sysmara db generate, sysmara db migrate, sysmara db status.
  • Configuration: Database adapter settings in the database section of sysmara.config.yaml.

Flow Execution Engine (v0.4.0)

A production-ready flow executor that makes declared flows actually run — not just validate.

  • FlowExecutor: Executes multi-step flows with pluggable capability handlers, context threading between steps, and structured execution records.
  • Saga compensation: On step failure with onFailure: "compensate", runs compensation capabilities in reverse order for all previously completed steps.
  • Retry with exponential backoff: Steps with onFailure: "retry" are retried up to a configurable number of times with exponentially increasing delays.
  • Condition evaluation: Safe recursive descent expression parser (no eval()) for step conditions like context.input.role === "admin".
  • AI-readable execution log: Every execution produces structured JSON records with summaries including success rate, average duration, and recent failures.
  • Flow validation: Validates that all step actions reference existing capabilities before execution.
  • CLI commands: sysmara flow list, sysmara flow validate, sysmara flow run, sysmara flow log.

Scaffold Generator (v0.7.1)

Automatic generation of starter TypeScript implementation files from YAML specs, integrated into the build pipeline.

  • Entity stubs: Typed interfaces with runtime validation helpers from entity specs.
  • Capability handlers: Handler functions with typed I/O imports, policy/invariant TODOs.
  • Policy enforcers: Enforcement functions with condition comments from specs.
  • Invariant validators: Validation functions referencing entity types.
  • Module services: Service classes with method stubs per capability.
  • Safe generation: Files written once, never overwritten on re-run.
  • CLI: sysmara scaffold standalone or integrated into sysmara build (step 5).

Real Database Drivers & Auto-Start (v0.7.0)

Full database connectivity and zero-config server startup — closing the gap from YAML specs to a running HTTP API.

  • Real database drivers: PostgreSQL (pg), MySQL (mysql2), and SQLite (better-sqlite3) as optional peer dependencies. In-memory fallback when no driver is installed.
  • sysmara start command: Parses specs, connects to the database, applies schema (CREATE TABLE IF NOT EXISTS), auto-wires every capability to an HTTP route based on naming conventions, and starts the server. Zero boilerplate.
  • Server entry point generation: sysmara build generates app/server.ts — a standalone runnable entry point that imports all scaffolded handlers and registers routes.
  • ORM lifecycle: connect(), disconnect(), applySchema(), isConnected() — full database connection management.
  • Auto route inference: Capability names map to HTTP methods and paths automatically (e.g., create_user → POST /users, get_user → GET /users/:id).
  • Config parser upgrade: Uses the yaml package instead of a hand-rolled parser, supporting full YAML including nested objects and arrays.

AI Bootstrap Guide (v0.4.10)

A complete protocol for AI agents to turn a single human prompt into a fully working SysMARA project — from npx @sysmara/core init to a running server.

  • BOOTSTRAP.md: Standalone protocol document that AI agents read to understand how to scaffold a complete project from a product description.
  • One-Prompt Workflow: Step-by-step instructions with copy-paste AI prompts for each stage — spec generation, validation, build, implementation, and server startup.
  • Three example projects: Complete generated specs for a SaaS Task Manager (5 entities, 15 capabilities), E-Commerce API (6 entities, 16 capabilities), and Blog Platform (6 entities, 21 capabilities).
  • AI Agent Guide: Documentation explaining SysMARA from an AI agent's perspective, including spec reading order, modification protocol, and the "why this works" philosophy.

What Is Coming Next

The following items are planned. Priorities may shift based on community feedback and real-world usage.

Authentication Middleware Patterns

Reference implementations and patterns for common authentication scenarios: JWT validation, session-based auth, API key authentication, OAuth flows. These would be examples and optional middleware, not built-in authentication.

Status: Planned. Will be released as a separate package or documented patterns.

Plugin and Extension System

A formal plugin API that allows third-party extensions to:

  • Add new spec types beyond the core six.
  • Register custom diagnostic rules.
  • Extend the compiler with new transformation passes.
  • Add new CLI commands.

Status: Early design. The internal architecture already supports this pattern, but a stable public API needs to be defined.

IDE Integrations

Extensions for popular editors that provide:

  • YAML autocompletion for spec files based on Zod schemas.
  • Inline diagnostic display (red squiggles for errors, yellow for warnings).
  • Go-to-definition for spec references (click an entity name in a capability to jump to the entity file).
  • Hover information showing spec details and relationships.

Status: Planned. VS Code extension is the first target.

AI Agent SDK

A dedicated SDK for AI agents to interact with SysMARA projects programmatically. This would provide:

  • Structured API for reading and modifying specs.
  • Impact analysis before making changes.
  • Automatic validation after changes.
  • System map and graph access without CLI invocation.

Status: Planned. The current CLI with --json output serves as an interim solution.

Additional Diagnostic Rules

More diagnostic rules to catch common architectural issues:

  • Detecting overly large modules (too many entities or capabilities).
  • Warning about deep dependency chains.
  • Identifying capabilities that could be split.
  • Detecting naming convention violations.
  • Checking for missing descriptions in specs.

Status: Ongoing. New rules are added regularly.

Performance Benchmarks

Published benchmarks for:

  • Spec parsing speed at various project sizes (10, 100, 1000 specs).
  • Graph construction time.
  • Impact analysis traversal time.
  • Runtime request handling overhead compared to raw Node.js HTTP.

Status: Planned. Internal benchmarks exist but are not yet published.

Production Hardening

Improvements for production use:

  • Structured logging with configurable transports.
  • Metrics export (Prometheus, OpenTelemetry).
  • Rate limiting patterns.
  • Request tracing and correlation IDs.
  • Graceful degradation when specs cannot be loaded.

Status: Planned. The current server handles graceful shutdown but lacks observability features.

How to Influence the Roadmap

SysMARA's roadmap is shaped by real-world usage. If you are using SysMARA and have specific needs:

  • Open an issue on GitHub describing your use case and what you need.
  • Contribute — many of the items above are good candidates for community contributions. See the Contributing guide.
  • Share feedback on what works well and what does not. Even bug reports help prioritize work.

Versioning Policy

While SysMARA is pre-1.0, minor versions (0.x.0) may include breaking changes. Patch versions (0.x.y) are backward-compatible bug fixes. Once SysMARA reaches 1.0, it will follow strict semantic versioning.

Pin your version in package.json and read the changelog before upgrading.