entrix
A Harness Engineering tool for turning quality rules, architecture constraints, and validation steps into executable guardrails.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/phodal--entrix)HTML
<a href="/listings/phodal--entrix"><img src="/api/listings/phodal--entrix/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Choose one installation path:
Claude Code Plugin (recommended)
/plugin marketplace add phodal/entrix /plugin install entrix@entrix
Restart Claude Code after plugin installation.
Standalone CLI (`uv` or `pip`)
uv tool install entrix # or pip install entrix entrix --help
If you want Claude Code MCP integration in the current repository after installing the CLI:
entrix install --repo .
Requires Python 3.10+. `uv` is only needed for the `uv` / `uvx` workflow.
<details> <summary><strong>What it does</strong></summary> <br>
- codify quality gates and architecture constraints as reusable guardrail specs - run checks by `fast` / `normal` / `deep` tiers - run change-aware checks on diffs with weighted scoring and hard gates - route risky changes to deeper validation with `review-trigger` - optionally add graph-based impact, test-radius, and review context analysis
</details>
<details> <summary><strong>Guardrails in the change lifecycle</strong></summary> <br>
- checks run before risky code lands - each run generates evidence - policy can hard-stop, warn, or escalate to human review automatically
</details>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 25 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "entrix",
- "owner": {
- "name": "Phodal"
- },
- "plugins": [
- {
- "name": "entrix",
- "source": "./",
- "description": "Harness Engineering plugin exposing executable fitness functions for architecture quality, change-aware validation, and MCP-powered review context.",
- "version": "0.1.14",
- "author": {
- "name": "Phodal"
- },
- "category": "development",
- "tags": [
- "fitness",
- "quality",
- "mcp",
- "architecture",
- "code-review"
- ]
- }
- ]
- }
README.md · README · 728 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <h1 align="center">Entrix</h1>
- <p align="center">
- <strong>Shift quality from manual review to executable change guardrails.</strong>
- </p>
- <p align="center">
- <a href="https://pypi.org/project/entrix/">
- <img src="https://img.shields.io/pypi/v/entrix.svg" alt="PyPI version" />
- </a>
- <a href="https://pypi.org/project/entrix/">
- <img src="https://img.shields.io/pypi/pyversions/entrix.svg" alt="Python versions" />
- </a>
- <a href="https://opensource.org/licenses/MIT">
- <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" />
- </a>
- </p>
- <p align="center">
- <img src="https://raw.githubusercontent.com/phodal/entrix/main/docs/lifecycle.svg" alt="Entrix Lifecycle" width="85%" />
- </p>
- <br>
- ## Install
- Choose one installation path:
- ### Claude Code Plugin (recommended)
- ```bash
- /plugin marketplace add phodal/entrix
- /plugin install entrix@entrix
- ```
- Restart Claude Code after plugin installation.
- ### Standalone CLI (`uv` or `pip`)
- ```bash
- uv tool install entrix
- # or
- pip install entrix
- entrix --help
- ```
- If you want Claude Code MCP integration in the current repository after installing the CLI:
- ```bash
- entrix install --repo .
- ```
- Requires Python 3.10+. `uv` is only needed for the `uv` / `uvx` workflow.
- <details>
- <summary><strong>What it does</strong></summary>
- <br>
- - codify quality gates and architecture constraints as reusable guardrail specs
- - run checks by `fast` / `normal` / `deep` tiers
- - run change-aware checks on diffs with weighted scoring and hard gates
- - route risky changes to deeper validation with `review-trigger`
- - optionally add graph-based impact, test-radius, and review context analysis
- </details>
- <details>
- <summary><strong>Guardrails in the change lifecycle</strong></summary>
- <br>
- - checks run before risky code lands
- - each run generates evidence
- - policy can hard-stop, warn, or escalate to human review automatically
- </details>
- ## Lifecycle View
- 
- Additional design context:
- - `tools/entrix/docs/adr/README.md`: Entrix architecture decisions and rationale
- ## Terminology
- Entrix uses **fitness** in the evolutionary architecture sense: a fitness
- function is an executable check that measures whether a codebase still satisfies
- a quality or architecture goal. In product-facing language, you can think of
- these as versioned quality guardrails.
- ## Requirements
- - Python 3.10+
- - Git repository context for commands that use `--base HEAD~1`
- Optional:
- - `uv` for `uv tool install ...` and `uvx ...`
- - `pip install entrix[graph]` for graph commands
- ## Advanced Installation
- ### Alternate CLI Invocations
- <details>
- <summary><strong>CLI invocation options</strong></summary>
- <br>
- ```bash
- uv tool install entrix
- # or
- pip install entrix
- uvx entrix --help
- uvx entrix run --tier fast
- uvx entrix run --tier normal --stream failures
- uvx entrix run --tier normal --stream all
- uvx entrix review-trigger --base HEAD~1
- ```
- </details>
- <details>
- <summary><strong>Optional extras</strong></summary>
- <br>
- ```bash
- pip install entrix[graph]
- pip install entrix[mcp]
- pip install entrix[dev]
- uvx entrix install --repo .
- ```
- </details>
- ## First Run
- ### 1. Create a guardrail spec
- By default, `entrix run` looks for specs under the current project's:
- ```text
- docs/fitness/*.md
- ```
- When `docs/fitness/manifest.yaml` is present, Entrix uses the manifest as the
- source of truth. That allows nested evidence files such as
- `docs/fitness/runtime/observability.md` and `docs/fitness/runtime/performance.md`.
- Example `docs/fitness/code-quality.md`:
- ```yaml
- ---
- dimension: code_quality
- weight: 20
- threshold:
- pass: 90
- warn: 80
- metrics:
- - name: lint
- command: npm run lint 2>&1
- hard_gate: true
- tier: fast
- description: ESLint must pass
- - name: unit_tests
- command: npm run test:run 2>&1
- pattern: "Tests\\s+\\d+\\s+passed"
- hard_gate: true
- tier: normal
- description: unit tests must pass
- ---
- # Code Quality
- Narrative evidence, rules, and ownership notes can live below the frontmatter.
- ```
- ### Advanced metric fields
- Beyond the basic fields shown above, each metric in the frontmatter supports additional options:
- ```yaml
- metrics:
- - name: api_contract
- command: npm run test:contract 2>&1
- hard_gate: false
- tier: normal
- description: API contract tests
- # Execution scope — where this metric is authoritative
- # Values: local, ci, staging, prod_observation
- execution_scope: ci
- # Timeout in seconds (null = no limit)
- timeout_seconds: 120
- # Gate severity: hard, soft, advisory
- gate: soft
- # Evidence type: command, test, probe, sarif, manual_attestation
- evidence_type: test
- # Confidence level: high, medium, low, unknown
- confidence: high
- # Signal stability: deterministic, noisy
- stability: deterministic
- # Fitness kind: atomic (single check) or holistic (system-wide)
- kind: atomic
- # Analysis mode: static (code structure) or dynamic (runtime)
- analysis: dynamic
- # Owner responsible for this metric
- owner: team-platform
- # Only run when these file patterns change
- run_when_changed:
- - "src/api/**"
- - "openapi.yaml"
- # Temporary waiver to bypass a failing metric
- waiver:
- reason: "Known flaky test, fix tracked in issue #42"
- owner: team-platform
- tracking_issue: 42
- expires_at: "2025-06-01"
- ```
- ### 2. Run the checks
- ```bash
- entrix run --tier fast
- entrix run --tier normal
- entrix run --tier normal --scope ci --dimension code_quality --dimension testability
- entrix run --tier fast --metric eslint_pass --metric ts_typecheck_pass
- entrix run --changed-only --base HEAD~1
- entrix validate
- ```
- Use `--metric` when you want to run only specific metric names without creating a temporary dimension file split. Commands that use `--base HEAD~1` must run inside a git repository with a valid base revision.
- ### 3. Add review triggers
- By default, `review-trigger` loads the current project's:
- ```text
- docs/fitness/review-triggers.yaml
- ```
- Example `docs/fitness/review-triggers.yaml`:
- ```yaml
- review_triggers:
- - name: high_risk_directory_change
- type: changed_paths
- paths:
- - src/core/acp/**
- - src/core/orchestration/**
- - services/api/**
- severity: high
- action: require_human_review
- - name: oversized_change
- type: diff_size
- max_files: 12
- max_added_lines: 600
- max_deleted_lines: 400
- severity: medium
- action: require_human_review
- ```
- Run it:
- ```bash
- entrix review-trigger --base HEAD~1
- entrix review-trigger --base HEAD~1 --json
- ```
- Example output:
- ```json
- {
- "human_review_required": true,
- "base": "HEAD~1",
- "changed_files": [
- "services/api/src/routes/acp_routes.rs"
- ],
- "diff_stats": {
- "file_count": 13,
- "added_lines": 936,
- "deleted_lines": 20
- },
- "triggers": [
- {
- "name": "high_risk_directory_change",
- "severity": "high",
- "action": "require_human_review",
- "reasons": [
- "changed path: services/api/src/routes/acp_routes.rs"
- ]
- }
- ]
- }
- ```
- ### Develop from the Routa.js checkout
- If you are using the copy of `entrix` vendored in the Routa.js monorepo, the
- current repository workflow is:
- ```bash
- pip install -e tools/entrix
- PYTHONPATH=tools/entrix python3 -m entrix --help
- PYTHONPATH=tools/entrix python3 -m entrix run --tier fast
- PYTHONPATH=tools/entrix python3 -m entrix review-trigger --base HEAD~1
- ```
- Most local hooks and helper scripts in this repository use the
- `PYTHONPATH=tools/entrix python3 -m entrix ...` form so they can run directly
- from the monorepo checkout without requiring a separately installed global
- binary.
- ### Develop the package itself from source
- If you are working on the `entrix` package source itself, clone this repository and install it from the repository root.
- From the repository root:
- ```bash
- git clone https://github.com/phodal/entrix.git
- cd entrix
- uv pip install -e .
- ```
- With `pip`:
- ```bash
- git clone https://github.com/phodal/entrix.git
- cd entrix
- pip install -e .
- ```
- ## CLI Reference
- Most repositories only need these three commands:
- - `entrix run`: execute guardrail checks from `docs/fitness/*.md`
- - `entrix validate`: validate the guardrail configuration
- - `entrix review-trigger`: escalate risky diffs to human review
- Use `entrix analyze long-file` for oversized-file structure analysis and `entrix graph ...` for graph-backed impact analysis.
- ## Example Packs
- Entrix includes copyable examples under [`examples/`](./examples/):
- - [`examples/file-length-hook/`](./examples/file-length-hook/): pre-commit file budget hook
- - [`examples/frontend-quality-pack/`](./examples/frontend-quality-pack/): layered frontend quality gates with review-trigger guidance
- ### `entrix run`
- Runs dimension-based guardrail checks loaded from `docs/fitness/*.md`.
- Common flags:
- ```bash
- entrix run --tier fast
- entrix run --parallel
- entrix run --dry-run
- entrix run --verbose
- entrix run --format ascii
- entrix run --format rich
- entrix run --changed-only --base HEAD~1
- entrix run --files src/app.ts src/lib.ts
- entrix run --output report.json
- entrix run --output - # JSON to stdout
- entrix run --min-score 90
- ```
- Use `--output` to write a JSON report to a file (or `-` for stdout), useful for CI artifact collection. Use `--files` to pass an explicit list of changed files for incremental metric selection. Use `--format ascii` for a zero-dependency visual scorecard, or `--format rich` for richer terminal rendering when `rich` is installed (`pip install entrix[visual]`).
- ### `entrix install` / `entrix init`
- Generate `.mcp.json` for Claude Code MCP integration in a target repository.
- ```bash
- entrix install --repo .
- entrix init --dry-run
- ```
- ### `entrix serve`
- Run the Entrix MCP server over stdio.
- ```bash
- entrix serve
- ```
- ### `entrix validate`
- Checks that dimension weights sum to `100%`.
- ```bash
- entrix validate
- ```
- ### `entrix review-trigger`
- Evaluates governance-oriented trigger rules for risky changes.
- Common flags:
- ```bash
- entrix review-trigger --base HEAD~1
- entrix review-trigger --json
- entrix review-trigger --fail-on-trigger
- entrix review-trigger --config docs/fitness/review-triggers.yaml
- ```
- ### `entrix analyze long-file`
- Structural analysis for oversized or explicit source files. Returns ClassMap / FunctionMap payloads showing classes, methods, and standalone functions with line spans.
- Supported languages: Python, Rust, Go, Java, and TypeScript/JavaScript
- (including `tsx` / `jsx` files).
- ```bash
- entrix analyze long-file --files src/app.ts src/lib.ts
- entrix analyze long-file --json
- entrix analyze long-file --config file_budgets.json --strict-limit
- entrix analyze long-file --min-lines 100
- ```
- When no `--files` are given, the command auto-discovers files that exceed their configured line budget.
- ### `entrix graph ...`
- Graph-backed commands support building the code graph, querying relationships, impact analysis, test radius estimation, commit history analysis, and AI-friendly review context generation.
- Requires the optional graph dependency: `pip install entrix[graph]`.
- #### `entrix graph build`
- Build or update the code graph.
- ```bash
- entrix graph build --base HEAD~1
- entrix graph build --build-mode full --json
- ```
- #### `entrix graph stats`
- Show graph statistics (node and edge counts).
- ```bash
- entrix graph stats
- entrix graph stats --json
- ```
- #### `entrix graph impact`
- Analyze the blast radius of changed files.
- ```bash
- entrix graph impact --base HEAD~1
- entrix graph impact --base HEAD~1 --depth 3 --json
- ```
- #### `entrix graph test-radius`
- Estimate which tests are affected by changed files.
- ```bash
- entrix graph test-radius --base HEAD~1
- entrix graph test-radius --base HEAD~1 --max-targets 50 --json
- ```
- #### `entrix graph query`
- Run a structural query against the code graph.
- Available patterns: `callers_of`, `callees_of`, `imports_of`, `importers_of`, `children_of`, `tests_for`, `inheritors_of`, `file_summary`.
- ```bash
- entrix graph query callers_of "mymodule.MyClass.my_method"
- entrix graph query tests_for "src/core/engine.py" --json
- ```
- #### `entrix graph history`
- Estimate test radius for recent commits using the current graph.
- ```bash
- entrix graph history --count 20 --ref main
- entrix graph history --json
- ```
- #### `entrix graph review-context`
- Build an AI-friendly review context from the current graph.
- ```bash
- entrix graph review-context --base HEAD~1 --json
- entrix graph review-context --base HEAD~1 --max-files 20 --no-source
- entrix graph review-context --base HEAD~1 --output context.json
- ```
- ## Preset System
- Entrix uses a preset system to adapt behavior to different project layouts. The default `ProjectPreset` looks for guardrail specs in `docs/fitness/` and review triggers in `docs/fitness/review-triggers.yaml`.
- Custom presets can override:
- - `fitness_dir(project_root)` — where to find guardrail spec files
- - `review_trigger_config(project_root)` — path to the review trigger YAML
- - `should_ignore_changed_file(file_path)` — filter out irrelevant changed files
- - `domains_from_files(files)` — extract domain tags from changed file paths
- A built-in `RoutaPreset` is included as a reference implementation for monorepo layouts.
- ## AI-Friendly Authoring Notes
- If an AI agent is generating or updating guardrail specs, these conventions work best:
- - keep one dimension per file
- - make the frontmatter executable and the body explanatory
- - prefer stable command outputs over fragile text matching
- - use `hard_gate: true` only when failure should really block progress
- - keep review-trigger rules separate from scoring metrics
- - treat markdown as the narrative layer, not the only source of structure
- Recommended file layout:
- ```text
- your-project/
- docs/
- fitness/
- README.md
- manifest.yaml
- code-quality.md
- security.md
- runtime/
- observability.md
- performance.md
- review-triggers.yaml
- ```
- Minimal bootstrap flow for a new repository:
- ```bash
- mkdir -p docs/fitness
- cat > docs/fitness/code-quality.md <<'EOF'
- ---
- dimension: code_quality
- weight: 100
- threshold:
- pass: 100
- warn: 80
- metrics:
- - name: lint
- command: npm run lint 2>&1
- hard_gate: true
- tier: fast
- ---
- # Code Quality
- EOF
- entrix validate
- entrix run --tier fast
- ```
- Bootstrap authoring rules:
- - keep default local `entrix run` green on a fresh machine
- - if a command is authoritative only in CI or a provisioned environment, model
- it with `execution_scope: ci` instead of leaving it in the default local path
- - update every existing agent entry document consistently:
- `AGENTS.md`, `CLAUDE.md`, or both
- - if neither entry document exists, create only `AGENTS.md`
- Recommended bootstrap policy:
- - do not stop at a plausible draft; the bootstrap is done only after local
- `entrix validate` and plain local `entrix run` pass
- - keep default local runs backed by repo-safe wrappers or cheap smoke checks
- - move authoritative but provisioned checks into `execution_scope: ci`
- - treat `AGENTS.md` and `CLAUDE.md` discoverability as part of the bootstrap,
- not optional follow-up cleanup
- The repository also ships a bundled skill at `skills/entrix/` for agents that
- need to generate or repair `docs/fitness/` automatically. The skill follows the
- same bootstrap rules above and is validated against multiple real repositories.
- ## Skill Regression Harness
- The bundled `/entrix` skill ships with two regression modes:
- ```bash
- bash scripts/skill_regression.sh --fixtures
- bash scripts/skill_regression.sh /abs/path/to/repo-a /abs/path/to/repo-b
- ```
- - `--fixtures` validates bundled repository profiles under
- `tests/fixtures/skill_regression/`
- - path mode injects the bundled skill into each target repository, runs
- `claude -p /entrix`, then verifies the result with `entrix validate`,
- `entrix run --dry-run`, `entrix run --tier fast`, and plain `entrix run`
- Use fixture mode in CI and path mode for local forward validation against real
- repositories before publishing skill changes.
- ## Python API
- ### Review trigger example
- ```python
- from pathlib import Path
- from entrix.review_trigger import (
- collect_changed_files,
- collect_diff_stats,
- evaluate_review_triggers,
- load_review_triggers,
- )
- repo_root = Path(".").resolve()
- rules = load_review_triggers(repo_root / "docs" / "fitness" / "review-triggers.yaml")
- changed_files = collect_changed_files(repo_root, "HEAD~1")
- diff_stats = collect_diff_stats(repo_root, "HEAD~1")
- report = evaluate_review_triggers(rules, changed_files, diff_stats, base="HEAD~1")
- print(report.to_dict())
- ```
- ### Fitness spec loading example
- ```python
- from pathlib import Path
- from entrix.evidence import load_dimensions
- dimensions = load_dimensions(Path("docs/fitness"))
- for dimension in dimensions:
- print(dimension.name, len(dimension.metrics))
- ```
- ## Recommended Hook Integration
- For generic repositories, a practical pattern is:
- - `pre-commit`: run `entrix hook file-length` first, then quick lint
- - `pre-push`: run full checks, then print review-trigger warnings
- - CI: run `entrix run` and publish JSON/report output
- That lets automation catch deterministic failures early while still escalating ambiguous risky changes to humans.
- ### Current Routa.js hook layout
- The current Routa.js monorepo intentionally uses a slightly different split:
- - `pre-commit`: `npm run lint`
- - `post-commit`: `PYTHONPATH=tools/entrix python3 -m entrix hook file-length --config tools/entrix/file_budgets.pre_commit.json --strict-limit ...` as a warning-only budget report
- - `pre-push`: `./scripts/smart-check.sh`, which runs a curated `entrix run --metric ...` set and then evaluates `review-trigger`
- This keeps commit-time friction low while still surfacing file-budget drift and
- enforcing the higher-signal fitness gates before push.
- ## Submodule Bump Guidance
- If Entrix is vendored into a larger repository as a git submodule:
- - push the Entrix release commit first from a clean `tools/entrix` worktree
- - update the superproject pointer in its own commit
- - prefer a clean superproject branch or worktree for the pointer bump so
- unrelated application fitness hooks do not block a pure submodule update
- This keeps Entrix releases and superproject pointer bumps reviewable as separate
- changes.
- ### Reusable file-length guard
- `entrix` now exposes a reusable hook entrypoint:
- ```bash
- python3 -m entrix hook file-length \
- --config tools/entrix/file_budgets.pre_commit.json \
- --staged-only \
- --strict-limit
- ```
- Use it when you want AI-friendly oversized-file failures during `pre-commit`, for example:
- ```text
- current file length 2383 exceeds limit 1600: src/app/page.tsx
- ```
- A copy-pasteable template lives in [`examples/file-length-hook/`](examples/file-length-hook/).
- ## Project Status
- Current state:
- - stable for production use in real repository workflows
- - installable as a standalone PyPI package
- - suitable for AI-assisted project configuration
- Current boundaries:
- - the default authoring format is markdown frontmatter under `docs/fitness`
- - graph commands require the optional graph dependency: `pip install entrix[graph]`
- - the current public CLI in this checkout exposes `run`, `validate`, `review-trigger`, `hook`, `analyze`, and `graph`
- - `analyze long-file` structural analysis supports Python, Rust, Go, Java, TypeScript, and JavaScript
- - the internal architecture is still evolving toward a cleaner core / adapter / preset split
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines and contribution workflow.
- ## License
- This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.