Filesystem as Database

matic stores all operational state — agents, projects, decisions, artifacts, memory — as files and directories in a git repository. There is no proprietary database: a human with a text editor and git can inspect, modify, and recover any part of the system. This section explains the filesystem-first model, the repository layouts that encode org, project, and agent state, and the conventions that let matic enforce scope and auditability through files alone.

Overview

overview.md — The philosophy behind filesystem-first design: why every primitive is a file, how git provides audit, reproducibility, and human-agent parity, and what that means in practice for operators.

Org Directory Layout

org-directory-layout.md — The top-level structure of an org repository: charter.md, .matic/ runtime config, and the canonical placement of agents/, projects/, teams/, archetypes/, library/, decisions/, feeds/, and audit/.

Project Directory Layout

project-directory-layout.md — The directory structure under projects/<slug>/: brief, goals, backlog, milestones, team roster, shared workspace repos, library, decisions, and feeds.

Agent Directory Layout

agent-directory-layout.md — The per-agent directory structure under agents/<handle>/: profile, experience, probes, workspace repos, library, routines, memory, decisions, and work-pile — and what each directory's immutability rules are.

Frontmatter and Markdown

frontmatter-and-markdown.md — How matic uses YAML frontmatter and markdown bodies across all primitive types: mandatory fields, lifecycle status values, and the schema conventions for decisions, probes, work contracts, and run records.

Workspace and Artifacts

workspace-and-artifacts.md — The lifecycle of work assets from staging through delivery: how inbound signal payloads are staged, how wip-assets/ become artifacts/, and how verified outputs move to delivery/ or are promoted to the library.

Worktrees and Repos

worktrees-and-repos.md — How agents use git worktrees for task isolation, the hard constraint that shared-surface writes require pull requests, and how the packages/fs and packages/git layers enforce commit scope.