---
kind: knowledge
when-and-why-to-read: When you are choosing how to shape a node — which kind to spawn, base vs orchestrator, which profile, or which memory scope a doc belongs in — this reference should be read so each task gets the right role, orchestration depth, identity, and guidance reach instead of paying for a mismatched agent shape.
short-form: The four orthogonal dials that shape a node — kind (role + model tier), mode (base vs orchestrator), profile (identity + purview), and memory tier (who sees a doc) — plus when to reach for each over its alternatives.
system-prompt-visibility: name
file-read-visibility: none
rationale: Agents pick shaping dials by reflex from the one-line `-h` blurbs and get the discriminators wrong — delegating debugging to explore instead of advisor, grinding an orchestrator-shaped job in base, minting a duplicate memory doc at the wrong scope. The per-kind base docs carry the rationale but only the running node of that kind ever sees them; nothing gave a chooser the cross-cutting "which one, and why it's built this way" view before committing.
---

# Agent shaping — kinds, modes, profiles, and memory tiers

Four orthogonal dials shape every node. This is the **when-to-use-which** layer over them — the philosophy of each and how to choose between alternatives. It does not cover mechanics: the node/canvas/lifecycle model is `internal/nodes-and-canvas`, the physical disk layout of every store is `internal/storage-tiers`, and the authoring/routing/visibility contract for memory docs is `crtr memory write -h`. Point at those; this doc decides which dial to turn.

The dials are independent — you set each without constraining the others:

- **kind** — the node's role and expertise (`explore`, `developer`, a custom persona). Carries a model tier and a tool set.
- **mode** — `base` (do it yourself; yield hands-on when an unsplittable task needs another window) vs `orchestrator` (delegate and hold a roadmap across cycles).
- **profile** — the node's identity: which project dirs it can see and which memory/config store it resolves against.
- **memory tier** — where a shared doc lives, which decides who ever reads it.

A fifth axis, **lifecycle** (`terminal` vs `resident`), is orthogonal too but belongs to the runtime model — see `internal/nodes-and-canvas`. Terminal owes a final up the spine and reaps; resident stays interactable and is never forced to submit. Orchestrating never earns residency on its own.

## Kinds — role, model tier, and tools

