naeos

README

Nusantara AI Engineering Operating System

The Engineering Control Plane for AI Coding Agents.

Build software with AI agents under explicit architecture, policy, execution, evidence, and verification controls.

NAEOS is an open-source engineering framework for building production software with AI coding agents. It provides the engineering layer between what a team intends, what an agent proposes, what is authorized to execute, and what can be independently verified afterward.

It is not another AI coding assistant. NAEOS is the control plane around the agent.

Why NAEOS?

AI coding agents can generate code quickly. Production engineering still requires explicit answers to harder questions:

What architecture is the agent operating within?
Which actions are allowed?
Who or what authorizes an external side effect?
What actually happened during execution?
What evidence proves the result?
Can another system independently verify the claim?
Can the same engineering intent be carried across different AI agents?

NAEOS treats these as engineering-system concerns rather than prompt-writing concerns.

The model

Without an engineering control plane:

Prompt → AI Agent → Code / Action → ?

With NAEOS:

Specification
      ↓
NEIR
      ↓
Validation + Policy
      ↓
Agent Context / Intent
      ↓
Authorized Execution
      ↓
Observation → Evidence
      ↓
Independent Verification

Two architectural views describe the same system:

Engineering model

Specification → NEIR → Validation → Policy → AI Context → Generation

AI Engineering control plane

Agent Intent → Policy Decision → Authorized Execution
            → Observation → Evidence → Independent Verification

The first describes how engineering knowledge moves through NAEOS. The second describes how agent actions are controlled and made auditable.

Core concepts

Concept	Role
Specification	Declares system intent and engineering requirements
NEIR	Canonical engineering representation derived from specifications
Policy	Determines which proposed actions are permitted
Runtime	Executes only within the authorized boundary
Evidence	Records observable results and integrity-relevant metadata
Verification	Independently checks claims about outputs or side effects
Handoffs	Carries explicit contracts between agents, tools, and execution boundaries
AI Compiler	Translates engineering context into agent-specific instructions
Extensions	Adds profiles, plugins, adapters, and integrations without changing the core model

See it run

The fastest way to understand NAEOS is the CLI control-plane demo:

git clone https://github.com/NAEOS-foundation/naeos.git
cd naeos

go build -o naeos ./cmd/naeos
./examples/demo-cli/run-demo.sh

The demo exercises the specification-first pipeline and produces traceable run metadata.

Golden Path: docs/GOLDEN-PATH.md defines the reproducible five-minute flow, acceptance criteria, and evidence map used for technical evaluation and regression testing.

Reference Demo & Evidence Story: docs/REFERENCE-DEMO.md turns the same run into an independent reviewer checklist, traceability narrative, and partner-pilot evidence format.

External Validation: docs/EXTERNAL-VALIDATION.md provides a reproducible third-party runbook and evaluation record. Engineering Note #001: docs/ENGINEERING-NOTE-001-EXTERNAL-VALIDATION.md explains the engineering rationale and evidence boundary for independent external validation.

External Validator Program: docs/EXTERNAL-VALIDATOR-BRIEF.md is the public entry point for Cohort #001; see Program and Missions for the program protocol.

For the Todo API demonstration:

go build -o naeos ./cmd/naeos
./examples/todo-api/run-demo.sh

See START-HERE.md for the supported onboarding path.

A concrete run

The naeos run path exposes structured engineering-run metadata, including identifiers such as:

run_id
specification_hash
neir_hash
validation_state
policy_evaluation
generated_context
artifacts
evidence

The goal is not merely to generate code. The goal is to preserve enough engineering context and evidence to understand what was intended, what was authorized, what happened, and what can be verified.

AI coding agents

NAEOS is designed to remain vendor-neutral at the engineering layer.

NAEOS targets Go 1.26.10 or later and can produce agent-specific instruction/context artifacts for tools such as:

GitHub Copilot
Claude Code
OpenAI Codex
Cursor
Gemini CLI
OpenCode
Windsurf

The engineering model remains upstream of the individual agent. Changing agents should not require rebuilding the project's engineering rules from scratch.

Evidence and verification

NAEOS includes engineering experiments and implementation paths around:

policy boundaries and authorization
durable audit/evidence records
tamper detection
handoff contracts
independent verification
artifact signing and verification
SBOM generation
security and vulnerability checks
benchmark and fuzz gates

These experiments are evidence of specific mechanisms and behaviors. They should not be interpreted as blanket proof of every production property.

See experiments/ for the current experiment suite, including the Evidence V5.6 milestone.

Trust model

NAEOS is built around explicit boundaries:

