Org Filesystem Layout

An org in matic is a git repository on disk — every agent, team, project, decision, and policy is a file or directory you can read, diff, and branch with no specialised tooling. This section documents the canonical layout produced by matic init: where each primitive lives, how the runtime control plane is isolated from operational state, and the naming rules that make handles addressable across the CLI, channels, and frontmatter.

Org Root

The repository directory itself — anchor for the runtime, source of truth for all state, and the only path the Daemon and CLI need to bootstrap.

.matic/ Directory

The runtime control plane — YAML configuration, the Daemon socket, dead-letter queue, staged signals, and org-level decision records.

agents/ Directory

Persistent AI actors with durable identity — profiles, experience logs, probes, private workspaces, routines, memory, and work-piles, with Auto Matic always present as the org's Chief Agent.

archetypes/ Directory

Versioned blueprints used to spawn new agents — personas, skills, and default probe profiles, captured from experienced agents or hand-authored.

teams/ Directory

Project-scoped agent compositions and reusable Squad Templates — rosters, shared workspaces, and team-local routines, memory, and decisions.

projects/ Directory

Bounded goal-directed bodies of work — briefs, backlogs, milestones, staffing, project-owned repos, and the workspace where assets move from WIP to delivery.

Naming Conventions

Handle rules and file-naming patterns — kebab-case identifiers used uniformly across @mentions, CLI flags, directory names, and frontmatter references.