Skip to content

Declare once, derive every interface

One typed declaration per capability, one file per object of the layer; every interface, generated document and page is derived from the registry those declarations build, and a stale projection fails the build.

A capability is written in one place, and the command line, the HTTP API, the OpenAPI document, MCP, the Cockpit, the reference and this website are projections of it.

status
stable
exposed through
area
documentation
governance

What it does

An executable capability is one capability! block in its module's file, with a typed input, a typed output and a handler. A declarative object — a rule, a skill, a decision, a use case, an operational moment, a feature like this one — is one file under .ai/ whose kind and schema the tool distribution declares. The registry is built from both on every start, validated and fingerprinted, and everything a person or a program reaches is a reading of it: the MCP tools and resources, the routes under /api/v1/, the OpenAPI document and the Swagger UI over it, the words after majordomus, the benchmark targets, the Cockpit's pages, the generated reference under docs/generated/, and the datasets this website is rendered from.

majordomus generate writes every committed projection from one plan; majordomus generate --check refuses a tree in which any of them differs from what the sources produce, and CI refuses to merge or deploy such a tree. The feature you are reading is itself one file under the layer, and the surfaces listed beside it were derived from that file rather than typed onto this page.

What it does not do

It does not discover a capability nobody declared: a handler without a capability! block is not exposed anywhere, by design. It does not infer a relation from a name or a substring; every reference a file makes is typed and resolved against the thing it names, and one that resolves to nothing fails validation rather than becoming a link to nothing.

The capabilities behind it

The capability modules of the executable this feature names, each with the capabilities it composes. The command line, the HTTP route, the MCP tool and the reference beside every row are projections of one declaration, not four registrations.

Capabilities capabilities behaviorally verified

The registry seen through itself: every capability with its kind, stability, provenance, exposures, benchmark and cache policy, and one capability in full.

apps/majordomus-cli/src/capability/builtin/capabilities.rs

Generated artifacts artifacts behaviorally verified

What `majordomus generate` writes: every document with the encodings it is committed in — JSON for a program, YAML beside it, Markdown for a reader — each with its schema, its source and its hash, reconciled with the working tree. The declaration is the generator's own manifest; nothing here keeps a list.

apps/majordomus-cli/src/capability/builtin/artifacts.rs

Product product behaviorally verified

What this repository's product does for a person, as the features under the layer's features section declare it: each feature made of modules, commands, kinds, rules, documents, decisions, claims, use cases, Cockpit areas and web surfaces it names, with the interfaces it is exposed through, every count, the moments it answers and what is guaranteed derived from those references. The matrix of features against interfaces, the providers the tool has an adapter for, and the model's own validation. The homepage is a reader of this module and holds no inventory of its own.

  • One feature query

    $ majordomus product showGET /api/v1/product/featuremajordomus_feature

  • The features query

    $ majordomus product listGET /api/v1/product/featuresmajordomus_features

  • Features against interfaces query

    $ majordomus product matrixGET /api/v1/product/matrixmajordomus_product_matrix

  • The providers query

    $ majordomus product providersGET /api/v1/product/providersmajordomus_providers

  • Validate the model query

    $ majordomus product validateGET /api/v1/product/validatemajordomus_product_validate

apps/majordomus-cli/src/capability/builtin/product.rs

The commands that run it

  • majordomus update setup

    Regenerate every provider instruction file from the one policy, deterministically.

  • majordomus doctor inspect · read-only

    Is Majordomus itself healthy, and is every enforcement it declares actually wired here?

The objects it is made of

Kinds of the layer. Each is a schema, a source class and a file on disk; the number beside it is what this repository holds today, counted at build time.

  • feature20
  • command29
  • claim148

What it answers

Operational moments from the Why catalogue that name one of this feature's mechanisms. Nothing here was assigned: a moment appears because it names a rule, a command, a capability or a claim this feature also names.

The rules that hold it

  • blockingExternal interfaces are projections of one capability definitionproject.interfaces-are-projections
  • blockingOne canonical declaration; modules compose capabilities; the root composes modulesproject.rust-canonical-declaration
  • blockingDerived files are regenerated, never editedproject.derived-files-regenerated
  • blockingA generated artifact declares its document, its encoding, its contract and its sourceproject.generated-artifacts-are-typed
  • advisoryDerived state is computed once per state versionproject.derived-once

What is guaranteed

Executable use cases