Intent is not authorization.
Policy decisions are distinct from runtime execution.
Observations are distinct from claims.
Evidence should outlive an agent's conversational memory.
Verification should not depend solely on the component making the claim.
Untrusted handoff input must not silently become downstream authority.
Controllable boundaries must be revalidated before consequential external actions.
Version and contract mismatches should fail closed where required by the governing specification.

These are engineering principles, not guarantees that every integration is automatically safe.

Architecture authority

NAEOS uses a normative documentation hierarchy:

Constitution
    ↓
Reference Architecture
    ↓
Master Technical Specification
    ↓
Engineering Specifications / ADRs
    ↓
Implementation
    ↓
Experiments

Public guides such as README, START-HERE, and GETTING-STARTED explain and navigate the system; they do not override normative specifications.

Start with DOCUMENTATION-AUTHORITY.md, then review:

Architecture Drives Engineering.

Repository map

naeos/
├── cmd/naeos/          # CLI
├── internal/
│   ├── specification/  # parsing, normalization, resolution
│   ├── neir/           # engineering representation
│   ├── compiler/       # AI instruction compilation
│   ├── governance/     # policy and governance
│   ├── runtime/        # execution gateway
│   ├── evidence/       # evidence storage
│   ├── verification/   # independent verification
│   ├── audit/          # audit trail
│   ├── signing/        # artifact signing
│   ├── pluginsdk/      # plugin SDK
│   └── ...             # supporting subsystems
├── pkg/                 # public Go packages
├── docs/                # engineering specifications
├── experiments/         # executable engineering experiments
├── constitution/        # project constitution
├── governance/          # governance material
└── examples/            # runnable examples

Current release

NAEOS 3.7.1 is the current documented software release.

NAEOS software releases and experiment milestones use different version sequences. For example, NAEOS 3.7.1 is a software release, while Evidence V5.6 identifies an engineering experiment milestone.

For release history and changes, see CHANGELOG.md.

Documentation

START-HERE.md — onboarding and first contribution path
GETTING-STARTED.md — developer setup
DOCUMENTATION-AUTHORITY.md — normative documentation model
WHITEPAPER-EN.md — English whitepaper
WHITEPAPER.md — official English whitepaper
DOCUMENTATION-INDEX.md — document index
docs/ — NAEOS engineering specifications
CHANGELOG.md — release history

Contributing

NAEOS is built in the open. Contributions are welcome across the engineering stack:

Track	Examples
Policy	authorization, governance, policy evaluation
Runtime	execution boundaries, lifecycle, runtime controls
Evidence	audit, receipts, integrity, evidence storage
Handoffs	agent/tool contracts and boundary revalidation
Verification	independent checks and trust mechanisms
Plugins	SDK, adapters, profiles, extensions
Experiments	reproducible engineering experiments and benchmarks
Documentation	specifications, architecture, guides

Read CONTRIBUTING.md, then start with START-HERE.md.

Slack + GitHub community

NAEOS uses Slack for real-time engineering coordination and GitHub as the durable engineering source of truth.

NAEOS Slack Community — real-time engineering discussion
GitHub repository — source code, issues, pull requests, and evidence

For workspace administrators, install the official GitHub integration for Slack, then subscribe the relevant channels to repository activity. The integration supports GitHub notifications, issue and pull-request collaboration, rich link previews, and GitHub actions from Slack. See GitHub's Slack integration documentation.

Recommended operating model:

Slack coordinates → GitHub records → CI verifies → Evidence closes the loop

For public community acquisition, use the workspace's Slack shared-invite URL rather than the workspace home URL. Keep that invite URL configurable in the website deployment so it can be rotated without changing repository code.

Community and partnerships

GitHub Discussions — technical discussion and ideas
Discord — community discussion
NAEOS Partner Program — technology, infrastructure, AI, academic, community, pilot, and strategic collaboration

Social identity and distribution

Social Identity Source of Truth defines the canonical public positioning, channel roles, profile copy, visual rules, and verification status for NAEOS social distribution.

Security and governance

SECURITY.md — supported release lines and security reporting
Engineering Constitution — project-level engineering principles
Governance — project governance material
AI-assisted provenance policy — guidance for AI-assisted contributions
Open-core boundary — relationship between NAEOS Core and future offerings
Legal Architecture — IP provenance, trademarks, third-party licensing, and release legal controls

License

NAEOS is released under the Apache License 2.0. See NOTICE for attribution and branding information.

Contributions are accepted under the Developer Certificate of Origin as described in CONTRIBUTING.md.

The NAEOS, NEIR, and NAEOS logo names are branding of the NAEOS OSS. The Apache License grants no trademark rights; see NOTICE for the current branding and trademark policy.

Active development · NAEOS 3.7.1

Architecture Drives Engineering.