NAEOS Foundation — NAEOS

Specify Once. Build Anywhere.

NAEOS (Nusantara Engineering & Architecture Operating System) is a declarative engineering platform that transforms specifications into high-quality software systems through a consistent, validated, and extensible pipeline.

NAEOS is not just a project generator. NAEOS is an engineering runtime that understands specifications, builds an internal model, orchestrates execution plans, generates artifacts, validates results, and keeps projects aligned with specifications throughout their lifecycle.

Vision

Build an open-source engineering platform that enables developers and organizations to describe their system once, then build, validate, and evolve software across multiple languages, frameworks, and platforms.

Quick Start

# Clone dan build
git clone https://github.com/NAEOS-foundation/naeos.git
cd naeos
go build ./cmd/naeos/

# Buat spesifikasi
cat > spec.yaml << 'EOF'
project: my-app
modules:
  - name: auth
    path: ./auth
  - name: api
    path: ./api
    dependencies: [auth]
services:
  - name: gateway
    kind: http
    port: 8080
architecture:
  pattern: hexagonal
generation:
  languages: [go, typescript]
EOF

# Init membuat config (naeos.yaml) yang otomatis dideteksi oleh run
naeos init
naeos run --input-file spec.yaml

# Generate AI context
naeos context --input-file spec.yaml

# Compile ke AI tools
naeos ai compile --input-file spec.yaml --target opencode

Features

Core Pipeline

• Parser — YAML/JSON specification parsing with variable interpolation
• Normalizer — data normalization
• Resolver — cross-reference resolution
• NEIR Builder — unified project model
• Validator — comprehensive validation (circular deps, port conflicts, module boundaries)
• Scheduler — DAG-based task scheduling
• Generator — multi-language code generation (Go, TypeScript, Python, Java, Rust)

Spec Language v2

• ${var} — variable interpolation
• $env{VAR} — environment variable resolution
• $ref{path} — cross-reference resolution
• $include{file} — multi-file spec composition
• $fn{name(args)} — custom functions (upper, lower, slug, default, len, coalesce)
• $if{condition} / $endif — conditional sections
• Schema versioning with auto-check (minimum v0.1.0)

AI Integration

• Compiler — transform NEIR ke AI instruction sets
• 6 Output Adapters:
  • GitHub Copilot — .github/copilot-instructions.md
  • Claude Code — CLAUDE.md
  • Cursor — .cursorrules
  • Gemini CLI — .gemini/CONFIG.md
  • Codex — AGENTS.md
  • OpenCode — AGENTS.md
• MCP Server — Model Context Protocol untuk AI agent integration
• Context Bundles — LLM-optimized project summaries

Marketplace

• Profile Marketplace — publish, search, download industry profiles
• Plugin Marketplace — install, uninstall, search plugins
• 5 Built-in Profiles: SaaS, AI Agent, FinTech, Healthcare, Government

Governance

• Policy Evaluator — 7 operators, 5 default rules
• Artifact Review — governance rules
• Audit Trail — traceability

Developer Tools

• 67 CLI Commands — run, validate, compile, context, test, docgen, mcp, marketplace, etc.
• Watch Mode — hot-reload pipeline on spec changes
• Diff Engine — compare specs with colorized output
• Migration Engine — schema version transforms (v0.1→v0.2→v0.3)
• Testing Framework — multi-language test runner
• Documentation Generator — auto-generate API/module docs
• Benchmarks & Fuzz Testing — performance and robustness
• Docker — multi-stage Dockerfile

Architecture

┌─────────────────────────────────────────────────────────┐
│                    NAEOS Architecture                     │
├─────────────┬──────────────┬──────────────┬─────────────┤
│    Input    │  Core Layer  │  Generation  │   Output    │
├─────────────┼──────────────┼──────────────┼─────────────┤
│  Spec YAML  │   Parser     │   Generator  │  Code Files │
│  CLI cmds   │   Normalizer │   Adapters   │  Configs    │
│  Profiles   │   Resolver   │   Renderers  │  Docs       │
│  Context    │   Validator  │   Compiler   │  AI Context │
│             │   Scheduler  │   Profiles   │  Artifacts  │
│             │   Kernel     │              │             │
│             │   Policy     │              │             │
│             │   Review     │              │             │
└─────────────┴──────────────┴──────────────┴─────────────┘

Core Components

Kernel

The kernel provides the runtime foundation:

