Nomos: The 3-Pass Developer Tutorial Handbook

Welcome to Nomos. Whether you are pair-programming with Claude Code, Cursor, or Antigravity, Nomos provides the deterministic execution harness that keeps your codebase clean, linear, and rot-free.

This handbook takes you on a 3-pass journey: from instant single-developer guardrails to advanced enterprise policy customization.

🏃 Pass 1: Solo Developer Quickstart (Day 1: Zero Friction)#

Goal: Get up and running in under 2 minutes. Protect your main branch, give your AI coding agent a sandbox, and release clean code without merge drama.

Step 1: Universal Installation#

Install the pre-compiled nomos binary directly into your standard Go binary path ($GOBIN / $(go env GOPATH)/bin / ~/go/bin):

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

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

Step 2: Initialize Your Repository Once#

Inside any Git repository (Go, TypeScript, Python, Rust, or Polyglot):

cd my-project
nomos init

What just happened?

• nomos init scaffolded nomos.yaml, indirect-control contracts (AGENTS.md, CLAUDE.md), ambient lifecycle hooks (.agents/hooks.json), and self-healing Git defense hooks that lock your main trunk.
• Zero custom slash commands or manual nomos handshake calls are required: your coding agent triggers nomos handshake automatically on SessionStart when you prompt in plain English.

Step 3: Fast Maintenance with Chores#

Need to fix a typo, update a config, or patch a bug?

nomos task chore "Fix database reconnect timeout"

Sample Output:

🚀 Task SUB-1 started successfully!
  Branch:   feature/SUB-1
  Worktree: worktrees/my-project-SUB-1
  Phase:    EDIT

You are immediately placed in an isolated Git worktree. Your main branch is untouched.

Step 4: Verify the 7x3 Invariant Suite#

Once code changes are made:

nomos verify

Sample Output:

🛡️  Nomos Definition of Done (DoD) Gatekeeper
────────────────────────────────────────────────────────────
  Phase Discipline Invariant       : PASSED
  Hermetic Worktree Invariant      : PASSED
  Go Toolchain Invariant           : PASSED
  Cognitive Debt Score Invariant   : PASSED (CDS: 18, max: 45)
  Anti-Shim AST Invariant          : PASSED
  Secret & Credential Leak Gate    : PASSED
────────────────────────────────────────────────────────────
  ✅ DoD verification succeeded!

Step 5: Atomic Two-Phase Commit Release#

Merge directly to main with cryptographic receipts:

nomos task sync SUB-1 -F .tmp/walkthrough.md

The worktree is cleanly removed, main is updated linearly, and the release receipt is recorded in Git Notes.

🧭 Pass 2: Team Flow & Cryptographic Receipts (Week 1: State & Memory)#

Goal: Scale to teams. Audit agent execution, leverage semantic vector recall, and inspect cryptographic proofs.

1. Living Ledger & Topological Planning#

Nomos tracks the execution wavefront across architectural planes:

# View active tasks
nomos task list

# Inspect causal dependency DAG
nomos task dag

2. Semantic Memory Recall with Nomos Mneme#

Every release walkthrough and architectural reflection is vectorized into local SQLite (mneme.db):

# Save an architectural finding
nomos mem save "Redis lock timeouts require jitter backoff" --kind decision --topic "infra/redis"

# Recall past solutions semantically
nomos mem recall "how did we handle redis lock timeouts?"

3. Intent-to-Substrate Parity Audit#

Ensure your code, CUE schemas, and documentation links match your architectural specifications:

nomos verify

Verifies that all exported functions, @intent traceability anchors, CUE schemas, and embedded templates maintain 1:1 parity across all 42 DoD gates.

4. Cryptographic Release Receipts#

Inspect mathematical gate integrity and release proofs attached to Git Notes without polluting commit history:

nomos verify proof

Or inspect any release receipt directly via standard Git:

git notes --ref=nomos/releases show HEAD

🛠️ Pass 3: Deep Customization (Month 1: Power Users & Platform Teams)#

Goal: Mold Nomos to your organization's exact architectural policies, custom AST linters, and capability rules.

1. Declarative Dials in nomos.yaml#

Fine-tune quality gate thresholds for your team (shown with statutory defaults):

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. Custom CUE Schemas#

All task contracts and YAML configurations are strictly verified against CUE schemas in intent/contracts/cue/. You can extend task schemas with required compliance fields (e.g., SOC2 tags, issue references, risk ratings).

3. Declarative Pipeline Customization (pipeline.cue)#

Add custom verification probes or calibrate phase bindings without recompiling the Go binary by declaring #GateSpec entries in intent/contracts/cue/pipeline.cue:

{
    id:      "custom_api_contract"
    name:    "Custom OpenAPI Schema Parity Gate"
    law:     4
    ring:    "dynamic"
    domain:  "Contracts & Schemas"
    sensor:  "custom"
    phase:   "REVIEW"
    enabled: true
    remedy:  "synchronize OpenAPI definitions with compiled Go handlers"
}

nomos verify dynamically evaluates intent/contracts/cue/pipeline.cue on every pre-flight and 2PC release check.

4. Polyglot Workspace Filters#

Nomos automatically detects and isolates non-source dependencies. In Python and Node environments, .venv/, node_modules/, and binary shared libraries (.so, .dylib) are automatically ignored during secret and cognitive scans.

🏁 Summary Checklist for Production Teams#

• Universal installer run across developer machines.
• nomos init bootstrapped once on protected repositories (ambient SessionStart hooks active).
• Quality gate thresholds calibrated in nomos.yaml.
• Release walkthroughs archived to .tmp/ and synced to Git Notes.