Tramuri

English · Português (Brasil)

From intent to verified outcomes.

Tramuri is open-source, local-first infrastructure for turning product and business objectives into coordinated work and verifiable outcomes. It helps people, agents, and tools carry context between sessions and distinguish completed work from results that have actually been reviewed.

Tramuri is designed for Product Engineers, Forward Deployed Engineers (FDEs), and product teams. It works without requiring a source-code repository, an LLM, or a particular agent framework.

New to Tramuri? Start with the Product Engineer or FDE tutorial. Both include Portuguese (Brazil) versions.

What Tramuri provides

• Missions and Success Contracts to describe an objective and its acceptance criteria.
• Persistent knowledge with source references and history.
• Execution and evidence records that keep work, supporting references, and assessment distinct.
• Verified outcomes based on explicit criterion reviews; a completed execution alone does not mark a Mission as achieved.
• Project Discovery as an optional way to inventory a code project. Scanning does not execute repository files and excludes sensitive paths by default.
• Capability Discovery to catalog supported project-local skills, instructions, agents, hooks, and MCP declarations without executing or connecting to them.
• A native Rust CLI and a Python SDK backed by the same Rust core.

The published Python SDK includes a prebuilt Rust extension on supported platforms; users do not need a Rust toolchain.

Tramuri stores its local project state under .tramuri/, with SQLite at .tramuri/database/tramuri.sqlite3 and the latest scan report under .tramuri/discovery/. Evidence is recorded as references; Tramuri does not fetch external resources or store scanned file contents as evidence. The capability catalog is a derived snapshot; declared MCP servers and hooks are not considered operationally verified.

Prerequisites

PyPI installations use prebuilt wheels on supported platforms. You do not need Rust installed.

Install

Python SDK

Install Tramuri into an existing Python project:

uv add tramuri

Or use pip:

python -m pip install tramuri

CLI and assistant integrations

The Tramuri package includes the CLI distribution and project integration installer. Install the CLI in an isolated tool environment:

uv tool install tramuri
tramuri --version

pipx install tramuri is also available as an isolated-install alternative. If the tramuri command is not found after installation, run uv tool update-shell and reopen your terminal.

After a new Tramuri release is published, update it with the package manager used to install it:

uv tool upgrade tramuri
# If installed with pipx instead:
pipx upgrade tramuri
tramuri --version

Install Tramuri into the project for the assistant you use, preserving existing instructions and hooks:

tramuri install --platform codex --project

Then describe a substantive goal in the assistant chat, for example: “I want to improve customer onboarding” or “I am taking over this customer integration.” The installed instructions guide a Mission start or resume even if you do not mention Tramuri. For a new Mission, explicitly choose one of three perspectives: Product Engineer (shapes the product problem and helps decide what to build), FDE (connects systems to solve a customer need), or mixed work (combines product evolution and a customer integration). In a terminal, use the arrow-key selector and press Enter; in an agent session, answer in chat. Tramuri stores the choice on the Mission. Saved defaults and intent routing may suggest a perspective but cannot replace the user's choice. A unique exact match can resume an existing Mission with its recorded perspective. You do not need to run tramuri init first or learn CLI syntax. Mission and Success Contract setup stays exploratory, and a project scan is optional. At the end of a coherent work session that changes Mission records, the assistant refreshes the local reports. It opens the HTML only if it has not already opened it during that session; otherwise it refreshes the files without opening another browser window. You can also ask “open the Tramuri report,” run tramuri status --open, or run tramuri status --refresh to refresh without opening the browser.

The local report opens in English or Brazilian Portuguese and shows work perspective (Product Engineer/FDE) separately from the recorded actor. Actor labels are provided by the caller and are not authenticated; Tramuri does not infer a current Mission owner.

tramuri capabilities --type skill --json filters the latest declarative catalog. Scanning honors project ignore rules and sensitive-path exclusions; it does not read global agent settings, execute hooks, start MCP servers, or make network connections.

Codex, Claude Code, Cursor, Gemini CLI, and GitHub Copilot receive native project instructions, Tramuri skills, and project-local hooks. The hooks block supported local project tools until tramuri start or tramuri resume succeeds for the current prompt/turn. They do not read or store prompt text or Mission records. Hooks follow each host's trust settings; disabled, unsupported, or bypassed hook paths are not enforced (including hosted Codex tools and Copilot surfaces other than the documented hook-capable runtimes). Direct preflight queries (tramuri --version, tramuri status, and tramuri mission list) remain available while locked but do not unlock the gate. Instructions remain fallback guidance. Installation preserves unrelated instructions and hook entries. Cursor uses .cursor/rules/tramuri.mdc, .cursor/skills/tramuri/, and .cursor/hooks.json; Copilot uses .github/hooks/tramuri.json; the other hosts use their native instruction, skill, and hook locations.

tramuri install --project --platform copilot
tramuri install --project --platform claude
tramuri install --project --platform cursor
tramuri install --project --platform gemini

tramuri status summarizes the workspace, tramuri status --open generates and opens the local report, tramuri status --refresh refreshes the report files without opening a browser, and tramuri resume --mission <id> reconstructs recorded work and readiness for the selected next activity. A Mission can start without criteria; its Outcome stays pending until required criteria are added and reviewed. Readiness is advisory and never blocks execution:

