A Substrate is the shared layer that defines **how behaviours emerge and change over time**, rather than just which features are available at a given moment.
In the Hitchhiker ecosystem, a substrate is the specification that tells agents and human developers how identity, memory, events and governance fit together so that many different platforms and tools can grow on top of them.
Where Platform vs Substrate describes the conceptual distinction, this page focuses on **how to write a Substrate Specification that agents can implement.
# Purpose Of A Substrate Spec A Substrate spec is a standardised document that. - Defines the **behavioural rules and feedback loops** of a domain, not just its APIs. - Can be read both by humans and by software agents tasked with implementation. - Allows multiple platforms and tools to be built on top of the same shared layer. - Makes it possible to test whether an implementation “is on” this substrate.
The spec does **not** dictate UI, product strategy or company structure. It defines the **conditions of emergence** for communities and software built using that substrate.
# When To Define A Substrate Define a Substrate when. - You want many platforms, tools or services to share the same underlying behaviour. - You expect communities to fork, remix or extend the rules while staying interoperable. - You care about long term governance, memory and identity more than any one app.
If you only need a single product with tightly controlled features, you may only need a platform spec. If you want a whole ecosystem, you probably need a Substrate spec.
# Structure Of A Substrate Spec A Substrate spec should follow a consistent structure so that agents can recognise it and extract the pieces they need. The rest of this page describes the recommended sections.
# 1 Name And Scope This section answers. - What is this Substrate called. - What domain or problem space does it cover. - What is explicitly out of scope. Keep the scope small enough that the substrate can be implemented and reasoned about, but large enough that multiple platforms can share it. Reference related substrates when scope overlaps.
# 2 Narrative Overview Explain the substrate in plain language, as a short story. - Who are the typical actors and communities. - What kinds of activities happen repeatedly. - What changes over days, months and years. This gives agents and humans an intuitive handle on the substrate before they see formal structures. It should be consistent with the explanations on pages like The Substrate and Hitchhiker Guides.
# 3 Core Principles List the guiding principles that shape the substrate. For example. - Identities outlast individual platforms. - Memory is federated and forkable. - Governance is explicit and evolvable. Each principle should have operational consequences later in the spec. Agents should be able to derive design choices from these principles when details are underspecified.
# 4 Domain Vocabulary Define the key terms of the substrate. - The words the spec will use in a precise way. - Any overloaded words that need disambiguation. Each term should have. - A short definition. - Notes on how it differs from similar concepts. This vocabulary becomes the shared language between specification, implementers and governance processes like Hitchhiker Constitution and Community-Driven Development.
# 5 Actors And Roles Describe who or what participates in the substrate. - Human actors. - Software agents. - Organisations, collectives or other non human entities. For each actor or role specify. - What they can see. - What they can do. - What they are responsible for. This gives agents implementing the substrate a clear model of permissions and perspectives.
# 6 State Model Describe the **canonical state** that the substrate cares about. This is the part that must be preserved and migrated, even when platforms change. Include. - Core objects or records that must exist. - Relationships that matter between them. - Minimal fields and constraints that define validity. This section should be implementation neutral. It can be mapped to schemas and data models later, but here it defines the conceptual state that all conforming implementations must maintain.
# 7 Events And Behaviours Describe the events that can occur in the substrate and how they change state. For each event type specify. - Preconditions. - The state changes that must occur. - Side effects on other processes such as notifications or indexing. - How the event is recorded in shared memory. This section is where platforms find their “verbs”. Agents should be able to generate APIs or commands from these event definitions, but the spec itself is not tied to a particular API style.
# 8 Emergence Rules And Feedback Loops This is the core difference between a substrate and a platform spec. Describe how behaviours emerge over time from repeated events and state changes. - How do events accumulate into history, reputation or shared memory. - How does past behaviour constrain or enable future actions. - What feedback loops are intentionally present or intentionally blocked.
Examples. - How attending events changes trust or access. - How governance decisions alter future decision procedures. - How content visibility is derived from previous actions, not just raw state. Agents should be able to simulate scenarios from this section. It should be clear what patterns the substrate is trying to encourage, discourage or simply observe.
# 9 Protocols And Interfaces Only after defining state, events and emergence should the spec talk about interfaces. Describe. - Required protocols for interoperability, if any. - Minimal interface patterns that any conforming platform must expose. - How messages, documents or pages move between implementations. This section should make it possible for two independent implementations to interoperate without sharing code, only the spec.
# 10 Invariants And Safety Constraints Specify the conditions that must **always** hold in a valid system. - Logical invariants on state. - Governance invariants such as consent requirements. - Safety limits such as maximum authority escalation. Agents should treat violations of these invariants as bugs or governance breaches. This section is the substrate equivalent of a type system and safety harness.
# 11 Governance And Evolution Describe how the substrate itself can change. - Who can propose changes. - How proposals are discussed, ratified and recorded. - How breaking changes are handled and versioned. This section links the substrate to governance practices described on pages like Hitchhiker Constitution and Community-Driven Development. It turns the substrate into a living agreement rather than a static spec.
# 12 Implementation Notes Provide non normative guidance. - Reference architectures. - Known good patterns. - Known pitfalls and anti patterns. Agents can treat this as hints, but conformance is judged against the formal sections above, not these notes. This section can include migration strategies from legacy systems or prior versions.
# 13 Conformance And Test Scenarios Explain what it means to “be on” this substrate. - Minimal requirements for conformance. - Test scenarios that any implementation should pass. - Example narratives that can be turned into automated tests. A conformance suite is especially important when agents are generating or evolving implementations. It gives them a target beyond vague “alignment” with the spec. # 14 Relationship To Other Substrates And Platforms Finally, explain how this substrate fits into the wider ecosystem. - Which other substrates it depends on or extends. - Which platforms currently implement it. - How it might coexist with alternative or competing substrates. This section helps agents and humans understand composition. A platform may implement several substrates. A substrate may reuse parts of another. Explicit links keep the ecosystem coherent.
# Using This Page As A Template When creating a new substrate, clone this structure and fill in each section with domain specific content. Agents can then be instructed. - “Read the Substrate spec for X.” - “Generate or update code so that Platform Y conforms to that Substrate.”
Over time, a library of Substrate specs forms the shared backbone beneath many different platforms and experiments, all grounded in the same philosophy of emergence described in Platform vs Substrate and embodied in The Substrate itself.