hivevm/nuc
Template for agentic development in a Dev Container. A written specification and architecture decision records guide the work, and one AGENTS.md rules file is read by all coding agents.
- Spec-driven
- Dev Container
- AGENTS.md
- Language
- Shell
- License
- MIT
- Commits
- 16 commits
- Last update
- Oct 2026
01 / Overview
NUC is a starting point for building software with coding agents inside a ready-to-use Dev Container. It is named after the small nucleus colony a full hive grows from.
The work is driven by a written specification and Architecture Decision Records, so intent and the reasoning behind structural choices stay reviewable. The other HiveVM projects follow the same layout.
02 / Architecture
How it fits together
INPUT
Spec and ADRs
Intent and decisions
CORE
Coding agent
Rules from AGENTS.md
OUTPUT
Software
Built in a Dev Container
Dev Container
Defined entirely in devcontainer.json: a prebuilt base image plus Dev Container Features and VS Code extensions. No Dockerfile or Compose file. Claude Code and Mistral Vibe are preinstalled.
AGENTS.md
The single source of truth for all coding agents (ADR-0001). Procedures are Agent Skills in .agents/skills/ (ADR-0003).
Git hooks
The container enables hooks that block commits on main and run checks before a push.
Spec structure
SPECIFICATION, GLOSSARY, CONVENTIONS and ARCHITECTURE in docs/, plus Architecture Decision Records with a template. CODEOWNERS names who must approve changes.
03 / Decisions
Specifications and decisions
Written specifications and architecture decision records live next to the code, so the reasoning behind the design stays reviewable.
- docs/SPECIFICATION.mdProblem, goals, success criteria
- docs/ARCHITECTURE.mdThe system as it currently stands
- docs/adr/Architecture Decision Records
- AGENTS.mdRules for coding agents
04 / Getting started
Try it
Open the repository in VS Code and choose Reopen in Container, then authenticate your coding agent inside the container. The README still marks the build, test and run commands as TODO, because it is a template.
$ git clone https://github.com/hivevm/nuc
$ cd nuc
$ code .