Question

What is a governing spec in Traverse?

Q: What is a governing spec in Traverse?

A governing spec is a document that must be approved before any feature is implemented in Traverse. It describes the problem, the proposed solution, alternatives considered, and acceptance criteria. The spec precedes the code. Traverse has 9 approved governing specs as of v0.7.0. This prevents speculative code and ensures every feature is intentional. It is similar to an Architecture Decision Record but required for all feature work.

A governing spec is a design document that must be written and approved before any feature is implemented in Traverse. The spec precedes the code. Not the other way around.

Every change in the Traverse codebase that adds or modifies significant behavior must be backed by an approved governing spec. You cannot open a pull request implementing a feature that does not have a corresponding approved spec. This is what "spec-governed development" means in practice.

What a governing spec contains

Problem statement — what specific problem this change addresses
Proposed solution — the design being implemented, in enough detail to be reviewed on its own
Alternatives considered — what other approaches were evaluated and why they were not chosen
Acceptance criteria — what must be true for the implementation to be considered complete

How many governing specs exist

Traverse has 9 approved governing specs as of v0.7.0. Each one corresponds to a major system component or behavioral capability: the runtime execution model, contract validation, the registry, placement targeting, the browser adapter, the state machine, trace artifacts, the MCP integration, and the expedition example.

You can read them in the repository under the specs/ directory.

Why this matters

Most codebases accumulate speculative features. Someone has an idea, writes the code, and the feature exists. Without a record of why it was built, you cannot evaluate whether it is still needed, whether it conflicts with a newer direction, or what it was meant to solve.

Governing specs prevent that. Every piece of Traverse has a documented reason for existing. When something changes in a future version, the spec record shows what the original intent was and what the acceptance criteria were. That is useful for contributors, for auditors, and for anyone trying to understand why a design decision was made.

How it relates to contract-driven development

Traverse applies contract-driven thinking at two levels. At the capability level, contracts govern execution. At the project level, governing specs govern implementation. Both are about making intent explicit and machine-checkable before anything runs or ships.

The governing spec process is similar to an Architecture Decision Record (ADR), but it is required for all feature work, not just high-level architectural decisions. That is a higher bar, and it is intentional.

For contributors

If you want to contribute a new feature to Traverse, the first step is drafting a governing spec and opening it for discussion. See the contribution guide for details on the process.