Integration Implementation Skill

This skill provides guidance for integrating components within a container into a cohesive, runnable Docker container. The integration-developer works after component coding is complete, creating Dockerfiles, entrypoints, scripts, and integration tests.

Core Principle

You create Docker containers that package and run the components.

code

Individual components implemented by coding-agent
              ↓
     [Integration Developer]
              ↓
    Dockerfile.local + Entrypoints + Scripts + Tests
              ↓
         Container is runnable via Docker

Docker-Based Local Development

CRITICAL: The primary output is Dockerfile.local - a Docker image optimized for local development with hot reload support.

Why Docker?

Benefit	Explanation
Reliable cleanup	`docker stop` always works (no unkillable processes)
Consistent environments	Same behavior on any machine
No manual dependencies	No Python venv activation, Node version issues
Simple orchestration	docker-compose handles everything

Technology Agnostic

This skill is technology-agnostic. All implementation details depend on:

code

.constraints/TECHNOLOGY.md

Always read this file first to understand:

•Programming language(s)
•Frameworks and entry patterns
•Base Docker images to use
•Test framework for integration tests
•Environment variable handling

Success Factors

1. Docker Build Succeeds

Criterion	Measure
Dockerfile.local exists	File created in container root
Build completes	`docker build -f Dockerfile.local .` succeeds
Image runs	Container starts without crash
Health check passes	Container becomes healthy

2. Container Runs Successfully

Criterion	Measure
Starts Clean	No errors on startup
All Components Wired	Dependencies properly injected
Environment Configured	All required vars documented
Health Checks Pass	Endpoints respond correctly

3. Integration Tests Pass

Criterion	Measure
All Scenarios Covered	Every IT-x from integration.md
Tests Pass	100% of integration tests green
Error Paths Tested	Failure scenarios validated

Input: What You Receive

From Container Architect (Primary)

code

{container}/.specs/integration.md     # Your primary input

From Component Implementations

code

{container}/{component}/src/          # Implemented components

From Container Specs (Context)

code

{container}/.specs/components.md      # Component overview
{container}/.specs/interfaces/        # Internal contracts
{container}/.specs/technology.md      # Tech stack

Output: What You Create

code

{container}/
├── Dockerfile.local                  # Docker image for local dev (PRIMARY OUTPUT)
├── .dockerignore                     # Files to exclude from Docker build
├── src/
│   └── main.{ext}                    # Container entrypoint(s)
├── scripts/
│   ├── start.{ext}                   # Production start script
│   ├── dev.{ext}                     # Development start script
│   └── setup.{ext}                   # Environment setup script
├── tests/
│   └── integration/
│       ├── conftest.{ext}            # Integration test fixtures
│       └── test_{scenario}.{ext}     # Integration test files
└── .env.example                      # Environment template

Workflow

Step 1: Read Constraints and Specs

code

Read (in order):
├── .constraints/TECHNOLOGY.md         → Language, conventions
├── {container}/.specs/integration.md  → Primary guide
├── {container}/.specs/components.md   → Component overview
└── {container}/.specs/technology.md   → Container tech stack

Step 2: Verify Components Exist

Check that each component referenced in integration.md has:

•{container}/{component}/src/ directory with implementation

If missing, report and stop.

Step 3: Create Dockerfile.local

This is the PRIMARY output. Create a Dockerfile optimized for local development:

dockerfile

# Dockerfile.local - Local development with hot reload
FROM {base_image}

WORKDIR /app

# Install dependencies first (cached layer)
COPY {dependency_files} ./
RUN {install_command}

# Copy source code
COPY . .

# Set environment for local development
ENV LOCAL_RUN=true
ENV {other_env_vars}

# Expose port
EXPOSE {port}

# Health check
HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=3 \
    CMD {health_check_command}

# Start with hot reload
CMD {dev_command}

Step 4: Create .dockerignore

code

node_modules
.venv
venv
__pycache__
*.pyc
.git
.gitignore
*.md
!README.md
.env
.env.local
.local-logs
*.log
target
build
dist
.next
coverage
.pytest_cache
.mypy_cache

Step 5: Create Container Entrypoint

Based on integration.md Entrypoints section:

•Import all required components
•Wire dependencies per startup order
•Initialize from environment
•Start main process

Step 6: Create Scripts

Based on integration.md Launch Scripts section:

•start - Production mode
•dev - Development with hot reload
•setup - Environment configuration

Step 7: Create Environment Template

Based on integration.md Environment Setup section:

•List all required variables
•Provide defaults where applicable
•Document purpose of each

Step 8: Create Integration Tests

Based on integration.md Integration Test Scenarios:

•Create fixtures wiring all components
•Implement each IT-x scenario
•Test happy and error paths
•Verify health checks

Step 9: Verify Docker Build

Test the Dockerfile:

bash

cd {container}
docker build -f Dockerfile.local -t {container}-local:latest .
docker run -d --name {container}-test -p {port}:{port} {container}-local:latest
# Wait for health check
docker inspect --format='{{.State.Health.Status}}' {container}-test
docker stop {container}-test
docker rm {container}-test

Dockerfile Templates by Technology

Node.js (Express, Fastify)

dockerfile

# Dockerfile.local - Local development with hot reload
FROM node:20-alpine

WORKDIR /app

# Install dependencies first (cached layer)
COPY package*.json ./
RUN npm ci

# Copy source code
COPY . .

# Set environment for local development
ENV NODE_ENV=development
ENV LOCAL_RUN=true

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Start with hot reload (nodemon, tsx, or similar)
CMD ["npm", "run", "dev"]

Python (FastAPI, Flask)

dockerfile

# Dockerfile.local - Local development with hot reload
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies first (cached layer)
COPY requirements*.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# Copy source code
COPY . .

