secret

name	secret
description	Generate Swarm secret/config management — external secret references, versioned rotation, config mounts.
user-invocable	true
argument-hint	<secret-name> [--external] [--rotate] [--config]

/secret — Generate Swarm Secret/Config Management

Input examples

/secret db-password --external
/secret db-password --rotate         (versioned rotation: db-password → db-password_v2)
/secret nginx-conf --config          (non-sensitive → docker config, not docker secret)

Process

1. Decide secret vs config: sensitive value (password, token, key) → docker secret; non-sensitive file (nginx.conf, feature-flag JSON) → docker config. Both mount as files, neither belongs in an env var's literal value.
2. Reference it in the stack file as external: true — the agent never writes the actual secret value into a generated file.
3. For --rotate: generate a versioned secret name ({name}_v{n}) plus the service-level change needed to point at it, and note that the old version stays available until every service referencing it has been updated (Swarm secrets are immutable and can't be edited in place).
4. L1 approval → Write/Edit (the stack file reference only — never the secret's contents).

Mandatory rules

• Never write a real secret value into any file the agent generates — only docker secret create commands (for the user to run) or external: true references.
• Rotation is always additive (new versioned name), never an in-place overwrite.
• App code must read /run/secrets/<name> (the file), not an env var containing the raw value — flag it if the target codebase currently expects an env var.

Output

Reference block added to docker-stack.yml (secrets:/configs: sections, external: true)
docker-secret-create.sh   (reference command showing how to create it out-of-band, not executed by the agent)

References

• @.claude/rules/swarm-conventions.md