Infrastructure

The /speckit.infra command creates a comprehensive infrastructure specification covering development, production, CI/CD, observability, and disaster recovery.

Overview

The infra spec is the source of truth for all deployment decisions. Actual infrastructure files (docker-compose.yml, Helm charts, .gitlab-ci.yml) should be derived from this spec.

How It Works

Phase 1: Gather Context

The command scans your project for existing infrastructure artifacts:

• docker-compose.yml / docker-compose.*.yml — services, ports, volumes
• Dockerfile / Dockerfile.* — build stages, base images
• charts/ or helm/ — Helm charts, values files
• .gitlab-ci.yml / .gitlab/ci/ — pipeline stages and jobs
• Makefile — available targets
• .env.template / .env.example — environment variables
• deploy.sh / scripts/ — deployment automation
• kubernetes-manifests/ — raw K8s manifests
• providers/ — cloud provider configurations

It also reads the constitution and architecture spec for infrastructure-related principles.

Phase 2: Interactive Definition

Walks you through each section, pre-filling with discovered data:

/speckit.infra Docker Compose for dev with PostgreSQL and Redis, Kubernetes for production on AWS

Phase 3: Generate Outputs

Creates the spec and optionally scaffolds missing files (always asks before creating).

What the Spec Covers

Development Environment (Docker Compose)

Section	Details
Services	Image, ports, volumes, health checks, dependencies
Environment Variables	Key vars for local dev, maps to .env.template
Feature Flags	ENABLE_* pattern for optional components
Volumes	Mount paths, persistence settings
Networking	Ingress, DNS (*.localhost), TLS (mkcert)
Convenience	Makefile targets (dev, test, lint, build)

Production Environment (Kubernetes/Helm)

Deployment follows a 5-phase approach:

Phase	Purpose	Examples
Phase 1: Infrastructure	Foundation services	Ingress controller, cert-manager
Phase 2: Data Layer	Databases and storage	PostgreSQL, Redis, MinIO
Phase 3: Observability	Monitoring stack	Prometheus, Grafana, Loki, Tempo
Phase 4: Platform	Platform services	Auth, API gateway
Phase 5: Application	Your app services	Frontend, backend, workers

For each service: namespace, replicas, resource requests/limits, auto-scaling rules, pod security.

Data Layer

• Databases — Engine, version, purpose, dev mode (container) vs. prod mode (managed)
• Message Brokers — RabbitMQ, Kafka, etc.
• Caching — Redis, Memcached with eviction policies
• Object Storage — MinIO (dev) → S3/Blob/Spaces (prod)
• Extensions — PostGIS, TimescaleDB, etc.
• Backup Strategy — Tool, schedule, retention, storage target

CI/CD Pipeline (GitLab)

stages:
  - test        # Unit tests, linting, type checking
  - lint        # YAML lint, Helm lint, ShellCheck
  - security    # Image scanning, secret detection, SAST
  - build       # Docker build + push to GitLab Container Registry
  - release     # Tag release, publish packages
  - deploy      # Helm upgrade --install to target cluster

Includes: container registry config, deployment strategy (staging: auto, production: manual), rollback procedures.

Observability

Area	Details
Logging	Format (JSON structured), aggregation (Loki), retention, correlation IDs
Metrics	Collection (Prometheus), dashboards (Grafana), key alerts
Tracing	Protocol (OpenTelemetry), backend (Tempo), sampling rate
Alerting	Conditions, severity levels, notification channels

Networking & Security

• Network Policies — Default deny + explicit allow rules
• Secrets Management — Source, rotation schedule, consumers
• TLS Certificates — Self-signed (dev), Let's Encrypt staging/production

Disaster Recovery

• RPO/RTO Targets — Per component (database, object storage, full cluster)
• Recovery Procedures — Documented steps for each failure scenario
• Testing Schedule — When recovery is tested and last test date

Cloud Provider Matrix

Settings that vary per provider:

Setting	Local	AWS	Azure	GCP	DigitalOcean
Storage Class	hostpath	gp3	managed-premium	pd-ssd	do-block-storage
Load Balancer	Kind LB	NLB	Azure LB	GCP LB	DO LB
Managed DB	Docker	RDS	Azure DB	Cloud SQL	Managed DB

Scaffolding

After generating the spec, the command offers to create files that don't exist yet:

File	Purpose
docker-compose.yml	Local dev services
.env.template	Environment variable template
Makefile	Convenience targets (dev, test, lint, build, deploy)
charts/{project}/	Helm chart structure
.gitlab-ci.yml	CI/CD pipeline skeleton
deploy.sh	Phased deployment script

Each file is generated from the infra spec. The command asks before creating each one and never overwrites existing files without confirmation.

Acceptance Scenarios

The infra spec includes built-in acceptance scenarios:

• First-time setup: make dev starts all services within 3 minutes
• Restart without data loss: Services restart with persisted data
• Idempotent deployment: Re-running deploy.sh produces no changes
• End-to-end tracing: Distributed traces span all services
• Disaster recovery: Recovery meets defined RPO/RTO targets

Drift Detection

When the infra spec changes, re-run /speckit.infra to detect drift between the spec and actual files. The command compares the current spec against discovered artifacts and flags discrepancies.