Building a Filesystem-First AI Organization Runtime in Python

The first implementation move is deliberately plain: put the organization on disk.

Matic's ontology starts from a strong position. The filesystem is the primary database, git is the persistence and collaboration layer, and markdown is the universal medium for operational state. The Python MVP should make that belief visible before it tries to look intelligent.

What the first slice includes

The foundation creates the core domain language:

• Org: the root operational scope.
• Agent: a persistent actor, not a stateless prompt call.
• Workflow and Stage: a readable path through work.
• Task: a bounded body of work.
• Run: one execution attempt for a task.
• Artifact: the tangible evidence produced by work.

That language is intentionally smaller than the full ontology. It does not yet implement staffing, channels, policy enforcement, budgets, daemon scheduling, or full lifecycle automation. Those concepts remain part of the north star, but M0 starts by proving that durable operational state can be inspected without special tooling.

Why the filesystem comes first

For AI work to become operational, state needs to survive the end of a chat session. The MVP org scaffold writes human-readable files and predictable directories:

<org>/
  charter.md
  .matic/
    config.yaml
    org.json
    queue/
    journal/
  agents/
    auto-matic/
      profile.md
      workspace/
      memory/
      work-pile/
  workspace/
  library/
  routines/
  decisions/
  policies/
  feeds/
  audit/

This is not the full canonical layout yet. It is the first coherent subset. A human can open it, diff it, commit it, and recover it. An agent can do the same.

The Agent Runtime boundary

The MVP also keeps a conceptual boundary intact: matic is not the Agent Runtime.

Agent Runtimes such as Codex, Claude Code, Gemini CLI, or other execution environments are where model-native work happens. Matic coordinates identity, state, work, history, and validation around those runtimes. That distinction matters early because it prevents the Python MVP from collapsing into a single chatbot wrapper.

In the MVP foundation, the boundary is represented in the domain and filesystem. Later work adds the adapter and runtime integration.

What success looks like

The first implementation succeeds when the repo can:

• Create a minimal org scaffold.
• Persist the org record.
• Represent agents, workflows, tasks, runs, and artifacts.
• Enqueue and move tasks through a basic lifecycle.
• Append operational journal entries.
• Expose the foundation through a simple CLI.

The point is not sophistication. The point is that every later capability has somewhere durable and legible to live.