The Invisible Harness: Zero-CLI Agent Walkthrough
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 initornomos init --local): Enable Branch Guard with automatic brownfield baseline detection and auto-detected agent hooks (or a zero-footprint.git/info/excludestealth trial), then code normally onfeat/*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 isolatedworktrees/<repo>-<task>sandboxes withMTPOcollision 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 AtoGrade 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 LOCmonoliths,>60 LOCfunctions, high-arity (>8parameter) signatures, deep control-flow nesting (>5levels), and directory-scoped magic-string duplication clusters (>10repeats). - Anti-Cheat & Security Signals: Counts empty/
TODOfunction shims, skipped test annotations (t.Skip,@pytest.mark.skip,#[ignore],xit), swallowed/unchecked errors (_ = fn(), bareexcept: pass, emptycatch {}), hardcoded secret/host-path leaks, and CWE taint sinks. - Ready-to-Lock Hexagonal Boundaries: Infers zero-violation directional
architecture_boundariesyou 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 | bashOr 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 initscans your codebase automatically, freezes observed legacy debt innomos.baseline.json(strict_mode: false) when debt exists, keeps greenfield repos strict (--strictforces strict mode anywhere), and configuresisolation_mode: "branch"without touchingmainhistory. - Stealth Trial (
--local): Registersnomos.yaml,nomos.baseline.json,AGENTS.md, and installed agent hooks in.git/info/excludeinstead of modifying.gitignore, keepinggit statusclean 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,cursorto eliminate unwanted dot-dir clutter. - Compiled Contracts & Self-Healing Git Guards: Generates `nomos.yaml`, compact
AGENTS.md/@AGENTS.mdCLAUDE.mdpointers, sub-5msPreToolUse/PostToolUse/Stophooks (nomos hook installfor explicit additions), and Git hooks (pre-commit,commit-msg,post-commit,pre-push) that block direct mutations onmainand automatically distill resolved traps into localmneme.dbafter 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 SatisfiedPass 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 HEAD3. 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: 552. 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-readonly3. 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.site4. 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
nomosacross developer workstations and CI runners (curl -fsSL https://sophialabs.ca/install | bash). - Run
nomos xray .to audit baseline AI Hangover hotspots, then runnomos init(ornomos init --localfor a zero-footprint.git/info/excludestealth trial). - Run
nomos init --ci(or wiremgantlett/nomosviaaction.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 withpre-commitverification, and runnomos init --worktreeswhenever your team wants isolated worktrees and 2PC receipts (git notes --ref=nomos/releases show HEAD).
Nomos