---
title: Naming
description: "be-<type>-<name>. The name is the routing table for every repo, folder, page and command."
---

Every thing Belief Engines makes is named the same way. The name says
whose it is, what kind it is, and which one. Nothing else carries that
information — not a parent folder, not a registry, not a README.

```text
   be  -  type  -  name
   │        │        │
   │        │        └── which one          kebab-case, 1-3 words
   │        └─────────── what kind it is    one word, from the list
   └──────────────────── ours               always "be"
```

## Why it matters

```text
  human says         "idea about zoom transcripts"
  Claude runs        be wiki new zoom-etl
  CLI creates        github.com/beliefengines/be-wiki-zoom-etl  ->  ~/be-wiki-zoom-etl
  teammate's Claude  be wiki pull zoom-etl
  any agent reads    ~/be-wiki-zoom-etl/docs/    knows the shape on sight
  it graduates to    be-internal/docs/be-pipeline-zoom-etl/
```

Home on the dev box is flat: every folder under `~` is `be-<type>-<name>`
and `ls ~` is the whole inventory.

One name, five places, zero lookups. A cold agent or a new hire sorts by
type and finds everything of that kind. That is what keeps flat survivable.

## Types

| Type | Is a | Lives as |
|---|---|---|
| `wiki` | one person's idea, being flushed out | its own repo, from `be-wiki-template` |
| `customer` | a client engagement | `be-internal/docs/customers/` |
| `agent` | an agent we are specifying | area in `be-internal` |
| `pipeline` | a data flow, source to sink | area in `be-internal` + eng repo |
| `app` | something with a UI | eng repo |
| `infra` | AWS, Vercel, DNS, the plumbing | eng repo |
| `flow` | a multi-step process | area or eng repo |
| `cli` | a command-line tool | eng repo |
| `podcast` | an audio project | eng repo |
| `harness` | the invariant layer under everything | singleton `be-harness` |

Need a type that is not here? Add the row first, in this page, then use it.
A type is a shared word — inventing one in a repo name creates a category
of one.

## Singletons

When there is exactly one of a type and there will only ever be one, the
name is dropped: `be-internal`, `be-website`, `be-cli`, `be-harness`. The test is *could a
second one exist?* If yes, it gets a name now, not later.

## Where the pattern repeats

The same three parts name smaller things, so the type is visible at every
level:

```text
  repo      be-wiki-zoom-etl
  area      docs/be-pipeline-zoom-etl/
  page      docs/.../decision-storage-layer.md     <kind>-<what>.md
  command   be wiki new zoom-etl                   be <type> <verb> <name>
  agent     .claude/agents/historian.md            one word, a role
```

Page kinds are fixed: `idea` `question` `research` `decision` `spec`.
`index.md` is the only page without a kind prefix.

## Rules

- Lowercase, hyphens only. No underscores, no camelCase, no dots.
- Type is one word. Name is one to three.
- Never nest a type inside a type: `be-wiki-agent-wolf` is a wiki named
  `agent-wolf`, and that is fine — but it is a wiki, not an agent.
- Order is fixed. `be-template-app` reads as "a template called app";
  `be-app-template` reads as "the app that is a template". The second is
  right. Rename candidates go in the table below, not in place.

## Rename candidates

| Now | Should be | Why |
|---|---|---|
| `be-template-app` | `be-app-template` | type before name |
| `be-pulpcrew` | `be-<type>-pulpcrew` | missing type |
| `be-vincent` | `be-<type>-vincent` | missing type |