continuum

crystal cli agplv3 ameba dag Crystal-lang podman sphinx flaw RAG gitops multi-agent story-engine

Deterministic state machine and multi-agent narrative execution pipeline with GitOps cascades, RAG vector memory, and asynchronous asset synthesis.

Deterministic state machine and multi-agent narrative execution pipeline with GitOps cascades, RAG vector memory, and asynchronous asset synthesis.

GitLab Project Metadata:

Description: Deterministic state machine and multi-agent narrative execution pipeline with GitOps cascades, RAG vector memory, and asynchronous asset synthesis.

Topics / Tags: crystal, crystal-lang, story-engine, multi-agent, dag, gitops, rag, cli, podman, ameba, flaw, sphinx, agplv3

Overview

Continuum is a compiled, high-performance deterministic story engine and multi-agent execution pipeline written in Crystal. It acts as an immutable physics orchestrator, semantic memory manager, and Git repository controller, coordinating a Directed Acyclic Graph (DAG) of LLM subagents for continuity analysis, research, narrative drafting, asynchronous visual asset synthesis, and adversarial quality assurance.

Key Highlights

Deterministic State Machine: Mutex-protected YAML/JSON state management with path-sandboxed, delta-aware mutations (add, subtract, set) committed only after passing adversarial QA.
Multi-Agent Execution DAG: Coordinates Continuity, Researcher (Google Search + RAG vector cosine similarity), Writer, Asset Synthesis, and Auditor agents with dynamic temperature escalation.
GitOps Retroactive Cascades: Treats historical timeline divergence like a Git rebase—branching into isolated cascade-<slug> branches, restoring state checkpoints, and recompiling downstream chapters.
Asynchronous Asset Synthesis: Fiber-based background rendering pipeline synchronized via WaitGroup barriers for local diffusion workflows (sdcli.py / ComfyUI).
Zero-Defect Quality Gates: Enforces 100% spec verification, Ameba static analysis, Flaw SAST security scanning, and cRSTLint documentation validation.

Quickstart

Prerequisites

Crystal: >= 1.21.0
Shards: Bundled with Crystal
GNU Make & Git
Podman (optional, for container runs)
cRSTLint (for documentation linting)

Build and Run Locally

# 1. Clone repository
git clone https://gitlab.com/renich/continuum.git
cd continuum

# 2. Setup dependencies and pre-commit hooks
make setup

# 3. Build the binary
make build

# 4. Run application CLI
./bin/continuum --help

Usage Examples

# Initialize a new story workspace
./bin/continuum init my_story
cd my_story

# Generate a narrative scene from timeline or prompt
continuum generate --prompt "Describe the discovery of the monolith."

# Trigger a retroactive multiversal recompilation cascade
continuum cascade --event=slug-of-the-divergence-event

# Validate or format project YAML/JSON state and timeline files
continuum data validate
continuum data format

# Compile master outline from timeline ledger
continuum outline

Running with Podman

# Build container image with Podman
make containers-build

# Run containerized CLI
make containers-run

Build System Targets

The repository includes a comprehensive, standard GNUmakefile:

Target	Description
`make build`	Compiles development binary in `bin/continuum`
`make release`	Builds stripped, optimized production binary
`make static`	Builds static binary using Alpine container in Podman
`make test`	Executes the complete spec test suite (`crystal spec`)
`make lint`	Runs Ameba static analysis and Flaw SAST security scanner
`make doc-check`	Lints all reStructuredText files using `crstlint` and `rstcheck`
`make check`	Aggregates `test`, `lint`, and `doc-check`
`make install`	Installs binary to `$(DESTDIR)$(bindir)` (FHS compliant)
`make install-local`	Installs binary to `~/.local/bin/continuum`
`make containers-build`	Builds rootless container image using Podman
`make clean`	Cleans build artifacts in `bin/`
`make distclean`	Removes dependencies, cache directories, and build outputs

Documentation

Full architectural blueprints, functional specifications, and operational playbooks are maintained under docs/:

Guide	Scope & Highlights	Entry Point
Business Context & Strategy	Stakeholder requirements, ROI objectives, and user personas.	Business Specs
Functional Specifications	Requirements [FUNC-001]–[FUNC-006] and behavioral contracts.	Functional Specs
Technical Architecture	DAG execution pipeline, state mutations, RAG memory, and cascades.	Technical Specs
Release Playbook	SemVer, Keep a Changelog, and GPG-signed GitLab release steps.	Release Procedure
Architecture Decisions (ADRs)	Immutable logs of architectural decisions and trade-offs.	ADR Index
Project Roadmap	Phased milestone tracking and delivery roadmaps.	Project Roadmap
User Guide	Timeline schemas, cascade workflows, and CLI command reference.	User Guide
Crystal API Reference	Compiler-generated API reference.	API Reference