• Service Registry
• Event Bus (pub/sub)
• Telemetry Collection
• Lifecycle Management

Specification

Specifications use NAEOS Specification Language v2 as the single source of truth.

NEIR

NAEOS Engineering Intermediate Representation is the central engineering model representing the entire system. NEIR encompasses project, architecture, domain, module, component, service, API, storage, infrastructure, security, AI, documentation, deployment, testing, and metadata.

Compiler

The compiler transforms NEIR into AI instruction sets for 6 target tools.

Marketplace

A marketplace for profiles, plugins, and templates that can be published, searched, and installed.

CLI Commands

Repository Structure

cmd/naeos/           # CLI commands (35+ files)
internal/
  specification/     # Parser, normalizer, resolver
  neir/             # NEIR model and builder
  compiler/         # AI instruction compiler
  context/          # Context bundle generator
  generation/       # Code generation
  governance/       # Policy and review
  artifacts/        # Artifact store
  profiles/         # Industry profiles
  marketplace/      # Profile & plugin marketplace
  migration/        # Schema migration
  mcp/              # MCP server
  testrunner/       # Test framework
  docgen/           # Documentation generator
  diff/             # Diff engine
  watch/            # File watcher
  security/         # Security rules
  knowledge/        # Knowledge graph
  database/         # Database layer (PostgreSQL, MySQL, SQLite)
  websocket/        # WebSocket real-time communication
  eventsourcing/    # Event sourcing and aggregate snapshots
  distributed/      # Distributed task execution
  configreload/     # Configuration hot-reload
  pipelinecache/    # Pipeline result caching
  pipelinemiddleware/ # Composable pipeline middleware
  audit/            # Audit logging layer
  hcl/              # HCL configuration parser
  profiledetect/    # Automatic language/framework detection
  ai/               # AI service and LLM integration
  pluginsdk/        # Plugin SDK with WASM runtime
pkg/
  pipeline/         # Main pipeline
  kernel/           # System kernel
  config/           # Configuration
  plugin/           # Plugin system
docs/               # Documentation (56 NES specs)

Documentation

• WHITEPAPER-EN.md — official whitepaper (English)
• WHITEPAPER.md — whitepaper resmi (Bahasa Indonesia)
• DOCUMENTATION-INDEX.md — document index
• GETTING-STARTED.md — onboarding guide
• CONTRIBUTING.md — contribution guidelines
• CHANGELOG.md — version history
• docs/ — 57 NES specification documents (NES-000 to NES-054, including Kernel API and NEIR Model references)

Roadmap

Completed

• v0.1.0 — Foundation (parser, NEIR, pipeline, CLI)
• v0.2.0 — Compiler Foundation (6 adapters, artifact store, profiles)
• v0.3.0 — Core Specification (Spec v2, validation, context bundles)
• v0.4.0 — MCP Server, migration engine, marketplace, benchmarks
• v1.0.0 — Stable release (test coverage, security hardening, 67 commands)
• v1.1.0 — Critical fixes (WebSocket races, interface{}→any, godoc, OpenAPI)
• v1.2.0 — Database layer (PostgreSQL/MySQL/SQLite, retry, logging, health checks)
• v1.3.0 — Quality, Correctness & Production Readiness (code gen fixes, security audit, CLI --output json/yaml)
• v1.3.1 — Code Quality & Lint Compliance (999 issues resolved, 22 unused symbols removed)
• v1.4.0 — Prompt Library & Platform Improvements (YAML templates, observability dashboard, workflow manager)
• v1.5.0 — Production Hardening (HTTP timeouts, context propagation, error logging, SSE fixes, test fixes)
• v2.1.0 — RBAC, multi-tenant workspaces, schema registry API, industry profiles, compliance export
• v2.2.0 — Supabase backend integration, lint zero-failure, fuzz testing, coverage-gated CI
• v3.0.0 — Pipeline profiling, stage caching, schema-based validation, NEIR-aware LSP server, official plugin examples
• v3.1.0 — Pipeline caching on naeos run, run-level profiling (--profile/--pprof), architecture patterns, WASM plugin hardening

For upcoming work, see DEVELOPMENT_PLAN.md and ROADMAP.md.

License

Apache License 2.0

Status

🟢 Active Development — NAEOS is under active development with full features for specification-driven engineering. Latest version: v3.1.0 (Pipeline caching on naeos run, run-level profiling, architecture patterns, WASM plugin hardening).