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:

curl -sSL https://raw.githubusercontent.com/mgantlett/nomos/main/install.sh | bash

Step 2: Initialize Your Repository#

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

cd my-project
nomos init
nomos hook init
nomos sys handshake

What just happened?

• nomos init created a clean .agents/ harness and nomos.yaml.
• nomos hook init installed CapBAC pre-commit defense hooks that lock your main trunk.
• nomos sys handshake verified SQLite database connectivity and initialized phase discipline.

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 28 Quality Gates#

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 --approve

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

# Plan topological execution wavefront
nomos task plan

2. Semantic Memory Recall with GitGudBrain#

Every release walkthrough and architectural reflection is vectorized into local SQLite (gitgudbrain.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 matches your architectural specifications:

nomos intent check

Verifies that all exported functions, ADRs, and schemas have 1:1 bidirectional traceability.

4. Cryptographic Release Receipts#

Inspect release proofs attached to Git Notes without polluting commit history:

nomos task receipt SUB-1

Or 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:

governance:
    quality_gates:
        thresholds:
            max_cognitive_debt_score: 45
            max_cyclomatic_complexity: 15
            max_file_loc: 400
            max_func_loc: 60
            min_test_coverage_pct: 65
    hitl:
        production_gate: true        # Require human sign-off on release

2. Custom CUE Schemas#

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

3. Dynamic Post-Sync Lifecycle Hooks#

Automate local builds, notifications, or binary installations whenever a task syncs: Create .nomos/hooks/post-sync:

#!/usr/bin/env bash
set -euo pipefail
# Automatically recompile binaries after 2PC merge
go install ./cmd/my-app
echo "🚀 Application rebuilt and ready in \$GOPATH/bin"

Nomos automatically detects and runs .nomos/hooks/post-sync upon every successful release merge.

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 hook init configured on protected repositories.
• Quality gate thresholds calibrated in nomos.yaml.
• Release walkthroughs archived to .tmp/ and synced to Git Notes.