A kind is a **persona** (gated memory docs at `kinds/<kind>/00-base.md` and `01-orchestrator.md`, gated `{kind, mode}` so exactly the node's role prose splices into its boot context) plus a **`KindConfig`** in the launch registry (its one-line `whenToUse`, a default model tier, the tools/extensions it gets, and which sub-personas it may spawn). Set it at spawn with `crtr node new --kind`, or change it live with `crtr node config --kind` / `crtr node promote --kind`.

**Why kinds exist at all.** Two payoffs a per-task instruction can't buy. First, **model-tier economics ride the kind boundary**: `explore` defaults to a fast/cheap model (right for mapping and summarization, wrong for judgment); `advisor` defaults to the slow, expensive think-y tier (right for debugging and tradeoffs). Fencing the tier into the kind is what stops an orchestrator from delegating debugging to a cheap explore scout. Second, a kind is **standing role discipline** that survives across every task of that type — the reviewer's neutral priming, the developer's done-bar, the planner's decision-resolution — rather than prose you must restate and that erodes each spawn.

### The builtin roster

| kind | what it's for | reach for it when |
|---|---|---|
| **general** | catch-all worker for work that fits no specialist kind | nothing more specific fits. Its persona optimizes for self-agency — reshaping its own kind/mode/config mid-flight — because it's the default spawn, not custom-shaped for the task |
| **explore** | read-only orientation and code-path mapping, `file:line` evidence, facts without opinion, effort scaled to requested depth | you need to understand unfamiliar code or architecture. **Never** for diagnosis — anything about why something is broken or misbehaving is advisor |
| **advisor** | diagnosis, debugging, tradeoff analysis, engineering second opinions — reason from evidence, recommend the next move | you need to find out what is going wrong, or want judgment on a consequential call. The reciprocal of explore: expensive think-y tier, fenced here so judgment doesn't leak onto a cheap scout |
| **spec** | discover-then-write *what to build* — behavior, non-goals, interfaces, edge cases, testable acceptance criteria | the requirement itself is unsettled and needs enumerating (which pages exist, which error cases) before anyone designs |
| **design** | architect *how it should be built* — cross-service, high-level decisions (schema, patterns, performance), worked out interactively, deliberately not the most obvious solution | the *how* has real architectural weight. Distinct from plan: design decides the shape; plan sequences an already-decided shape |
| **plan** | decompose an approved spec/design into concrete, phased, parallelizable steps with every decision resolved | you have a spec or design and need an executable breakdown a less-capable model can run without re-deciding. A plan 80% right costs more than no plan — pin every decision |
| **developer** | implement a change and make it *genuinely work* against acceptance criteria, not merely compile | you're building the feature or fix. Green proves it ran, not that it's right — the persona carries the prove-it discipline and the build→review cycle |
| **review** | critique code, a plan, or a spec once — deliver a complete, severity-rated verdict, **detect don't adjudicate** | substantive work needs one independent check. Use a *separate* node from the author — agents can't self-audit — and prime it neutrally ("review this", never "find what fails", which manufactures false positives) |
| **product** | discover the real user need behind a request and define the product experience, grounded in comparable products; hands off to spec | the client is non-technical and the *what-and-why* must be found before any spec. **Speculative** — the product→spec baton has not yet run end to end |
| **personal-assistant** | Silas's standing personal assistant — resident on the canvas, wakes on his iMessage thread, remembers across conversations | only for that standing assistant role (resident lifecycle), not general work |

The discriminators that get missed: **explore vs advisor** (mapping vs judgment — cheap vs expensive tier); **spec vs design** (what to build vs how to build it); **design vs plan** (decide the shape vs sequence a decided shape); **review is always a separate node from the implementer**. Two current truths about the roster itself: **product is speculative** (earns its slot on principle, never run end to end), and **developer is the kind closest to "general with a mood"** — the first merge candidate if the roster ever shrinks.

### Sub-kinds

Specialist sub-personas hang off a parent kind — `plan/reviewers/*` (architecture-fit, code-smells, pattern-consistency, requirements-coverage, security), `product/teardown`, `spec/requirements`. They aren't in the top-level `--kind` list but are valid by exact path (`crtr node new --kind plan/reviewers/security`). Use a sub-persona for one narrowly targeted assignment, not as a mandatory lens roster; discover the available roles with `crtr sys prompt-review --list --kind <kind>`.

### Custom personas

The roster is extensible. Add a `kinds.<name>` entry to a `config.json` at user or project scope (fields: `whenToUse` required, plus optional `model`, `orchestratorModel`, `tools`, `extensions`, `availableTo`) and author the persona prose at `kinds/<name>/00-base.md` (and `01-orchestrator.md`) gated `{kind: <name>, mode: ...}`. The registry merges **project > user > builtin**, so a custom kind can add a new role or shadow a builtin one without restating the rest. Reach for a custom kind when a **recurring role** wants its own standing discipline and model/tool defaults that outlast any single task — not for a one-off instruction, which belongs in the spawn prompt.

## Modes — base vs orchestrator

Every kind has both a `base` and an `orchestrator` persona; mode picks which one splices in.

- **base** — hands-on. Do the work yourself and finish it with `crtr push final`. Your scarce resource is the task. Spawn a child only for a cleanly separable unit, never as your first move. When an unsplittable task needs another context window, `crtr node yield` and continue hands-on as base.
- **orchestrator** — you own a goal too large for one window. Decompose it, delegate each piece, integrate what comes back, hold a `context/roadmap.md` that survives refreshes, and yield (`crtr node yield`) into a clean window when context fills. Your scarce resource is your own context window; the moment you start grinding the goal out by hand you've lost the plot. The shared loop lives in the `orchestration-kernel` doc (auto-gated for orchestrators).

**When to reach for orchestrator over base.** When the *shape* of the job needs decomposition across children — many phases visible up front, or a base task that keeps getting extended into independently delegable work. Promote *early* (`crtr node promote`), the moment you recognize that shape, not after the window wears down; or spawn the child directly as a sub-orchestrator (`crtr node new --mode orchestrator`) rather than hoping a base worker promotes itself, which is unreliable. An unsplittable task that merely needs another context window stays base: `crtr node yield` and continue hands-on.

## Profiles — identity, purview, and a memory store

A profile is a stable **agent identity**: a fixed id, a display name, its own memory store, and a **purview** of project directories it resolves memory and config from. Select it at spawn with `crtr node new --profile <id-or-name>`; omit and a child inherits the caller's profile. Pin a directory's default profile with `crtr profile default` so the startup chooser stops asking. Manage the identity and purview with `crtr profile new/show/project/rename/delete` (see `crtr profile -h`).

Reach for a **new** profile when a distinct body of work has its own set of directories and its own conventions worth a dedicated store — not for every repo. The **profile memory scope** is exactly where cross-repo conventions and your stance toward that body of work belong (see the memory tiers below); a profile spanning several related dirs lets one doc reach every node working anywhere in that bundle.

## Memory tiers — where a doc lives decides who sees it

A memory doc's **scope** is a reach dial: the wider the scope, the more agents pay to carry it, forever. Choose the **narrowest scope that still reaches the next agent who needs it**. Physical paths and durability contracts are in `internal/storage-tiers`; the frontmatter/routing/visibility contract is `crtr memory write -h`. The scopes, narrowest reach to widest:

- **node** (`nodes/<id>/context/memory/`) — only *this* running node sees it; rides its boot context and dies with the node. Scratch memory for one goal's cross-refresh state.
- **profile** (the profile's own store) — every node running under that profile, across all the dirs in its purview. Cross-repo conventions and the user's stance toward that bundle of work.
- **project** (`<project>/.crouter/memory/`) — any agent operating in that one repo. Facts and procedures tied to that codebase. Resolves to the nearest ancestor `.crouter/` walking up from cwd; `--dir` pins an exact repo.
- **user** (`~/.crouter/memory/`) — person-wide facts and preferences that follow the user everywhere, regardless of repo or profile.
- **builtin** (`src/builtin-memory/` in the crouter repo) — ships inside crtr, so *every crtr user on every host* carries it. This tier is the runtime's own self-documentation (this doc lives here); a change here is a change to the product. Author here only for guidance every crouter user needs, never for anything person- or repo-specific.