Docker Architect

Docker Architect

Generate hardened, production-ready Docker architecture across two workflows:

• Compose/Swarm — service topology, runtime hardening, secrets, healthchecks
• Image/Build — Dockerfile, Buildx/Bake, SBOM/provenance/signing

---

When to use this skill

Activate this skill when the user asks to:

• Write a Dockerfile or containerize an application
• Create a compose.yaml or Compose stack
• Set up a Docker Swarm deployment
• Harden or secure an existing Dockerfile or compose file
• Add healthchecks to containers
• Configure Docker secrets management
• Create a .dockerignore file
• Set up multi-stage Docker builds
• Add resource limits or security constraints to containers
• Configure non-root container users
• Set up a CI/CD pipeline for Docker builds
• Scan Docker images for vulnerabilities
• Pin Docker image versions or digests
• Create init containers or permission sidecars
• Optimize Docker layer caching or image size

---

Primary Directives

The executor shall follow these rules for every output.

1. Clarification and defaults

• Ask the user at most 2 clarifying questions before generating output.
• When requirements are ambiguous, apply secure defaults and note assumptions inline.
• Default workflow: if the user mentions "docker-compose" or "deploy", use Compose. If the user mentions "Dockerfile" or "build", use Image. When both apply, emit both.

2. Dockerfile invariants

Every generated Dockerfile shall satisfy:

#	Rule ID	Requirement
1	AC-DF-MULTISTAGE	Use multi-stage builds; isolate build deps from runtime.
2	AC-DF-USER	Final stage runs as non-root (USER instruction).
3	(behavioral)	Use minimal base images (-slim, -alpine, distroless).
4	AC-DF-FROM-DIGEST	Pin base images by digest in production (tag acceptable for templates).
5	AC-DF-HEALTHCHECK	Include HEALTHCHECK in final stage.
6	AC-DF-OCI-LABELS	Include OCI labels: image.source, image.revision, image.licenses.
7	AC-DF-CACHE-MOUNTS	Use BuildKit --mount=type=cache for package managers.
8	AC-DF-SUID-SGID	Strip SUID/SGID bits in final stage (enforcing only).
9	(behavioral)	Never embed secrets in layers (use build secrets or runtime mounts).
10	AC-DF-DOCKERIGNORE	Emit a companion .dockerignore file.
11	AC-DF-REPRODUCIBLE	Declare ARG SOURCE_DATE_EPOCH for reproducible builds.
12	AC-DF-PACKAGE-MGR	Final stage must not invoke runtime package managers (apt, apk, pip, etc.).
13	(behavioral)	Order layers: system deps → app deps (lockfiles) → source code.

3. Compose / Swarm invariants

Every generated compose or stack file shall satisfy:

#	Rule ID	Requirement
1	AC-CMP-READONLY	read_only: true — immutable root filesystem.
2	AC-CMP-CAPDROP	cap_drop: [ALL] — drop all capabilities.
3	AC-CMP-NNP	security_opt: [no-new-privileges:true].
4	AC-CMP-USER	user: set to non-root UID:GID.
5	AC-CMP-HEALTH	healthcheck: with test, interval, timeout, retries.
6	AC-CMP-RESOURCES	Compose: cpus, mem_limit, pids_limit; Swarm: deploy.resources.limits.
7	AC-CMP-SECRETS	Route TOKEN/PASS/KEY values through secrets:, not environment:.
8	AC-CMP-DIGEST / AC-SWM-DIGEST	Pin service images by digest for deterministic pulls.
9	AC-CMP-RESTART	restart: unless-stopped (Compose) or deploy.restart_policy (Swarm).
10	AC-CMP-WRITABLE	Explicit tmpfs: for writable paths under read-only root.
11	AC-CMP-PERMS-INIT	Init-permissions sidecar for non-root volume ownership (Compose only).
12	(behavioral)	Use YAML anchors (x-defaults: &) for shared hardening.
13	(behavioral)	Define explicit networks: (no default bridge).
14	(behavioral)	Use depends_on: { svc: { condition: service_healthy } }.
15	(behavioral)	Use profiles: only for optional services (debug, admin jobs), never for required *-init-perms sidecars.
16	AC-SWM-RESTART	Swarm: deploy.restart_policy.condition: on-failure.

Rows marked (behavioral) are enforced by LLM output review only and are not checked by policy-check.

3.1 Migration notes

• Behavior change: AC-CMP-PERMS-INIT and AC-CMP-RESTART service exemptions match only the canonical <service>-init-perms suffix. Generic init-* service names are intentionally no longer exempt from ensure_key checks.

4. Response format

4.1 Compose mode

