Populate best practices from claude-foundations

Migrates 20 topic files from claude-foundations/best-practices/ to this
standalone repo. Adds BESTPRACTICES.md index, CLAUDE.md conventions, and
updated README.md. Container agents clone this repo to /best-practices.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

git-source-control.md

@@ -0,0 +1,61 @@
+# Git & Source Control
+
+## Commit Practices
+
+- Use meaningful commit messages; prefer small, focused commits over large batches
+- Never commit secrets in plaintext — use SOPS + age or equivalent encryption
+- Enable pre-commit hooks where appropriate (secret detection, linting, formatting)
+
+## Pre-Commit Hooks
+
+- Block `local_secrets/` and similar directories from being committed
+- Auto-encrypt files matching `.sops.yaml` rules that aren't yet encrypted
+- Enable with `git config core.hooksPath .githooks`
+- Consider secret detection, linting, and formatting hooks
+
+## GitOps Workflow
+
+- All infrastructure changes should be tracked in Git
+- No manual changes without corresponding GitOps manifests — anything applied manually (e.g., `kubectl apply`, `helm install`) should immediately get a corresponding tracked manifest
+- For ArgoCD-managed clusters: edit in Git, push, sync — never edit live resources directly
+
+## Remote Conventions
+
+- SSH workflows preferred over HTTPS for Git remotes
+- Use SSH config host aliases for multi-user setups (e.g., `gitea.example.com-<user>`)
+- Remote URL format: `git@<host-alias>:<org>/<repo>.git`
+- Optionally push-mirror to GitHub for public visibility
+
+## Access and Clone Gotchas
+
+- **Org repos require explicit collaborator grants.** Don't assume organizational membership implies write access — verify permissions before setting up automation or CI/CD.
+- **Shallow clones break push operations.** `git clone --depth 1` is fine for read-only CI jobs, but pipelines that push artifacts, tags, or mirror to other remotes need full clones.
+
+## Version Management
+
+- Use the latest stable version of dependencies unless pinned for a reason
+- Verify versions from live sources (`helm search repo`, upstream docs, package registries) — don't rely on memory
+- Document the reason in a comment if a version is intentionally pinned below latest
+- Check compatibility matrices before upgrading (e.g., Talos ↔ Kubernetes, framework ↔ runtime)
+
+## Placeholder Conventions in Template-Heavy Repos
+
+When files contain multiple templating syntaxes (Go templates `{{ .var }}`, CI variables `${{ }}`, Helm `{{ }}`, etc.), use a distinct placeholder convention for your own substitutions that can't be confused with any templating language:
+
+- **Double-underscore:** `__CUSTOMER_NAME__`, `__DOMAIN__`
+- **All-caps curly brace (no spaces):** `{{CUSTOMER_NAME}}` (distinct from Go's `{{ .Title }}` with spaces and dots)
+
+Choose one convention per repo and document it.
+
+## Git Worktrees for Parallel Agent Work
+
+When running parallel agents or tasks that modify the same repo:
+- Give each task its own branch and worktree (`git worktree add .worktrees/<task-id> -b <branch>`)
+- Tasks with no dependencies branch from HEAD; tasks with one dependency branch from that dependency's branch
+- Tasks with multiple dependencies get an octopus merge base branch
+- Worktrees share the `.git` object store — fast creation, minimal disk usage
+- Keep containers detached (`docker run -d`, not `--rm`) so logs survive for inspection after exit
+
+## API-Created Repos Need SSH User as Collaborator
+
+If a repo is created via API token (user A) but pushes use an SSH alias authenticating as user B, user B has no access by default. Add the SSH-authenticating user as admin collaborator via API before the first push. This applies to Gitea, GitHub, and any platform where API auth and SSH auth use different identities.