tramuri start --goal "Create a product for small businesses" --perspective product_engineer
tramuri status
tramuri resume --mission <id>

Product Engineering DEFINE workflow

Starting a Mission with the product_engineer perspective automatically creates a persistent DEFINE workflow in the Rust Core. The host asks the Core for the authorized step, loads the named skill, submits structured output, and advances only after acceptance. The five steps cover objective and context; problem, audience, and business; requirements and criteria; facts and hypotheses; and a Product Brief. A complete Success Contract is not required to begin.

tramuri start --goal "Create a SaaS for selling online courses" --perspective product_engineer --json
tramuri mission define status --mission <id> --json
tramuri mission define next --mission <id> --json

next returns the authorized step, its skill name, and the output contract. After producing the JSON, the host submits it with tramuri mission define submit --mission <id> --step <step> --file <result.json>. The Core rejects missing required fields, invalid references, and out-of-order submissions; rejection leaves the current step open. A material decision can be recorded with tramuri mission define question request and tramuri mission define question answer. The limit of two ordinary clarification questions persists across sessions.

Use status and next to resume saved progress. Each CLI transition attempts to refresh .tramuri/reports/tramauri.html, tramauri.md, and tramauri.json without reopening the browser. The Python SDK exposes the same mission_define_* operations; when using it directly, refresh the reports afterward with tramuri status --refresh.

The Core enforces sequence, structural validation, and persistence. It cannot prove that the host loaded a skill, that research claims are true, or that the Product Brief is correct. The host does the analysis and uses its available tools. Completing DEFINE stores a Product Brief; it does not build, ship, or verify the product, and it does not mark the Mission Outcome as achieved.

tramuri start creates an exploratory Mission only after an explicit perspective is selected. New Missions accept product_engineer, fde, or mixed; the legacy other value remains readable in existing records but is not offered at start. Product Engineer Missions retain their product_framing focus; other perspectives start with Discovery. The DEFINE checklist is a separate, deterministic Product Engineering workflow. Context Readiness stays not_assessed until someone records an assessment. Rust Core routing may suggest a perspective using a small phrase set, but it is not general natural-language understanding and does not confirm a choice for the user.

Choose a default perspective for this workspace with:

tramuri profile set product_engineer
tramuri profile set fde --ask always
tramuri profile set auto

The current Mission focus can be changed without changing perspective provenance or approving Context Readiness. Product Engineer phases can use product_framing, discover, define, scope, prototype, implement, validate, launch, and learn. Record a meaningful Execution once work starts, then close that same record explicitly:

tramuri mission workflow set --mission <id> --perspective product_engineer --activity prototype
tramuri mission workflow set --mission <legacy-id> --perspective product_engineer --source inferred --activity product_framing
tramuri mission workflow activity --mission <id> --activity discover
tramuri execution update --id <execution-id> --status completed

The available terminal statuses are completed, blocked, failed, and cancelled. Execution completion does not verify the Mission outcome. Add or revise criteria during Discovery when they become clear:

tramuri readiness assess --mission <id> --activity discover --state needs_review \
  --gap "Interview data is not available yet"
tramuri status --open

Use tramuri readiness show --mission <id> to review the current assessment and its history. Changing the objective, Success Contract, or explicitly linked Knowledge/Capabilities marks the latest readiness as stale while retaining the original assessment. tramuri mission list discovers Missions. The report files are .tramuri/reports/tramauri.html, tramauri.md, and tramauri.json. Opening an older supported database can apply its existing schema migrations; status reads do not change Mission, execution, evidence, or outcome records. These commands work without an assistant; integrations are optional.

Knowledge and discovered Capabilities can be explicitly associated with a Mission using tramuri mission link-knowledge and tramuri mission link-capability. tramuri resume --mission <id> includes only those recorded associations. Tramuri does not infer Mission relevance; capability links retain the observed source hash and become changed, missing, or unverified after later scans. Actor attribution is caller supplied and is not authenticated.

Follow the Product Engineer and FDE tutorials, with step-by-step setup, work, evidence, review, and handoff using fictional data.

How an assistant can use Tramuri

The project installer adds platform-native instructions and Tramuri skills. They guide the assistant to start or resume a Mission before using project tools. Where a host supports a trusted, enabled native hook, the hook blocks supported local project-tool calls until tramuri start or tramuri resume succeeds in the current prompt or turn. Coverage depends on each host's hook surface; disabled, untrusted, bypassed, and hosted tool paths are not enforced. Hooks use only the host's event metadata and the matching Tramuri command result; they do not read or store prompt text or Mission records. This gate is a workflow guardrail, not authentication or a guarantee that an assistant's product analysis is correct. See the integration details.

Mission creation does not require a Git repository or project scan. See the product vision for Tramuri's scope and principles, and the changelog for release history.

Project status

Tramuri is in active early development. Project and Capability Discovery, persistent knowledge, Missions, explicit Knowledge/Capability links, manual Execution and Evidence records, and criterion assessments are part of the current product. Capability formats are platform-specific; only documented project paths are recognized. Versioned Context Pack and Evidence Pack export is planned; it will use explicit selection and authorization and will be safe by default.

Community

• Contributing
• Code of Conduct
• Security policy
• Support
• License (Apache-2.0)