recipe-maintainer/AGENTS.md

Getting Started

At the start of each session, before doing any work:

1. Read README.md to understand this project's purpose, structure, skills, and test environment setup.
2. Read the docs.coopcloud.tech/ folder to understand how Co-op Cloud and abra work, including recipe structure, deployment patterns, configuration conventions, and best practices.

This background context is essential for all recipe-related tasks.

3. Read learnings.md for abra CLI best practices — it contains critical information about TTY requirements, --chaos flag usage, and other operational patterns that will save you from common pitfalls. In particular:

   • Many abra commands (e.g. abra app cmd, abra app backup create, abra app logs) require a TTY wrapper: script -qefc "abra ..." /dev/null
   • Always use --chaos during local recipe development to prevent abra from changing your working tree
   • Prefer docker service logs via SSH over abra app logs in non-interactive environments

4. Read these key skill files so you understand operational patterns used across all tasks:

   • .claude/commands/test-context-reset.md — how context reset works, including the in-use lock file mechanism (in-use/<recipe>.lock): these files protect recipes from being undeployed during active work. Always create one when starting work on a recipe, remove it when done.
   • .claude/commands/recipe-deploy.md — the standard deploy flow (chaos mode, force, no-input)
   • .claude/commands/recipe-test.md — how recipe tests are run
   • .claude/commands/init-instance.md — how the test instance is initialised from scratch

Always pull the latest recipe before answering questions about it

Before answering any question about a specific recipe (config, env vars, compose overlays, secrets, etc.), git fetch and check origin/main in the recipe's checkout. The local copy can be days or weeks behind, and recipes change — new compose.*.yml overlays, new secrets, env-var renames, and entrypoint changes land regularly. Answering from a stale tree produces confidently-wrong advice.

cd /workspace/.container-abra/recipes/<recipe>
git fetch
git log --oneline HEAD..origin/main   # show what you're missing

If origin/main is ahead, either pull or git show/git diff the new commits before answering.

Recipe semver vs. image versions

Co-op Cloud recipe versions are independent of the upstream app/image version, and follow semver for the recipe — not the app. The recipe version label (the coop-cloud.${STACK_NAME}.version tag in compose.yml, e.g. 0.3.4+v5.2.0) has two parts: <recipe-semver>+<app-version>.

When you bump an image tag (the +<app-version> part), you must also bump the recipe semver (the part before +). The size of that bump is determined by what the operator has to do, not by how big the app's own version jump is:

• Patch (0.3.4 → 0.3.5) — the usual case. The image version increased but no operator action is required: deploying the new version "just works" (no new/renamed env vars, no new secrets, no manual migration, no breaking config changes).
• Minor (0.3.4 → 0.4.0) — new optional functionality or new env vars/secrets that have safe defaults; the operator may want to act but isn't forced to.
• Major (0.3.4 → 1.0.0) — operator action is required: breaking changes, mandatory new secrets/env vars, manual data migrations, or anything that breaks an existing deployment if applied blindly.

Default to a patch bump for routine image-version upgrades. Only go minor/major when the upgrade genuinely demands operator awareness or action.

Git commits

• Author every commit as notplants <@notplants> (use --author="notplants <@notplants>").
• Do not add Co-Authored-By trailers to commit messages — no Claude/AI co-author lines.

Tailscale + SSH (userspace mode)

Some test servers require Tailscale for SSH access. To connect from this containerized environment:

1. Start tailscaled in userspace mode (no root, no TUN device needed):

   tailscaled --state=/tmp/tailscale-state --tun=userspace-networking \
     --socks5-server=localhost:1055 --socket=/tmp/tailscale-run/tailscaled.sock &>/tmp/tailscaled.log &
   

2. Authenticate using an auth key from test-ssh/.testenv:

   source test-ssh/.testenv
   tailscale --socket=/tmp/tailscale-run/tailscaled.sock up \
     --authkey=$TS_AUTH_KEY --hostname=claude-recipe-maintainer
   

3. SSH via the SOCKS5 proxy — set ALL_PROXY before any SSH command:

   export ALL_PROXY=socks5://localhost:1055
   ssh -o StrictHostKeyChecking=no server.example.com "echo connected"
   

4. The SSH config in test-ssh/ssh-config should use HostName with the Tailscale IP (100.x.x.x) for servers that require Tailscale. Auth keys are stored in test-ssh/.testenv (not committed).

OpenCode

If you are running in OpenCode, read OPENCODE.md for details on how skills and commands are configured.