Library

All specifications

Filter by kind, domain, or trait, or search by name and path. Every card opens a specification and its connections.

Convention Build & Delivery

Actions

Local composite actions under .gitea/actions/ capture reusable orchestration steps, while the logic they orchestrate stays in the build system.

.gitea/actions/ 3

Architecture Build & Delivery

Automation & CI/CD

.gitea/ is the repository’s automation control folder: event-driven workflows and local actions that orchestrate the repository’s own commands.

.gitea/ 2

Architecture Documentation & Metadata

Catalog Descriptors

Machine-readable repository identity that tells catalog systems what a repository is and produces, and where the authoritative definitions live.

.descriptor/ 2

Architecture Documentation & Metadata

Code Map

A generated CODEMAP.md that says what each area of the repository is for and which local README to open next — a navigation guide, not a reference.

CODEMAP.md 2

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 4

Convention Documentation & Metadata

Decision Records

Architecture decision records are a last resort, written only when the repository’s structure, code, tests, and owner documentation cannot make a choice clear.

docs/pdlc/decisions/ 2

Convention Infrastructure & Runtime

Derived Developer Identity

A developer deployment names its instance from the Terraform workspace, chosen from an override, the CI branch, or the local username — never from a per-developer file.

workspaces/ 3

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/ 8

Architecture 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/ 4

Contract 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/ 4

Architecture Infrastructure & Runtime

Environments

Thin, canonical deployable roots under env/ that compose reusable modules for a concrete deployment target and run without ad hoc parameters.

env/ 4

Contract 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/ 6

Contract Build & Delivery

Fingerprinted Cache Tiers

Content-hashed CSS and JS are cached for a year as immutable; everything else is revalidated on every request and kept fresh by invalidation.

public/ 2

Lifecycle 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/ 2

Lifecycle Documentation & Metadata

Issue Plan Tree

Plans live on disk as a tree of milestone folders and issue files that a planner reserves and syncs into Gitea, moving from slug-only drafts to ID-prefixed synced names.

<root>/ 1

Contract 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 4

Architecture 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/ 2

Orchestration 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/ 5

Convention Documentation & Metadata

Managed Standard Files

Standard files copied into every repository carry a DO NOT EDIT header; they are changed at their source, never in the repository that received them.

./ 0

Architecture Infrastructure & Runtime

Modules

Small, focused infrastructure building blocks with explicit inputs and outputs, consumed by deployable roots in env/ and workspaces/.

modules/ 3

Orchestration Environment & Tooling

Offline Validation

Networked setup hydrates the workspace once; validation then runs with OFFLINE=1 and never quietly re-downloads anything.

scripts/build/ 3

Lifecycle 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/ 4

Convention Documentation & Metadata

Owner Documentation

Conventions are described beside the thing that owns them — a directory’s layout in its own README, a command’s behaviour in its module or script.

<area>/README.md 4

Contract Infrastructure & Runtime

Parameterless Deployment

A canonical deployable root runs under a generic deployer with no ad hoc parameters; every value it needs resolves from committed, well-defined sources.

env/ 2

Architecture Infrastructure & Runtime

Pinned Module Composition

Every deployable root composes the same published module at the same pinned version, so roots differ only in backend, domain, and credentials.

env/ 3

Lifecycle 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/ 3

Lifecycle 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/ 4

Lifecycle 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/ 4

Architecture Documentation & Metadata

Product Development Life Cycle

docs/pdlc/ holds the durable product context behind a repository — problems, constraints, tradeoffs, and decisions — and nothing short-lived.

docs/pdlc/ 2

Convention Documentation & Metadata

Reference Over Duplication

Each fact is stated once, where it is maintained, and every other place that needs it points there instead of keeping a copy.

./ 2

Lifecycle Build & Delivery

Release Pipeline

Every change moves through the same Build → Test → Publish pipeline locally, on the pull request, and on merge, ending in a deployment only where there is one.

docs/RELEASING.md 2

Orchestration 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/ 1

Architecture 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/ 4

Convention 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/ 1

Orchestration Product Code

Staged Content Mounts

Repository documentation is staged from docs/ into .cache/docs-site/ and mounted into a Hugo site, so the docs stay where they are owned.

.cache/docs-site/ 2

Orchestration Build & Delivery

Static Site Delivery

make deploy is the whole deployment model: build the site, initialise and apply its Terraform root, upload public/, and invalidate the CDN.

scripts/deploy.sh 5

Architecture Product Code

Static Websites

Each child of www/ is a self-contained site root whose content, layouts, assets, and configuration travel together and whose output is disposable.

www/ 3

Architecture 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/ 2

Lifecycle 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/ 5

Orchestration Build & Delivery

Workflows

Workflow YAML decides when automation runs and in what order, and hands the work itself to stable repository commands and reusable actions.

.gitea/workflows/ 4

Architecture Infrastructure & Runtime

Workspaces

Developer-oriented deployment roots under workspaces/ whose instance identity may come from the current user or branch, kept apart from canonical environments.

workspaces/ 3