Getting Started with Nomos

Nomos is a deterministic engineering substrate for autonomous AI coding agents. It replaces stochastic conversational guardrails with compiled Go binaries, isolated transient Git worktrees, SQLite transactional state, and 36 machine-enforced AST verification gates.

---

⚡ Prerequisites

• Go: 1.24+ (compiled substrate engine)
• Git: 2.40+ (worktree and notes support)
• Nix / Direnv (Optional, Recommended): For deterministic reproducible host environments
• SQLite: Local state engine (~/.nomos/data/db/)

---

📦 Installation & Setup

1. Build & Install CLI

Clone the repository and install the nomos binary directly into your ~/.nomos/bin or $GOPATH/bin:

git clone https://github.com/mgantlett/nomos.git
cd nomos
make install

Ensure ~/.nomos/bin is in your $PATH:

export PATH="$HOME/.nomos/bin:$PATH"

2. The Boot Handshake

Every agentic engineering session begins with the boot handshake. This verifies SQLite database health, indexes subconscious GitBrain memories, and injects localized architectural context:

nomos handshake

---

🔄 The 4-Stage Autonomous Engineering Loop

Nomos enforces strict Phase Discipline across four procedural gates:

stateDiagram-v2
    [*] --> PLAN : nomos task start [KEY]
    PLAN --> EDIT : nomos task transition EDIT
    EDIT --> REVIEW : nomos verify (36 Gates)
    REVIEW --> IDLE : nomos task sync --approve -F walkthrough.md
    IDLE --> [*]

1. Claim & Sandbox (PLAN Phase)

When an agent claims a task, Nomos snapshots uncommitted working tree diffs, provisions an isolated transient Git worktree (worktrees/[repo]-[task]), dynamically links dependencies via go.work, and locks the workspace to read-only PLAN phase:

nomos task start NOM-101

2. Transition to Edit (EDIT Phase)

Before modifying source code, the agent transitions to EDIT phase to acquire the cryptographic workspace lock:

nomos task transition EDIT

(For surgical ≤ 3-line hotfixes, use nomos task transition EDIT --override=surgical)

3. Definition of Done (REVIEW Phase)

Before committing, Nomos runs 39 binary AST quality gates verifying zero cyclomatic complexity debt (< 15), docstring density (≥ 10%), clean import boundaries, and full TDD test suite execution:

nomos verify

4. Atomic Release & Teardown (IDLE Phase)

Once verification passes, the release is executed via an atomic Two-Phase Commit (2PC):

nomos task sync --approve -F walkthrough.md

This command signs the phase state, validates the walkthrough schema, fast-forward merges into the active branch, prunes the feature branch, tears down the transient worktree, and resets the workspace to IDLE.

---

🧭 Next Steps

• Review the Unified Agent Protocol (AGENTS.md) for the 16 Core Architectural Axioms and 7 Invariant Laws.
• Explore the Core Architecture Specifications to understand the Dual-Core split and transient worktree sandboxing.
• Consult the CLI Command Reference for all flags and commands.
• Read Workflows & Playbooks to integrate Nomos into IDE agents.
• For high-level philosophical essays on AI engineering maturity, visit the SophiaLabs Handbook.