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.
Requirements: Rust 1.94+
git clone https://github.com/traverse-framework/Traverse.git
cd Traverse
cargo build
cargo run -p traverse-cli -- 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
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 -- 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.6.0.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
| Crate | Role |
|---|---|
traverse-runtime |
Core execution engine — validates, places, and executes capabilities |
traverse-contracts |
Contract definitions, parsing, and validation |
traverse-registry |
Capability and event registries with deterministic traversal |
traverse-cli |
Command-line interface: register, list, validate, run |
traverse-mcp |
Model Context Protocol stdio server and governed MCP-facing surface |
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 |
| ID | Spec | Governs |
|---|---|---|
| 001 | foundation-v0-1 | Core runtime, CLI, MCP surface |
| 002 | capability-contracts | Contract definitions and validation |
| 003 | event-contracts | Event contract definitions |
| 004 | spec-alignment-gate | CI merge gate |
| 005 | capability-registry | Registry behavior |
| 006 | runtime-request-execution | Execution model |
| 007 | workflow-registry-traversal | Workflow composition |
| 008 | expedition-example-domain | Example domain |
| 009 | expedition-example-artifacts | Example artifacts |
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 v1.2.0 |
- 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