recipe-maintainer/.claude/commands/recipe-review.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Review a recipe for Co-op Cloud best practices	<recipe-name>	Bash Read Write Glob Grep WebFetch WebSearch

Recipe Review

Review a Co-op Cloud recipe against best practices and suggest improvements. This performs a thorough audit of the recipe's configuration, security, and operational readiness.

The recipe name is: $ARGUMENTS

Read and follow the instructions in .claude/commands/includes/logging.md. Read and follow the instructions in .claude/commands/includes/guidelines.md.

Steps

1. Fetch the recipe — check for uncommitted local changes first (see guidelines). If clean, run abra recipe fetch $ARGUMENTS --force. If there are local changes, skip the fetch and note that you're using the local checkout. The recipe lives at ~/.abra/recipes/$ARGUMENTS/.

2. Read all recipe files — read every file in the recipe directory:

   • compose.yml (and any compose.*.yml overlay files)
   • .env.sample
   • abra.sh
   • README.md
   • Any config templates (.tmpl, .conf, .ini, .js, etc.)
   • Any entrypoint scripts (entrypoint*.sh)
   • release/ directory contents (if present)
   • MAINTENANCE.md (if present)

3. Run the linter (if available):

   abra recipe lint $ARGUMENTS
   

   Note any warnings or errors.

4. Check the recipe against each best practice area below. For each area, note whether the recipe follows the practice, partially follows it, or is missing it entirely. Suggest specific fixes where applicable.

Checklist

Compose structure

• Uses compose version 3.8
• Services use named volumes (not bind mounts)
• No ports: definitions — routing is handled by Traefik labels
• No env_file: directives — environment is managed by abra
• Internal services (databases, caches) are on an internal network, not proxy
• The main web-facing service is on both proxy (external) and an internal network

Version label

• The app service has a coop-cloud.${STACK_NAME}.version deploy label
• The version follows the X.Y.Z+upstream_version format

Traefik labels

• traefik.enable=true on the web-facing service
• traefik.http.routers.${STACK_NAME}.rule=Host(...) is set
• traefik.http.routers.${STACK_NAME}.tls=true or .tls.certresolver is set
• traefik.http.routers.${STACK_NAME}.entrypoints=web-secure is set
• Traefik network is specified: traefik.docker.network=proxy

Deploy configuration

• restart_policy is configured (ideally with max_attempts to prevent infinite restarts)
• update_config with failure_action: rollback and order: start-first (recommended)
• rollback_config with order: start-first (recommended)

Healthchecks

• At least one service has a healthcheck defined
• Database/cache services have appropriate healthchecks (e.g. redis-cli ping, pg_isready)
• If healthchecks are absent, note this as an improvement area

Backups

Consult the README of the backup-bot-two recipe (~/.abra/recipes/backup-bot-two/README.md) for details on how to configure backup labels in Co-op Cloud recipes. Fetch it first if needed (abra recipe fetch backup-bot-two).

• backupbot.backup=true label is present on each service that has volumes to back up (can be on multiple services)
• By default all volumes on a labelled service are backed up — only use backupbot.backup.volumes.<name>.path or backupbot.backup.volumes.<name>: false when you need to limit or exclude specific volumes
• For database services: backupbot.backup.pre-hook dumps the database, backupbot.restore.post-hook restores it
• If backups are not configured, suggest adding backupbot.backup labels based on the backup-bot-two README

Secrets

• Sensitive values (passwords, API keys, tokens) use Docker secrets, not plain-text env vars
• Secret names are < 12 characters (to avoid the 64-char Docker limit after stack name + version are appended)
• .env.sample has SECRET_*_VERSION=v1 entries for each secret
• abra.sh has secret generation hints (length, charset) if applicable

Environment variables

• .env.sample exists with all required variables
• Optional env vars are commented out in .env.sample
• Domain templating uses <recipe>.example.com pattern (auto-replaced by abra app new)
• New/optional env vars in compose.yml use defaults: ${MY_VAR:-default_value}
• STACK_NAME is exposed in environment: for any service that needs it in config templates

Config management

• If the recipe uses Docker configs, versions are exported in abra.sh
• Config naming is consistent through the chain: configs stanza name, name: interpolation, and abra.sh export
• Config templates use template_driver: golang when Go template interpolation is needed
• Secrets in templates accessed via {{ secret "name" }}, env vars via {{ env "NAME" }}

README metadata

• README has the <!-- metadata --> ... <!-- endmetadata --> section
• All fields are present: Category, Status, Image, Healthcheck, Backups, Email, Tests, SSO
• Scores are accurate and reflect the current state of the recipe
• At least one named maintainer is listed (required for "stable" status)

Optional features

• SMTP/email support via compose.smtp.yml (if the app can send email)
• SSO/OIDC support via compose.oidc.yml (if the app supports it)
• Release notes in release/ directory for each version

Resource limits

• Consider whether deploy.resources.limits should be set (memory/CPU) to prevent OOM issues on shared servers

5. Summarise the review with three sections:

   What's good — things the recipe already does well.

   Recommended fixes — issues that should be addressed (missing backup config, missing healthchecks, security concerns, incorrect labels, etc.). For each, provide the specific change needed (ideally a code snippet showing what to add/change in compose.yml or other files).

   Nice-to-haves — optional improvements that would raise the recipe's quality/status score (SMTP support, SSO, better deploy config, resource limits, etc.).

   Update the README metadata scores if they don't reflect reality (e.g. if backups are configured but README says "No").