Handles and Addressing

Every entity in matic — orgs, projects, teams, and agents — is identified by a handle: a kebab-case string that doubles as its filesystem path, CLI argument, and @-mention target. Handles are the only identifier used across the system, so naming, scope, and routing all build on the same addressing model. This section explains how handles are formed, how mentions resolve into routing decisions, how direct and group addressing differ, and what happens when a message cannot be delivered.

Overview

Read Overview for the end-to-end addressing model: how a handle becomes a routable target, the relationship between scope and group, and the single-response-owner invariant that governs all conversations.

Handle Format

Read Handle Format for naming rules, uniqueness constraints, and where handles appear, from directory names to frontmatter references to CLI flags.

Scope-Qualified Handles

Read Scope-Qualified Handles to see how scope narrows handle resolution, and how scope context determines which entity a bare handle resolves to when ambiguity exists.

@-Mention Routing

Read @-Mention Routing for the classification and routing pipeline: how @agent-handle triggers direct routing, how @group-handle triggers group resolution, and how unmentioned messages fall through to Auto Matic.

Direct vs. Group Addressing

Read Direct vs. Group Addressing for the two explicit addressing modes — targeting a named agent versus targeting a group — and how each determines the response owner for a session.

Response Ownership

Read Response Ownership for the invariant that every live session has exactly one response owner at any moment, how ownership is assigned during routing, and how it is transferred during handoff.

Dead Letter Queue

Read Dead Letter Queue for what happens when a signal cannot be routed: no matching agent, no eligible group member, or suspended Auto Matic, and how dead-lettered signals are stored, inspected, re-routed, and expired.