MotusSupra | Build

THE HANDOFF

From site to software.

Control, Define, and Verify explained the model. Build is where you use it. Everything from installing the CLI through configuring your environment and scaling to your team.

the path

I understand the concept. Now I want to see it work.

install

get the CLI, init your repo

workflow

claim, evidence, release, receipt

contracts

define what must be true

gates

enforce policy at acceptance

CI

wire into your pipeline

scale

team adoption, org rollout

PREREQUISITES

What you need.

Python 3.9+, git, and a repo. That's it.

Motus doesn't replace your stack. It doesn't require a platform account, a hosted service, or a new database. Contracts live in your repo. Receipts export as JSON. The CLI runs locally.

You choose where data lives. You choose what to surface. You choose how to integrate. This is ownership by design, not missing features.

python3

3.9 or later

git

any recent version

a repo

where you want workflow discipline

no platform

contracts and receipts are yours

INSTALL

Get the CLI.

One pip install. Then init in your repo.

install

One command. If it breaks, I haven't lost anything.

# install the CLI
$ pip install motusos
$ motus --help

# init in your repo
$ cd your-repo
$ motus init --integrate .
$ motus doctor --json

FIRST WORKFLOW

Claim, evidence, release.

One workflow end to end. This is the pattern you will repeat for every piece of work. People, automation, or agents.

core loop

I want to see the full loop before I customize anything.

# set your agent ID
$ export MC_AGENT_ID=you-local

# claim work
$ motus work claim TASK-001 --intent "Add hello script" --json
# returns LEASE_ID

# make your change, then attach evidence
$ motus work evidence <LEASE_ID> test_result --passed 1 --failed 0 --json

# release
$ motus work release <LEASE_ID> success --json
# receipt recorded

VERIFY

Check your work.

After release, query your receipts and verify integrity locally. Local acceptance is authoritative. The Ledger is optional. Use it when you need proof across environments.

verify

I need proof I can point to. For myself, first.

# list recent work
$ motus work list --json

# show receipt
$ motus receipt show <RECEIPT_ID> --json

# verify receipt integrity
$ motus receipt verify <RECEIPT_ID>

WORK CONTRACTS

Define what must be true.

A work contract specifies scope, required checks, required evidence, and ownership before execution begins. The contract locks the decision so execution can move without reopening what was already settled.

why contracts

I need to define what done looks like before anyone starts.

scope

what paths can change, what files are in bounds

checks

what must pass: tests, lint, security scan, custom gates

evidence

what must exist: test results, coverage, screenshots, sign-off

ownership

who decides acceptance, who can release

# example work contract
work_id: TASK-042
scope:
  paths: ["src/auth/**", "tests/auth/**"]
checks:
  - pytest tests/auth
  - ruff check src/auth
evidence:
  - test_result: passed > 0, failed = 0
  - coverage: >= 80%
owner: @security-team

GATES

Two options to start.

Gates are userland policy. You have two practical paths: use the built-in policy runner or create a custom script.

gates

I need checks that can't be bypassed.

policy

motus policy run (fastest to start)

custom

repo gate script (recommended for team ownership)

# Option A: Motus policy gate
$ motus policy plan --repo . --files README.md --json
$ motus policy run --repo . --files README.md --json
# deterministic evidence bundle output

# Option B: Custom gate script
# scripts/gates/gate-001-no-todo.sh
#!/usr/bin/env bash
set -euo pipefail
if grep -RInE 'TODO|FIXME' . --exclude-dir=.git --exclude-dir=.motus --exclude='*.md' >/dev/null; then
  echo "FAIL: TODO/FIXME markers found in code."
  exit 1
fi
echo "PASS: no TODO/FIXME markers in code."

CI WIRING

Wire gates into your pipeline.

Gates run in CI like any other check. The verifier runs from a pinned reference so execution cannot modify the rules it is judged by.

ci

I need this wired into my existing pipeline, not a new system.

# .github/workflows/gate-001.yml
name: gate-001
on:
  pull_request:
    branches: [main]

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run gate-001
        run: ./scripts/gates/gate-001-no-todo.sh

# commit your gate + workflow
$ git add scripts/gates/gate-001-no-todo.sh .github/workflows/gate-001.yml
$ git commit -m "gate: add no-todo gate and CI workflow"

GITHUB GOVERNANCE

Leverage GitHub correctly.

Motus complements GitHub governance. It does not replace it. Configure these controls in your repo settings.

github

I need Motus to work with what I already have, not replace it.

protect main

require PR, require checks, block force-push

require gates

make your gate workflows required status checks

code scanning

enable code scanning and secret scanning

CODEOWNERS

require approval from owners for sensitive paths

human approval

require human sign-off for high-impact merges

SECURITY MODEL

What Motus secures. What you secure.

Motus is open source and local-first. Local acceptance is authoritative. You own security and controls. Motus gives workflow discipline and evidence structure. It is not a security appliance.

security

I need to know what's my job and what's Motus's job.

motus secures

acceptance boundary, pinned verification, receipts, provenance

you secure

IAM, credentials, endpoint hardening, network policy, secrets, branch protections, audit retention, incident response

threat model

Motus closes self-judging and self-attested compliance

not a runtime

Motus is not an execution sandbox, agent framework, or transport

ledger optional

Motus works without the Ledger; the Ledger only stamps receipts

The research preview is open to teams who want to pressure-test the control plane with real work.

Request access View on GitHub

Build.