arch-scaffold-namespace git:20261014.7748a1fA

Immutable. This exact content never changes and is served at /api/v1/blob/42c40a6be8e9244e.

---
name: arch-scaffold-namespace
description: "Create an object-model namespace (a swimlane) with its first entity: the manager interface and impl, storage in Postgres and memory, its README, and the wiring into both roots, in the shape of the scaffold's own namespaces. Python."
allowed-tools: Read, Grep, Glob, Write, Edit, Bash(make check), Bash(make infra-up), Bash(make migrate), Bash(make migrate-check), Bash(make openapi), Bash(docker info:*), Bash(uv run:*), Bash(git status:*)
---

# arch-scaffold-namespace

A path that starts with `../` is read from this skill's folder
as `realpath` resolves it.
Conventions: `../_shared/scaffold-conventions.md`.
Sections of `../../architecture.md`: Namespaces as
Swimlanes, Interfaces (Injectability), The Business Layer
(Cross-Manager Dependencies), The Storage Layer (Namespace Shape,
Storage Root, Cross-Storage Dependencies), Documentation as Code (A
README at Every Level).

## Input

`<namespace> <FirstEntity> [field:type ...] [--role core|activity|queue|admin] [--scope system|org|identity|both]`

Example: `inventory Warehouse address:str timezone:str`. Both are
required; ask for them when missing. A namespace arrives with its first
entity, since `om/tests/unit/test_interfaces.py` refuses an interface
that declares no method. The entity arguments, the role, and the scope
go to `arch-scaffold-entity` in step 3.

## Created

The shape is the `media` namespace, `om/src/<name>/om/media/`. Under
`om/src/<name>/om/<ns>/`:

| File | Holds |
|------|-------|
| `__init__.py` | `from .manager import <Ns>ManagerInterface` |
| `README.md` | the namespace in the product's language, one level below `om/README.md`: its nouns, what can happen to them, the rules that hold; no developer or operator instruction |
| `manager.py` | `<Ns>ManagerInterface`, a docstring naming the swimlane |
| `impl/manager.py` | `<Ns>ManagerImpl`, taking its storage interface, the `OutboxRelayInterface`, and every manager it calls, each by interface |
| `storage/__init__.py` | `<Ns>StorageInterface`, a docstring saying every operation takes `org_id` first |
| `storage/impl/postgres.py` | `<Ns>StoragePostgresImpl(PgStorageBase, <Ns>StorageInterface)` |
| `storage/impl/memory.py` | `<Ns>StorageMemoryImpl(MemoryStorageBase, <Ns>StorageInterface)` |
| `types/__init__.py`, `impl/__init__.py`, `storage/impl/__init__.py`, `storage/tables/__init__.py` | empty; the entity skill fills `types/` and `storage/tables/` |

In a tree whose ops skills read `.agents/skills/_shared/signals/`, the
namespace's signals file is created there too, `<ns>.md`: `# Signals:
<ns>` and one sentence on what the namespace does, in the shape of the
scaffold's own files beside it. A skill that later gives the namespace
a kind, an outcome, a log line, or a failure event adds it there, under
the heading the folder's `README.md` names.

## Changed

| File | Change |
|------|--------|
| `om/src/<name>/om/storage/root.py` | `get_<ns_singular>_storage()` on the storage root, below the marker |
| `om/src/<name>/om/storage/impl/postgres.py`, `memory.py` | each root builds its impl and returns it from the getter, each below its marker |
| `om/src/<name>/om/root.py` | below each marker: the field `<ns>` on `Managers`, the namespace's options on `build_managers`, the call `<ns> = build_<ns>(...)` in its body, `<ns>=<ns>` in `Managers(...)`, and, at the end of the module, `build_<ns>`, which builds `<Ns>ManagerImpl` |
| `om/README.md` | the namespace's nouns, each defined for a reader with no code, the first linked to the namespace's README, and in the relations the page names |

## Procedure

1. Write the files, then wire both storage roots and `build_managers`,
   as `media` is wired. A manager this one calls is a constructor
   parameter typed by its interface, and `build_managers` builds the
   callee first.
2. The namespace reaches the API with its first entity, whose skill
   adds the service, its impl, and its router.
3. Read `../arch-scaffold-entity/SKILL.md` and
   follow it with `<namespace> <FirstEntity> <field:type ...> --role
   <role> --scope <scope>`, before the gates run.

## Output

As `../_shared/scaffold-conventions.md` states.