Declare once, derive every interface

Why it exists

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.

• →opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repository
• →found the rule for that directory in a README no session ever loaded
• →read three roadmaps for one project and believed none of them
• →watched the always-loaded instruction file grow past a thousand lines
• →changed a policy in one place and found the old one still in force in three others
• →found a rule everyone believed was enforced and nothing ever invoked

How it works

The capability modules of the executable this feature names, each with the capabilities it composes. The interfaces each one reaches are listed under Interfaces below: they are projections of one declaration, not separate registrations.

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.

• feature29
• domain6
• command31
• claim250

Where it sits

domain

Surfaces — One declaration in the repository becomes the command line, the HTTP API, MCP, the UI, the Cockpit, the documentation and this site, and a projection that disagrees with it fails the build.

areas of work

documentationgovernance

names

InterfacesCockpit

named by

InterfacesPolicyCockpitSkillsWhyEvidenceBenchmarksCommits

Interfaces

Each capability behind it, on every interface it is projected onto. A link goes to this site's reference for that interface; an HTTP route and an MCP tool are answered by a running majordomus serve, not by this site.

in the Cockpit, of a running server

/cockpit/capabilities Capabilities

/cockpit/artifacts Artifacts

served by the executable

/openapi.json The OpenAPI document of the capability registry

Evidence

What is guaranteed

Each claim this feature names, with the status its row declares, the verdict the recorded runs support, and the test that settles it.

• ○declared status: guaranteed ○recorded evidence: not run Every capability of the Rust executable is defined once, and the registry refuses a duplicate id or a colliding projection name, naming both parties apps/majordomus-cli/tests/registry.rs
• ○declared status: guaranteed ○recorded evidence: not run MCP, HTTP, OpenAPI, Swagger UI, the capabilities commands and the generated reference are derived from the registry, and a change to one definition reaches every one of them test/cases/76_capabilities_projections.sh
• ○declared status: guaranteed ○recorded evidence: not run Every generated artifact declares the document it projects, the encoding it is written in, the schema its content satisfies and its source, and a structured document is written in every encoding it is committed in from one value test/cases/52_generated_artifact_typing.sh
• ○declared status: guaranteed ○recorded evidence: not run The committed projections, the OpenAPI document, the capability reference and the allow-lists, are regenerated from the registry and the schemas, and generate --check refuses a stale one test/cases/76_capabilities_projections.sh
• ○declared status: guaranteed ○recorded evidence: not run What the tool knows about itself is written once and derived everywhere else, and a second copy is a test failure test/cases/28_no_hardcoded_values.sh
• ○declared status: guaranteed ○recorded evidence: not run A commit whose derived data is behind its canonical inputs is refused before it exists, and a repository that unwires that gate is a doctor failure test/cases/56_derived_current_gate.sh
• ○declared status: guaranteed ○recorded evidence: not run Every committed derived artifact of the repository is regenerated by one command in dependency order and checked by one read-only command that names every stale artifact, a second regeneration on a clean tree changes nothing, and no derived file records the commit it lands in test/cases/400_derivation_is_one_graph.sh
• ○declared status: guaranteed ○recorded evidence: not run The site's Registry page is rendered from site/data/registry/registry.json, a dataset majordomus generate site derives from the registry and the index with their fingerprints, and generate --check refuses a stale one in CI apps/majordomus-cli/tests/projections.rs
• ○declared status: guaranteed ○recorded evidence: not run The site's pages about the Rust executable (one per module, one per capability, the command line, the MCP surface, the benchmarks, the executable's own narrative) are derived from the registry manifest and the registry dataset the executable generates, nothing names a capability by hand, and a capability that joins or leaves the registry gains or loses its page, its index entries and its links from the generators alone test/cases/95_executable_reference.sh

Executable use cases

• extensionExtend what the executable serves by adding a file, never by rebuilding it

The rules that hold it

• ✕blocking External interfaces are projections of one capability definitionproject.interfaces-are-projections
• ✕blocking One canonical declaration; modules compose capabilities; the root composes modulesproject.rust-canonical-declaration
• ✕blocking Derived files are regenerated, never editedproject.derived-files-regenerated
• ✕blocking A generated artifact declares its document, its encoding, its contract and its sourceproject.generated-artifacts-are-typed
• !advisory Derived state is computed once per state versionproject.derived-once

The decisions behind it

• adr-0002A canonical capability registry, with MCP, HTTP, OpenAPI, Swagger UI, the CLI and the reference as projections accepted
• adr-0004One canonical declaration, composed modules, derived projections, and performance as evidence accepted
• adr-0005One projection plan over the canonical inputs, named owners for every truth, and the site as a view of the registry accepted
• adr-0023Product features are objects of the layer, and the landing page is a projection of them accepted

