Your business logic runs in the browser, on your server, and in a cloud function. They drift. You maintain three versions of the same behavior. Traverse keeps it in one contract and runs it anywhere — with a full execution trace every time.
Traverse is the working implementation of Universal Microservices Architecture.
Traverse is pre-1.0 (v0.8.1) and evolving under spec-driven governance — every capability below is real, running code, not a plan.
- 8 crates in this repo plus the capability registry (now its own repo, see below) — 7 of these 9 are published on crates.io: runtime, contracts, registry, CLI, MCP server, embedder SDK, and the expedition WASM example.
traverse-native-bridgeandtraverse-swift-hostare newer, not yet published. - 87 approved, immutable specs govern the runtime, contracts, registry, MCP surface, WASM execution, native embedding, and durable local storage. Full list:
jq -r '.specs[].id' specs/governance/approved-specs.json(or see Governance below). - 100% coverage enforced on core logic, spec-alignment and supply-chain gates on every PR, 5-platform CI matrix (Linux x86_64/aarch64, macOS x86_64/arm64, Windows x86_64).
- Capability registry was extracted into its own repo,
traverse-framework/registry, so capabilities can be published, versioned, and consumed independently of the runtime. Browse what's actually published at the live catalog: registry.traverse-framework.com. - Reference apps for multiple platforms (web, iOS, macOS, Android, Windows, Linux, CLI) live in
traverse-framework/reference-apps.
v1.0.0 is gated, not a date — governed by spec 049-v1-milestone-gate and checkable locally with bash scripts/ci/v1_gate_check.sh. It signals stable public API surfaces, every published crate live on crates.io, and the runtime stress-tested on every supported platform. Full gate conditions: docs/v1-milestone.md.
Explicitly not required for v1.0.0: a reference app in this repo (that's reference-apps), an HTTP admin API, a cloud deployment surface, or worker-isolation message passing (planned for v2).
Requirements: Rust 1.94+
git clone https://github.com/traverse-framework/traverse.git
cd traverse
cargo build
cargo run -p traverse-cli-rs -- bundle inspect examples/expedition/registry-bundle/manifest.jsonExpected output:
bundle_id: expedition.planning.seed-bundle
version: 1.0.0
capabilities: 6
events: 5
workflows: 1
You just inspected a live capability bundle — 6 capabilities, 5 events, 1 workflow, all defined in contracts that the runtime validates and executes.
Ready to run the full browser demo? → quickstart.md
Build the UI. Traverse owns execution, workflow state, and trace output. The same capability contract runs locally in development and on the edge in production — no rewrite.
→ quickstart.md · docs/app-consumable-entry-path.md
Expose capability discovery and execution over stdio. Downstream AI clients and tools discover and call governed capabilities without touching your internals.
Package executable behavior as WASM. Traverse validates, places, and runs it — browser, edge, or cloud — under the same contract.
→ docs/wasm-agent-authoring-guide.md
Building with Claude or another coding agent? traverse-framework/claude-skills hosts Claude Skills that walk through checking the registry, authoring and composing capabilities, and validating them against the real traverse-cli — including this platform's current honest limitations.
Model multi-step business behavior as a workflow. The runtime traverses it deterministically and produces a structured trace you can inspect and audit.
→ docs/workflow-composition-guide.md · docs/getting-started.md
cargo run -p traverse-cli-rs -- app new my-appScaffolds a governed app bundle. Add your capability contracts, workflows, and WASM components.
→ docs/expedition-example-authoring.md
| Goal | Start here | Continue with |
|---|---|---|
| First runnable flow | quickstart.md | docs/app-consumable-entry-path.md |
| Learn the core path | docs/getting-started.md | docs/expedition-example-authoring.md |
| Author a capability contract | docs/capability-contract-authoring-guide.md | docs/getting-started.md |
| Author an event contract | docs/event-contract-authoring-guide.md | docs/event-publishing-tutorial.md |
| Build WASM capabilities | docs/wasm-agent-authoring-guide.md | docs/wasm-microservice-authoring-guide.md |
| Integrate a downstream app | docs/app-consumable-consumer-bundle.md | docs/youaskm3-integration-validation.md |
| Troubleshoot a failure | docs/troubleshooting.md | docs/quality-standards.md |
- docs/releases/v0.8.1.md — current release notes
- docs/app-consumable-consumer-bundle.md — versioned consumer bundle
- docs/app-consumable-package-release-pointer.md — package release pointer
- docs/packaged-traverse-runtime-artifact.md — packaged runtime artifact
- docs/packaged-traverse-mcp-server-artifact.md — packaged MCP server artifact
- docs/youaskm3-canonical-app-http-path.md — canonical HTTP app path
- docs/youaskm3-canonical-mcp-client-path.md — canonical MCP client path
- docs/youaskm3-integration-validation.md — youaskm3 integration validation
- docs/youaskm3-published-artifact-validation.md — published-artifact validation
- docs/youaskm3-compatibility-conformance-suite.md — compatibility conformance suite
- docs/youaskm3-real-shell-validation.md — real shell validation
- docs/mcp-real-agent-exercise.md — real AI agent exercise for the MCP surface
- docs/v0.3.0-public-surface-compatibility.md — v0.3.0 public surface compatibility
- docs/v0.3.0-source-build-consumer-packaging.md — source-build packaging for v0.3.0 consumers
- docs/v0.3.0-downstream-validation-path.md — downstream validation path for v0.3.0
- docs/youaskm3-v0.3.0-integration-readiness.md — v0.3.0 integration readiness index
- docs/adapter-boundaries.md — adapter and portability boundaries
- docs/compatibility-policy.md — versioning and compatibility
- docs/troubleshooting.md — shortest path through common failures
- docs/what-can-i-build.md — concrete app and integration patterns
- docs/benchmarks.md — measured latency numbers
- docs/decision-log.md — consolidated architecture decisions
In this repo:
| Crate | Role |
|---|---|
traverse-runtime |
Core execution engine — validates, places, and executes capabilities |
traverse-contracts |
Contract definitions, parsing, and validation |
traverse-cli-rs |
Command-line interface (binary: traverse-cli) — register, list, validate, run |
traverse-mcp |
Model Context Protocol stdio server and governed MCP-facing surface |
traverse-embedder |
Public Rust embedder SDK (embedder-api/1.0.0) for Linux GTK and CLI clients |
traverse-expedition-wasm |
Expedition example domain compiled to wasm32-wasi |
traverse-native-bridge |
Deterministic builder for the governed native runtime WebAssembly bridge |
traverse-swift-host |
Apple static-library feasibility host for the Traverse runtime bridge |
In a separate repo:
| Crate | Repo | Role |
|---|---|---|
traverse-registry |
traverse-framework/registry |
Capability and event registries with deterministic traversal — extracted from this repo (spec 051) so capabilities can be published and versioned independently. Live catalog: registry.traverse-framework.com |
Please read before opening a PR:
All work follows the governance workflow below. Every PR must be backed by an approved spec.
GitHub Project 1 is the canonical board. All active work has an issue, a project item, and a PR.
Traverse is the runtime that Universal Microservices Architecture describes — the answer in working Rust code to the question: how do you keep one business behavior portable and governed as execution moves across browser, edge, cloud, workflows, and AI?
| UMA | Traverse | |
|---|---|---|
| What it is | Architecture model + book | Working runtime implementation |
| Business capabilities | Defines the concept | Executes them with contracts and specs |
| Portability | Describes the pattern | Enforces it through WASM and adapters |
| Governance | Specifies the rules | Implements them as immutable specs and CI gates |
| AI safety | Describes requirements | Delivers through explainable runtime traces |
If you want to understand the ideas: read the UMA book and explore the UMA code examples.
Traverse is spec-driven. Code must align with an approved, immutable spec or it does not merge.
| Artifact | Location | Role |
|---|---|---|
| Specs | specs/ |
Versioned, immutable, merge-gating |
| Contracts | contracts/ |
Source of truth for runtime behavior |
| Constitution | .specify/memory/constitution.md |
Overrides all convenience decisions |
| CI gate | scripts/ci/spec_alignment_check.sh |
Deterministic, AI-agnostic |
87 approved specs currently govern this repo, spanning the runtime, contracts, registry integration, CLI, MCP surface, WASM execution, native embedding, and durable local storage. The list changes as specs are approved — query it instead of reading a snapshot:
jq -r '.specs[].id' specs/governance/approved-specs.jsonFoundational specs worth reading first: 001-foundation-v0-1 (core runtime, CLI, MCP surface), 004-spec-alignment-gate (this CI gate), 049-v1-milestone-gate (what v1.0.0 requires).
This project supports AI-assisted development with Codex and Claude Code running in parallel.
| Agent | File | Purpose |
|---|---|---|
| Claude Code | CLAUDE.md |
Project context, governance rules, speckit workflow |
| Codex | AGENTS.md |
Project context, coordination rules, speckit workflow |
| All agents | .specify/memory/constitution.md |
Governing constitution — mirrors traverse-framework/.github at the version in .governance-version |
- Read your entry point file (
CLAUDE.mdorAGENTS.md) - Claim the ticket — check for
agent:claude/agent:codexlabels and existing branches - Create a feature branch:
NNN-feature-name - Run
.specify/scripts/bash/setup-plan.sh --jsonto initialize the spec directory - Write
specs/<branch>/spec.mdandplan.mdbefore any code - Implement the smallest change that satisfies the spec and contracts
- Open a PR with
## Governing Spec,## Project Item, and## Validationsections
agent:claudelabel = claimed by Claude Code — Codex must skipagent:codexlabel = claimed by Codex — Claude Code must skip- Full coordination rules:
docs/multi-thread-workflow.md