Cloud Native Readiness

Cloud Native Readiness Assessment Skill

Overview

This skill evaluates a repository's readiness for cloud-native microservice deployment through a 3-phase workflow:

1. Assess - Analyze the project against cloud-native criteria and produce a readiness report 2. Detect - Check if Docker artifacts already exist (Dockerfile, docker-compose, container images) 3. Route - If artifacts exist, return the result directly; if not, invoke dockerfile-skill to containerize

Workflow

cloud-native-readiness
  │
  ├─ Phase 1: Cloud-Native Assessment
  │    ├─ NOT suitable → Report reasons, suggest remediation, END
  │    └─ Suitable → Continue
  │
  ├─ Phase 2: Existing Artifacts Detection
  │    ├─ Found Dockerfile/docker-compose/image → Report existing setup, END
  │    └─ Not found → Continue
  │
  └─ Phase 3: Route to dockerfile-skill
       └─ Invoke /dockerfile to generate Docker configuration

Usage

/cloud-native-readiness              # Assess current directory
/cloud-native-readiness <path>       # Assess specific path
/cloud-native-readiness <github-url> # Clone and assess

Quick Start

When invoked, ALWAYS follow this sequence:

1. Read and execute modules/assess.md — Cloud-native readiness evaluation 2. Read and execute modules/detect.md — Existing Docker artifacts detection 3. Read and execute modules/route.md — Decision routing

Phase 1: Cloud-Native Readiness Assessment

Load and execute: modules/assess.md

Evaluates 6 dimensions (each scored 0-2):

Scoring:

• 10-12: Excellent — fully cloud-native ready
• 7-9: Good — ready with minor adjustments
• 4-6: Fair — needs some refactoring before containerization
• 0-3: Poor — significant rework needed, not recommended for containerization now

Output: Structured readiness report with score, findings, and recommendations.

Phase 2: Existing Artifacts Detection

Load and execute: modules/detect.md

Checks for:

• Dockerfile / Dockerfile.* (multi-stage, multi-service)
• docker-compose.yml / docker-compose.yaml / compose.yml
• .dockerignore
• DOCKER.md or docker-related documentation
• Container registry references (ghcr.io, docker.io, ECR, GCR, ACR)
• Kubernetes manifests (k8s/, kubernetes/, deploy/, helm/, charts/)
• CI/CD pipeline with Docker build steps (.github/workflows/, .gitlab-ci.yml)

Output: Inventory of existing Docker/K8s artifacts with quality assessment.

Phase 3: Routing Decision

Load and execute: modules/route.md

Decision Matrix:

Readiness Report Format

The final output MUST use this format:

# Cloud-Native Readiness Report

## Summary
- **Project**: {name}
- **Score**: {score}/12 ({rating})
- **Verdict**: {Ready | Ready with caveats | Needs work | Not recommended}

## Assessment Details