# Set environment for local development
ENV PYTHONUNBUFFERED=1
ENV LOCAL_RUN=true

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# Start with hot reload
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

Next.js (Frontend)

dockerfile

# Dockerfile.local - Local development with hot reload
FROM node:20-alpine

WORKDIR /app

# Install dependencies first (cached layer)
COPY package*.json ./
RUN npm ci

# Copy source code
COPY . .

# Set environment for local development
ENV NODE_ENV=development
ENV LOCAL_RUN=true
ENV NEXT_PUBLIC_LOCAL_RUN=true
ENV NEXT_TELEMETRY_DISABLED=1

# Expose port
EXPOSE 3000

# Health check (longer start_period for Next.js)
HEALTHCHECK --interval=10s --timeout=5s --start-period=60s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000 || exit 1

# Start Next.js dev server
CMD ["npm", "run", "dev"]

Java (Spring Boot)

dockerfile

# Dockerfile.local - Local development
FROM eclipse-temurin:17-jdk

WORKDIR /app

# Copy gradle/maven wrapper and dependencies first (cached layer)
COPY gradlew build.gradle* settings.gradle* ./
COPY gradle ./gradle
RUN ./gradlew dependencies --no-daemon || true

# Copy source code
COPY . .

# Set environment for local development
ENV SPRING_PROFILES_ACTIVE=local
ENV LOCAL_RUN=true

# Expose port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=10s --timeout=5s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:8080/actuator/health || exit 1

# Start with bootRun for hot reload
CMD ["./gradlew", "bootRun", "--no-daemon"]

Entrypoint Patterns

HTTP Server Entrypoint

code

// Generic pattern - adapt to language

import { loadConfig } from "./config"
import { createApp } from "./app"
import { ComponentA, ComponentB, ComponentC } from "./components"

async function main() {
    // 1. Load configuration from environment
    const config = loadConfig()

    // 2. Initialize components in startup order
    const compA = new ComponentA(config)
    const compB = new ComponentB(compA)
    const compC = new ComponentC(compA, compB)

    // 3. Create application with components
    const app = createApp({ compA, compB, compC })

    // 4. Register health endpoints
    app.get("/health", () => ({ status: "ok" }))
    app.get("/ready", async () => ({
        status: await compC.isReady() ? "ok" : "not_ready"
    }))

    // 5. Start server
    await app.listen(config.port)
    console.log(`Server running on port ${config.port}`)
}

main().catch(err => {
    console.error("Startup failed:", err)
    process.exit(1)
})

Worker Entrypoint

code

// Generic pattern - adapt to language

import { loadConfig, connectQueue } from "./config"
import { WorkerComponent } from "./components"

async function main() {
    const config = loadConfig()
    const queue = await connectQueue(config.queueUrl)

    const worker = new WorkerComponent(config)

    // Process messages
    queue.consume(async (message) => {
        try {
            await worker.process(message)
            message.ack()
        } catch (err) {
            console.error("Processing failed:", err)
            message.nack()
        }
    })

    // Health check (if applicable)
    startHealthServer(config.healthPort)
}

main()

Environment Template Pattern

bash

# .env.example - {Container Name}
# Copy to .env and configure values
#
# For local development:
#   - Set LOCAL_RUN=true
#   - Use Docker service names for infrastructure (mongodb, redis, azurite)

# =============================================================================
# Required Configuration
# =============================================================================

# Enable local development mode (uses Docker infrastructure)
LOCAL_RUN=true

# Database connection (use Docker service name in docker-compose)
DATABASE_URL=mongodb://mongodb:27017

# API configuration
API_PORT=3000
API_HOST=0.0.0.0

# =============================================================================
# Optional Configuration (has defaults)
# =============================================================================

# Logging
LOG_LEVEL=debug                        # debug, info, warn, error

# =============================================================================
# Docker Infrastructure (when LOCAL_RUN=true)
# =============================================================================
# These are typically set in docker-compose.local.yml
# MONGODB_URI=mongodb://mongodb:27017
# REDIS_URL=redis://redis:6379
# AZURE_STORAGE_CONNECTION_STRING=...

Quality Checklists

Before Marking Complete

Dockerfile.local (PRIMARY)

• File exists in container root
• Build succeeds without errors
• Container starts successfully
• Health check passes
• Hot reload works (source mounted)

.dockerignore

• Excludes node_modules, .venv, etc.
• Excludes .env files
• Excludes build outputs

Entrypoint

• Imports all required components
• Wires dependencies in correct order
• Loads configuration from environment
• Handles startup errors gracefully
• Implements health check endpoints

Scripts

• Start script works in production mode
• Dev script enables development features
• Setup script configures environment
• All scripts have usage documentation
• Scripts are executable

Environment

• .env.example lists all variables
• Required vs optional clearly marked
• Defaults provided where sensible
• Each variable documented
• Docker service names documented

Integration Tests

Anti-Patterns to Avoid

Anti-Pattern	Problem	Solution
No Dockerfile.local	Can't run in Docker	Always create Dockerfile.local
Modifying Components	Breaks separation	Report issue to coding-agent
Hardcoded Config	Not portable	Use environment variables
Missing Health Check	Can't verify ready	Add HEALTHCHECK in Dockerfile
No .dockerignore	Slow builds, large images	Always create .dockerignore
localhost in env	Won't work in Docker	Use Docker service names

Coordination

When to Escalate

To container-architect:

•integration.md is missing/incomplete
•Circular dependencies in startup order
•New integration requirements discovered

To coding-agent:

•Component missing expected exports
•Component has bugs blocking integration
•Interface mismatch with spec

Do NOT:

•Modify component implementation code
•Add features not in integration.md
•Change component interfaces
•Skip Dockerfile.local creation
•Skip integration tests