Using it

The commands that run it

• majordomus update setup

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

• majordomus doctor inspect · read-only

  It checks governance only: is Majordomus itself healthy, and is every enforcement it declares actually wired here?

From the executable's command line

The synopsis of each, as the executable's own help prints it.

• majordomus capabilities list [OPTIONS]

  Every capability, one line each, with its projections

• majordomus capabilities describe [OPTIONS] <ID>

  One capability by canonical id: schemas, provenance, every projection

• majordomus capabilities projections [OPTIONS]

  Where each capability is projected, and every claim its surface does not answer

• majordomus product list [OPTIONS]

  Every feature, narrowed by any filter, with the surfaces derived for each

• majordomus product show [OPTIONS] <ID>

  One feature in full: what it is made of, resolved, and everything derived from that

• majordomus product domains [OPTIONS]

  The domains of the product, each with the stable features that name it and what they add up to

• majordomus product matrix [OPTIONS]

  Every feature against every interface, and every module, command and kind against the features that name it

• majordomus product providers [OPTIONS]

  Every provider the tool has an adapter for, with what this repository does with it

• majordomus product validate [OPTIONS]

  Every finding over the model; exit 10 when any is an error

• majordomus quality report [OPTIONS]

  Measure the crate and report every finding, with the rule it breaks and what to do about it

• majordomus quality rustdoc [OPTIONS]

  Judge the crate's rustdoc tree against the crate: every page present, HEAD's, nothing broken or leaked

Where this page comes from

the file

.ai/repo/features/declare-once.md

the same answer

majordomus product show declare-once

read further

Capabilities — one definition, every interface derived

Canonical ownership and derivation

GitHub Pages architecture

Related features

• named by this feature · names this feature · same domain

  Interfaces

  ✓feature status: stable

  Every agent, script and person reads the same repository through the interface it already speaks, and none of the interfaces is maintained by hand.

  Explore Interfaces →

• names this feature

  Policy

  ✓feature status: stable

  Every provider the tool declares — an agent, an orchestrator that runs agents, any tool that reads AGENTS.md — gets the same rules from the same place, because their instruction files are generated from one policy and never written by hand; the providers are the table in docs/generated/providers.md.

  Explore Policy →

• same domain

  Observatory

  ✓feature status: stable

  One screen of the UI rotates eight scenes on a display nobody is sitting at, and every mark on it is a value a capability answered; a scene with nothing true to draw says why and is never drawn empty.

  Explore Observatory →

• same domain

  UI

  ✓feature status: stable

  The shared server's primary surface answers how the delivery stands — health, releases, the roadmap, the work and its pull requests, the mesh, the evidence and the rules — and every value on it names the capability it was read from and every other surface that serves it.

  Explore UI →

• named by this feature · names this feature · same domain

  Cockpit

  ✓feature status: stable

  The same server that answers agents renders every capability, object, graph, worktree and health check as pages, with a runner generated from each capability's own schema; nothing on it is a second list.

  Explore Cockpit →

• same domain

  Install

  ✓feature status: stable

  The installer downloads one archive for your machine, verifies its digest against the release metadata before unpacking anything, and installs atomically; no git, no Rust, no Node, no root.

  Explore Install →

• names this feature

  Skills

  ✓feature status: stable

  A skill is one directory under the layer; adding it is the whole act, and the command line, the website and MCP all read it from the same file.

  Explore Skills →

• names this feature · same domain

  Why

  ✓feature status: stable

  Every operational moment the tool exists for is one file with the signals that identify it and the mechanisms that answer it, and a reader's own symptoms resolve to a diagnosis by counting, not by inference.

  Explore Why →

• names this feature

  Evidence

  ✓feature status: stable

  Every claim is joined to the execution recorded for its test — the outcome, the commit, the tree, the digest and the command that produces it again — and a run against this commit is never reported as the same thing as a run whose inputs merely have not changed.

  Explore Evidence →

• names this feature

  Benchmarks

  ✓feature status: stable

  Every externally callable operation is timed directly, over MCP and over HTTP, the denominator is generated from the registry, and a regression against the accepted baseline fails the check.

  Explore Benchmarks →

• names this feature

  Commits

  ✓feature status: stable

  The commit message has one grammar, one policy and one verdict; the scope it is written under is learned from the repository's own history rather than kept in a table, and a message that does not satisfy the policy is refused while it is still being written.

  Explore Commits →