Metadata-Version: 2.4
Name: tramuri
Version: 0.12.1
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
License-File: LICENSE
Summary: Local-first, agent-native infrastructure for verified work outcomes
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Tramuri

<p align="center">
  <img src="https://raw.githubusercontent.com/tramuri/tramuri/main/assets/logo.png" alt="Tramuri logo" width="220">
</p>

<p align="center"><a href="https://github.com/tramuri/tramuri/blob/main/README.md">English</a> · <a href="https://github.com/tramuri/tramuri/blob/main/README.pt-BR.md">Português (Brasil)</a></p>

<p align="center"><strong>From intent to verified outcomes.</strong></p>

<p align="center">
  <a href="https://github.com/tramuri/tramuri/actions/workflows/ci.yml"><img src="https://github.com/tramuri/tramuri/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://pypi.org/project/tramuri/"><img src="https://img.shields.io/pypi/v/tramuri" alt="PyPI version"></a>
</p>

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](docs/examples/product-engineer/README.md)
> or [FDE tutorial](docs/examples/fde/README.md). 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

| Requirement | Version | Check | Install |
| --- | --- | --- | --- |
| Python | 3.11 or newer | `python --version` | [python.org](https://www.python.org/downloads/) |
| `uv` (recommended) | Any current version | `uv --version` | [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) |

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

## Install

### Python SDK

Install Tramuri into an existing Python project:

```bash
uv add tramuri
```

Or use pip:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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](docs/README.md), 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](docs/reference/product-engineering-execution-flow.md).

| Interface | Use |
| --- | --- |
| CLI | Run local discovery, knowledge, and mission workflows. |
| Assistant skill and instructions | Help an installed assistant choose and use Tramuri's CLI. |
| Native hooks | Gate supported local project tools until a Mission is started or resumed, when active and trusted by the host. |
| Python SDK | Call the same Rust-backed capabilities from Python applications. |
| MCP | No Tramuri MCP server is available currently; use the CLI or SDK. |

Mission creation does not require a Git repository or project scan. See the
[product vision](VISION.md) for Tramuri's scope and principles, and the
[changelog](CHANGELOG.md) 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](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security policy](SECURITY.md)
- [Support](SUPPORT.md)
- [License](LICENSE) (Apache-2.0)

