PRACTICAL WALKTHROUGH ZERO-CLI QUICKSTART ⏱️ 5 min read

The Invisible Harness: Zero-CLI Agent Walkthrough

Mark Gantlett
Mark Gantlett
Founder & Principal Systems Architect
Sophia AI
⚡ AI AUGMENTED
Tier 1 Frontier Reasoning + On-Premise RTX 4080 Silicon
FIG T1.1 // INVISIBLE HARNESS WALKTHROUGH - Install once, prompt your coding agent in plain English, and let compiled Go gates govern worktrees and 2PC merges underneath.

Nomos is not a CLI workflow you have to memorize or babysit by hand. It is an indirect-control governance layer that sits silently between your existing Tier 1 coding agent (Claude Code, Cursor, Antigravity, OpenCode, Windsurf, or Aider) and your Git repository.

Adoption follows a 3-rung progressive ramp with zero Day-1 workflow tax:

  • Pass 0 (nomos xray .): Audit any legacy repository in 5 seconds with zero file writes (--markdown, --sarif, --json).
  • Pass 1 (nomos init or nomos init --local): Enable Branch Guard with automatic brownfield baseline detection and auto-detected agent hooks (or a zero-footprint .git/info/exclude stealth trial), then code normally on feat/* branches.
  • Pass 2 (nomos init --ci & nomos init --worktrees): Scaffold offline GitHub Actions (SARIF 2.1.0) and GitLab CI workflows, enforce diff-scoped PR mutation proofs, and graduate to isolated worktrees/<repo>-<task> sandboxes with MTPO collision checks and atomic 2PC releases whenever ready.

Pass 0: Zero-Init Brownfield X-Ray (5 Seconds, Zero Writes)#

Goal: Quantify AI technical debt, skipped tests, hollow stubs, CWE sinks, and ready-to-lock architectural boundaries before touching a single file in your repository.

Before committing any configuration to an existing 50k-500k+ LOC repository, run the read-only polyglot X-Ray scanner after installing nomos:

curl -fsSL https://sophialabs.ca/install | bash
cd your-project
nomos xray .

nomos xray mutates zero files and outputs a Lipgloss terminal scorecard (--json, --markdown for PRs/Slack, or --sarif for OASIS SARIF 2.1.0 Code Scanning) in milliseconds across 11 languages (including pure-Go wazero WASM AST scanning for Java and C# with CGO_ENABLED=0):

  • AI Hangover Score (0-100, Grade A to Grade F): Composite Git-index-aware (git ls-files --cached --others --exclude-standard, honoring .gitignore) structural health index across 11 languages, automatically skipping untracked build artifacts, *.min.js, .svelte-kit, and .next.
  • Signature, Reuse & Structural Debt Signals: Flags structural code clones, >400 LOC monoliths, >60 LOC functions, high-arity (>8 parameter) signatures, deep control-flow nesting (>5 levels), and directory-scoped magic-string duplication clusters (>10 repeats).
  • Anti-Cheat & Security Signals: Counts empty/TODO function shims, skipped test annotations (t.Skip, @pytest.mark.skip, #[ignore], xit), swallowed/unchecked errors (_ = fn(), bare except: pass, empty catch {}), hardcoded secret/host-path leaks, and CWE taint sinks.
  • Ready-to-Lock Hexagonal Boundaries: Infers zero-violation directional architecture_boundaries you can freeze immediately on Day 0.

Pass 1: Day 1 - Progressive Branch Guard (nomos init & --local)#

Goal: Lock main, auto-baseline legacy debt, auto-detect installed coding agents, and work normally on feat/* branches in under 60 seconds.

Step 1: Install the Static nomos Binary Once#

Install the SHA-256-verified static Go binary (CGO_ENABLED=0, zero runtime dependencies) into your standard Go binary path ($GOBIN / $(go env GOPATH)/bin / ~/go/bin):

curl -fsSL https://sophialabs.ca/install | bash

Or compile directly from source with Go 1.26+:

CGO_ENABLED=0 go install github.com/mgantlett/nomos/substrate/cmd/nomos@main

(To uninstall cleanly at any time: curl -fsSL https://sophialabs.ca/uninstall | bash.)

Step 2: Initialize Branch Guard or Stealth Mode#

Inside any Git repository (Go, TypeScript/Svelte, Python, Rust, Ruby, C/C++, Java, Kotlin, C#, or polyglot):

cd your-project
nomos init                # Branch Guard + auto-baseline + auto-detected agent hooks (zero silent main commits)
# nomos init --local      # Optional: stealth trial registered solely in .git/info/exclude (clean git status)
  • Zero Silent Trunk Commits & Automatic Brownfield Baseline: Bare nomos init scans your codebase automatically, freezes observed legacy debt in nomos.baseline.json (strict_mode: false) when debt exists, keeps greenfield repos strict (--strict forces strict mode anywhere), and configures isolation_mode: "branch" without touching main history.
  • Stealth Trial (--local): Registers nomos.yaml, nomos.baseline.json, AGENTS.md, and installed agent hooks in .git/info/exclude instead of modifying .gitignore, keeping git status clean before opening a team PR.
  • Auto-Detected Agent Hooks (--agents): Automatically wires only the coding agents detected on your workstation (Claude Code, Cursor, OpenCode, Gemini CLI, or Antigravity) or accepts --agents claude,cursor to eliminate unwanted dot-dir clutter.
  • Compiled Contracts & Self-Healing Git Guards: Generates `nomos.yaml`, compact AGENTS.md / @AGENTS.md CLAUDE.md pointers, sub-5ms PreToolUse / PostToolUse / Stop hooks (nomos hook install for explicit additions), and Git hooks (pre-commit, commit-msg, post-commit, pre-push) that block direct mutations on main and automatically distill resolved traps into local mneme.db after passing feature-branch commits.

Step 3: Code on Normal Feature Branches With Any Agent#

Create a feature branch and prompt Claude Code, Cursor, Antigravity, OpenCode, or Windsurf in plain English:

git switch -c feat/ttl-cache
# Prompt your agent: "Add TTL cache eviction to Store with unit tests"
git add -A && git commit -m "feat: add TTL cache eviction"

Because nomos init wired ambient hooks and Branch Guard, pre-commit evaluates all 42 AST & toolchain gates on your diff before the commit lands, and post-commit distills verified patterns into mneme.db. When an agent hits a gate violation (empty stub, skipped test, function over 60 LOC, or hardcoded path), nomos verify returns a structured `NomosError` with the exact file, line, violated law, and remedy so the agent fixes itself on the next turn:

🛡️  Nomos Deterministic Engineering Substrate · Definition of Done
────────────────────────────────────────────────────────────────────────────
  Law 1: The Dual-Core Inversion Law    [3/3 Cells]     PASS   (Governance & Control)
  Law 2: The Non-Verbal Proof Law       [3/3 Cells]     PASS   (Epistemology & Verification)
  Law 3: The Hermetic Worktree Law      [3/3 Cells]     PASS   (State & Isolation)
  Law 4: The Single Source of Truth Law [3/3 Cells]     PASS   (Contracts & Schemas)
  Law 5: The Zero-Hardcoded-Path Law    [3/3 Cells]     PASS   (Portability & Environment)
  Law 6: The Canonical Singularity Law  [3/3 Cells]     PASS   (Action Space & Surface)
  Law 7: The Fail-Closed Pre-Flight Law [3/3 Cells]     PASS   (Safety & Budgets)
────────────────────────────────────────────────────────────────────────────
  ✅ All Laws Enforced · 42/42 Gates Satisfied

Pass 2: CI Proofs, Worktree Graduation & Episodic Memory (--ci & --worktrees)#

Goal: Add zero-phone-home CI verification + OASIS SARIF 2.1.0 Code Scanning, and graduate to isolated Git worktrees, write-time MTPO collision radar, and 2PC receipts when your team scales.

1. Scaffold Offline CI Workflows & GitHub PR Mutation Proofs (nomos init --ci)#

Generate deterministic CI workflows (.github/workflows/nomos-verify.yml with OASIS SARIF 2.1.0 upload and .gitlab-ci.yml) in one command, or run diff-scoped AST mutation testing (0 LLM tokens) across Go, TypeScript/JS, and Python:

# Generate zero-phone-home GitHub Actions (SARIF) & GitLab CI workflows:
nomos init --ci

# Generate a Zero-Trust PR governance & diff-scoped AST mutation proof receipt locally:
nomos verify --pr --mutate-diff

# Attest built-in gate mutation sensitivity (100% MS, 0% FPR):
nomos verify proof

(In GitHub Actions CI, you can also reference mgantlett/[email protected] via the root composite action.yml to post deterministic PR proof receipts in the Job Summary on every pull request.)

2. Graduate to Isolated Worktrees, Causal DAG & MTPO Radar (nomos init --worktrees)#

Whenever you want parallel multi-agent isolation (worktrees/<repo>-<task>), strict INT-* / SUB-* separation, and atomic 2PC release notes (refs/notes/nomos/releases), run nomos init --worktrees. Nomos then tracks live exported AST symbol hulls (MTPO) across sibling worktrees and warns on write-time symbol collisions before agents drift into merge conflicts:

# Upgrade an existing Branch Guard repository to hermetic worktrees:
nomos init --worktrees

# Inspect unified phase, active worktrees, CapBAC lease, and HATEOAS Next Actions:
nomos status

# Provision a hermetic chore worktree, run MTPO physics radar, or sync via 2PC:
nomos task chore "Add TTL cache eviction"
nomos task dag
nomos physics
nomos task sync SUB-1 -m "Add TTL cache eviction with unit coverage"
git notes --ref=nomos/releases show HEAD

3. Query, Seed & Surface Agent Tooling (Nomos Mneme & nomos --help-agent)#

Walkthrough lessons and passing feature-branch commits promote into pure-Go SQLite hybrid vector memory (mneme.db). Run nomos --help-agent anytime to inspect internal agent-harness RPCs (handshake, hook, directive, capabilities, physics, and the hidden read-only nomos mcp JSON-RPC 2.0 stdio server):

# Query hybrid 64-dim vector + lexical memory (< 50ms local query):
nomos mem recall "redis lock backoff"

# Record an explicit architectural decision for future agent sessions:
nomos mem save "Redis distributed locks require bounded jitter backoff" --kind decision --topic "infra/redis"

Pass 3: Month 1 - Policy Dials & Zero-Trust Guardrails (nomos.yaml)#

Goal: Calibrate AST budgets, zero-trust MCP boundaries, and bilateral contract parity for team and regulated repositories.

All policy configuration lives in nomos.yaml, backed by compiled Go SSoT structs (nomos.schema.json) and pinned against main (ThresholdIntegrityGate) so a coding agent inside a task worktree can never weaken your thresholds to force a failing build green.

1. Cognitive & Coverage Ratchets#

governance:
  quality_gates:
    thresholds:
      max_cognitive_debt_score: 45
      max_cyclomatic_complexity: 15
      max_file_loc: 400
      max_func_loc: 60
      min_comment_density_pct: 10
      min_test_coverage_pct: 55

2. Zero-Trust MCP & Compositional Taint Guards#

Restrict which Model Context Protocol (MCP) servers a coding agent can invoke and block untrusted web ingress from flowing into credential reads or outbound network sinks (`capability_flow_taint_guard_spec.md` and `zero_trust_mcp_ifc_spec.md`):

governance:
  mcp:
    default_policy: deny
    allowed_servers:
      - github-local
      - postgres-readonly

3. Declarative Outbound Egress, SSRF & Credential Airlock#

Lock down outbound shell HTTP/network commands (curl, wget, nc, ssh, scp) in PreToolUse with zero proxy infrastructure. Even in default allow mode, Nomos blocks cloud metadata/RFC1918 SSRF targets (169.254.169.254, localhost, private CIDR ranges) and outbound high-entropy API tokens (sk-*, ghp_*, AKIA*, PEM keys):

boundaries:
  egress_mode: allowlist            # allow | allowlist | offline
  allowed_egress_domains:
    - github.com
    - proxy.golang.org
    - registry.npmjs.org
  blocked_egress_domains:
    - pastebin.com
    - webhook.site

4. Strict Specification & Schema Parity#

For repositories maintaining formal intent/architecture/specs/*_spec.md contracts alongside implementation code, enable strict_mode and contracts so nomos verify enforces the Canonical Specification Blueprint, @intent AST anchors, and NCTE-100 prose deterministically:

governance:
  quality_gates:
    strict_mode: true
    contracts:
      contracts:
        enabled: true
        spec_roots: ["intent/architecture/specs"]
        schema_files: ["nomos.schema.json"]

Production Rollout Checklist#

  • Install nomos across developer workstations and CI runners (curl -fsSL https://sophialabs.ca/install | bash).
  • Run nomos xray . to audit baseline AI Hangover hotspots, then run nomos init (or nomos init --local for a zero-footprint .git/info/exclude stealth trial).
  • Run nomos init --ci (or wire mgantlett/nomos via action.yml) into pull-request CI so OASIS SARIF 2.1.0 findings and tautological agent tests are surfaced before review.
  • Code on normal feat/* branches with pre-commit verification, and run nomos init --worktrees whenever your team wants isolated worktrees and 2PC receipts (git notes --ref=nomos/releases show HEAD).
Mark Gantlett
⚡
Mark Gantlett
Founder, SophiaLabs & Principal Systems Architect
Architect of Nomos & Dual-Core Systems

This handbook is human-directed and AI-augmented, authored to eliminate the non-deterministic guessing of modern software engineering through compiled Go runtimes and machine-enforced Definition of Done gates.

1. Human Architecture
Mark Gantlett
System vision, architectural synthesis, and first-principles governance.
2. Tiered AI Augmentation
Sophia AI Stack
Frontier agentic orchestration paired with private zero-egress sovereign silicon.
3. Cognitive Inversion
Nomos Substrate
Go runtime as the core loop calling LLMs as bounded heuristic functions with AST gates.
Ask Sophia Docs & Specs Sophia AI · Grounded Nomos Architecture & Docs Concierge