tropo

From the Tropo Vault9b3e8c47

Capsule-vs-Instance Naming

A short explainer on Tropo's kernel rule for distinguishing capsule definitions from their instances on the file syst...

Capsule-vs-Instance Naming

A short explainer on Tropo's kernel rule for distinguishing capsule definitions from their instances on the file system. The convention was locked in v1.6 design brief b6f1e9c4 Decision 5 by Mike Maziarz + Argus A44 on 2026-05-04. This article is the canonical reference.

Distinct from How Naming Conventions Work — that article covers numerical prefixes (00-, 01-, 99-) for structural folder sort discipline. This article covers the capsule-vs-instance distinction in file naming. Both are kernel-level rules; they operate at different layers.

The convention in 30 seconds

| Form | Used for | Examples | |---|---|---| | Dotted (<kind>.capsule.md, <name>.playbook.md, <name>.action.md, <name>.skill.md) | Kernel-file definitions. The dot is a kernel-file-marker — equivalent to a file extension. Declares "this is a kernel-governed file of type X." | pipeline.capsule.md, task.capsule.md, welcome.playbook.md, create-project.action.md | | Hyphenated (<name>/, <name>.md) | Project / instance folder and file names. Carries no kernel-marker; identifies an instance in the work substrate. | tropo-work/, dev-pipeline/, legacy-work-pipeline/, release-pipeline/ |

The bridge: instance frontmatter carries type: <kind> — the bare kind name, no .capsule suffix — referencing the capsule definition that governs the instance.

Why this exists

A stranger reading the file tree should know at a glance whether they're looking at a definition or an instance. Without a syntactic rule, both forms collide:

agents/dev-pipeline/             ← is this the definition of pipelines? or a specific pipeline?
.tropo/capsules/pipeline.capsule.md  ← clearly a definition (capsule extension)

The dotted form is reserved for kernel-file definitions because the dot semantically reads like a file extension — <name>.capsule parallels <name>.txt or <name>.json. It marks the file's structural role.

Hyphenated form is for instances because they're the work; they don't need a kernel-marker — they have their own identity (UID + frontmatter). Hyphens read as ordinary names; that's appropriate for ordinary instances.

The convention earns its place by disambiguation in the file viewer (the primary surface where strangers and agents first encounter the substrate).

What's a kernel-file?

The dotted form applies to four kernel-file types:

| Suffix | Kernel-file type | Lives in | |---|---|---| | .capsule.md | Capsule definition (type schema + rules) | .tropo/capsules/ | | .playbook.md | Governed procedure (multi-step workflow) | .tropo/playbooks/ | | .action.md | Single-action constructor (creates one artifact type) | .tropo/actions/ | | .skill.md | Reusable procedure (boot/retire/maintenance) | .tropo/skills/ |

These are the "kernel surface" — files that define HOW things work in Tropo. They live under .tropo/ (the kernel directory). Their dotted form makes their kernel role visible at the path level.

Examples — getting it right

.tropo/capsules/pipeline.capsule.md     ← definition: "a capsule of type pipeline"
.tropo/capsules/project.capsule.md      ← definition: "a capsule of type project"
.tropo/playbooks/agent-activation.playbook.md  ← definition: a playbook
.tropo/actions/create-project.action.md  ← definition: an action
.tropo/skills/scan-channels.skill.md     ← definition: a skill

tropo-work/                              ← instance: the L0 work-substrate root project
tropo-work/dev-pipeline/                 ← instance: a specific pipeline
tropo-work/legacy-work-pipeline/         ← instance: the deprecated pipeline
agents/cosmo/                            ← instance: a specific agent (Cosmo)
vault/files/b6f1e9c4.md                 ← instance: a specific design brief

# In the design brief's frontmatter:
type: design-brief                       ← bridge: bare kind name, references design-brief.capsule.md

Examples — what v1.6 Stream B fixed

The pre-v1.6 vault had one violation pattern of the dotted-instance form, which v1.6 Stream B corrected. Conceptual diff:

| Before (v1.5 and earlier) | After (v1.6 onward) | |---|---| | agents/dev.pipeline/ (violation: dotted form on an instance container) | agents/dev-pipeline/ (hyphenated; convention-conformant) | | agents/dev.pipeline/activations/7c0402b8/run.jsonl | agents/dev-pipeline/activations/7c0402b8/run.jsonl |

The rename is mechanical. UID stays stable (cd1fcd25); only the path/name changes. Reference sweeps update capsule exemplars, KB articles, memory pins, run.jsonl path strings, and any other docs that mention the old form.

Similarly for the deprecated 4-stage Innovation Pipeline:

| Before | After | |---|---| | work-pipeline (name; ambiguous against generic "work") | legacy-work-pipeline (name; explicit deprecation visible) | | member_of: [] (orphan at L0) | member_of: [<tropo-work-uid>] (reparented for lineage-in-graph) |

Different kind of fix — the rename adds the legacy- prefix to make deprecation visible in the name; both forms are hyphenated (instances). The reparent records the deprecation in the substrate's graph lineage rather than orphaning at L0.

Known violation NOT fixed at v1.6 (deferred to v1.7+ migration sweep)

.tropo/playbooks/pipelines/tropo-work-pipeline.pipeline.md (UID 7c5a2b8f) ships at v1.6 with three convention violations:

  1. Filename uses .pipeline.md suffix — but .pipeline is NOT a kernel-file-type suffix (the four valid suffixes are .capsule.md, .playbook.md, .action.md, .skill.md)
  2. Frontmatter type: playbook while filename declares .pipeline.md — type and filename disagree
  3. Folder playbooks/pipelines/ mixes the two kinds in one path

This artifact is pre-existing (v1.3-era, argus-a30 2026-04-21). v1.6 locks the convention but doesn't sweep all pre-existing violations — that's a v1.7+ Patient-Honing migration sweep. Documenting the violation here so readers don't infer the convention is universally enforced; it's locked forward, not retroactively.

When this convention is NOT relevant

  • Numerical-prefix sort discipline. Folders like 01-inbox/ or 99-archive/ follow a separate convention. The numerical prefix is orthogonal to the capsule-vs-instance form.
  • First-class artifacts with established names. briefing-package/, transfers/, <name>-charter.md, <name>-soul.md — these have their own identity conventions and don't take dotted form (they're not capsule/playbook/action/skill kernel files).
  • Configuration files. STUDIO.md, OPERATING-AGREEMENT.md, CLAUDE.md, README.md — vault-level config files use UPPER-CASE-DOT-MD as their identity form.

Why this is a kernel rule, not a release-specific deliverable

The convention is structural — it shapes how every file in the substrate is named. Once locked, it applies forward to every new capsule, playbook, action, skill, project, pipeline, agent, and instance. Future releases reference but don't redefine it.

Per v1.6 design brief b6f1e9c4 Decision 5:

"Dotted form is reserved for kernel-file-type suffixes — equivalent to a file-extension marker. Hyphenated form is for project/instance folder names. Frontmatter type: field is the bridge."

v1.9 (taxonomy thesis) will apply this rule when defining the tropo-subsystems vocabulary — but doesn't redefine it. Future work in the v1.6+ chain inherits the rule.

Related

capsule-vs-instance-naming.md | KB | Argus A44 | 2026-05-04 "Definitions are dotted. Instances are hyphenated. The frontmatter type: field is the bridge."