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.

You run two setup commands once per repository. After that, you prompt your coding agent in plain English the exact way you already do while Nomos enforces hermetic worktree isolation, 42 polyglot AST and toolchain gates, and atomic Two-Phase Commit (2PC) releases underneath the agent.

Pass 1: Day 1 - Two Commands Once, Zero CLI After#

Goal: Protect main, sandbox your coding agent inside isolated Git worktrees, and ship verified commits in under 60 seconds without changing how you prompt.

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 Your Repository Once#

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

cd your-project
nomos init

nomos init detects your language stack and drops four deterministic artifacts into the repository:

nomos.yaml: Stack-calibrated governance configuration validated against `nomos.schema.json`.
AGENTS.md & CLAUDE.md: Compiled indirect-control contracts instructing any Tier 1 coding agent on the 7 Laws, worktree isolation, and phase discipline.
.agents/hooks.json: Sub-5ms ambient lifecycle hooks (nomos hook session-start, pre-tool, post-tool) providing automatic session boot, 3-strike loop circuit-breaking, and compositional taint protection.
Self-healing Git defense hooks (pre-commit, commit-msg, pre-push): Physical branch guards that block direct commits on main even if an agent ignores prompt instructions.

Step 3: Prompt Your Coding Agent in Plain English#

You are done with the terminal. Open Claude Code, Cursor, Antigravity, OpenCode, or Windsurf and ask for a feature or fix in natural language:

> "Add TTL cache eviction to Store with unit tests"

Because nomos init wired ambient hooks and repository contracts, your coding agent autonomously drives the entire Nomos lifecycle under the hood (none of these commands are typed by you):

# 1. Triggered automatically on SessionStart (~4ms):
nomos handshake                                    # Verifies CapBAC state & recalls repo memory

# 2. Executed autonomously by your coding agent:
nomos task chore "Add TTL cache eviction"          # Provisions hermetic worktrees/<repo>-SUB-1
# ... agent edits code & tests inside worktrees/<repo>-SUB-1 (~24ms AST post-tool checks) ...
nomos verify -w worktrees/your-project-SUB-1       # Evaluates all 42 AST & toolchain DoD gates
nomos task sync SUB-1 -F .tmp/walkthrough.md       # Atomic 2PC fast-forward merge to main + Git Note

When the agent hits a quality gate violation (such as an 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 self-healing remedy so the agent fixes its own mistake on the very next turn before merging to main:

🛡️  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: Week 1 - Operator Visibility, Proof & Memory#

Goal: Inspect cryptographic audit trails, review causal task graphs, and steer multi-session memory when you want deeper visibility into what your agents shipped.

While your coding agent handles day-to-day execution automatically, operators use four read-and-audit surfaces to inspect provenance or seed architectural decisions:

1. Inspect Cryptographic Release Receipts (`Git Notes`)#

Every atomic nomos task sync attaches a tamper-evident JSON verification receipt directly to refs/notes/nomos/releases without polluting commit messages:

# Inspect the 2PC verification receipt on the latest commit on main:
git notes --ref=nomos/releases show HEAD

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

2. Inspect the Causal `INT-` / `SUB-` DAG#

For multi-step architectural work where specifications (INT-*) and implementation (SUB-*) evolve as linked twins:

# View active tasks, worktrees, and lifecycle phases:
nomos task list

# Render the causal dependency wavefront:
nomos task dag

3. Query & Seed Repository Memory (`Nomos Mneme`)#

Walkthrough lessons and architectural patterns promote into local pure-Go SQLite hybrid vector memory (mneme.db) strictly after a verified 2PC release receipt:

# 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"

4. High-Signal Agent Steering (`NCTE-100`)#

Want to prompt agents with zero token waste? Inspect the 36-term Succinct Action Lexicon (Pair, Chore, Verify, Sync, Prune) via nomos directive --lexicon or read Chapter 11: The Agent-Steering Protocol & NCTE-100 Lexicon.

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. 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 init once per repository and commit the generated nomos.yaml, AGENTS.md, CLAUDE.md, and .agents/hooks.json to main.
Calibrate language coverage and complexity budgets in nomos.yaml before locking strict_mode: true.
Prompt your coding agent in plain English and verify your first 2PC receipt via git notes --ref=nomos/releases show HEAD.