tropo

How Capsules Work

Every governed file in Tropo is a typed file — and the type is a capsule: a plain-markdown contract that says what an entry must contain, how its status is allowed to change, and what counts as valid.

A capsule is how Tropo turns a folder of markdown into a system you can check, query, and compose. Every entry declares a type:, and that type points at a capsule — a definition that spells out exactly what an entry of that type must contain and how it's allowed to change over its life. The contract is itself a file you can open and read. A script, an agent, and a person all work from the same rules, because the rules are written down in one place.

Why typed files, and not free-form notes

Plain prose can't be governed — you'd have to read every file to know what it is. Typing each file fixes three things at once:

  • Validation by construction. Because every governed file declares a type, one script can walk every file and check it against that type's contract — and tell you exactly which rule a file breaks. (tropo-validate.py does this.)
  • Composition by reference. Typed files point at each other by UID through fields like member_of, governed_by, and depends_on. The result is a graph any tool can walk — the validator, an agent, a board — and they all get the same answer.
  • Lifecycles that compose. Each type carries its own state machine, and they nest: a project can't be done until its tasks are done. High-level state stays honest because it's computed from the work underneath.

Without types, every file is freeform and every reader has to guess. With types, the folder becomes a database that's still just markdown you can open in any editor.

Two shapes — the definition and the instance

Every type in Tropo has exactly two file shapes, and keeping them straight is the whole idea:

  • The capsule definition lives at .tropo/capsules/<name>.capsule.md. It's the contract — the schema, the state machine, the validation rules, the governance. There's one per type.
  • A capsule instance lives at vault/files/<uid>.md. It's a specific file of that type that obeys the contract. There are as many as you've created.

Read the definition once to learn the type; read instances to read the actual work.

STRUCTURE · ONE CONTRACT, MANY INSTANCES task.capsule the definition — the contract schema — required fields state machine — legal changes validation rules governance — who may author governs every vault/files/8f2a4c10.mdthe Customer Summit save-the-date · type: task vault/files/b7e3f582.mdanother task · type: task vault/files/a4f8c291.mdanother task · type: task each instance obeys the one contract

Diagram 1 — one contract, many instances. The definition at .tropo/capsules/task.capsule.md declares what a task is; every task file in the Vault is an instance bound to it. Read the definition once; read instances for the work.

What a definition declares

A capsule definition follows a consistent shape, so once you can read one you can read all of them:

  1. Intent — what the type is for, and what failure it prevents.
  2. Schema — the required frontmatter fields and what they hold (string, list, UID reference, enum).
  3. State Machine — the legal lifecycle for instances. Each type names its own states; there's no universal lifecycle.
  4. Validation Rules — numbered checks that run against every instance ("a task MUST have a requested_by:").
  5. Composes-With — how this type points at others in the graph.

Because the contract is declared, the checking is mechanical. tropo-validate.py walks every governed file, resolves its type, and flags any instance that breaks a rule — by rule number. Governance stops being a matter of vigilance and becomes a property of the system.

MECHANISM · VALIDATION BY CONSTRUCTION the definition declares Intent Schema — required fields State Machine — legal states Validation Rules Composes-With checked against 8f2a4c10.md · an instance ✓ required fields present ✓ status is a legal state ✓ every referenced UID resolves ✗ illegal jump → flagged by rule number tropo-validate.py walks every governed file, resolves its type, and checks each instance against its contract — by rule.

Diagram 2 — the contract makes checking mechanical. A definition's five sections are the rules; the validator resolves each instance's type and checks it, flagging breaks by rule number. Typed files turn governance from vigilance into a property of the system.

One task, the contract in action

Take the Customer Summit save-the-date again. It's an instance of type task, so task.capsule (3289712a) is its contract. The file is just this:

# vault/files/8f2a4c10.md
type: task
status: active                 # one of: new · accepted · active · closed
title: Send the Customer Summit save-the-date to our top 50 accounts
owner: ada
requested_by: <you>
member_of: [9c1d…]             # the "Customer Summit 2026" project

The contract says a task moves new → accepted → active → closed (closing with a resolution), and that some fields are required from the start (requested_by persists the whole way). Set status: active and you've made a legal move; try to jump straight to closed without the contract's conditions and the validator refuses it — by rule. The rules live in the capsule, so the same task behaves the same way whether a person or an agent is driving it.

The capsule library — one root, many types

You don't author most capsules — they ship. A Tropo studio comes with the common types already defined; this public studio carries 60-plus of them. They share one root: core.capsule, the floor every other type extends. Specialized capsules — task, project, decision, agent, release, document — add their own fields and rules on top of it.

COMPOSITION · ONE ROOT, MANY TYPES task project decision agent release document extend core.capsule the root every type extends 60+ types ship with the studio. New ones are rare — author a definition only for a genuinely novel type.

Diagram 3 — one root, many types. core.capsule is the floor; every specialized type extends it and adds its own fields and rules. The library ships with the common types, so most teams never write a new one.

How capsules compose with the other five primitives

  • Vault — every entry in the Vault is an instance of some capsule; the type is what makes it queryable.
  • Agents — agent.capsule (2f8b4e3d) is the capsule that governs agent identities, the same way task.capsule governs tasks.
  • Playbooks — a playbook is a typed entry too; running one produces more typed entries, each checked against its capsule.
  • Channels — events on the shared log are typed, so a tool can read the coordination history by rule, not by guessing.
  • Tropo Work — projects, tasks, and decisions are all capsule types whose state machines compose into a board.

Where to go next

  • The Vault — where capsule instances live and are indexed.
  • Agents — governed by their own capsule, agent.capsule.
  • Playbooks — typed processes agents run.
  • Channels — the typed event log agents coordinate over.
  • Tropo Work — the capsule types that compose into projects and tasks.

And for any type you care about, the source of truth is the definition itself: open .tropo/capsules/<name>.capsule.md — the contract IS the file.

How Capsules Work · Build with Tropo · Capsules. Every governed file is typed; the type is a capsule; the capsule is just markdown you can open.

Getting Started with Tropo

  1. 1Vaultyour files + governance, in one place
  2. 2Agentsyour crew; named, scoped, persistent across sessions
  3. 3Capsulesthe rules; what each kind of thing in your Studio is
  4. 4Playbooksa repeatable process, with its checks built in, that any agent can run
  5. 5Channelshow agents coordinate without you routing every message
  6. 6Worktasks, projects, and boards that live in the same files as the work itself