Specification

Cabinet File Format

A cabinet is a directory on disk. This page documents every file that makes up a cabinet — the identity file, agent personas, scheduled jobs, and knowledge base.

Overview

Directory structure

Every cabinet directory must contain these files. Child cabinets are nested subdirectories that also contain a .cabinet file.

required structure

my-cabinet/
  .cabinet              # identity & metadata (YAML, no extension)
  .cabinet-state/       # runtime state directory (gitkeep'd)
  .agents/              # AI team members
    ceo/persona.md      #   agent persona (markdown + YAML frontmatter)
    cto/persona.md
  .jobs/                # scheduled automations
    weekly-brief.yaml   #   job definition (YAML)
  index.md              # entry point (markdown + YAML frontmatter)
  company/              # knowledge base (any markdown/CSV files)
  marketing/            # child cabinet (has its own .cabinet file)
    .cabinet
    .agents/
    .jobs/
    index.md

.cabinet

Identity file

The .cabinet file is YAML with no file extension. It declares the cabinet's identity, version, and relationship to its parent. Every cabinet directory must have one.

Root cabinet

.cabinet

schemaVersion: 1
id: text-your-mom-root
name: Text Your Mom
kind: root
version: 0.1.0
description: Relatable B2C app company cabinet.
entry: index.md

Child cabinet with parent context

app-development/.cabinet

schemaVersion: 1
id: text-your-mom-app-development
name: App Development
kind: child
version: 0.1.0
description: Product, engineering, QA, and release cabinet.
entry: index.md

parent:
  shared_context:
    - /company/strategy/index.md
    - /company/goals/index.md

access:
  mode: subtree-plus-parent-brief

Root cabinet with attribution

career-ops/.cabinet

schemaVersion: 1
id: career-ops-root
name: Career Ops
kind: root
version: 0.1.0
description: >
  AI-powered job search command center.
entry: index.md
attribution:
  source: https://github.com/santifer/career-ops
  author: Santiago Fernandez de Valderrama (@santifer)
  license: MIT

Fields

Field	Required	Description
schemaVersion	yes	Schema version number. Currently 1.
id	yes	Unique identifier for this cabinet (kebab-case).
name	yes	Human-readable display name.
kind	yes	"root" for top-level cabinets, "child" for nested ones.
version	yes	Semantic version string.
description	yes	One-line description of the cabinet.
entry	yes	Path to the markdown entry point (usually index.md).
parent	no	Parent relationship. Contains shared_context (list of files visible from parent).
access	no	Access control. mode defines visibility scope (e.g. subtree-plus-parent-brief).
attribution	no	Credit for the original source: source URL, author, license.

.agents/

Agent personas

Each agent lives in its own directory under .agents/<slug>/persona.md. The file uses YAML frontmatter for structured fields and markdown body for the agent's persona and instructions.

CEO agent persona

.agents/ceo/persona.md

---
name: CEO
slug: ceo
emoji: "🎯"
type: lead
department: leadership
role: Strategic leadership, cross-cabinet coordination
heartbeat: "0 9 * * 1-5"
budget: 100
active: true
focus:
  - strategy
  - prioritization
  - company-rhythm
tags:
  - leadership
  - strategy
---

# CEO Agent

You are the CEO of Text Your Mom.
Your job is to keep the whole company aligned around
one simple truth: we are building the tiny, emotionally
intelligent app that helps people stop neglecting the
people they love.

Frontmatter fields

Field	Required	Description
name	yes	Display name for the agent.
slug	yes	Directory name and unique identifier (kebab-case).
emoji	no	Visual identifier emoji.
type	yes	"lead" for team leads, "specialist" for individual contributors.
department	no	Organizational grouping (e.g. leadership, engineering, marketing).
role	yes	One-line role description.
heartbeat	no	Cron schedule for periodic check-ins (e.g. "0 9 * * 1-5" for weekdays at 9am).
budget	no	Relative token budget from 0-100. Higher means more context per run.
active	no	Whether the agent is active. Defaults to true.
focus	no	List of focus area tags.
tags	no	Classification tags for filtering.

The markdown body is the agent's persona — its system prompt. Write it in second person ("You are the CEO") and describe what the agent should care about, how it should behave, and what success looks like.

