naeos

README

Nusantara Engineering & Architecture Operating System

Specify once. Build anywhere.

NAEOS is a declarative engineering platform that transforms software specifications into validated, extensible engineering workflows. It provides a consistent model for defining, generating, governing, and evolving software systems.

Unlike a project generator, NAEOS maintains an engineering model throughout the lifecycle: it parses specifications, builds NEIR (NAEOS Engineering Intermediate Representation), validates dependencies and policies, orchestrates execution, generates artifacts, and compiles context for AI development tools.

Vision
How NAEOS works
Quick start
Demo
Capabilities
Architecture
Core components
CLI commands
Repository structure
Documentation
Roadmap
Contributing
License

Vision

NAEOS aims to help developers and organizations describe a system once, then build, validate, and evolve it across languages, frameworks, and platforms through an open-source engineering platform.

How NAEOS works

Specification
     │
     ▼
Parse → Normalize → Resolve → Build NEIR → Validate
                                             │
                                             ▼
                                  Schedule → Generate
                                             │
                                             ▼
                           AI context · Governance · Artifacts

The specification is the source of truth. NAEOS turns it into a structured engineering model that can be consumed by validation, generation, governance, documentation, and AI tooling.

AI Engineering Control Plane

NAEOS now exposes a coherent control-plane workflow around the existing pipeline:

Specification
  ↓
Parse → Normalize → Resolve → Build NEIR
  ↓
Validate → Policy → AI Context
  ↓
Execution / Generation
  ↓
Artifacts → Evidence / Audit

The naeos run command is the primary demonstration path. In JSON mode it returns explicit engineering-run metadata such as run_id, specification_hash, and neir_hash, so a developer can trace the exact specification, derived NEIR, validation state, policy evaluation, generated context, and produced artifacts.

Project guides

Marketing strategy — evidence-based positioning, content calendar, funnel, and experiments.
Marketing experiment template — record campaign hypotheses, metrics, results, and learnings.
Marketing assets — posts, scripts, video demo, and backlog for social campaigns.

Social posting scripts

Scripts in scripts/ publish announcement content to community channels. Credentials (tokens) live in the gitignored .env; never commit them.

Script	Purpose	Env vars	Example
`scripts/linkdin-post.sh`	Post to the personal LinkedIn feed (Posts API, public)	`LINKEDIN_ACCESS_TOKEN`, `LINKEDIN_URN`	`./scripts/linkdin-post.sh --file brand/marketing/linkedin-post-cli-demo.md`
`scripts/social-post.sh`	Post today's `brand/marketing/content-calendar.json` entry to Discord/Slack/LinkedIn	`DISCORD_TOKEN`, `DISCORD_ANNOUNCE_CHANNEL`, `NAEOS_SLACK_TOKEN`, `NAEOS_SLACK_ANNOUNCE_CHANNEL`, `LINKEDIN_ACCESS_TOKEN`, `LINKEDIN_URN`	`./scripts/social-post.sh --dry-run --date 2026-09-10`

The content calendar lives at brand/marketing/content-calendar.json (date → platforms → message per channel). The social-post.yml workflow runs it automatically at 07:30 UTC daily; the required values are supplied as GitHub repository secrets (DISCORD_TOKEN, DISCORD_ANNOUNCE_CHANNEL, NAEOS_SLACK_TOKEN, NAEOS_SLACK_ANNOUNCE_CHANNEL, LINKEDIN_ACCESS_TOKEN, LINKEDIN_URN).

All scripts support --dry-run to preview the payload without publishing. social-post.sh also guards against duplicate posts (retries failed sends up to 3 times, logs every post to .social-post.log, and skips dates/platforms already sent), plus --show-log / --reset-log for inspecting or clearing that log.

Quick start

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

# Create a specification
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

# Initialize configuration and run the pipeline
naeos init
naeos run --input-file spec.yaml

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

# Compile instructions for an AI tool
naeos ai compile --input-file spec.yaml --target opencode

The example above demonstrates the core workflow: define a specification, run validation and orchestration, generate an AI context bundle, and compile instructions for a target AI tool.

Requirements

Go 1.25 or later
Git

Run the local CLI demo

Run the complete local demo (validate → context → generate):

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

See examples/demo-cli/README.md for output location and optional AI compiler usage.

Demo

