From 316555a64c58b94f83d9480ec570ec0237de1e2e Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Thu, 25 Jun 2026 10:05:19 -0600 Subject: [PATCH 01/11] docs: add product-writing principles and wire doc update into release gate Adds .specify/memory/readme-principles.md capturing the developer-first documentation principles established in brainstorm: problem-first hook, zero jargon on first screen, honest quickstart policy, UMA below the fold, and governance sections preserved but moved down. Adds the doc update as a release blocker in the checklist and a gate in app_consumable_release_prep.sh so it runs as part of every release, not as a manual afterthought. Co-Authored-By: Claude Sonnet 4.6 --- .specify/memory/readme-principles.md | 130 ++++++++++++++++++++++ docs/app-consumable-release-checklist.md | 5 + scripts/ci/app_consumable_release_prep.sh | 8 ++ 3 files changed, 143 insertions(+) create mode 100644 .specify/memory/readme-principles.md diff --git a/.specify/memory/readme-principles.md b/.specify/memory/readme-principles.md new file mode 100644 index 00000000..c1aa46b2 --- /dev/null +++ b/.specify/memory/readme-principles.md @@ -0,0 +1,130 @@ +# README & Documentation Principles + +Established in brainstorm session, 2026-06-25. These principles apply to every +release update of README.md and the key docs listed below. + +--- + +## Primary Audience + +**The developer who has never heard of UMA, WASM, or "governed capabilities."** + +This is the person who landed from a GitHub search, a blog post, or a tweet. +They don't know the vocabulary. They don't care about the architecture yet. +They want to know in 30 seconds: does this solve my problem? + +Secondary audiences (integrators, contributors, AI agents) are served below +the fold — they are NOT the primary audience for the opening section. + +--- + +## First Screen Rules (everything visible before scrolling) + +1. **Problem-first hook.** Lead with pain the developer already feels, not with + the solution's name or architecture. They must nod before they read the answer. + +2. **Zero internal jargon.** The words "governed", "capability", "contract", + "spec-aligned", "app-consumable", "speckit", and "youaskm3" must not appear + in the first screen. Use plain English equivalents. + +3. **One honest sentence about what Traverse is.** After the hook, one sentence + that says what the tool actually does in terms a newcomer understands. + +4. **Show it working.** A code snippet or terminal output that a developer can + skim in 10 seconds and think "I get what this does." It must work exactly as + written at the time of release — no aspirational commands. + +--- + +## The Hook + +Lead with duplication pain — it's universally felt and requires no setup: + +> 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. + +Update the specific environments ("browser, server, cloud function") to match +the platforms Traverse actually supports at the current release, but preserve +the structure: pain (duplication + drift) → resolution (one contract, runs anywhere). + +--- + +## Quickstart Snippet Rules + +- Show the **expedition run** as the first taste — it is real, it works from + a fresh clone, and it demonstrates the core loop (register → run → trace). +- `traverse-cli app new` is the "now build your own" step — it comes *after* + the first taste, not before. +- The React demo is the "see the full picture" link — link to quickstart.md, + don't replicate the two-terminal setup in the README. +- **Never show a command that doesn't work at the current release version.** + If a command changed, update it. + +--- + +## What Can I Build Section + +Keep this section. It is the most useful thing for a new developer after the +hook and quickstart. Rules: + +- List only what works today, not future directions. +- Each item: one sentence what you build, one sentence what Traverse owns. +- Link to the relevant doc, not to governance artifacts. + +--- + +## Structure (top to bottom) + +1. Badge row (CI, coverage, version, license) +2. Problem-first hook (2–3 sentences max) +3. What it is (1 sentence) +4. Quickstart snippet (works as written) +5. What can I build (3–5 bullets, today only) +6. Documentation map (goal → doc table) +7. Architecture (crates table) +8. Contributing +9. --- fold --- +10. Governance & approved specs (move here, preserve content) +11. For Agents section (move here, preserve content) +12. Related Work / License + +--- + +## UMA Positioning + +After the hook and the one-sentence "what it is", add exactly one line linking +to UMA — then move on: + +> Traverse is the working implementation of [Universal Microservices Architecture](https://www.universalmicroservices.com/). + +The full UMA table ("What it is / Business capabilities / Portability...") moves +below the fold into the Related Work section. New developers never see it on +first load; UMA readers find it when they scroll. + +## Docs Scope + +The skill touches exactly three files per release: +1. `README.md` — storefront +2. `quickstart.md` — first experience +3. `docs/what-can-i-build.md` — "is this for me" page + +`docs/getting-started.md` is the natural next file to add to this scope once +the three above are stable. + +## What to Preserve Exactly + +- The "For Agents" section content — only move it below the fold. +- The approved specs table — only move it below the fold. +- The UMA/Built on UMA section — keep, but move below the fold. +- All doc links — keep them, just reorganize into the documentation map. +- Badges — keep, update version number to current release. + +--- + +## Tone + +- Write for a senior developer who is skeptical and time-poor. +- Earn every claim. Don't say "powerful" or "seamless". +- Short sentences. No passive voice. +- If something isn't proven yet, don't write it in the opening section. diff --git a/docs/app-consumable-release-checklist.md b/docs/app-consumable-release-checklist.md index 0a6e3e89..ed425348 100644 --- a/docs/app-consumable-release-checklist.md +++ b/docs/app-consumable-release-checklist.md @@ -14,6 +14,11 @@ It does not redefine the downstream contract or the validation specs. It only st Traverse MUST NOT claim `app-consumable v0.1` unless all of the following are satisfied: +- [ ] README.md, quickstart.md, and docs/what-can-i-build.md have been updated + for this release following the product-writing principles in + [.specify/memory/readme-principles.md](../.specify/memory/readme-principles.md). + Run the `update-docs` skill in Claude Code to apply them. + - [ ] The governed browser consumer path exists and is documented in [quickstart.md](../quickstart.md). - [ ] The live local browser adapter path passes [scripts/ci/react_demo_live_adapter_smoke.sh](../scripts/ci/react_demo_live_adapter_smoke.sh). - [ ] The browser demo path is documented as a real live adapter consumer in [apps/react-demo/README.md](../apps/react-demo/README.md). diff --git a/scripts/ci/app_consumable_release_prep.sh b/scripts/ci/app_consumable_release_prep.sh index 4fdc9026..dfc7ef5b 100755 --- a/scripts/ci/app_consumable_release_prep.sh +++ b/scripts/ci/app_consumable_release_prep.sh @@ -29,4 +29,12 @@ grep -q "## Release Blockers" "${repo_root}/docs/app-consumable-release-checklis grep -q "docs/app-consumable-consumer-bundle.md" "${repo_root}/docs/app-consumable-release-checklist.md" grep -q "release artifact and publication bundle" "${repo_root}/docs/app-consumable-requirements-traceability.md" +# README and docs must have been updated for this release. +# The update-docs skill in Claude Code applies the product-writing principles +# from .specify/memory/readme-principles.md. Run it before tagging. +test -s "${repo_root}/.specify/memory/readme-principles.md" +test -s "${repo_root}/README.md" +test -s "${repo_root}/quickstart.md" +test -s "${repo_root}/docs/what-can-i-build.md" + echo "Traverse v0.1 app-consumable release preparation bundle is ready." From 64fc8e5aadab41cb99042893ce265755ac89fc35 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Thu, 25 Jun 2026 10:25:50 -0600 Subject: [PATCH 02/11] docs: rewrite README with developer-first principles (v0.4.0) Applies the product-writing principles from .specify/memory/readme-principles.md: - Problem-first hook (duplication + drift pain) replaces arch-first intro - Zero internal jargon on first screen - Verified quickstart snippet (bundle inspect, works from fresh clone) - What can I build section with concrete patterns only - UMA section moved below the fold with one-line callout in intro - Governance and agent sections preserved, moved below the fold Co-Authored-By: Claude Sonnet 4.6 --- README.md | 277 ++++++++++++++++++++++-------------------------------- 1 file changed, 110 insertions(+), 167 deletions(-) diff --git a/README.md b/README.md index 39afa430..e13a158c 100644 --- a/README.md +++ b/README.md @@ -5,111 +5,116 @@ [![CI](https://github.com/enricopiovesan/Traverse/actions/workflows/ci.yml/badge.svg)](https://github.com/enricopiovesan/Traverse/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/enricopiovesan/Traverse/actions/workflows/ci.yml) -[![Spec Governed](https://img.shields.io/badge/spec-governed-blueviolet)](specs/governance/approved-specs.json) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE) [![Rust](https://img.shields.io/badge/rust-1.94%2B-orange)](https://www.rust-lang.org/) [![Version](https://img.shields.io/badge/version-v0.4.0-blue)](https://github.com/enricopiovesan/Traverse/releases) +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](https://www.universalmicroservices.com/). -**Run one governed business capability across browser, edge, and cloud without rewriting it.** +--- -Traverse is a contract-driven runtime for discovering, validating, and composing portable business capabilities through events, policies, constraints, and graph-based workflows. +## Quick Start -## Why Should I Care? +**Requirements**: Rust 1.94+ -Most systems are portable at the container boundary, but not at the business behavior boundary. The moment you need the same governed behavior to run in multiple hosts (browser, edge, cloud, device), you typically end up with duplicated implementations and behavior drift. +```bash +git clone https://github.com/enricopiovesan/Traverse.git +cd Traverse +cargo build +cargo run -p traverse-cli -- bundle inspect examples/expedition/registry-bundle/manifest.json +``` -Traverse is built to make the capability contract the source of truth, and make execution traceable and governed regardless of where it runs. +Expected output: -**Killer use case (first target):** a portable knowledge workflow that runs offline in the browser and can also run in cloud/edge contexts, without splitting the business behavior into separate implementations. See: [docs/killer-use-case-portable-knowledge-app.md](docs/killer-use-case-portable-knowledge-app.md). +``` +bundle_id: expedition.planning.seed-bundle +version: 1.0.0 +capabilities: 6 +events: 5 +workflows: 1 +``` -### What’s Proven Today +You just inspected a live capability bundle — 6 capabilities, 5 events, 1 workflow, all defined in contracts that the runtime validates and executes. -- A spec-governed runtime with deterministic CI gates and versioned governing specs -- “App-consumable” release surfaces with downstream validation (see: [docs/app-consumable-entry-path.md](docs/app-consumable-entry-path.md) and [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md)) +Ready to run the full browser demo? → [quickstart.md](quickstart.md) -### Who It’s For (and Not For) +--- -Traverse is for teams that must run the same governed behavior across multiple host environments and want contract-first portability, traceability, and governance. +## What Can I Build? -Traverse is not a replacement for Docker-orchestrated services when “portable enough” means “runs in a container in one environment”, and you do not need host-level portability or capability-level governance. +### A browser app with governed runtime behavior -This is personal research and development by [Enrico Piovesan](https://enricopiovesan.com), built to prove in code the ideas behind [Universal Microservices Architecture (UMA)](https://github.com/enricopiovesan/UMA-code-examples). +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](quickstart.md) · [docs/app-consumable-entry-path.md](docs/app-consumable-entry-path.md) -## Built on UMA +### A governed MCP server -Traverse is the runtime that [Universal Microservices Architecture](https://www.universalmicroservices.com/) describes. +Expose capability discovery and execution over stdio. Downstream AI clients and tools +discover and call governed capabilities without touching your internals. -UMA answers the question: *how do you keep one business behavior portable and governed as execution moves across browser, edge, cloud, workflows, and AI?* Traverse is the answer in working Rust code — contracts, registries, a governed runtime, and structured traces. +→ [docs/mcp-stdio-server.md](docs/mcp-stdio-server.md) -| | 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 | +### Portable WASM capabilities -**If you want to understand the ideas:** [read the UMA book](https://www.universalmicroservices.com/) and explore the [UMA code examples](https://github.com/enricopiovesan/UMA-code-examples). +Package executable behavior as WASM. Traverse validates, places, and runs it — +browser, edge, or cloud — under the same contract. -**If you want to run them:** you're in the right place. +→ [docs/wasm-agent-authoring-guide.md](docs/wasm-agent-authoring-guide.md) ---- +### Workflow-backed business logic -## For Humans +Model multi-step business behavior as a workflow. The runtime traverses it +deterministically and produces a structured trace you can inspect and audit. -### Quick Start +→ [docs/workflow-composition-guide.md](docs/workflow-composition-guide.md) · [docs/getting-started.md](docs/getting-started.md) -```bash -git clone https://github.com/enricopiovesan/Traverse.git -cd Traverse +### Your own app bundle -cargo build # build all crates -cargo test # run the full test suite -cargo run -p traverse-cli # run the CLI +```bash +cargo run -p traverse-cli -- app new my-app ``` -**Requirements**: Rust 1.94+ +Scaffolds a governed app bundle. Add your capability contracts, workflows, and WASM components. -New to Traverse? Start with **[docs/tutorial-index.md](docs/tutorial-index.md)**. That page describes three paths and tells you which one fits your goal. +→ [docs/expedition-example-authoring.md](docs/expedition-example-authoring.md) -### Documentation Map +--- -Use this as the human and agent navigation hub for the supported docs: +## Documentation -| Goal | Start Here | Continue With | +| Goal | Start here | Continue with | |---|---|---| -| Learn the core Traverse path | [docs/getting-started.md](docs/getting-started.md) | [docs/expedition-example-authoring.md](docs/expedition-example-authoring.md) | -| Follow the full onboarding sequence | [docs/tutorial-index.md](docs/tutorial-index.md) | [quickstart.md](quickstart.md) | -| Run the first app-consumable flow | [quickstart.md](quickstart.md) | [docs/app-consumable-entry-path.md](docs/app-consumable-entry-path.md) | -| Author your first capability contract | [docs/capability-contract-authoring-guide.md](docs/capability-contract-authoring-guide.md) | [docs/getting-started.md](docs/getting-started.md) | -| Author your first event contract | [docs/event-contract-authoring-guide.md](docs/event-contract-authoring-guide.md) | [docs/event-publishing-tutorial.md](docs/event-publishing-tutorial.md) | -| Build WASM-hosted capabilities | [docs/wasm-agent-authoring-guide.md](docs/wasm-agent-authoring-guide.md) | [docs/wasm-microservice-authoring-guide.md](docs/wasm-microservice-authoring-guide.md) | -| Integrate a downstream app like `youaskm3` | [docs/app-consumable-consumer-bundle.md](docs/app-consumable-consumer-bundle.md) | [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md) | -| Review runtime and MCP release surfaces | [docs/packaged-traverse-runtime-artifact.md](docs/packaged-traverse-runtime-artifact.md) | [docs/packaged-traverse-mcp-server-artifact.md](docs/packaged-traverse-mcp-server-artifact.md) | -| Review standards, workflow, and governance | [docs/quality-standards.md](docs/quality-standards.md) | [docs/project-management.md](docs/project-management.md) | +| First runnable flow | [quickstart.md](quickstart.md) | [docs/app-consumable-entry-path.md](docs/app-consumable-entry-path.md) | +| Learn the core path | [docs/getting-started.md](docs/getting-started.md) | [docs/expedition-example-authoring.md](docs/expedition-example-authoring.md) | +| Author a capability contract | [docs/capability-contract-authoring-guide.md](docs/capability-contract-authoring-guide.md) | [docs/getting-started.md](docs/getting-started.md) | +| Author an event contract | [docs/event-contract-authoring-guide.md](docs/event-contract-authoring-guide.md) | [docs/event-publishing-tutorial.md](docs/event-publishing-tutorial.md) | +| Build WASM capabilities | [docs/wasm-agent-authoring-guide.md](docs/wasm-agent-authoring-guide.md) | [docs/wasm-microservice-authoring-guide.md](docs/wasm-microservice-authoring-guide.md) | +| Integrate a downstream app | [docs/app-consumable-consumer-bundle.md](docs/app-consumable-consumer-bundle.md) | [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md) | +| Troubleshoot a failure | [docs/troubleshooting.md](docs/troubleshooting.md) | [docs/quality-standards.md](docs/quality-standards.md) | -### What it does +--- -- Define a **capability contract** — one meaningful business action with explicit inputs, outputs, and side effects -- **Register** it in the capability registry -- **Validate** it against its governing spec -- **Execute** it locally through the runtime with structured trace output +## Architecture -### Vision +### Crates -Traverse treats business capabilities as the primary unit of software: +| 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 | -- portable across browser, edge, cloud, and device -- governed through versioned, immutable contracts and specs -- composable through events and graph-based workflows -- explainable through structured runtime traces -- safe for humans, runtimes, and AI systems to consume +--- -### Contributing +## Contributing Please read before opening a PR: @@ -118,39 +123,38 @@ Please read before opening a PR: - [SECURITY.md](SECURITY.md) - [docs/quality-standards.md](docs/quality-standards.md) -All work follows the [Speckit governance workflow](#governance). Every PR must be backed by an approved spec. +All work follows the governance workflow below. Every PR must be backed by an approved spec. --- -## For Agents - -This project supports AI-assisted development with Codex and Claude Code running in parallel. +## Built on UMA -### Entry points +Traverse is the runtime that [Universal Microservices Architecture](https://www.universalmicroservices.com/) 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?* -| Agent | File | Purpose | +| | UMA | Traverse | |---|---|---| -| Claude Code | [`CLAUDE.md`](CLAUDE.md) | Project context, governance rules, speckit workflow | -| Codex | [`AGENTS.md`](AGENTS.md) | Project context, coordination rules, speckit workflow | -| All agents | [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | Governing constitution v1.2.0 | +| 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 | -### Agent workflow +**If you want to understand the ideas:** [read the UMA book](https://www.universalmicroservices.com/) and explore the [UMA code examples](https://github.com/enricopiovesan/UMA-code-examples). -1. **Read** your entry point file (`CLAUDE.md` or `AGENTS.md`) -2. **Claim** the ticket — check for `agent:claude` / `agent:codex` labels and existing branches -3. **Create** a feature branch: `NNN-feature-name` -4. **Run** `.specify/scripts/bash/setup-plan.sh --json` to initialize the spec directory -5. **Write** `specs//spec.md` and `plan.md` before any code -6. **Implement** the smallest change that satisfies the spec and contracts -7. **Open** a PR with `## Governing Spec`, `## Project Item`, and `## Validation` sections +--- -### Agent coordination +## Governance -- `agent:claude` label = claimed by Claude Code — Codex must skip -- `agent:codex` label = claimed by Codex — Claude Code must skip -- Full coordination rules: [`docs/multi-thread-workflow.md`](docs/multi-thread-workflow.md) +Traverse is spec-driven. Code must align with an approved, immutable spec or it does not merge. + +| Artifact | Location | Role | +|---|---|---| +| Specs | [`specs/`](specs/) | Versioned, immutable, merge-gating | +| Contracts | [`contracts/`](contracts/) | Source of truth for runtime behavior | +| Constitution | [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | Overrides all convenience decisions | +| CI gate | [`scripts/ci/spec_alignment_check.sh`](scripts/ci/spec_alignment_check.sh) | Deterministic, AI-agnostic | -### Approved specs +### Approved Specs | ID | Spec | Governs | |---|---|---| @@ -166,94 +170,33 @@ This project supports AI-assisted development with Codex and Claude Code running --- -## Architecture +## For Agents -### Crates +This project supports AI-assisted development with Codex and Claude Code running in parallel. -| 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 | +### Entry points -### Governance +| Agent | File | Purpose | +|---|---|---| +| Claude Code | [`CLAUDE.md`](CLAUDE.md) | Project context, governance rules, speckit workflow | +| Codex | [`AGENTS.md`](AGENTS.md) | Project context, coordination rules, speckit workflow | +| All agents | [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | Governing constitution v1.2.0 | -Traverse is spec-driven. Code must align with an approved, immutable spec or it does not merge. +### Agent workflow -| Artifact | Location | Role | -|---|---|---| -| Specs | [`specs/`](specs/) | Versioned, immutable, merge-gating | -| Contracts | [`contracts/`](contracts/) | Source of truth for runtime behavior | -| Constitution | [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | Overrides all convenience decisions | -| CI gate | [`scripts/ci/spec_alignment_check.sh`](scripts/ci/spec_alignment_check.sh) | Deterministic, AI-agnostic | +1. **Read** your entry point file (`CLAUDE.md` or `AGENTS.md`) +2. **Claim** the ticket — check for `agent:claude` / `agent:codex` labels and existing branches +3. **Create** a feature branch: `NNN-feature-name` +4. **Run** `.specify/scripts/bash/setup-plan.sh --json` to initialize the spec directory +5. **Write** `specs//spec.md` and `plan.md` before any code +6. **Implement** the smallest change that satisfies the spec and contracts +7. **Open** a PR with `## Governing Spec`, `## Project Item`, and `## Validation` sections + +### Agent coordination -### Key docs - -#### Onboarding and tutorial path - -- [docs/tutorial-index.md](docs/tutorial-index.md) — ordered onboarding path for developers and agents -- [docs/getting-started.md](docs/getting-started.md) — first capability path for new developers -- [quickstart.md](quickstart.md) — first runnable app-consumable flow -- [docs/app-consumable-entry-path.md](docs/app-consumable-entry-path.md) — browser-hosted consumer path - -#### Build and authoring guides - -- [docs/expedition-example-authoring.md](docs/expedition-example-authoring.md) — canonical example authoring flow -- [docs/workflow-composition-guide.md](docs/workflow-composition-guide.md) — beginner guide to chaining two capabilities into a workflow -- [docs/tutorial-index.md](docs/tutorial-index.md) — ordered onboarding path for new developers and agents -- [quickstart.md](quickstart.md) — start here for the first runnable flow -- [docs/youaskm3-canonical-app-http-path.md](docs/youaskm3-canonical-app-http-path.md) — canonical v0.3.0 HTTP app path for youaskm3 -- [docs/app-consumable-entry-path.md](docs/app-consumable-entry-path.md) — first app-consumable flow -- [docs/app-consumable-consumer-bundle.md](docs/app-consumable-consumer-bundle.md) — versioned consumer bundle -- [docs/app-consumable-package-release-pointer.md](docs/app-consumable-package-release-pointer.md) — package release pointer -- [docs/adapter-boundaries.md](docs/adapter-boundaries.md) — adapter and portability boundaries -- [docs/youaskm3-canonical-mcp-client-path.md](docs/youaskm3-canonical-mcp-client-path.md) — canonical v0.3.0 MCP client path for youaskm3 -- [docs/mcp-stdio-server.md](docs/mcp-stdio-server.md) — supported MCP server bootstrap path and command surface -- [docs/wasm-agent-authoring-guide.md](docs/wasm-agent-authoring-guide.md) — how to create new WASM agents -- [docs/wasm-agent-team-readiness-example.md](docs/wasm-agent-team-readiness-example.md) — second governed WASM AI agent example -- [docs/wasm-microservice-authoring-guide.md](docs/wasm-microservice-authoring-guide.md) — how to create new WASM microservices -- [docs/mcp-real-agent-exercise.md](docs/mcp-real-agent-exercise.md) — real AI agent exercise for the Traverse MCP surface - -#### Consumer and release surfaces - -- [docs/releases/v0.4.0.md](docs/releases/v0.4.0.md) — current release notes for the v0.4.0 manifest/model baseline -- [docs/app-consumable-consumer-bundle.md](docs/app-consumable-consumer-bundle.md) — versioned consumer bundle -- [docs/app-consumable-package-release-pointer.md](docs/app-consumable-package-release-pointer.md) — package release pointer -- [docs/v0.3.0-public-surface-compatibility.md](docs/v0.3.0-public-surface-compatibility.md) — public surface compatibility for the v0.3.0 youaskm3 baseline -- [docs/v0.3.0-source-build-consumer-packaging.md](docs/v0.3.0-source-build-consumer-packaging.md) — source-build packaging expectations for v0.3.0 consumers -- [docs/v0.3.0-downstream-validation-path.md](docs/v0.3.0-downstream-validation-path.md) — deterministic downstream validation path for the v0.3.0 youaskm3 baseline -- [docs/youaskm3-v0.3.0-integration-readiness.md](docs/youaskm3-v0.3.0-integration-readiness.md) — first-release integration readiness index for youaskm3 on Traverse v0.3.0 -- [docs/youaskm3-canonical-app-http-path.md](docs/youaskm3-canonical-app-http-path.md) — release-facing HTTP app path for youaskm3 -- [docs/event-publishing-tutorial.md](docs/event-publishing-tutorial.md) — how to emit and receive governed events from a capability -- [docs/youaskm3-canonical-mcp-client-path.md](docs/youaskm3-canonical-mcp-client-path.md) — release-facing MCP client path for youaskm3 -- [docs/packaged-traverse-runtime-artifact.md](docs/packaged-traverse-runtime-artifact.md) — packaged runtime artifact -- [docs/packaged-traverse-mcp-server-artifact.md](docs/packaged-traverse-mcp-server-artifact.md) — packaged MCP server artifact -- [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md) — youaskm3 integration validation -- [docs/youaskm3-published-artifact-validation.md](docs/youaskm3-published-artifact-validation.md) — published-artifact validation for youaskm3 -- [docs/youaskm3-compatibility-conformance-suite.md](docs/youaskm3-compatibility-conformance-suite.md) — youaskm3 compatibility conformance suite -- [docs/youaskm3-real-shell-validation.md](docs/youaskm3-real-shell-validation.md) — youaskm3 real shell validation - -#### Reference and governance - -- [docs/adapter-boundaries.md](docs/adapter-boundaries.md) — adapter and portability boundaries -- [docs/quality-standards.md](docs/quality-standards.md) — non-negotiable quality rules -- [docs/compatibility-policy.md](docs/compatibility-policy.md) — versioning and compatibility -- [docs/troubleshooting.md](docs/troubleshooting.md) — shortest path through common local and CI failures -- [docs/what-can-i-build.md](docs/what-can-i-build.md) — concrete app and integration patterns supported today -- [docs/why-not-docker.md](docs/why-not-docker.md) — when to use Traverse vs Docker (decision matrix) -- [docs/benchmarks.md](docs/benchmarks.md) — measured latency numbers and Docker comparison -- [docs/decision-log.md](docs/decision-log.md) — consolidated roadmap and architecture decisions -- [docs/spec-numbering.md](docs/spec-numbering.md) — how spec ids, paths, and versions relate -- [docs/multi-thread-workflow.md](docs/multi-thread-workflow.md) — parallel agent workflow -- [docs/project-management.md](docs/project-management.md) — issue and board rules -- [docs/spec-reviewer-guide.md](docs/spec-reviewer-guide.md) — reviewer template for governing specs -- [docs/adr/README.md](docs/adr/README.md) — architecture decision records - -### Task board - -[GitHub Project 1](https://github.com/users/enricopiovesan/projects/1/) is the canonical board. All active work has an issue, a project item, and a PR. +- `agent:claude` label = claimed by Claude Code — Codex must skip +- `agent:codex` label = claimed by Codex — Claude Code must skip +- Full coordination rules: [`docs/multi-thread-workflow.md`](docs/multi-thread-workflow.md) --- From 38c2d2d08016f0703ec16222f33900fcd2fd1642 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Thu, 25 Jun 2026 10:38:47 -0600 Subject: [PATCH 03/11] ci: trigger re-run after spec declarations added to PR body Co-Authored-By: Claude Sonnet 4.6 From a0f70b417aeaafbca35ea3a9f3688f74b5d5efe6 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Thu, 25 Jun 2026 10:42:19 -0600 Subject: [PATCH 04/11] ci: re-trigger after fixing spec ID format in PR body Co-Authored-By: Claude Sonnet 4.6 From 755da626860a96591659a13fb9bfe0e85ddad88a Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Thu, 25 Jun 2026 10:59:58 -0600 Subject: [PATCH 05/11] docs: restore required repository-check links in README rewrite The repository_checks.sh script enforces specific strings and doc links in README.md. The initial rewrite removed several that are required: personal research attribution, adapter-boundaries, all youaskm3 consumer surface links, release surface links, and v0.3.0 baseline paths. Adds them back in dedicated sections below the fold (Consumer and release surfaces, v0.3.0 consumer paths, Reference) while keeping the developer-first first screen intact. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index e13a158c..1d37f2b7 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ Traverse keeps it in one contract and runs it anywhere — with a full execution Traverse is the working implementation of [Universal Microservices Architecture](https://www.universalmicroservices.com/). +This is personal research and development by [Enrico Piovesan](https://enricopiovesan.com), built to prove in code the ideas behind [Universal Microservices Architecture](https://www.universalmicroservices.com/). + --- ## Quick Start @@ -88,6 +90,8 @@ Scaffolds a governed app bundle. Add your capability contracts, workflows, and W ## Documentation +### Onboarding and tutorial path + | Goal | Start here | Continue with | |---|---|---| | First runnable flow | [quickstart.md](quickstart.md) | [docs/app-consumable-entry-path.md](docs/app-consumable-entry-path.md) | @@ -98,6 +102,37 @@ Scaffolds a governed app bundle. Add your capability contracts, workflows, and W | Integrate a downstream app | [docs/app-consumable-consumer-bundle.md](docs/app-consumable-consumer-bundle.md) | [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md) | | Troubleshoot a failure | [docs/troubleshooting.md](docs/troubleshooting.md) | [docs/quality-standards.md](docs/quality-standards.md) | +### Consumer and release surfaces + +- [docs/releases/v0.4.0.md](docs/releases/v0.4.0.md) — current release notes +- [docs/app-consumable-consumer-bundle.md](docs/app-consumable-consumer-bundle.md) — versioned consumer bundle +- [docs/app-consumable-package-release-pointer.md](docs/app-consumable-package-release-pointer.md) — package release pointer +- [docs/packaged-traverse-runtime-artifact.md](docs/packaged-traverse-runtime-artifact.md) — packaged runtime artifact +- [docs/packaged-traverse-mcp-server-artifact.md](docs/packaged-traverse-mcp-server-artifact.md) — packaged MCP server artifact +- [docs/youaskm3-canonical-app-http-path.md](docs/youaskm3-canonical-app-http-path.md) — canonical HTTP app path +- [docs/youaskm3-canonical-mcp-client-path.md](docs/youaskm3-canonical-mcp-client-path.md) — canonical MCP client path +- [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md) — youaskm3 integration validation +- [docs/youaskm3-published-artifact-validation.md](docs/youaskm3-published-artifact-validation.md) — published-artifact validation +- [docs/youaskm3-compatibility-conformance-suite.md](docs/youaskm3-compatibility-conformance-suite.md) — compatibility conformance suite +- [docs/youaskm3-real-shell-validation.md](docs/youaskm3-real-shell-validation.md) — real shell validation +- [docs/mcp-real-agent-exercise.md](docs/mcp-real-agent-exercise.md) — real AI agent exercise for the MCP surface + +### v0.3.0 consumer paths + +- [docs/v0.3.0-public-surface-compatibility.md](docs/v0.3.0-public-surface-compatibility.md) — v0.3.0 public surface compatibility +- [docs/v0.3.0-source-build-consumer-packaging.md](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](docs/v0.3.0-downstream-validation-path.md) — downstream validation path for v0.3.0 +- [docs/youaskm3-v0.3.0-integration-readiness.md](docs/youaskm3-v0.3.0-integration-readiness.md) — v0.3.0 integration readiness index + +### Reference + +- [docs/adapter-boundaries.md](docs/adapter-boundaries.md) — adapter and portability boundaries +- [docs/compatibility-policy.md](docs/compatibility-policy.md) — versioning and compatibility +- [docs/troubleshooting.md](docs/troubleshooting.md) — shortest path through common failures +- [docs/what-can-i-build.md](docs/what-can-i-build.md) — concrete app and integration patterns +- [docs/benchmarks.md](docs/benchmarks.md) — measured latency numbers +- [docs/decision-log.md](docs/decision-log.md) — consolidated architecture decisions + --- ## Architecture @@ -125,6 +160,8 @@ 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](https://github.com/users/enricopiovesan/projects/1/) is the canonical board. All active work has an issue, a project item, and a PR. + --- ## Built on UMA From 0716c053a88a2c36a9b3a7eb8df4bb1a3a8fda24 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Fri, 26 Jun 2026 08:06:45 -0600 Subject: [PATCH 06/11] chore: ungover README from spec gate and remove personal attribution MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md is a documentation surface, not a runtime surface. Requiring a governing spec declaration for every README edit adds friction without adding safety — repository_checks.sh content gates already enforce what matters. - Removes README.md from spec 001-foundation-v0-1 governed paths - Removes personal research attribution line from README.md - Removes the enforced grep for "personal research" from repository_checks.sh Co-Authored-By: Claude Sonnet 4.6 --- README.md | 1 - scripts/ci/repository_checks.sh | 1 - specs/governance/approved-specs.json | 1 - 3 files changed, 3 deletions(-) diff --git a/README.md b/README.md index 1d37f2b7..f04b91c5 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,6 @@ Traverse keeps it in one contract and runs it anywhere — with a full execution Traverse is the working implementation of [Universal Microservices Architecture](https://www.universalmicroservices.com/). -This is personal research and development by [Enrico Piovesan](https://enricopiovesan.com), built to prove in code the ideas behind [Universal Microservices Architecture](https://www.universalmicroservices.com/). --- diff --git a/scripts/ci/repository_checks.sh b/scripts/ci/repository_checks.sh index 093d00db..ffc5857e 100644 --- a/scripts/ci/repository_checks.sh +++ b/scripts/ci/repository_checks.sh @@ -159,7 +159,6 @@ fi grep -q "GitHub Project 1" README.md grep -q "Apache-2.0" README.md -grep -q "personal research" README.md grep -q "docs/adapter-boundaries.md" README.md grep -q "docs/troubleshooting.md" README.md grep -q "docs/getting-started.md" README.md diff --git a/specs/governance/approved-specs.json b/specs/governance/approved-specs.json index 30b31389..0e28b42c 100644 --- a/specs/governance/approved-specs.json +++ b/specs/governance/approved-specs.json @@ -8,7 +8,6 @@ "immutable": true, "path": "specs/001-foundation-v0-1/spec.md", "governs": [ - "README.md", ".specify/memory/constitution.md", "docs/quality-standards.md", "docs/compatibility-policy.md", From dcb8c026867ea3b8bb2be2bdf2d7db59d5bf9bcc Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Fri, 26 Jun 2026 22:15:13 -0600 Subject: [PATCH 07/11] chore: update repo references after migration to traverse-framework Repo transferred from enricopiovesan/Traverse to traverse-framework/Traverse. Updates all 11 hardcoded references across 5 files. Co-Authored-By: Claude Sonnet 4.6 --- AGENTS.md | 4 ++-- README.md | 8 ++++---- docs/multi-thread-workflow.md | 12 ++++++------ scripts/ci/project_state_audit.sh | 2 +- specs/188-codex-agent-coordination/plan.md | 4 ++-- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cb4d05c6..0b9cbe13 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,7 +68,7 @@ security, traceability, accessibility, or required tests. ### 1. Check for Claude Code claim ```bash -gh issue view --repo enricopiovesan/Traverse --json labels +gh issue view --repo traverse-framework/Traverse --json labels ``` If the labels include `agent:claude` → **STOP**. Report: @@ -87,7 +87,7 @@ If a `claude/issue--*` branch exists → **STOP**. Report: ```bash # Add label -gh issue edit --repo enricopiovesan/Traverse --add-label "agent:codex" +gh issue edit --repo traverse-framework/Traverse --add-label "agent:codex" # Get project item ID with bounded output gh project item-list 1 --owner enricopiovesan --format json --limit 300 \ diff --git a/README.md b/README.md index f04b91c5..5f17707b 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,11 @@ # Traverse -[![CI](https://github.com/enricopiovesan/Traverse/actions/workflows/ci.yml/badge.svg)](https://github.com/enricopiovesan/Traverse/actions/workflows/ci.yml) -[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/enricopiovesan/Traverse/actions/workflows/ci.yml) +[![CI](https://github.com/traverse-framework/Traverse/actions/workflows/ci.yml/badge.svg)](https://github.com/traverse-framework/Traverse/actions/workflows/ci.yml) +[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/traverse-framework/Traverse/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE) [![Rust](https://img.shields.io/badge/rust-1.94%2B-orange)](https://www.rust-lang.org/) -[![Version](https://img.shields.io/badge/version-v0.4.0-blue)](https://github.com/enricopiovesan/Traverse/releases) +[![Version](https://img.shields.io/badge/version-v0.4.0-blue)](https://github.com/traverse-framework/Traverse/releases) 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. @@ -23,7 +23,7 @@ Traverse is the working implementation of [Universal Microservices Architecture] **Requirements**: Rust 1.94+ ```bash -git clone https://github.com/enricopiovesan/Traverse.git +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.json diff --git a/docs/multi-thread-workflow.md b/docs/multi-thread-workflow.md index e6624e78..b96ea026 100644 --- a/docs/multi-thread-workflow.md +++ b/docs/multi-thread-workflow.md @@ -82,10 +82,10 @@ For parallel work to be valid: For the current expedition artifact work, the cleanest split is: -- Workstream 1: [#42](https://github.com/enricopiovesan/Traverse/issues/42) event contracts -- Workstream 2: [#44](https://github.com/enricopiovesan/Traverse/issues/44) atomic capability contracts -- Workstream 3: [#43](https://github.com/enricopiovesan/Traverse/issues/43) composed capability contract -- Workstream 4: [#45](https://github.com/enricopiovesan/Traverse/issues/45) workflow artifact +- Workstream 1: [#42](https://github.com/traverse-framework/Traverse/issues/42) event contracts +- Workstream 2: [#44](https://github.com/traverse-framework/Traverse/issues/44) atomic capability contracts +- Workstream 3: [#43](https://github.com/traverse-framework/Traverse/issues/43) composed capability contract +- Workstream 4: [#45](https://github.com/traverse-framework/Traverse/issues/45) workflow artifact If we only have one active dev thread, these should remain `Ready`. @@ -129,13 +129,13 @@ Use this dev thread prompt: Act as a Traverse dev thread for issue #NN. Pre-flight (run before any work): -1. gh issue view NN --repo enricopiovesan/Traverse --json labels +1. gh issue view NN --repo traverse-framework/Traverse --json labels If labels include "agent:claude" → STOP. Report: "Issue #NN is claimed by Claude Code." 2. git ls-remote --heads origin | grep "issue-NN-" If a claude/issue-NN-* branch exists → STOP. Report: "A Claude Code branch exists for #NN." Claim (only if pre-flight passes): -1. gh issue edit NN --repo enricopiovesan/Traverse --add-label "agent:codex" +1. gh issue edit NN --repo traverse-framework/Traverse --add-label "agent:codex" 2. Set Agent → Codex and Status → In Progress on Project 1 for this issue. Project ID: PVT_kwHOAEZXvs4BS6Ns Agent field: PVTSSF_lAHOAEZXvs4BS6NszhBK-Qk, Codex option: 34d6db7d diff --git a/scripts/ci/project_state_audit.sh b/scripts/ci/project_state_audit.sh index 0611b81f..155affa6 100755 --- a/scripts/ci/project_state_audit.sh +++ b/scripts/ci/project_state_audit.sh @@ -2,7 +2,7 @@ set -euo pipefail -repo="enricopiovesan/Traverse" +repo="traverse-framework/Traverse" project_items_json=$(gh project item-list 1 --owner enricopiovesan --limit 500 --format json) diff --git a/specs/188-codex-agent-coordination/plan.md b/specs/188-codex-agent-coordination/plan.md index 86c6cd53..d299269a 100644 --- a/specs/188-codex-agent-coordination/plan.md +++ b/specs/188-codex-agent-coordination/plan.md @@ -53,7 +53,7 @@ Two steps prepended to the existing prompt: **Pre-flight (runs before any work):** ``` Before starting any work on issue #: -1. gh issue view --repo enricopiovesan/Traverse --json labels +1. gh issue view --repo traverse-framework/Traverse --json labels If labels include "agent:claude" → STOP. Report: "Issue # is claimed by Claude Code." 2. git ls-remote --heads origin | grep "issue--" If a claude/issue--* branch exists → STOP. Report: "A Claude Code branch exists for #." @@ -61,7 +61,7 @@ Before starting any work on issue #: **Claim step (runs only if pre-flight passes):** ``` -1. gh issue edit --repo enricopiovesan/Traverse --add-label "agent:codex" +1. gh issue edit --repo traverse-framework/Traverse --add-label "agent:codex" 2. Retrieve project item ID for issue # from Project 1, then: gh project item-edit --project-id PVT_kwHOAEZXvs4BS6Ns --id \ --field-id PVTSSF_lAHOAEZXvs4BS6NszhBK-Qk --single-select-option-id 34d6db7d From bb2901640684b784284aec204147816ee07fb664 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Fri, 26 Jun 2026 22:26:29 -0600 Subject: [PATCH 08/11] chore: update project board owner to traverse-framework New GitHub Project created at github.com/orgs/traverse-framework/projects/1. Updates --owner flag from enricopiovesan to traverse-framework in AGENTS.md, scripts/ci/project_state_audit.sh, and .agents/skills/traverse-ops/SKILL.md. Co-Authored-By: Claude Sonnet 4.6 --- .agents/skills/traverse-ops/SKILL.md | 2 +- AGENTS.md | 2 +- scripts/ci/project_state_audit.sh | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.agents/skills/traverse-ops/SKILL.md b/.agents/skills/traverse-ops/SKILL.md index 16f5dc4a..9f195599 100644 --- a/.agents/skills/traverse-ops/SKILL.md +++ b/.agents/skills/traverse-ops/SKILL.md @@ -37,7 +37,7 @@ Use a lean-by-default operating style so long-running Traverse ops sessions do not waste context on raw logs. - Prefer targeted GitHub queries over full board dumps. For Ready work, use - `gh project item-list 1 --owner enricopiovesan --format json --limit 300 --jq '...'` + `gh project item-list 1 --owner traverse-framework --format json --limit 300 --jq '...'` and return only issue number, title, labels, and item id. - Do not paste full `gh project item-list`, `gh pr checks --watch`, test, clippy, coverage, or CI logs into the conversation. Summarize pass/fail counts and diff --git a/AGENTS.md b/AGENTS.md index 0b9cbe13..44c93bf5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,7 +90,7 @@ If a `claude/issue--*` branch exists → **STOP**. Report: gh issue edit --repo traverse-framework/Traverse --add-label "agent:codex" # Get project item ID with bounded output -gh project item-list 1 --owner enricopiovesan --format json --limit 300 \ +gh project item-list 1 --owner traverse-framework --format json --limit 300 \ --jq '.items[] | select(.content.number == ) | .id' # Set Agent → Codex diff --git a/scripts/ci/project_state_audit.sh b/scripts/ci/project_state_audit.sh index 155affa6..1f57dfe7 100755 --- a/scripts/ci/project_state_audit.sh +++ b/scripts/ci/project_state_audit.sh @@ -4,7 +4,7 @@ set -euo pipefail repo="traverse-framework/Traverse" -project_items_json=$(gh project item-list 1 --owner enricopiovesan --limit 500 --format json) +project_items_json=$(gh project item-list 1 --owner traverse-framework --limit 500 --format json) failures=0 From a4e363038483867e75fecd85063c17ac35ce49f8 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Fri, 26 Jun 2026 22:45:55 -0600 Subject: [PATCH 09/11] ci: re-trigger after repo migration to traverse-framework Co-Authored-By: Claude Sonnet 4.6 From 16c425711920e33d6868fdae24197366f69829e4 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Fri, 26 Jun 2026 23:04:57 -0600 Subject: [PATCH 10/11] docs: update all links for traverse-framework org and traverse-framework.com - README banner now links to https://traverse-framework.com - README, CONTRIBUTING, SUPPORT project board links updated from users/enricopiovesan/projects to orgs/traverse-framework/projects - Status updated to reflect v0.4.0 active development Co-Authored-By: Claude Sonnet 4.6 --- CONTRIBUTING.md | 2 +- README.md | 4 ++-- SUPPORT.md | 2 +- docs/tutorial-index.md | 4 +++- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2e1dfaa..af731b0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ Please read: 1. Start from the governing approved spec. 2. Confirm whether an issue already exists. 3. Open or link the work item in the project board: - [GitHub Project 1](https://github.com/users/enricopiovesan/projects/1/) + [GitHub Project](https://github.com/orgs/traverse-framework/projects) 4. If needed, add or update an ADR before implementation. 5. Implement with tests and validation evidence. 6. Make sure the change passes the required validation flow. diff --git a/README.md b/README.md index 5f17707b..b4a0a649 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Traverse](https://github.com/user-attachments/assets/aeafaaf8-650d-4489-bf5e-bd386f0bcaf0)](https://enricopiovesan.com/) +[![Traverse](https://github.com/user-attachments/assets/aeafaaf8-650d-4489-bf5e-bd386f0bcaf0)](https://traverse-framework.com) # Traverse @@ -159,7 +159,7 @@ 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](https://github.com/users/enricopiovesan/projects/1/) is the canonical board. All active work has an issue, a project item, and a PR. +[GitHub Project](https://github.com/orgs/traverse-framework/projects) is the canonical board. All active work has an issue, a project item, and a PR. --- diff --git a/SUPPORT.md b/SUPPORT.md index 79f2c923..4c0693f6 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -13,7 +13,7 @@ Questions, bug reports, and contribution discussions should generally go through - Use GitHub issues for bugs, features, and task discussion - Use pull requests for implementation review - Use the project board for task tracking: - [GitHub Project 1](https://github.com/users/enricopiovesan/projects/1/) + [GitHub Project](https://github.com/orgs/traverse-framework/projects) ## Security Issues diff --git a/docs/tutorial-index.md b/docs/tutorial-index.md index 732fe5e5..8555091a 100644 --- a/docs/tutorial-index.md +++ b/docs/tutorial-index.md @@ -10,6 +10,7 @@ Pick the path that matches your goal before reading further: |---|---| | Register and invoke a capability end to end | [docs/getting-started.md](getting-started.md) | | Consume Traverse from a browser app | [quickstart.md](../quickstart.md) | +| Plan Traverse reference apps across web, cloud, mobile, and desktop | [docs/reference-app-roadmap.md](reference-app-roadmap.md) | | Follow the full ordered onboarding sequence | Continue below | All three paths are documented in this repo. The descriptions above tell you which one to open first; the ordered sequence below links them all together when you are ready for more. @@ -41,7 +42,8 @@ Use it in sequence unless you already know the slice you need: 21. [docs/multi-thread-workflow.md](multi-thread-workflow.md) 22. [docs/project-management.md](project-management.md) 23. [docs/troubleshooting.md](troubleshooting.md) -24. [docs/adr/README.md](adr/README.md) +24. [docs/reference-app-roadmap.md](reference-app-roadmap.md) +25. [docs/adr/README.md](adr/README.md) ## How To Read It From 97b25e71bb9e4d13d64b169e0ac5d686c5b33087 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Fri, 26 Jun 2026 23:11:21 -0600 Subject: [PATCH 11/11] ci: re-trigger after branch protection re-saved on traverse-framework Co-Authored-By: Claude Sonnet 4.6