Help us improve
Share bugs, ideas, or general feedback.
From grimoire
Applies Twelve-Factor App methodology to build cloud-native applications ensuring portability, scalability, and operability across environments.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireHow this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:apply-twelve-factor-appThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Build cloud-native applications that are portable, scalable, and maintainable by applying twelve foundational factors.
References 15-factor Twelve-Factor App methodology for evaluating cloud-native app architecture, compliance reviews, config, scaling, observability, security, deployments.
Guides application design and refactoring using 12-Factor principles for cloud-native, containerized, and Kubernetes-deployed apps.
Implements 12-Factor principles for cloud-native apps: codebase via Git, dependencies with lockfiles/Docker multistage, config via env vars. For microservices, Kubernetes, containers.
Share bugs, ideas, or general feedback.
Build cloud-native applications that are portable, scalable, and maintainable by applying twelve foundational factors.
Adopted by: Heroku, Pivotal Cloud Foundry, Google App Engine, nearly every modern PaaS platform enforces these constraints Impact: Reduces environment-specific bugs by ~70%; enables horizontal scaling without code changes; new developer onboarding in hours not days Why best: Separates build/run concerns, externalizes configuration, and treats processes as ephemeral — prerequisites for container orchestration and CI/CD
Sources: Adam Wiggins "The Twelve-Factor App" (2011); CNCF Cloud Native Definition v1.0; Martin Fowler "Patterns of Enterprise Application Architecture"
Codebase (I) — Maintain one codebase per app in version control. Multiple deployments (staging, prod) deploy the same codebase with different config. If sharing code, extract shared libraries as dependencies, not forks.
Dependencies (II) — Declare all dependencies explicitly (package.json, requirements.txt, go.mod). Never rely on system-wide packages. Use dependency isolation (virtualenv, bundler, modules). Verify lock files are committed.
Config (III) — Store all config that varies between environments (credentials, URLs, feature flags) in environment variables. Never hard-code config in code. Never commit secrets to the repo. Validate required env vars at startup and fail fast.
Backing services (IV) — Treat databases, queues, caches, and external APIs as attached resources accessed via URL/credentials in config. Swapping a local DB for an RDS instance should require only a config change, not code change.
Build, release, run (V) — Strictly separate build (compile, asset bundle), release (combine build + config), and run (execute processes) stages. Releases are immutable and versioned. Never mutate code at runtime.
Processes (VI) — Execute the app as stateless, share-nothing processes. Persist all state to backing services. Never store sessions in memory or on local disk. This enables horizontal scaling by adding process instances.
Port binding (VII) — Export services via port binding. The app is self-contained and starts its own web server (Express, Gunicorn). It does not rely on a runtime-injected web server. This makes the app portable.
Concurrency (VIII) — Scale out via the process model. Assign process types (web, worker, scheduler) and scale each independently. Avoid threading for concurrency where possible; prefer multiple processes.
Disposability (IX) — Maximize robustness with fast startup (< 5 s target) and graceful shutdown. Handle SIGTERM: finish in-flight requests, return queued jobs, close connections. Design for crash-only restarts.
Dev/prod parity (X) — Keep development, staging, and production as similar as possible. Use the same backing services in dev (not SQLite in dev, Postgres in prod). Close the time gap (deploy frequently) and personnel gap (devs own deployment).
Logs (XI) — Treat logs as event streams. Write to stdout/stderr only; never manage log files. The execution environment captures and routes logs (to Splunk, CloudWatch, Datadog). Never buffer logs in the application.
Admin processes (XII) — Run admin/management tasks (migrations, scripts, REPL) as one-off processes in the same environment as the app. Ship admin code with app code. Never run one-off scripts from a local machine against production.
PORT environment variable so the platform can assign ports dynamically.