.jobs/

Scheduled jobs

Jobs are YAML files in the .jobs/ directory. Each job is a scheduled automation owned by an agent — think of them as the meetings and recurring workflows of your AI team.

Weekly executive brief

.jobs/weekly-executive-brief.yaml

id: weekly-executive-brief
name: Weekly Executive Brief
description: >
  Creates the weekly leadership brief covering
  growth, product risks, and next decisions.
ownerAgent: ceo
enabled: true
schedule: "0 9 * * 1"
prompt: |-
  Review the company strategy, goals, KPI pages,
  and all active child cabinet summaries.
  Write a sharp weekly executive brief that includes:
  - what changed this week
  - the biggest growth or retention signal
  - the top product risk
  - one decision leadership should make next

Fields

Field	Required	Description
id	yes	Unique identifier for the job (kebab-case).
name	yes	Human-readable display name.
description	no	What the job does.
ownerAgent	yes	Slug of the agent that runs this job. Must match an agent in .agents/.
enabled	yes	Whether the job is active.
schedule	yes	Cron expression (e.g. "0 9 * * 1" for Mondays at 9am).
prompt	yes	The prompt the agent executes when the job fires.

index.md

Entry point

The entry point markdown file is referenced by the entry field in .cabinet. It uses YAML frontmatter for metadata and describes the cabinet's purpose.

Cabinet entry point

index.md

---
title: Text Your Mom
created: '2026-04-11T00:00:00Z'
tags:
  - example
  - b2c
  - company
  - cabinet
order: 1
---

# Text Your Mom

Text Your Mom is a playful consumer app that helps
people stay close to family and friends by nudging
them to reply, check in, and keep tiny relationship
promises.

## Company Modules

- [[company/strategy]]
- [[company/goals]]
- [[marketing]]
- [[app-development]]

.cabinet-state/

Runtime state

The .cabinet-state/ directory is reserved for runtime state — logs, caches, ephemeral data generated by agents and jobs. In templates, keep it empty with a .gitkeep.

.cabinet-state/

.cabinet-state/
  .gitkeep              # keep the directory in version control
  # runtime files appear here when agents run

Nesting

Cabinet tree

Cabinets nest. A root cabinet can contain child cabinets, which can contain their own children. Each child is a self-contained operating unit that inherits shared context from its parent.

Text Your Mom — 1 root + 3 children, 16 agents

tree

text-your-mom/                    # root cabinet
  .cabinet                         # kind: root
  .agents/ceo, coo, cfo, cto      # 4 root agents
  .jobs/                           # root jobs

  marketing/
    reddit/                        # child cabinet
      .cabinet                     # kind: child
      .agents/growth-marketer, researcher, copywriter, data-analyst

    tiktok/                        # child cabinet
      .cabinet                     # kind: child
      .agents/trend-scout, script-writer, image-creator, post-optimizer

  app-development/                 # child cabinet
    .cabinet                       # kind: child
    .agents/product-manager, cto, qa, devops

Shared context — child cabinets declare which parent files they can see via parent.shared_context. This lets a marketing team read the company strategy without having access to financial data.

Transposition

From org chart to file tree

A cabinet maps the three pillars of a human organization onto plain files. This is the core insight — everything a team needs is already representable as directories and text.

Human Organization	Cabinet Equivalent	Location
People — employees, roles	Agents— personas, heartbeats	.agents/<slug>/persona.md
Meetings — standups, reviews	Jobs— cron schedules, prompts	.jobs/<name>.yaml
Knowledge — tribal, institutional	Files— markdown, CSV, data	.md, .csv in the tree

Conventions

Naming & rules

Directory names use kebab-case

text-your-mom, app-development, career-ops

.cabinet files are YAML with no file extension

.cabinet (not .cabinet.yaml)

Agent personas are markdown with YAML frontmatter

.agents/ceo/persona.md

Jobs are YAML files with .yaml extension

.jobs/weekly-brief.yaml

Every cabinet must have these files

.cabinet, .agents/, .jobs/, index.md, .cabinet-state/.gitkeep

Child cabinets are subdirectories with their own .cabinet file

marketing/reddit/.cabinet (kind: child)

.cabinet-state/ is for runtime only

Keep empty with .gitkeep in templates