Core Concepts

matic is built on a small set of interlocking ideas that define how organisations, agents, and work are structured. These concepts explain how org state is represented, how work moves through the system, and how identities, boundaries, and governance are enforced. Every higher-level feature in the documentation traces back to one or more of the primitives described here, so this section is the foundation for configuring a matic org correctly, reasoning about agent behaviour, and diagnosing operational problems.

Charter

Charter defines the governing document of an org, including purpose, admissibility criteria, and constraints that gate every project, agent, and policy decision.

Filesystem as Database

Filesystem as Database explains how all operational state is encoded as files and directories in a git repository, with no separate database, so every org entity is readable, diffable, and recoverable with standard tooling.

Git-Native Persistence

Git-Native Persistence describes Git as the persistence and collaboration layer, where state changes are commits, contributions flow through pull requests, and every run captures a reproducible snapshot of org state.

Handles and Addressing

Handles and Addressing covers the kebab-case handles used as canonical identifiers for every org, project, team, and agent across the filesystem, CLI, and all channel routing.

Scopes

Scopes defines the four hierarchical scopes — org, project, team, and agent — that determine where primitives live, what is visible to whom, and how configuration cascades.

Work Lifecycle

Work Lifecycle describes the end-to-end process by which signals become results through Ingestion, Processing, and Iteration, including phase transitions, resolution levels, and the mandatory learning loop.

Work Model

Work Model explains the atomic execution primitives — Signals, Activations, Tasks, Work Items, Work Contracts, and Runs — and how they relate during planning and execution.