Nucleus is an AI-first Go microservice kernel for contract-driven service generation, evolution, and verification.
It is designed for AI agents, CI systems, and human reviewers to work from the same source of truth: service contracts, manifests, generated freshness, safe edit surfaces, and verification evidence.
Status: pre-alpha. The public repository is being prepared for the first source import under
github.com/nucleuskit/nucleus.
Traditional Go microservice frameworks are optimized for humans writing code inside an IDE. Nucleus is optimized for AI agents changing services safely and repeatably.
Nucleus focuses on four rules:
- Contract-first: OpenAPI, protobuf, and error definitions are the source of truth for external behavior.
- Manifest-first: service identity, capabilities, dependencies, and AI edit surfaces are declared in
nucleus.yaml. - Thin kernel: core lifecycle, identity, errors, context, and response types stay small and dependency-aware.
- AI-safe loop:
describe -> plan -> lint -> verifymakes service changes reviewable, reproducible, and bounded.
Nucleus is not a full-stack middleware bundle. Redis, Kafka, SQL, Nacos, tracing exporters, and similar infrastructure are connected through explicit capability interfaces and optional bridges.
A Nucleus service treats these files as public behavior contracts:
api/openapi.yamlfor HTTP APIsapi/proto/*.protofor gRPC APIsapi/errors.yamlfor stable error codes and HTTP mappings
Generated handlers, types, clients, and freshness metadata are derived from these contracts.
nucleus.yaml describes the service identity and machine-readable operating surface:
- service name, version, tier, and ownership
- declared capabilities and providers
- dependencies and contract snapshots
- edit surfaces for AI agents
- verification commands for CI and local review
Nucleus separates capability declaration from infrastructure implementation:
github.com/nucleuskit/cap/*defines small interfaces, options, and no-op implementations.github.com/nucleuskit/bridge/*provides optional adapters.- Application wiring injects bridges into runtime code.
- Domain code stays independent from transport and infrastructure SDKs.
The intended workflow is:
nucleus describe --json
nucleus plan --task "change request" --json
nucleus gen
nucleus lint
nucleus verify
The goal is not just to generate code. The goal is to produce evidence that the change respected contracts, manifests, generated freshness, dependency boundaries, and verification commands.
The main repository hosts the CLI, examples, and public documentation:
api/ Contract files
cmd/nucleus/ CLI implementation
example/ Runnable examples
docs/ Concepts, ADRs, plans, and platform mapping
The kernel, contract, capability, bridge, and runtime packages are published as separate Go modules:
github.com/nucleuskit/coregithub.com/nucleuskit/contractgithub.com/nucleuskit/capgithub.com/nucleuskit/bridgegithub.com/nucleuskit/httpgithub.com/nucleuskit/grpcgithub.com/nucleuskit/worker
The early public roadmap is intentionally narrow:
- Publish the source under
github.com/nucleuskit/nucleus. - Stabilize the first
nucleus validate,gen,describe,plan,lint, andverifyloop. - Keep
corestandard-library-only. - Make
examples/hello-httpthe first runnable contract-first service. - Add focused capability protocols before adding optional bridges.
- Publish
v0.1.0-alpha.1once the public module path, CI, examples, and docs are aligned.
Nucleus is early, but contributions should already follow the project boundaries:
- Start with contracts and manifests when changing external behavior.
- Keep kernel code small and dependency-aware.
- Prefer explicit capabilities over hidden framework defaults.
- Add tests or verification evidence with behavior changes.
- Do not add compatibility shims for private or legacy internal SDKs.
See CONTRIBUTING.md and SECURITY.md.
Nucleus is licensed under the Apache License 2.0.