docs(adr): ADR-038 Rust-first for workspace execution and contracts#244
Open
NeuralEmpowerment wants to merge 1 commit into
Open
docs(adr): ADR-038 Rust-first for workspace execution and contracts#244NeuralEmpowerment wants to merge 1 commit into
NeuralEmpowerment wants to merge 1 commit into
Conversation
Makes the language policy explicit: the execution substrate (itmux), the AgentRunSpec->AgentRunResult contract + orchestration, recipe loading/validation, and hot-path tooling are Rust; Python is thin consumer glue + Claude hook plugins. Motivated by cold-start cost, single-binary portability, and 5 concurrency bugs that the Python async orchestration accrued across 3 reviewers. Updates CLAUDE.md/ AGENTS.md framing.
There was a problem hiding this comment.
Pull request overview
Adds an Architecture Decision Record (ADR) to explicitly codify a “Rust-first” policy for workspace execution + contracts, and updates the repo’s top-level CLAUDE.md to reflect that policy for contributors.
Changes:
- Add ADR-038 documenting “Rust-first for workspace execution and contracts” (Rust core + JSON contract + thin per-language clients).
- Update
CLAUDE.mdto reflect the Rust-first language policy and intended role of Python (thin glue + Claude hook plugins).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
docs/adrs/038-rust-first-execution-and-contracts.md |
New ADR defining Rust-first execution/contract policy and scope guardrails. |
CLAUDE.md |
Updates project framing and documents the ADR-038 language policy for contributors. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+22
to
+24
| agentic-primitives began as "Claude Code plugins + Python libraries." The interactive-tmux | ||
| workspace (the substrate that runs agents in isolation) was first written as a ~2500-line | ||
| Python driver, then ported to a Rust binary (`itmux`) for cold-start and single-binary |
| Atomic building blocks for AI agent systems. Claude Code plugins + Python libraries for reusable agent capabilities (SDLC, research, workspace management, observability, notifications). | ||
| Atomic building blocks for AI agent systems: a Rust workspace-execution substrate (`itmux`) + Claude Code plugins + supporting libraries for reusable agent capabilities (SDLC, research, workspace management, observability, notifications). | ||
|
|
||
| **Language policy (ADR-038):** the workspace execution substrate, the `AgentRunSpec -> AgentRunResult` contract + orchestration, recipe loading/validation, and hot-path tooling are **Rust-first**. Python is retained only as thin consumer glue and for Claude hook plugins. New substrate/contract/recipe/hot-path work is Rust unless there is a concrete reason it must be Python. |
This was referenced Jul 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Makes the Rust-first language policy explicit as an ADR (there was no prior ADR stating a language preference; CLAUDE.md just described 'Python libraries').
Decision: the workspace execution substrate (
itmux), theAgentRunSpec -> AgentRunResultcontract + orchestration, recipe loading/validation, and hot-path tooling are Rust-first, exposed as a language-neutral JSON contract + thin per-language clients. Python is retained only as thin consumer glue (Syntropic137's shell-out client) and for Claude hook plugins.Motivation: cold-start (~120ms Python vs ~5ms Rust), single-binary portability (local/docker/ssh), and the 5 concurrency defects the Python async orchestrator accrued across Claude + codex + Copilot reviews - all artifacts of async orchestration in Python, none in the contract. Matches the event-sourcing-platform 'Rust core, thin SDK' precedent.
Scope guard: NOT 'rewrite every Python package in Rust' - existing libs + Claude plugins stay. Follow-up: rework the Python contract into
itmux run(Rust) + JSON schema + thin Python client. Tracks okrs-o78.