nuos-builder

A disciplined build harness for directing AI agents to plan, build, verify, and remember real software. nuos-builder scaffolds a structured build catalogue into your project and drives the work through planning protocols, an agent build loop, verification gates, and a searchable, local-first build memory.

nuos-builder is the engine. The consumer-facing product series built on it is Freehold — own the software you build, don't rent SaaS.

Quick start

This is the one command you run to set the harness up in a project:

npx nuos-builder init

init scaffolds docs/build/, methodfile.json, the slash-command protocols (.claude/commands/), CLAUDE.md, and the git/Claude hooks — then probes Ollama and pulls a small embedding model so semantic search works locally. It refuses to run if docs/build/ already exists.

Options:

| Flag | Effect | |---|---| | --name=X --tagline="Y" --role=consumer | Set project identity non-interactively | | --interactive | Guided prompts | | --no-llm | Skip the Ollama / embedding-model step |

What you get

Once initialised, you drive the build with slash commands (in Claude Code):

| Command | Does | |---|---| | /plan-orientation → /plan-review | Planning protocols: project, architecture, UI/UX, maps, first work units, review | | /wu-new, /build-wu | File a work unit; orchestrate an agent swarm to build it end-to-end | | /explore | Investigate a surface and file a durable finding | | /start-of-session, /end-of-session | Session discipline + verification gate |

…and the CLI underneath:

nuos-builder index                # index the build catalogue for semantic search
nuos-builder search "<query>"     # semantic search across decisions, WUs, contracts…
nuos-builder wu list|show|start   # work-unit operations
nuos-builder memory search …      # cross-agent build memory
nuos-builder state compile|drift-check
nuos-builder install-protocols    # refresh protocols/hooks after a CLI upgrade

The command nuos-catalogue remains as a hidden alias for backward compatibility; nuos-builder is the canonical name.

Semantic search & memory — sovereignty by default

The build catalogue is indexed for semantic search using a small, local Ollama embedding model (qwen3-embedding:0.6b, ~600 MB) — no network egress; your catalogue never leaves your machine. nuos-builder init pulls the model for you; you just need ollama serve running (--no-llm skips this).

For better recall on a machine with headroom, raise the model with NUOS_CATALOGUE_OLLAMA_MODEL=qwen3-embedding:4b (or :8b) and re-index. Changing the model needs a full reindex (rm -rf .nuos-catalogue && nuos-builder index) because the vector dimensions differ.

The index lives at .nuos-catalogue/index.nv with a sibling hashes.json, so re-indexing only re-embeds changed files. If it ever gets corrupt, delete .nuos-catalogue/ and re-run nuos-builder index.

Architecture in one paragraph

crawl walks the catalogue picking up .md files (skipping _index.md, done/, archive/, superseded/). Each file goes to chunkMarkdown, which splits on H1/H2/H3 boundaries (preserving code fences) into ~600-token chunks with deterministic IDs. extractMetadata produces structured metadata per file (kind, idInKind, status, date, cross-refs). The Embedder turns chunk texts into vectors; runIndex only re-embeds files whose content hash changed, then upserts them into NuVector. runSearch embeds the query and returns the top-K hits as a human-readable list or JSON.

Develop

npm install
npm run build        # tsc → dist/
npm test             # full suite (364 tests)
npm run typecheck

License

Proprietary. Published to npm as nuos-builder.