Quick start

Quick start

Five minutes, from clone to a remediation plan for one of your own repositories.

1. Install

git clone https://github.com/thiagocorreanet/mestre-yoda.git
cd mestre-yoda
npm ci
npm install --global .

Confirm it works:

mestre-yoda handshake

Provider: mestre-yoda@0.1.0
Protocol: 1.0.0
Mode: read-only
Capabilities: profiles.list, profiles.describe, project.inspect, project.recommend, project.check, project.plan, catalog.validate

Mode: read-only is the promise that everything below reads and nothing writes.

2. See what standards exist

mestre-yoda profiles

dotnet-modular-react-postgresql@1.0.0: .NET Modular + React + PostgreSQL

One profile ships in 0.1. To read what it prescribes:

mestre-yoda describe dotnet-modular-react-postgresql

.NET Modular + React + PostgreSQL (dotnet-modular-react-postgresql@1.0.0)
Golden Path for ASP.NET Core .NET 10 APIs built as a modular monolith, with React applications and PostgreSQL.
Rules: 21
Digest: sha256:89963b03fac95b7af4972176a46b92143948ddf280b3bc627d53539af797b56f

Note the digest. It identifies this exact catalog content, and it is what a pipeline pins so a silent catalog change cannot flip a build result. See Scoring and compliance.

3. Look at your repository

Start with inspect, which reports raw observations without judging them:

mestre-yoda inspect --root ~/code/my-api

Project: /home/you/code/my-api
Files: 412
✓ apiVersioning
✓ applicationLayer
· architectureTests
✓ authorizationPolicies
· defaultDeny
✓ domainLayer
...

A checkmark means the signal was found, a dot means it was not. Every signal and its detection method is documented in the signal reference. If a signal you expected is missing, that page tells you exactly what the detector looks for.

4. Ask which standard fits

mestre-yoda recommend --root ~/code/my-api

Profile: dotnet-modular-react-postgresql@1.0.0
Stack confidence: 100%
Conformity: 77%

Stack confidence answers "is this the right standard for this repository". It looks at three signals only: a modular .NET solution, a React web app, and PostgreSQL through EF Core. Conformity answers "how well does it already comply". A repository can score 100% confidence and 40% conformity, which is the normal case for an existing project.

5. Get the compliance report

mestre-yoda check dotnet-modular-react-postgresql --root ~/code/my-api

Profile: dotnet-modular-react-postgresql@1.0.0
Status: not compliant
Score: 77%
Rules: 16 passed, 5 pending, 2 blocking
- [blocking] api.version-v1: Version public routes under /api/v1 and document the evolution policy.
- [blocking] security.default-deny: Set an authenticated FallbackPolicy and grant anonymous access only where it is declared.
- [required] database.migrations: Add versioned migrations and validate them before deployment.
- [required] quality.integration-tests: Add integration tests for the API and for PostgreSQL persistence.
- [recommended] quality.architecture-tests: Add architecture tests that prevent unwanted dependencies between layers.

Status is driven by blocking failures alone, not by the score. A repository at 95% with one blocking failure is still not compliant, and a repository at 60% with no blocking failures is compliant. That distinction is deliberate: the score measures distance, the status measures whether something dangerous is missing.

6. Get the plan

mestre-yoda plan dotnet-modular-react-postgresql --root ~/code/my-api

Plan: sha256:e58b0438750d3f3a8be336f57f383f24d36c7b67c3028912428be06f53f7aa84
Mode: read-only
Tasks: 5
1. [blocking] Version public routes under /api/v1 and document the evolution policy.
2. [blocking] Set an authenticated FallbackPolicy and grant anonymous access only where it is declared.
3. [required] Add versioned migrations and validate them before deployment.
4. [required] Add integration tests for the API and for PostgreSQL persistence.
5. [recommended] Add architecture tests that prevent unwanted dependencies between layers.

Same information as the report, ordered for someone who is about to do the work. Blocking first, then required, then recommended, with ties broken alphabetically by rule id so the order never shifts between runs.

The plan id is a SHA-256 over the profile digest, the detected signals, and the tasks. Store it and you can prove later which standard, against which observed state, produced which advice.

7. Switch to JSON when a program is reading

Every command takes --json:

mestre-yoda check dotnet-modular-react-postgresql --root ~/code/my-api --json

{
  "protocolVersion": "1.0.0",
  "provider": "mestre-yoda",
  "providerVersion": "0.1.0",
  "command": "check",
  "status": "success",
  "result": {
    "contractVersion": "1.0.0",
    "profile": { "id": "dotnet-modular-react-postgresql", "version": "1.0.0", "digest": "sha256:..." },
    "compliant": false,
    "score": 77,
    "summary": { "passed": 16, "failed": 5, "blocking": 2, "total": 21 },
    "rules": []
  }
}

Full envelope shapes in the provider protocol.

Where to go next

If a result surprised you, the signal reference explains what the detector actually looked for. If you want this in a pipeline, read CI integration. If the profile does not match how your team builds things, write your own with Authoring a profile.