### ✅ Strengths
- {what's already cloud-native friendly}

### ⚠️ Concerns
- {issues that need attention}

### ❌ Blockers (if any)
- {critical issues preventing containerization}

## Dimension Scores

| Dimension | Score | Notes |
|-----------|-------|-------|
| Statelessness | {0-2} | {detail} |
| Config Externalization | {0-2} | {detail} |
| Horizontal Scalability | {0-2} | {detail} |
| Startup/Shutdown | {0-2} | {detail} |
| Observability | {0-2} | {detail} |
| Service Boundaries | {0-2} | {detail} |

## Existing Docker Artifacts
- {inventory or "None found"}

## Recommendation
- {next steps}

Supporting Resources

• Assessment Criteria: knowledge/criteria.md — Detailed scoring rubrics
• Anti-Patterns: knowledge/anti-patterns.md — Common cloud-native anti-patterns
• Examples: examples/ — Sample readiness reports

Integration with dockerfile-skill

When routing to dockerfile-skill, pass the assessment context:

1. The readiness report findings inform Dockerfile generation decisions 2. Detected external services map directly to docker-compose.yml services 3. Identified concerns become Dockerfile comments / DOCKER.md caveats 4. The assessment's config externalization findings drive ENV/ARG setup

Handoff: When invoking dockerfile-skill, include a summary of:

• Detected language/framework/package manager
• External service dependencies
• Config externalization status
• Any special concerns (stateful components, long startup, etc.)

Cloud-Native Readiness Report — Sample

Summary

• Project: marble (headless CMS)
• Score: 11/12 (Excellent)
• Verdict: Ready

Assessment Details

Strengths

• All data stored in external PostgreSQL (Neon serverless)
• Session management via Better Auth with DB-backed sessions
• File uploads to Cloudflare R2 (cloud object storage)
• Config fully driven by environment variables with .env.example
• Clear monorepo structure with independent deployable units
• Hono API is edge-first and stateless by design
• Redis-based rate limiting and caching via Upstash

Concerns

• No explicit SIGTERM handler detected in API (Hono handles it via runtime)

Blockers

• None

Dimension Scores

Per-Unit Assessment

Existing Docker Artifacts

• docker-compose.yml found at root (for local Postgres)
• No Dockerfile found for any app
• No Kubernetes manifests
• No CI/CD Docker build steps

Recommendation

• Project is fully cloud-native ready (score 11/12)
• Docker Compose exists for local dev but no production Dockerfiles
• Next step: Invoke dockerfile-skill to generate production Docker configuration
• Minor suggestion: Add /health endpoint to API for K8s readiness probes

Cloud-Native Anti-Patterns

Common patterns that indicate a project is NOT ready for containerization.

Critical Anti-Patterns (Blockers)

1. Local File Storage for User Data

Problem: User uploads saved to ./uploads/ or ./data/
Impact: Data lost on container restart, can't scale horizontally
Fix: Migrate to S3/R2/GCS for file storage

2. SQLite as Primary Database

Problem: SQLite file stored on local filesystem
Impact: Can't share between containers, data lost on restart without volume
Fix: Migrate to PostgreSQL/MySQL with external connection

3. Hardcoded Secrets in Source

Problem: API keys, passwords, tokens committed to git
Impact: Security risk, can't rotate without code change
Fix: Move all secrets to environment variables

4. Hardcoded localhost References

Problem: Code references localhost:5432, 127.0.0.1:6379
Impact: Won't work in container network
Fix: Use env vars for all service URLs (DATABASE_URL, REDIS_URL)

5. Process-Dependent State

Problem: Global variables storing user sessions, request counts
Impact: State lost on restart, inconsistent across instances
Fix: Externalize to Redis or database

Warning Anti-Patterns (Concerns)

6. In-Memory Session Store

Problem: express-session with default MemoryStore
Impact: Sessions lost on restart, can't load-balance across instances
Fix: Use Redis session store (connect-redis)

7. Cron Jobs Without Distributed Lock

Problem: node-cron or setInterval for scheduled tasks
Impact: Multiple instances = multiple executions
Fix: Use distributed scheduler (BullMQ, database-backed, leader election)

8. WebSocket Without Redis Adapter

Problem: Socket.IO or ws without pub/sub backing
Impact: Clients on different instances can't communicate
Fix: Add Redis adapter for Socket.IO, or use external pub/sub

9. Large Startup Payload

Problem: Loading large ML models, data files, or indexes at startup
Impact: Slow container startup, fails K8s readiness probes
Fix: Lazy loading, separate model-serving service, readiness probe with delay

10. No Graceful Shutdown

Problem: No SIGTERM handler, abrupt process exit
Impact: In-flight requests dropped, database connections leaked
Fix: Add signal handler, drain connections, close DB pool

11. Logging to Files

Problem: Winston/Bunyan configured to write to ./logs/app.log
Impact: Logs lost on container restart, fills up container filesystem
Fix: Log to stdout/stderr, use container log driver for aggregation

12. Build-Time Secrets Required

Problem: Next.js SSG pages need DATABASE_URL at build time
Impact: Secrets must be available during docker build (leaks into layers)
Fix: Use ARG with placeholder values for build, real values at runtime

Informational Anti-Patterns (Notes)

13. Monolith Without Clear Boundaries

Problem: Single process handles API, background jobs, WebSocket, cron
Impact: Can't scale components independently
Note: Works in containers but limits K8s benefits
Suggestion: Consider splitting into services over time

14. Shared Database Without Scoping

Problem: Multiple services access same tables directly
Impact: Schema changes require coordinated deployment
Note: Common and acceptable for many projects
Suggestion: Define clear table ownership per service

15. Missing Health Checks

Problem: No /health or /healthz endpoint
Impact: K8s can't determine if container is healthy
Fix: Add simple health endpoint that checks DB connectivity

Detection Cheat Sheet

Cloud-Native Readiness Scoring Criteria

Dimension 1: Statelessness (0-2)

Score 2 — Fully Stateless

• All persistent data stored in external database (PostgreSQL, MySQL, MongoDB)
• Session management via external store (Redis, DB) or stateless tokens (JWT)
• File uploads go to cloud storage (S3, R2, GCS) not local filesystem
• No in-memory caches that can't be lost (or cache is external like Redis)
• Application can be killed and restarted with zero data loss

Score 1 — Mostly Stateless

• Core data is external, but some local state exists:
• Temporary file processing (acceptable if using /tmp)
• In-memory cache for performance (acceptable if cache miss just hits DB)
• Local uploads that get moved to cloud storage eventually
• Losing an instance causes minor degradation, not data loss

Score 0 — Stateful

• SQLite or embedded database as primary store
• User uploads saved to local filesystem permanently
• In-memory session store (MemoryStore)
• Application state lives in process memory
• Killing instance = data loss

---

Dimension 2: Config Externalization (0-2)

Score 2 — Fully Externalized

• All environment-specific values from env vars
• .env.example documents all required variables
• Config validation at startup (e.g., envalid, @t3-oss/env-nextjs)
• No secrets in source code
• Same image works in dev/staging/prod with different env vars

Score 1 — Partially Externalized

• Most config via env vars, some hardcoded defaults
• .env.example exists but may be incomplete
• Some config files that could be overridden but aren't env-driven
• No secrets committed, but config isn't fully documented

Score 0 — Hardcoded

• Connection strings hardcoded in source
• Secrets committed to repo
• Config files with environment-specific values checked in
• No env var pattern

---

Dimension 3: Horizontal Scalability (0-2)

Score 2 — Fully Scalable

• Stateless HTTP handlers (REST/GraphQL)
• Background jobs via external queue (BullMQ, RabbitMQ, SQS)
• Database handles concurrency (proper transactions, no file locks)
• No singleton patterns that break with N instances
• WebSocket with Redis adapter (if applicable)

Score 1 — Mostly Scalable

• Core request handling is stateless
• Some single-instance concerns:
• Cron jobs without distributed lock
• WebSocket without sticky session support
• In-memory rate limiting
• Running 2+ instances mostly works, with minor issues

Score 0 — Single Instance Only

• File-based locking
• In-process scheduler with side effects
• Shared mutable state across requests
• Can only run one instance

---

Dimension 4: Startup/Shutdown (0-2)

Score 2 — Production Ready

• Explicit SIGTERM/SIGINT handling
• Graceful connection draining
• Health check endpoint (/health, /healthz, /readyz)
• Fast startup (< 10 seconds)
• Proper cleanup of resources on shutdown

Score 1 — Framework Defaults

• Framework handles basic lifecycle (Express, Next.js, Hono)
• No explicit signal handling but doesn't crash on SIGTERM
• No dedicated health endpoint but root responds quickly
• Moderate startup time (10-30 seconds)

Score 0 — Unmanaged

• No signal handling
• Long startup (> 30 seconds, loading large models/data)
• Abrupt termination loses in-flight requests
• No way to check if service is ready

---

Dimension 5: Observability (0-2)

Score 2 — Well Instrumented

• Structured logging (JSON to stdout/stderr)
• Error tracking (Sentry, Bugsnag)
• Metrics endpoint (Prometheus, custom)
• Request tracing (correlation IDs, OpenTelemetry)
• Centralized log-friendly output

Score 1 — Basic Logging

• Console.log to stdout (works with container log drivers)
• Some error handling middleware
• No structured format but parseable
• No metrics or tracing

Score 0 — Blind

• No logging or logs to local files only
• Silent error swallowing
• No way to diagnose issues in production
• No error reporting

---

Dimension 6: Service Boundaries (0-2)

Score 2 — Well Bounded

• Clear separation: each service has own entry point and package.json
• Independent deployment possible
• Well-defined API contracts (REST routes, GraphQL schema)
• Monorepo with apps/ directory pattern
• Database per service or clearly scoped queries

Score 1 — Logical Separation

• Routes/modules are organized but deploy as one unit
• Shared database with clear ownership
• Could be split into services with moderate effort
• Has clear API layer even if monolithic

Score 0 — Tightly Coupled

• Everything in one file or deeply intertwined
• No clear API boundaries
• Frontend and backend inseparable
• Circular dependencies between modules

---

Technology-Specific Bonuses (Informational, not scored)

These don't affect the score but are noted in the report:

Naturally Cloud-Native Frameworks

• Hono — Edge-first, stateless by design
• Fastify — Fast startup, graceful shutdown built-in
• Next.js — Standalone output mode = container-ready
• Go net/http — Single binary, fast startup, graceful shutdown
• FastAPI — ASGI, stateless, Uvicorn handles signals

Requires Extra Attention

• Express — No built-in graceful shutdown (needs manual SIGTERM)
• Django — ORM connection management in containers
• Spring Boot — JVM startup time, memory tuning needed
• Rails — Asset pipeline, Puma worker configuration

Deterministic Scoring Model

This document describes the code-level scoring algorithm implemented in dockerfile-service/scripts/score-model.js. It provides instant (< 1 second) readiness scoring by analyzing the local filesystem of a cloned repo.

Architecture

The model has two layers: 1. Signal Detection — filesystem scanning for files, dependencies, patterns 2. Scoring Algorithm — maps signals to 6 dimension scores (0-2 each)

Signal Detection

Language Detection

Scans root AND up to 2 levels deep (monorepo support):

Framework Detection (Node.js — scans ALL package.json in monorepo)

Collects dependencies from every package.json found up to 3 levels deep:

HTTP Server Detection

The most critical signal — does this project listen on a port?

State Externalization

Scans dependencies for database/cache libraries:

Config Externalization

Docker Artifacts (Bonus points, not dimension)

Scoring Algorithm

Dimension Scores (0-2 each, max raw = 12)

statelessness:
  2 = external DB (postgres/mysql/mongo) without sqlite
  1 = external DB + sqlite (mixed), or redis/s3 only, or web service without detected DB
  0 = no external state or HTTP

config:
  2 = .env.example found OR env validation library
  1 = .env found or docker-compose exists
  0 = nothing detected

scalability:
  2 = Go/Rust (compiled binary) OR HTTP + Redis
  1 = any HTTP handler
  0 = no HTTP

startup:
  2 = Go/Rust OR Hono/Fastify (lightweight frameworks)
  1 = Next.js/Express/FastAPI/Django/Flask/Spring or has start script
  0 = nothing

observability:
  2 = Dockerfile has HEALTHCHECK
  1 = HTTP handler (produces request logs)
  0 = nothing

boundaries:
  2 = monorepo with apps/ dir, OR monorepo detected
  1 = single service with build pipeline or HTTP handler
  0 = nothing

Bonus (capped at total 12)

• +1 if Dockerfile exists
• +1 if docker-compose exists

Final Score

total = min(12, sum(dimensions) + bonus)

Excellent (10-12): Fully cloud-native ready
Good      (7-9):   Ready with minor adjustments
Fair      (4-6):   Needs some refactoring
Poor      (0-3):   Significant rework needed

Accuracy (measured against 164 Sealos production templates)

All 164 templates are confirmed containerizable (ground truth = positive).

Projects scoring below 4 are typically:

• Shell wrapper projects (language=Dockerfile or Shell)
• Unknown language repos (private or incomplete data)
• Clojure/Erlang (niche languages not in detection list)

These edge cases are handled by the AI deep assessment fallback.

Usage

CLI

node scripts/score-model.js /path/to/repo

Programmatic

import { scoreProject } from './scripts/score-model.js';

const result = scoreProject('/path/to/cloned/repo');
// result.score: 0-12
// result.verdict: "Excellent" | "Good" | "Fair" | "Poor"
// result.dimensions: { statelessness, config, scalability, startup, observability, boundaries }
// result.signals: { language, framework, has_http_server, external_db, ... }

API

# Fast (code-only, < 5 seconds including git clone)
curl -X POST http://localhost:3000/assess \
  -H 'Content-Type: application/json' \
  -d '{"github_url": "https://github.com/lobehub/lobe-chat"}'

# Deep (AI-powered, 1-3 minutes, full markdown report)
curl -X POST http://localhost:3000/assess/deep \
  -H 'Content-Type: application/json' \
  -d '{"github_url": "https://github.com/lobehub/lobe-chat"}'

Real-World Containerizable Project Patterns

Data derived from analysis of 164 Sealos Cloud templates — all production-deployed containerized applications.

Key Finding

ALL 164 projects in the Sealos template marketplace are successfully containerized and running in production. This dataset provides ground truth for what "containerizable" looks like in practice.

Language Distribution (150 analyzed)

Insight: TypeScript + Go + Python + Rust = 65% of all containerizable projects. Go and Rust have the highest Dockerfile presence (single binary advantage).

Docker Artifact Presence

• 50% of repos have a Dockerfile in the repository root
• 35% have docker-compose.yml alongside
• 25% have both Dockerfile + docker-compose
• 41% have neither — Sealos builds from pre-built images or generates config

Insight: Having NO Dockerfile doesn't mean "not containerizable". Many mature projects publish pre-built images to registries (ghcr.io, Docker Hub), and Sealos references those directly.

Project Categories

Common Dockerfile Patterns (from 30 deep-analyzed repos)

Multi-Stage Builds

• 88% use multi-stage builds (2-5 stages)
• Average: 2.5 stages
• Pattern: deps → build → runtime
• Go/Rust projects: build → scratch/alpine (minimal final image)
• Node.js projects: deps → build → node:slim or → nginx

Base Image Choices

Security Practices

• 35% use non-root USER (e.g., USER node, USER nextjs, USER 1000)
• 18% have HEALTHCHECK instruction
• Most use fixed image versions (not :latest)

Entry Point Patterns

What Makes ALL These Projects Containerizable

Universal Characteristics (found in 100% of templates)

1. Web Service: Every project exposes HTTP/HTTPS (API, dashboard, or web UI) 2. External State: Data stored in PostgreSQL, MySQL, MongoDB, Redis — never embedded-only 3. Config via Environment: All use env vars for connection strings, API keys, secrets 4. Clear Entry Point: Single binary, npm start, or well-defined startup command 5. Single Responsibility: Each container runs one process/service

Common External Dependencies

Monorepo Patterns (common in TypeScript projects)

Many of the largest projects (Dify, AFFiNE, n8n, Plane, Twenty) are monorepos:

• Use Turborepo, pnpm workspaces, or nx
• Build specific app targets for Docker
• Often have separate Dockerfiles per service (api, web, worker)
• Use --filter or workspace commands in Dockerfile

Fast-Track Assessment Rules

Based on this data, these characteristics almost guarantee containerization readiness:

Instant Pass (Score >= 10)

• Go or Rust single-binary web server
• Next.js/Nuxt app with output: standalone
• Python FastAPI/Flask with PostgreSQL
• Any project that already has Dockerfile + docker-compose

Likely Pass (Score >= 7)

• TypeScript monorepo with apps/ structure
• Java Spring Boot application
• PHP app with composer (use official PHP-FPM image)
• Any project using PostgreSQL/MySQL + Redis

Needs Investigation (Score 4-6)

• Projects with SQLite as primary DB (might need volume mount)
• Desktop/Electron apps with web component
• Projects with heavy local file processing

Likely Fail (Score 0-3)

• Pure CLI tools with no web server
• Desktop-only applications
• Projects requiring GPU without web API
• Embedded systems code

Sealos Template Structure Reference

Each Sealos template defines:

spec:
  gitRepo: "https://github.com/org/repo"    # Source code
  defaults:
    app_name: "xxx-${{ random(8) }}"          # Random instance name
    app_host: "xxx-${{ random(8) }}"          # Random hostname
  inputs:                                      # User-configurable params
    OPENAI_API_KEY:                            # Most common: API keys
      type: string
      required: true
    admin_password:                            # Second: admin credentials
      type: string

Key patterns in inputs (most common): 1. OPENAI_API_KEY (9 templates) — AI service API key 2. admin_password (5) — Admin credentials 3. api_key (3) — Generic API key 4. root_password (3) — Database root password 5. BASE_URL (2) — Service URL configuration

This tells us: containerizable apps externalize their secrets and API configurations.

Module: Cloud-Native Readiness Assessment

Purpose

Evaluate a project against 6 cloud-native dimensions to produce a readiness score (0-12).

Data source: Patterns derived from 164 production-deployed Sealos Cloud templates. See knowledge/sealos-patterns.md for the full dataset.

Pre-Assessment: Fast-Track Rules

Before running the full 6-dimension assessment, check these fast-track rules derived from 164 real-world containerized projects. If a fast-track matches, you can assign a preliminary score and still verify with the full assessment.

Instant Pass (Preliminary Score >= 10)

Apply if ANY of these match:

• Go/Rust single binary with HTTP listener (e.g., net/http, actix-web, axum)
• Next.js app with output: "standalone" in next.config
• Python FastAPI/Flask/Django with external PostgreSQL/MySQL
• Project already has Dockerfile + docker-compose with health checks
• Published to container registry (ghcr.io, Docker Hub, ECR)

Likely Pass (Preliminary Score >= 7)

• TypeScript monorepo with apps/ structure (Turborepo, pnpm workspaces, nx)
• Java Spring Boot application with external database
• PHP app with composer.json using official PHP-FPM base image pattern
• Any web service using PostgreSQL + Redis with env var config
• Python app with requirements.txt and Uvicorn/Gunicorn entry point

Needs Full Assessment

• Projects with SQLite as primary database
• Desktop/Electron apps that also have a web component
• Projects with heavy local file processing or GPU requirements
• CLI tools that may or may not expose HTTP

Likely Fail (Preliminary Score 0-3)

• Pure CLI tools with no HTTP server
• Desktop-only GUI applications (Electron without web API)
• Embedded systems or hardware-specific code
• Projects requiring persistent local state with no external DB

Execution Steps

Step 1: Identify Project Type

First, determine the basic project characteristics:

Check for:
- package.json → Node.js ecosystem
- requirements.txt / pyproject.toml → Python
- go.mod → Go
- pom.xml / build.gradle → Java
- Cargo.toml → Rust
- composer.json → PHP
- Gemfile → Ruby

For monorepos, identify all services/apps:

Check for:
- pnpm-workspace.yaml / turbo.json / nx.json → Monorepo
- apps/ or services/ directory → Multiple deployable units
- Each deployable unit should be assessed independently

Output:

project:
  name: "{from package.json or directory name}"
  type: "monorepo | single-app"
  language: "typescript | python | go | java | rust | php | ruby"
  framework: "{detected framework}"
  deployable_units:
    - name: "api"
      path: "apps/api"
      type: "REST API"
    - name: "cms"
      path: "apps/cms"
      type: "Web application"

Step 2: Assess Statelessness (0-2 points)

What to check:

# Check for in-memory session stores
grep -rE "express-session|cookie-session|session\(\)|MemoryStore" --include="*.ts" --include="*.js"

# Check for local file system writes (non-temp)
grep -rE "fs\.(write|append|mkdir)|writeFile|createWriteStream" --include="*.ts" --include="*.js" | grep -v "node_modules" | grep -v "/tmp"

# Check for in-memory caches without external backing
grep -rE "new Map\(\)|global\.\w+Cache|let cache =|const cache =" --include="*.ts" --include="*.js"

# Check for SQLite or local database files
grep -rE "sqlite|better-sqlite3|\.db\"|\.sqlite" --include="*.ts" --include="*.js"
find . -name "*.db" -o -name "*.sqlite" | head -5

# Check for local upload directories (non-cloud storage)
grep -rE "multer\.diskStorage|upload.*dest.*['\"]\./" --include="*.ts" --include="*.js"

Scoring:

• 2: Fully stateless. State externalized to DB/Redis/S3. No local file dependency.
• 1: Mostly stateless. Minor local state (temp files, build cache) but core state is external.
• 0: Stateful. In-memory sessions, local file storage for user data, SQLite.

Positive indicators (state externalized):

• Uses PostgreSQL/MySQL/MongoDB for data → external DB
• Uses Redis/Memcached for sessions/cache → external cache
• Uses S3/R2/GCS for file storage → external storage
• Uses JWT or external auth (Better Auth, NextAuth) → stateless auth

Negative indicators (local state):

• MemoryStore for sessions
• fs.writeFileSync for user uploads
• SQLite as primary database
• In-process cron jobs with state

Step 3: Assess Config Externalization (0-2 points)

What to check:

# Check for environment variable usage
grep -rE "process\.env\.|os\.environ|os\.Getenv|System\.getenv" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" | wc -l

# Check for .env file patterns
ls -la .env* 2>/dev/null
ls -la */.env* 2>/dev/null

# Check for hardcoded connection strings
grep -rE "(localhost|127\.0\.0\.1):\d{4}" --include="*.ts" --include="*.js" | grep -v "node_modules" | grep -v ".env"

# Check for hardcoded secrets
grep -rE "password\s*[:=]\s*['\"][^'\"]+['\"]|secret\s*[:=]\s*['\"][^'\"]+['\"]" --include="*.ts" --include="*.js" | grep -v "node_modules" | grep -v ".env" | grep -v "placeholder"

# Check for config/env validation (good practice)
grep -rE "createEnv|envalid|env-var|joi.*env|zod.*env" --include="*.ts" --include="*.js"

Scoring:

• 2: All config via env vars. .env.example exists. No hardcoded secrets. Config validation present.
• 1: Mostly env var driven. Some hardcoded defaults but overridable. .env.example may be incomplete.
• 0: Hardcoded configs, connection strings, or secrets in source code. No env var pattern.

Positive indicators:

• .env.example with documented variables
• @t3-oss/env-nextjs or envalid for validation
• All connection strings from env vars
• Docker-friendly config patterns (12-factor)

Negative indicators:

• Hardcoded localhost:5432 without env var fallback
• Secrets committed in config files
• Config files that can't be overridden at runtime

Step 4: Assess Horizontal Scalability (0-2 points)

What to check:

# Check for WebSocket with sticky sessions concern
grep -rE "WebSocket|socket\.io|ws\(" --include="*.ts" --include="*.js"

# Check for distributed-friendly patterns
grep -rE "Redis|BullMQ|bull|@upstash|amqp|kafka" --include="*.ts" --include="*.js"

# Check for file-based locks
grep -rE "lockfile|\.lock\"|flock|advisory.*lock" --include="*.ts" --include="*.js"

# Check for singleton patterns that break with multiple instances
grep -rE "global\.\w+\s*=|globalThis\.\w+\s*=" --include="*.ts" --include="*.js" | grep -v "prisma"

# Check for cron/scheduler (single-instance concern)
grep -rE "node-cron|cron\.schedule|setInterval.*\d{4,}" --include="*.ts" --include="*.js"

# Check for leader election or distributed lock patterns (good sign)
grep -rE "redlock|@upstash/lock|leader.*election" --include="*.ts" --include="*.js"

Scoring:

• 2: Fully horizontally scalable. Stateless requests, external queue for background jobs, no file locks.
• 1: Mostly scalable. May need sticky sessions for WebSocket, or has cron jobs that should be single-instance.
• 0: Single-instance only. File-based locks, in-process schedulers with side effects, shared mutable state.

Positive indicators:

• REST/GraphQL API (naturally stateless)
• Redis-backed queues (BullMQ, etc.)
• Database-level locking (not file-level)
• No in-process cron with side effects

Negative indicators:

• setInterval for scheduled tasks without distributed lock
• File-based locking mechanisms
• In-memory pub/sub without Redis adapter

Step 5: Assess Startup/Shutdown (0-2 points)

What to check:

# Check for graceful shutdown handling
grep -rE "SIGTERM|SIGINT|process\.on.*signal|graceful.*shutdown|beforeExit" --include="*.ts" --include="*.js"

# Check for health check endpoints
grep -rE "health|healthz|readyz|livez|ready|alive" --include="*.ts" --include="*.js" --include="*.py"

# Check for long initialization (e.g., loading large ML models)
grep -rE "loadModel|warmup|preload|initialize.*cache" --include="*.ts" --include="*.js"

# Check framework - some handle graceful shutdown automatically
grep -rE "hono|express|fastify|nestjs|next" package.json 2>/dev/null

# Check for connection draining
grep -rE "server\.close|drain|closeAllConnections" --include="*.ts" --include="*.js"

Scoring:

• 2: Handles SIGTERM gracefully. Has health check endpoints. Fast startup (< 10s).
• 1: Framework handles basic shutdown. No explicit health check but responds to HTTP quickly. Moderate startup.
• 0: No signal handling. Long startup (loads large resources). Abrupt termination risks.

Positive indicators:

• Explicit SIGTERM handler
• /health or /healthz endpoint
• Frameworks like Hono/Fastify (lightweight, fast startup)
• Connection pooling with proper cleanup

Negative indicators:

• Loading large files at startup without lazy loading
• No graceful shutdown in custom server
• Long database migration at startup

Step 6: Assess Observability (0-2 points)

What to check:

# Check for structured logging
grep -rE "pino|winston|bunyan|structured.*log|JSON\.stringify.*log" --include="*.ts" --include="*.js"

# Check for console.log (not ideal but functional)
grep -rE "console\.(log|error|warn)" --include="*.ts" --include="*.js" | wc -l

# Check for metrics/monitoring
grep -rE "prometheus|prom-client|datadog|newrelic|opentelemetry|@sentry" --include="*.ts" --include="*.js"

# Check for request tracing
grep -rE "trace-id|x-request-id|correlation-id|opentelemetry" --include="*.ts" --include="*.js"

# Check for error tracking
grep -rE "sentry|bugsnag|rollbar|errorHandler" --include="*.ts" --include="*.js"

Scoring:

• 2: Structured logging (JSON). Metrics endpoint. Error tracking. Request tracing.
• 1: Has logging (even console.log to stdout). Some error handling. No metrics.
• 0: No logging. Silent failures. No observability infrastructure.

Positive indicators:

• Structured JSON logging → works with log aggregators
• Sentry/error tracking → crash reporting
• Prometheus metrics → monitoring
• Logs to stdout/stderr → container-friendly

Negative indicators:

• Logging to local files only (not stdout)
• No error handling middleware
• Silent catch {} blocks

Step 7: Assess Service Boundaries (0-2 points)

What to check:

# Check if it's a monorepo with clear service separation
ls apps/ services/ 2>/dev/null

# Check for clear API boundaries
grep -rE "app\.(get|post|put|delete|use)" --include="*.ts" --include="*.js" | head -5
grep -rE "router\.(get|post|put|delete)" --include="*.ts" --include="*.js" | head -5

# Check for tightly coupled components
# (e.g., frontend and backend in same process)
grep -rE "next.*custom.*server|express.*next\(" --include="*.ts" --include="*.js"

# Check for shared database access pattern
grep -rE "prisma|drizzle|typeorm|sequelize" --include="*.ts" --include="*.js" |
  cut -d: -f1 | sort -u

# For monorepos: check if services can deploy independently
ls apps/*/package.json 2>/dev/null

Scoring:

• 2: Clear service boundaries. Each service has its own entry point, dependencies, and can deploy independently.
• 1: Logical separation exists (routes, modules) but deployed as single unit. Monorepo with shared DB is fine.
• 0: Tightly coupled monolith. No clear service boundaries. Everything in one process with cross-cutting concerns.

Positive indicators:

• Monorepo with apps/ directory and independent package.json per app
• API and frontend are separate deployable units
• Clear route/controller structure
• REST/GraphQL API with well-defined endpoints

Negative indicators:

• Single index.js with everything
• Frontend rendering and API in same server without separation
• Circular dependencies between modules

Step 8: Calculate Total Score and Produce Report

Sum all dimension scores (0-12) and determine rating:

12-10: ★★★★★ Excellent — Fully cloud-native ready
 9-7:  ★★★★  Good     — Ready with minor adjustments
 6-4:  ★★★   Fair     — Needs some refactoring
 3-0:  ★★    Poor     — Significant rework needed

For monorepos: Assess each deployable unit separately, then provide an overall score.

Output Format

assessment:
  project_name: "{name}"
  project_type: "monorepo | single-app"
  overall_score: {0-12}
  rating: "Excellent | Good | Fair | Poor"
  verdict: "Ready | Ready with caveats | Needs work | Not recommended"

  dimensions:
    statelessness:
      score: {0-2}
      findings:
        - "{specific finding}"
      evidence:
        positive: ["{what's good}"]
        negative: ["{what's concerning}"]

    config_externalization:
      score: {0-2}
      findings:
        - "{specific finding}"
      evidence:
        positive: []
        negative: []

    horizontal_scalability:
      score: {0-2}
      findings: []
      evidence:
        positive: []
        negative: []

    startup_shutdown:
      score: {0-2}
      findings: []
      evidence:
        positive: []
        negative: []

    observability:
      score: {0-2}
      findings: []
      evidence:
        positive: []
        negative: []

    service_boundaries:
      score: {0-2}
      findings: []
      evidence:
        positive: []
        negative: []

  # Per-unit assessment for monorepos
  units:
    - name: "api"
      path: "apps/api"
      score: {0-12}
      notes: "{specific notes}"
    - name: "cms"
      path: "apps/cms"
      score: {0-12}
      notes: "{specific notes}"

  strengths:
    - "{summary of what's already good}"

  concerns:
    - "{issues that need attention}"

  blockers:
    - "{critical issues, if any}"

  recommendations:
    - "{actionable next steps}"

Module: Existing Docker Artifacts Detection

Purpose

Detect whether the project already has Docker/K8s configuration and assess its completeness.

Execution Steps

Step 1: Scan for Docker Files

# Dockerfile variants
find . -maxdepth 3 -name "Dockerfile" -o -name "Dockerfile.*" -o -name "*.Dockerfile" 2>/dev/null | grep -v node_modules

# Docker Compose variants
find . -maxdepth 3 \( -name "docker-compose.yml" -o -name "docker-compose.yaml" -o -name "compose.yml" -o -name "compose.yaml" -o -name "docker-compose.*.yml" \) 2>/dev/null | grep -v node_modules

# .dockerignore
find . -maxdepth 3 -name ".dockerignore" 2>/dev/null | grep -v node_modules

# Docker documentation
find . -maxdepth 3 -name "DOCKER.md" -o -name "docker-README.md" 2>/dev/null | grep -v node_modules

# Docker-related env files
find . -maxdepth 3 -name ".env.docker*" -o -name "*.dev.vars*" 2>/dev/null | grep -v node_modules

# Entrypoint scripts
find . -maxdepth 3 -name "docker-entrypoint.sh" -o -name "entrypoint.sh" 2>/dev/null | grep -v node_modules

Step 2: Scan for Kubernetes / Deployment Manifests

# Kubernetes manifests
find . -maxdepth 4 -type d \( -name "k8s" -o -name "kubernetes" -o -name "kube" -o -name "manifests" \) 2>/dev/null | grep -v node_modules

# Helm charts
find . -maxdepth 4 -type d -name "charts" 2>/dev/null | grep -v node_modules
find . -maxdepth 4 -name "Chart.yaml" 2>/dev/null | grep -v node_modules

# Kustomize
find . -maxdepth 4 -name "kustomization.yaml" -o -name "kustomization.yml" 2>/dev/null | grep -v node_modules

# Skaffold
find . -maxdepth 2 -name "skaffold.yaml" 2>/dev/null

# Tilt
find . -maxdepth 2 -name "Tiltfile" 2>/dev/null

# Docker Swarm
grep -rl "deploy:" docker-compose*.yml compose*.yml 2>/dev/null | head -5

Step 3: Scan for CI/CD Docker Build Steps

# GitHub Actions
grep -rl "docker" .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null
grep -rE "docker.*build|docker.*push|ghcr\.io|docker\.io" .github/workflows/ 2>/dev/null | head -10

# GitLab CI
grep -E "docker|image:|registry" .gitlab-ci.yml 2>/dev/null | head -10

# Other CI
find . -maxdepth 2 \( -name "Jenkinsfile" -o -name ".circleci" -o -name "bitbucket-pipelines.yml" \) 2>/dev/null

Step 4: Detect Container Registry References

# Search for registry references in all config files
grep -rE "(ghcr\.io|docker\.io|registry\.hub|ecr\.aws|gcr\.io|azurecr\.io|quay\.io)/[a-z0-9._/-]+" . \
  --include="*.yml" --include="*.yaml" --include="*.json" --include="*.toml" --include="*.md" \
  2>/dev/null | grep -v node_modules | head -10

# Check package.json for docker-related scripts
grep -E '"docker|"container|"image' package.json 2>/dev/null

Step 5: Assess Quality of Existing Artifacts

If Dockerfile found, check for:

# Multi-stage build?
grep -c "^FROM" Dockerfile

# Non-root user?
grep -E "USER|useradd|adduser" Dockerfile

# Health check?
grep "HEALTHCHECK" Dockerfile

# Proper .dockerignore?
if [ -f ".dockerignore" ]; then
  wc -l .dockerignore
  grep -E "node_modules|\.git|\.env" .dockerignore
fi

# Fixed base image version (not :latest)?
grep "^FROM" Dockerfile | grep -v ":latest"

# Uses COPY before RUN for cache optimization?
grep -n "^COPY\|^RUN" Dockerfile | head -20

If docker-compose found, check for:

# Health checks defined?
grep -c "healthcheck" docker-compose.yml

# Volumes for persistent data?
grep -c "volumes:" docker-compose.yml

# Networks defined?
grep -c "networks:" docker-compose.yml

# Environment variables properly handled?
grep -cE "env_file|\$\{" docker-compose.yml

# Restart policy?
grep -E "restart:" docker-compose.yml

Step 6: Produce Artifact Inventory

Output Format:

artifacts:
  status: "complete | partial | none"

  dockerfile:
    found: true | false
    paths: ["Dockerfile", "apps/api/Dockerfile"]
    quality:
      multi_stage: true | false
      non_root_user: true | false
      health_check: true | false
      fixed_versions: true | false
      cache_optimized: true | false
      score: "{good | acceptable | poor}"

  docker_compose:
    found: true | false
    paths: ["docker-compose.yml"]
    quality:
      health_checks: true | false
      volumes: true | false
      networks: true | false
      env_handling: true | false
      restart_policy: true | false
      score: "{good | acceptable | poor}"

  dockerignore:
    found: true | false
    paths: [".dockerignore"]
    covers_essentials: true | false  # node_modules, .git, .env

  kubernetes:
    found: true | false
    type: "raw manifests | helm | kustomize | none"
    paths: []

  ci_cd:
    docker_build: true | false
    registry_push: true | false
    platforms: ["github-actions", "gitlab-ci"]

  registry:
    found: true | false
    references: ["ghcr.io/org/repo"]

  entrypoint:
    found: true | false
    paths: []

  documentation:
    found: true | false
    paths: []

  # Overall completeness
  completeness:
    has_build: true | false          # Can build an image
    has_orchestration: true | false   # Can run with dependencies
    has_deployment: true | false      # Can deploy to K8s/cloud
    has_ci: true | false             # Automated build pipeline
    summary: "Production-ready | Development-ready | Incomplete | None"

Decision Points

Based on artifact inventory:

Complete (status: "complete"):

• Has Dockerfile with acceptable+ quality
• Has docker-compose with all dependent services
• Has .dockerignore

→ Report findings, no need for dockerfile-skill

Partial (status: "partial"):

• Has some artifacts but missing key pieces
• Or has artifacts with poor quality

→ Report gaps, suggest improvements or invoke dockerfile-skill

None (status: "none"):

• No Docker artifacts found

→ Proceed to dockerfile-skill if readiness score permits

Module: Decision Routing

Purpose

Based on the assessment score and artifact detection results, determine the next action.

Decision Matrix

┌─────────────────┬──────────────────┬─────────────────────────────────────┐
│ Readiness Score │ Artifacts Status │ Action                              │
├─────────────────┼──────────────────┼─────────────────────────────────────┤
│ ≥ 7 (Good+)    │ Complete         │ REPORT: Return existing setup info  │
│ ≥ 7 (Good+)    │ Partial          │ REPORT: Show gaps + improvements    │
│ ≥ 7 (Good+)    │ None             │ HANDOFF: Invoke dockerfile-skill    │
│ 4-6 (Fair)     │ Complete         │ REPORT: Show artifacts + concerns   │
│ 4-6 (Fair)     │ Partial/None     │ ASK: Confirm with user, then optionally handoff │
│ 0-3 (Poor)     │ Any              │ STOP: Report blockers, do NOT containerize │
└─────────────────┴──────────────────┴─────────────────────────────────────┘

Execution Steps

Step 1: Evaluate Decision

Read the assessment result and artifact inventory from previous modules.

input:
  assessment_score: {0-12}
  assessment_rating: "{Excellent | Good | Fair | Poor}"
  artifacts_status: "{complete | partial | none}"

Step 2: Route — REPORT (Artifacts Exist)

When artifacts are found and readiness is Good+:

1. Summarize existing setup:

• List all found Dockerfiles and their quality
• List docker-compose configuration
• List K8s manifests if any
• Note any CI/CD integration

2. Assess completeness:

• Can the user docker-compose up right now?
• Are all dependent services covered?
• Is the Dockerfile production-quality?

3. Suggest improvements (if partial):

• Missing health checks
• Missing .dockerignore
• Using :latest instead of fixed versions
• Missing multi-stage build
• No non-root user
• Missing restart policy in compose

4. Output the readiness report (format from SKILL.md)

Step 3: Route — HANDOFF (Need to Generate)

When score ≥ 7 and no artifacts exist:

1. Output the readiness report first

2. Inform the user:

   This project is ready for containerization but has no Docker configuration yet.
   Invoking dockerfile-skill to generate production-ready Docker setup...

3. Invoke dockerfile-skill with context:

• Pass the detected language, framework, package manager
• Pass external service dependencies
• Pass any specific concerns from the assessment
• Use: /dockerfile on the current project path

4. The dockerfile-skill will handle:

• Deep project analysis (its own Phase 1)
• Dockerfile generation (Phase 2)
• Build validation (Phase 3)
• Runtime validation (Phase 4)

Step 4: Route — ASK (Fair Score)

When score is 4-6:

1. Output the readiness report with concerns highlighted

2. Present options to user:

• Option A: Proceed with containerization anyway (with caveats)
• Option B: Address the concerns first, then re-run assessment
• Option C: Containerize with documented limitations

3. If user chooses to proceed:

• Add assessment concerns as comments in generated Dockerfile
• Include warnings in DOCKER.md
• Invoke dockerfile-skill

4. If user chooses to address concerns:

• Provide specific, actionable remediation steps:
• Which files to modify
• What patterns to add (e.g., SIGTERM handler, health endpoint)
• What dependencies to externalize

Step 5: Route — STOP (Poor Score)

When score is 0-3:

1. Output the readiness report with blockers

2. Provide remediation roadmap:

   ## Remediation Steps (Priority Order)

   ### 1. [Highest impact blocker]
   - What: {describe the issue}
   - Why: {why it blocks containerization}
   - How: {specific code changes needed}
   - Effort: {low | medium | high}

   ### 2. [Next blocker]
   ...

3. Do NOT invoke dockerfile-skill

• Generating a Dockerfile for a project that isn't ready leads to:
• Broken containers
• Silent runtime failures
• False sense of deployment readiness

4. Offer to re-assess after the user makes changes

Final Output

Regardless of route taken, always end with a clear summary:

## Next Steps

{One of:}
- ✅ Your project is already containerized. See the artifacts listed above.
- 🔧 Minor improvements suggested for your existing Docker setup (see above).
- 🐳 Generating Docker configuration now via dockerfile-skill...
- ⚠️ Some concerns noted. Would you like to proceed anyway or address them first?
- 🚫 Not recommended for containerization yet. See remediation steps above.