Perform 12-Factor App compliance analysis on any codebase. Use when evaluating application architecture, auditing SaaS applications, or reviewing cloud-native applications against the original 12-Factor methodology.
/plugin marketplace add existential-birds/beagle/plugin install beagle@existential-birdsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Reference: The Twelve-Factor App
The 12-Factor App methodology is a set of best practices for building Software-as-a-Service applications that are:
| Parameter | Description | Required |
|---|---|---|
codebase_path | Root path of the codebase to analyze | Required |
Principle: One codebase tracked in revision control, many deploys.
Search Patterns:
# Check for version control
ls -la .git 2>/dev/null || ls -la .hg 2>/dev/null
# Check for multiple apps sharing codebase
find . -name "package.json" -o -name "pyproject.toml" -o -name "setup.py" | head -20
# Check for environment-specific code branches
grep -r "if.*production\|if.*development\|if.*staging" --include="*.py" --include="*.js" --include="*.ts"
File Patterns: .git/, package.json, pyproject.toml, deployment configs
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Single Git repo, same codebase for all environments, no env-specific code branches |
| Partial | Single repo but some environment-specific code paths |
| Weak | Multiple repos for same app or significant code duplication across environments |
Anti-patterns:
if production: ...)Principle: Explicitly declare and isolate dependencies.
Search Patterns:
# Python dependency files
find . -name "requirements.txt" -o -name "pyproject.toml" -o -name "setup.py" -o -name "Pipfile" -o -name "uv.lock"
# JavaScript/TypeScript dependency files
find . -name "package.json" -o -name "package-lock.json" -o -name "yarn.lock" -o -name "pnpm-lock.yaml"
# Check for system tool assumptions
grep -r "subprocess.*curl\|subprocess.*wget\|os.system.*ffmpeg\|shutil.which" --include="*.py"
grep -r "exec.*curl\|child_process.*curl" --include="*.js" --include="*.ts"
# Docker/container isolation
find . -name "Dockerfile" -o -name "docker-compose*.yml"
File Patterns: **/requirements*.txt, **/package.json, **/*.lock, **/Dockerfile
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Lock files present, dependency isolation (venv/Docker), no implicit system tools |
| Partial | Dependencies declared but no lock files or isolation |
| Weak | Dependencies in documentation only, relies on system-installed packages |
Anti-patterns:
Principle: Store config in the environment.
Search Patterns:
# Environment variable usage
grep -r "os.environ\|os.getenv\|process.env\|ENV\[" --include="*.py" --include="*.js" --include="*.ts" --include="*.rb"
# Hardcoded credentials (anti-pattern)
grep -r "password.*=.*['\"]" --include="*.py" --include="*.js" --include="*.ts" | grep -v "test\|spec\|example"
grep -r "api_key.*=.*['\"]" --include="*.py" --include="*.js" --include="*.ts" | grep -v "test\|spec\|example"
grep -r "secret.*=.*['\"]" --include="*.py" --include="*.js" --include="*.ts" | grep -v "test\|spec\|example"
# Environment-specific config files (anti-pattern)
find . -name "config.dev.*" -o -name "config.prod.*" -o -name "settings.development.*" -o -name "settings.production.*"
# Database URLs in code
grep -r "postgresql://\|mysql://\|mongodb://\|redis://" --include="*.py" --include="*.js" --include="*.ts" | grep -v ".env\|test\|example"
File Patterns: **/.env*, **/config/*.py, **/settings.py, environment files
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | All config via environment variables, no hardcoded secrets, could open-source without leaks |
| Partial | Most config externalized but some hardcoded defaults |
| Weak | Hardcoded credentials, environment-specific config files |
Anti-patterns:
config/production.yml vs config/development.ymlif ENV == 'production': ...)Principle: Treat backing services as attached resources.
Search Patterns:
# Database connection via config
grep -r "DATABASE_URL\|DB_HOST\|REDIS_URL\|CACHE_URL" --include="*.py" --include="*.js" --include="*.ts"
# Service initialization
grep -r "create_engine\|MongoClient\|Redis\|Celery\|boto3" --include="*.py"
grep -r "createPool\|createClient\|new Redis\|S3Client" --include="*.js" --include="*.ts"
# Hardcoded service locations (anti-pattern)
grep -r "localhost:5432\|localhost:6379\|localhost:27017\|127.0.0.1" --include="*.py" --include="*.js" --include="*.ts" | grep -v "test\|spec\|example\|default"
File Patterns: **/database/*.py, **/services/*.py, **/db.py, connection configurations
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | All services via URL/connection string in config, swappable without code changes |
| Partial | Most services configurable but some hardcoded defaults |
| Weak | Hardcoded service locations, different code paths per environment |
Anti-patterns:
localhost for services in production codeif USE_S3: ... else: local_storage)Principle: Strictly separate build and run stages.
Search Patterns:
# Build/deploy configuration
find . -name "Dockerfile" -o -name "Makefile" -o -name "build.sh" -o -name "deploy.sh"
find . -name ".github/workflows/*.yml" -o -name ".gitlab-ci.yml" -o -name "Jenkinsfile"
# Build scripts in package.json
grep -A5 '"scripts"' package.json 2>/dev/null | grep -E "build|start|deploy"
# Check for runtime compilation (anti-pattern)
grep -r "compile\|transpile\|webpack" --include="*.py" | grep -v "test\|build"
File Patterns: **/Dockerfile, **/Makefile, **/.github/workflows/**, CI/CD configs
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Immutable releases, clear build/release/run stages, unique release IDs |
| Partial | Build and run separated but release not immutable |
| Weak | Runtime code modifications, asset compilation at startup |
Anti-patterns:
Principle: Execute the app as one or more stateless processes.
Search Patterns:
# Session storage patterns
grep -r "session\|Session" --include="*.py" --include="*.js" --include="*.ts" | head -20
# In-process state (anti-pattern)
grep -r "global.*cache\|process_local\|instance_cache" --include="*.py"
grep -r "global\..*=\|module\.exports\.cache" --include="*.js" --include="*.ts"
# External session stores (good pattern)
grep -r "redis.*session\|memcached.*session\|session.*redis" --include="*.py" --include="*.js" --include="*.ts"
# Sticky session configuration (anti-pattern)
grep -r "sticky.*session\|session.*affinity" --include="*.yml" --include="*.yaml" --include="*.json"
File Patterns: **/middleware/*.py, **/session/*.py, server configurations
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Stateless processes, all state in external datastores (Redis, DB) |
| Partial | Mostly stateless but some in-process caching |
| Weak | Sticky sessions, in-process session storage, shared memory state |
Anti-patterns:
user_sessions = {})Principle: Export services via port binding.
Search Patterns:
# Self-contained port binding
grep -r "app.run\|server.listen\|serve\|uvicorn" --include="*.py"
grep -r "app.listen\|server.listen\|createServer" --include="*.js" --include="*.ts"
# PORT environment variable
grep -r "PORT\|port" --include="*.py" --include="*.js" --include="*.ts" | grep -i "environ\|process.env"
# Webserver as dependency
grep -r "uvicorn\|gunicorn\|flask\|fastapi\|express\|koa\|hapi" package.json pyproject.toml requirements.txt 2>/dev/null
File Patterns: **/main.py, **/server.py, **/app.py, **/index.js
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Self-contained app binds to PORT, webserver is a dependency |
| Partial | Port binding but not configurable via environment |
| Weak | Relies on external webserver container (Apache, Nginx) to provide HTTP |
Anti-patterns:
Principle: Scale out via the process model.
Search Patterns:
# Process definitions
find . -name "Procfile" -o -name "process.yml" -o -name ".foreman"
# Multiple entry points
find . -name "worker.py" -o -name "scheduler.py" -o -name "web.py"
# Background job systems
grep -r "celery\|rq\|sidekiq\|bull\|agenda" --include="*.py" --include="*.js" --include="*.ts"
grep -r "Celery\|Worker\|BackgroundJob" --include="*.py" --include="*.js" --include="*.ts"
File Patterns: **/Procfile, **/worker.py, **/scheduler.py, queue configurations
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Explicit process types (web, worker, scheduler), horizontal scaling |
| Partial | Multiple process types but not easily scalable |
| Weak | Single monolithic process, no separation of concerns |
Anti-patterns:
Principle: Maximize robustness with fast startup and graceful shutdown.
Search Patterns:
# Signal handlers
grep -r "signal.signal\|SIGTERM\|SIGINT\|atexit" --include="*.py"
grep -r "process.on.*SIGTERM\|process.on.*SIGINT" --include="*.js" --include="*.ts"
# Graceful shutdown
grep -r "graceful.*shutdown\|shutdown_handler\|cleanup" --include="*.py" --include="*.js" --include="*.ts"
# Startup time
grep -r "startup\|initialize\|bootstrap" --include="*.py" --include="*.js" --include="*.ts" | head -20
File Patterns: **/main.py, **/server.py, lifecycle management code
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Fast startup (<10s), SIGTERM handling, graceful shutdown, jobs returnable to queue |
| Partial | Graceful shutdown but slow startup |
| Weak | No signal handling, jobs lost on process death, slow startup |
Anti-patterns:
Principle: Keep development, staging, and production as similar as possible.
Search Patterns:
# Different services per environment (anti-pattern)
grep -r "if.*development.*sqlite\|if.*production.*postgres" --include="*.py" --include="*.js" --include="*.ts"
grep -r "development.*SQLite\|production.*PostgreSQL" --include="*.py" --include="*.js" --include="*.ts"
# Docker for parity
find . -name "docker-compose*.yml" -o -name "Dockerfile"
# Environment-specific backends
grep -r "USE_LOCAL_\|LOCAL_STORAGE\|MOCK_" --include="*.py" --include="*.js" --include="*.ts"
File Patterns: **/docker-compose*.yml, environment configurations
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Same services everywhere (PostgreSQL in dev and prod), containerized |
| Partial | Mostly same but some lightweight dev alternatives |
| Weak | SQLite in dev, PostgreSQL in prod; different backing services |
Anti-patterns:
Principle: Treat logs as event streams.
Search Patterns:
# Stdout logging
grep -r "print(\|logging.info\|logger.info\|console.log" --include="*.py" --include="*.js" --include="*.ts" | head -20
# File-based logging (anti-pattern)
grep -r "FileHandler\|open.*\.log\|writeFile.*log\|fs.appendFile.*log" --include="*.py" --include="*.js" --include="*.ts"
grep -r "/var/log\|/tmp/.*\.log\|logs/" --include="*.py" --include="*.js" --include="*.ts" | grep -v "test\|example"
# Structured logging
grep -r "structlog\|json_logger\|pino\|winston" --include="*.py" --include="*.js" --include="*.ts"
File Patterns: **/logging.py, **/logger.py, logging configurations
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Unbuffered stdout only, structured logging (JSON), no file management |
| Partial | Stdout logging but with some file handlers |
| Weak | Application writes to log files, manages rotation |
Anti-patterns:
FileHandler, open('/var/log/app.log'))Principle: Run admin/management tasks as one-off processes.
Search Patterns:
# Management commands
find . -name "manage.py" -o -name "Rakefile" -o -name "artisan"
grep -r "@cli.command\|@click.command\|typer.command" --include="*.py"
# Migration scripts
find . -name "migrations" -type d
find . -name "*migration*.py" -o -name "*migrate*.py"
# Admin scripts with proper isolation
grep -r "bundle exec\|source.*venv\|uv run" --include="*.sh" --include="Makefile"
File Patterns: **/manage.py, **/cli.py, **/migrations/**, admin scripts
Compliance Criteria:
| Level | Criteria |
|---|---|
| Strong | Admin tasks use same dependencies/config, proper isolation, idempotent |
| Partial | Admin tasks exist but different setup from app |
| Weak | Manual database manipulation, scripts without isolation |
Anti-patterns:
| Factor | Status | Notes |
|--------|--------|-------|
| I. Codebase | **Strong/Partial/Weak** | [Key finding] |
| II. Dependencies | **Strong/Partial/Weak** | [Key finding] |
| III. Config | **Strong/Partial/Weak** | [Key finding] |
| IV. Backing Services | **Strong/Partial/Weak** | [Key finding] |
| V. Build/Release/Run | **Strong/Partial/Weak** | [Key finding] |
| VI. Processes | **Strong/Partial/Weak** | [Key finding] |
| VII. Port Binding | **Strong/Partial/Weak** | [Key finding] |
| VIII. Concurrency | **Strong/Partial/Weak** | [Key finding] |
| IX. Disposability | **Strong/Partial/Weak** | [Key finding] |
| X. Dev/Prod Parity | **Strong/Partial/Weak** | [Key finding] |
| XI. Logs | **Strong/Partial/Weak** | [Key finding] |
| XII. Admin Processes | **Strong/Partial/Weak** | [Key finding] |
**Overall**: X Strong, Y Partial, Z Weak
For each factor, provide:
Current Implementation
Compliance Level
Gaps
Recommendations
Initial Scan
Deep Dive (per factor)
Gap Analysis
Recommendations
Summary
| Score | Meaning | Action |
|---|---|---|
| Strong | Fully implements principle | Maintain, minor optimizations |
| Partial | Some implementation, significant gaps | Planned improvements |
| Weak | Minimal or no implementation | High priority for roadmap |
Use when working with Payload CMS projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.