• Deliverables: architecture.md, compose.yaml.
• Emit each file as a fenced code block labeled with its relative path.
• Emit order: .dockerignore (if applicable) → compose.yaml.
• Include inline comments referencing rule IDs (e.g., # AC-CMP-USER).
• Required gates: policy-check, output-check, docker compose config -q, verify (when Docker is available).
• Init-sidecar conformance is required for all *-init-perms services: must match the canonical contract (user 0:0, cap_drop ALL, cap_add CHOWN+FOWNER, security_opt no-new-privileges, read_only true, network_mode none, restart no, no profiles: key).
• After all files, include a brief "Next steps" section with scanning commands.

4.2 Swarm mode

• Deliverables: architecture.md, docker-stack.yaml.
• Emit each file as a fenced code block labeled with its relative path.
• Include inline comments referencing rule IDs (e.g., # AC-SWM-RESTART).
• Required gates: policy-check, output-check.
• Ownership-bootstrap section required for non-root stateful services with named volumes.
• Prohibited patterns: depends_on, init-perms sidecars, flat resource keys (cpus, mem_limit, pids_limit), profiles:.
• Use deploy.resources.limits for resource constraints, deploy.restart_policy for restart behavior.
• After all files, include a brief "Next steps" section with deploy commands.

4.3 Image mode

• Deliverables: .dockerignore, Dockerfile, docker-bake.hcl, architecture.md.
• Emit each file as a fenced code block labeled with its relative path.
• Emit order: .dockerignore → Dockerfile → docker-bake.hcl.
• Include inline comments referencing rule IDs (e.g., # AC-DF-USER).
• Required gates: policy-check, output-check.
• docker-bake.hcl must include default and release targets with multi-platform support.
• Release instructions must include attestation flags (--attest type=sbom, --attest type=provenance,mode=max) and signing guidance.
• After all files, include a brief "Next steps" section with build and scanning commands.

5. Delivery Checklist

The executor SHALL NOT report success until every condition below is met:

• Every required gate for the active mode (per sections 4.1–4.3) has passed, OR is explicitly skipped with a documented reason and residual risk statement in the architecture output.
• When a validation step is skipped because tooling is unavailable, the architecture output SHALL record the skipped step, the reason, and the residual risk (DA-PROC-3).
• When Docker is available, Compose mode SHALL treat runtime verify as mandatory. Skipping verify requires an explicit note in the output (DA-PROC-2).
• Ambiguous research results affecting runtime user, healthcheck, or provenance SHALL be treated as blockers requiring resolution, not soft informational notes.
• Provenance resolution SHALL distinguish source repository provenance from an exact upstream Dockerfile/build-definition path. Source repository provenance is mandatory; exact Dockerfile path SHOULD be included when deterministically discoverable.

---

Scanning Recommendations

After generating container files, recommend the user run:

# Lint Dockerfile
hadolint Dockerfile

# Validate compose schema
docker compose config -q

# Scan for vulnerabilities (after build)
trivy image --severity HIGH,CRITICAL <image>

See references/scanning.md for full install instructions, CI pipeline ordering, and additional tools (docker scout, trivy config scanning).

---

Fallback Behavior

When the Rust tooling (docker-architect-compose, docker-architect-image) is unavailable (no cargo, no pre-built binary):

1. Never refuse output. Generate files directly from the invariants above.
2. Use templates from references/fallback-templates.md as starting points.
3. Use .dockerignore templates from references/dockerignore-templates.md.
4. Apply all Dockerfile and Compose invariants manually.
5. Note in output that deterministic tooling validation was skipped.

The fallback path produces the same hardened output — the Rust tooling adds deterministic metadata enrichment and policy enforcement, not the hardening itself.

---

Tooling Reference

When the Rust tooling is available, use it for enhanced determinism and policy checks.

Workflow selection

• Use docker-architect-compose for stack/deployment architecture (docker-compose, Swarm).
• Use docker-architect-image for image/build architecture (Dockerfile, Buildx/Bake).
• When both are required, run compose first, then image, preserving traceability IDs.

Commands

# ── Compose/Swarm workflow ──
<skills-file-root>/scripts/docker-architect-compose extract <input> --format text
<skills-file-root>/scripts/docker-architect-compose refresh --cache-dir <skills-file-root>/references/cache --image nginx:1.27 --allow-scrape-fallback
<skills-file-root>/scripts/docker-architect-compose render --cache-dir <skills-file-root>/references/cache --format markdown
<skills-file-root>/scripts/docker-architect-compose check --cache-dir <skills-file-root>/references/cache --strictness balanced
<skills-file-root>/scripts/docker-architect-compose policy-check compose.yaml --policy <skills-file-root>/references/policy-compose-balanced.yaml --cache-dir <skills-file-root>/references/cache --mode compose
<skills-file-root>/scripts/docker-architect-compose policy-plan compose.yaml --policy <skills-file-root>/references/policy-compose-balanced.yaml --cache-dir <skills-file-root>/references/cache --mode compose
<skills-file-root>/scripts/docker-architect-compose policy-apply compose.yaml --plan patch-plan.json --output compose.hardened.yaml --mode compose
<skills-file-root>/scripts/docker-architect-compose compose-generate compose.yaml --policy <skills-file-root>/references/policy-compose-balanced.yaml --cache-dir <skills-file-root>/references/cache --output compose.anchored.yaml --mode compose --anchors auto
<skills-file-root>/scripts/docker-architect-compose output-check architecture.md --mode compose

# ── Swarm workflow ──
<skills-file-root>/scripts/docker-architect-compose policy-check docker-stack.yaml --policy <skills-file-root>/references/policy-swarm-balanced.yaml --cache-dir <skills-file-root>/references/cache --mode swarm
<skills-file-root>/scripts/docker-architect-compose policy-plan docker-stack.yaml --policy <skills-file-root>/references/policy-swarm-balanced.yaml --cache-dir <skills-file-root>/references/cache --mode swarm
# policy-apply currently supports only --mode compose (compose workflow) and --mode dockerfile (image workflow).
<skills-file-root>/scripts/docker-architect-compose compose-generate docker-stack.yaml --policy <skills-file-root>/references/policy-swarm-balanced.yaml --cache-dir <skills-file-root>/references/cache --output docker-stack.anchored.yaml --mode swarm --anchors auto

# ── Image/build workflow ──
<skills-file-root>/scripts/docker-architect-image extract <input> --format text
<skills-file-root>/scripts/docker-architect-image refresh --cache-dir <skills-file-root>/references/cache --image debian:12-slim --allow-scrape-fallback
<skills-file-root>/scripts/docker-architect-image render --cache-dir <skills-file-root>/references/cache --format markdown
<skills-file-root>/scripts/docker-architect-image check --cache-dir <skills-file-root>/references/cache --strictness balanced
<skills-file-root>/scripts/docker-architect-image policy-check Dockerfile --policy <skills-file-root>/references/policy-dockerfile-balanced.yaml
# policy-check exits 2 when blocked violations are present.
<skills-file-root>/scripts/docker-architect-image policy-plan Dockerfile --policy <skills-file-root>/references/policy-dockerfile-balanced.yaml
# policy-plan is non-gating and always reports to stdout.
<skills-file-root>/scripts/docker-architect-image policy-apply Dockerfile --plan patch-plan.json --output Dockerfile.hardened --mode dockerfile
<skills-file-root>/scripts/docker-architect-image output-check architecture.md --mode image

# ── CI gate ──
<skills-file-root>/scripts/docker-architect-ci-gate
DOCKER_ARCHITECT_ENABLE_VERIFY=1 <skills-file-root>/scripts/docker-architect-ci-gate

Portability contract

• This skill resolves all paths within <skills-file-root>.
• Cross-skill runtime path dependencies are non-compliant.

Determinism and hardening

• Refresh metadata only in explicit refresh operations.
• Render from cached JSON for normal runs.
• Prefer official APIs; use scrape fallback only when missing fields block output quality.
• For Docker Hub images, prefer registry v2 Docker-Content-Digest over Hub tag digest.
• Input guardrails: policy packs, image lists, and patch plans are capped at 1 MiB; general text inputs are capped at 8 MiB.
• Curated defaults: references/image-knowledge/knowledge.v1.yaml, references/compose-defaults/defaults.v1.yaml.

CI gate

• docker-architect-ci-gate runs deterministic fixture-based golden tests.
• Compose-mode executor output still treats verify as mandatory whenever Docker is available for the current task.
• Repository CI keeps live verify opt-in via DOCKER_ARCHITECT_ENABLE_VERIFY=1 (or local --verify) so non-Docker environments can still run deterministic golden tests.
• When live verify is enabled without an override, the gate runs both references/ci/verify.compose.yaml and references/ci/verify-stateful.compose.yaml.

---

References

File	Purpose
references/fallback-templates.md	Hardened Dockerfile + Compose templates
references/fallback-templates-swarm.md	Hardened Swarm stack template
references/fallback-templates-bake.md	docker-bake.hcl template (Image mode)
references/dockerignore-templates.md	.dockerignore templates by language
references/scanning.md	Scanner install, usage, CI pipeline order
references/protocol-compose.md	Compose workflow protocol
references/protocol-swarm.md	Swarm workflow protocol
references/output-contract-compose.md	Compose output contract
references/output-contract-swarm.md	Swarm output contract
references/protocol-image.md	Image workflow protocol
references/output-contract-image.md	Image output contract
references/cache/image-profiles.json	Cached image metadata
references/policy-compose-balanced.yaml	Compose policy (balanced)
references/policy-compose-enforcing.yaml	Compose policy (enforcing)
references/policy-swarm-balanced.yaml	Swarm policy (balanced)
references/policy-swarm-enforcing.yaml	Swarm policy (enforcing)
references/policy-dockerfile-balanced.yaml	Dockerfile policy (balanced)
references/policy-dockerfile-enforcing.yaml	Dockerfile policy (enforcing)
references/compose-defaults/defaults.v1.yaml	Compose anchor defaults
references/image-knowledge/knowledge.v1.yaml	Image knowledge base
references/ci/verify.compose.yaml	CI verify fixture
references/ci/verify-stateful.compose.yaml	CI stateful verify fixture