Architecture
Environment & Tooling
Command Surface
An identical root Makefile in every repository, with the repository’s own components declared once in scripts/build/repository.mk.
Makefile
4Domain
Environment & Tooling
The development container, the command surface, scripts, tools, and lint configuration.
Lifecycle
Environment & Tooling
Devcontainer Lifecycle
Six ordered hook phases that take a development container from host-side preparation to an attached, ready workspace.
.devcontainer/lifecycle/
8Architecture
Environment & Tooling
Development Container
The authoritative development environment for a repository — reusable features provide the toolchains, and repository-specific lifecycle hooks finish the workspace.
.devcontainer/
4Contract
Environment & Tooling
Environment Doctor
make doctor reports which required tools and repository files are present or missing — a standalone diagnostic, never a prerequisite of other targets.
scripts/build/
4Contract
Environment & Tooling
Explicit Skips
When a capability is intentionally unavailable, a command says so with a skip: line and succeeds, while a check that actually fails still exits non-zero.
scripts/
6Lifecycle
Environment & Tooling
Initialize Phase
Host-side hooks that run before the container is built or created, preparing only the files and directories the container definition expects.
.devcontainer/lifecycle/initialize.d/
2Contract
Environment & Tooling
Lint Gate
One aggregate lint command runs every linter that is installed, skips the rest with a clear message, and fails only on real findings.
scripts/lint.sh
4Architecture
Environment & Tooling
Linter Configuration
A single .linter/ directory holds the repository’s own lint configuration and overrides, layered over organisation defaults from the environment.
.linter/
2Orchestration
Environment & Tooling
Make Module Registries
Make modules register their targets and requirements into shared lists, and aggregate targets are composed from whatever registered.
scripts/build/
5Orchestration
Environment & Tooling
Offline Validation
Networked setup hydrates the workspace once; validation then runs with OFFLINE=1 and never quietly re-downloads anything.
scripts/build/
3Lifecycle
Environment & Tooling
On-Create Phase
Early in-container hooks that create container-local state — user-home caches, CLI configuration, directories — before repository-driven setup runs.
.devcontainer/lifecycle/on-create.d/
4Lifecycle
Environment & Tooling
Post-Attach Phase
Human-facing hooks that run each time a developer or editor attaches — short guidance, actionable warnings, and pointers to interactive sign-in.
.devcontainer/lifecycle/post-attach.d/
3Lifecycle
Environment & Tooling
Post-Create Phase
The last mile of workspace bootstrap — linking wrappers, configuring the shell, generating local configuration — once the container and content are in place.
.devcontainer/lifecycle/post-create.d/
4Lifecycle
Environment & Tooling
Post-Start Phase
Fast, repeatable hooks that run on every container start to repair ephemeral state, verify prerequisites, and keep lightweight services running.
.devcontainer/lifecycle/post-start.d/
4Orchestration
Environment & Tooling
Run-Parts Hook Directories
One small runner turns each lifecycle event into a directory of .sh hooks, run in lexical order and stopped by the first failure.
.devcontainer/lifecycle/
1Architecture
Environment & Tooling
Scripts
Narrow, deterministic command helpers for make modules, CI, and local tooling — glue that takes its inputs from the caller and leaves orchestration to it.
scripts/
4Convention
Environment & Tooling
Self-Documenting Help
make help is generated from ## comments on the targets themselves, so the list of commands cannot drift from the real ones.
scripts/build/
1Architecture
Environment & Tooling
Tools
Repository tooling with stable command entry points and documented contracts — small applications that own a workflow, rather than glue around one.
tools/
2Lifecycle
Environment & Tooling
Update-Content Phase
Hooks driven by repository content — lockfiles, manifests, checked-in configuration — that restore dependencies once the workspace is synchronised.
.devcontainer/lifecycle/update-content.d/
5No specification matches every filter.