Watch the NAEOS demo on YouTube
English terminal demo — naeos-terminal-demo-en.mp4
Indonesian terminal demo — naeos-terminal-demo-id.mp4
30-second cuts — naeos-demo-30s.mp4 and naeos-demo-en-30s.mp4

The poster and local videos are available in brand/marketing/.

Capabilities

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 into AI instruction sets
7 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
- Windsurf — .windsurfrules
MCP Server — Model Context Protocol for AI agent integration
Context Bundles — LLM-optimized project summaries

Marketplace

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

Governance

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

Developer tools

200+ CLI Commands — run, validate, compile, context, test, docgen, mcp, marketplace, serve, sign, helm, sbom, airgap, evidence, verify, policy, control, 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 7 target tools.

Marketplace

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

CLI Commands

Command	Description
`naeos run`	Execute full pipeline
`naeos validate`	Validate specification
`naeos compile`	Compile to AI instruction sets
`naeos context`	Generate AI context bundle
`naeos test`	Run tests for generated code
`naeos docgen`	Generate documentation
`naeos mcp`	Start MCP server
`naeos marketplace`	Browse marketplace
`naeos profile`	Manage industry profiles
`naeos artifacts`	Manage artifact store
`naeos migrate`	Schema migration
`naeos doctor`	System health check
`naeos diff`	Compare specifications
`naeos watch`	Watch for changes
`naeos init`	Initialize config
`naeos create`	Create project
`naeos scaffold`	Generate scaffold
`naeos export`	Export artifacts
`naeos audit`	Audit specification
`naeos kernel`	Inspect kernel
`naeos plugin`	Manage plugins
`naeos template`	Manage templates
`naeos workspace`	Manage workspace
`naeos rollback`	Rollback changes
`naeos repair`	Repair specification
`naeos status`	Pipeline status
`naeos ai`	AI assistance
`naeos docs`	Documentation
`naeos lock`	Lock dependencies
`naeos version`	Version info
`naeos completion`	Shell completion

Repository Structure

cmd/naeos/           # CLI commands (200+ commands)
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
  configprovider/   # Config providers (env, file, K8s secret, Vault)
  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
  serve/            # Production server daemon
  sbom/             # SBOM generation (CycloneDX)
  signing/          # Artifact signing (Ed25519)
  verification/     # Independent verification
  evidence/         # Immutable evidence store
  helm/             # Helm chart scaffolding
  airgap/           # Air-gapped bundles
  runtime/          # Runtime execution gateway
pkg/
  pipeline/         # Main pipeline
  kernel/           # System kernel
  config/           # Configuration
  plugin/           # Plugin system
docs/               # Documentation (57 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, 200+ 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
v3.2.0 — Production server daemon (naeos serve), TLS, graceful shutdown, systemd integration
v3.3.0 — SBOM generation (CycloneDX), Ed25519 artifact signing, SBOM verifier
v3.4.0 — Helm chart scaffolding, air-gapped bundles, config providers

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

Contributing

Contributions, documentation improvements, issue reports, and new integrations are welcome. Start with the contribution guidelines, then review the getting started guide and open an issue or pull request.

Community & Support

Contributor ladder — the nine stages from Observer to Ecosystem partner.
Discussions — ask questions, share ideas, and show what you built.
Discord — real-time discussion with the community and maintainers.
Discussions guide — categories, norms, and how conversations become contributions.

Governance

Open-core boundary — how open-source NAEOS Core relates to future NAEOS Cloud / Enterprise offerings.
AI-assisted provenance policy — guidance for commits written or generated with AI tools.
Engineering Constitution and governance — how the project governs itself.

License

NAEOS is released under the Apache License 2.0. See the NOTICE for attribution and branding information. Contributions are accepted under the Developer Certificate of Origin (see CONTRIBUTING.md).

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

Status

Active development — The latest documented release is v3.5.0, which brings observability (OTLP tracing, SLOs, SIEM export) and the investor demo control plane. See the release history for details.

naeos

naeos

README

NAEOS

Contents

Vision

How NAEOS works

AI Engineering Control Plane

Project guides

Social posting scripts

Quick start

Requirements

Run the local CLI demo

Demo

Capabilities

Core Pipeline

Spec Language v2

AI Integration

Marketplace

Governance

Developer tools

Architecture

Core components

Kernel

Specification

NEIR

Compiler

Marketplace

CLI Commands

Repository Structure

Documentation

Roadmap

Completed

Contributing

Community & Support

Governance

License

Status