autonomic-bot
f283a371bb
Sanitized single-commit public mirror of recipe-maintainer. - Removed test-ssh/.testenv (live creds); added test-ssh/.testenv.example placeholders. - Removed plans/ and planned-updates/ (deployment-planning docs) so no client/ deployment domains appear in the public repo. - All other secret stores were already gitignored. - docs.coopcloud.tech retained as a submodule (public upstream).
75 lines
4.7 KiB
Markdown
75 lines
4.7 KiB
Markdown
---
|
|
description: Explain what this project is and how to get started
|
|
allowed-tools: [Read, Glob]
|
|
---
|
|
|
|
Present this entire introduction to the user verbatim — do NOT summarize or condense it.
|
|
|
|
# Co-op Cloud Recipe Toolkit — Introduction
|
|
|
|
This repository is an AI-assisted toolkit for maintaining [Co-op Cloud](https://coopcloud.tech) recipes. It runs inside a container with `~/.abra` bind-mounted, providing an isolated environment where the `abra` CLI operates normally without access to the host's SSH keys or abra configuration. The only credentials available are the test SSH keys in `test-ssh/`, limiting all deployment operations to the designated test server.
|
|
|
|
## What it does
|
|
|
|
The toolkit wraps `abra` and other tools into slash-command skills that automate the full recipe maintenance lifecycle: checking for upstream upgrades, planning and applying updates, deploying to a test server, running tests, managing backups, reviewing recipes against best practices, and tagging releases.
|
|
|
|
## Repository structure
|
|
|
|
- **`.claude/commands/`** — Skill definitions (slash commands). This is where all the automation lives.
|
|
- **`recipe-info/`** — Per-recipe data organized by recipe name: upstream release note URLs, test instance environment files, and test scripts.
|
|
- **`planned-updates/`** — Upgrade reports and summaries generated by `/recipe-upgrade-plan` and `/recipe-upgrade-apply`.
|
|
- **`plans/`** — Project planning documents.
|
|
- **`test-ssh/`** — SSH config and keys for the test server where recipe instances are deployed.
|
|
- **`settings.toml`** — Defines which test server instances are available and which is the current default.
|
|
- **`maintained-recipes.md`** — List of recipes this toolkit actively maintains. Used by `/recipe-overview` and `/recipe-test-all`.
|
|
- **`learnings.md`** — Hard-won lessons and `abra` CLI quirks discovered during operation.
|
|
- **`docs.coopcloud.tech/`** — Local copy of the Co-op Cloud documentation; used as reference for recipe structure, deployment patterns, and platform conventions.
|
|
- **`lib/`** — Python helper library used by test scripts and automation (SSH, abra wrappers, secrets management).
|
|
- **`.opencode/`** — OpenCode stubs that point back to `.claude/commands/` so skills work in both Claude Code and OpenCode.
|
|
|
|
## Available skills
|
|
|
|
### Recipe lifecycle
|
|
- **`/recipe-overview`** — Check all maintained recipes, see what needs upgrading
|
|
- **`/recipe-check <name>`** — Check a single recipe for available upstream upgrades
|
|
- **`/recipe-upgrade-plan <name>`** — Research release notes and create a detailed upgrade plan
|
|
- **`/recipe-upgrade-apply <name>`** — Apply the plan: update images, deploy, test, commit, and tag
|
|
- **`/recipe-init <name>`** — Bootstrap a new recipe from scratch (fetch, create test instance, deploy)
|
|
- **`/recipe-new-tag <name>`** — Bump the version and create an annotated git tag
|
|
- **`/recipe-review <name>`** — Audit a recipe against Co-op Cloud best practices
|
|
|
|
### Deploying and testing
|
|
- **`/recipe-deploy <name>`** — Deploy local recipe checkout to the test server (chaos mode)
|
|
- **`/recipe-test <name>`** — Run all tests for a recipe
|
|
- **`/recipe-test-new <name>`** — Test a fresh install from scratch
|
|
- **`/recipe-test-update <name>`** — Test upgrading an existing deployment
|
|
- **`/recipe-test-backup <name>`** — Test the backup/restore cycle
|
|
- **`/recipe-test-all`** — Run tests for every maintained recipe
|
|
|
|
### Infrastructure and utilities
|
|
- **`/init-instance`** — Deploy all maintained recipes to the test server
|
|
- **`/test-context-reset`** — Undeploy all apps except traefik
|
|
- **`/switch-default-instance`** — Switch between test servers
|
|
- **`/sync-secrets`** — Sync secrets from the test server locally
|
|
- **`/opencode-sync`** — Sync Claude skills to OpenCode format
|
|
|
|
## Recommended workflow
|
|
|
|
1. **Daily check-in:** `/recipe-overview` to see what needs attention
|
|
2. **Upgrade a recipe:** `/recipe-check` → `/recipe-upgrade-plan` → review the plan → `/recipe-upgrade-apply`
|
|
3. **Day-to-day development:** edit a recipe locally → `/recipe-deploy` → `/recipe-test`
|
|
4. **Push when satisfied:** `cd ~/.abra/recipes/<name> && git push && git push --tags`
|
|
|
|
### Working with a recipe not yet in recipe-info?
|
|
|
|
Run `/recipe-init <recipe>` to set up tests for that recipe and a deployment to your local test instance.
|
|
|
|
### Developing a new recipe that doesn't exist yet?
|
|
|
|
Run `/new-recipe-guide` for detailed instructions on developing a new recipe from scratch.
|
|
|
|
## Next steps
|
|
|
|
- Run **`/test-setup`** to verify your environment is configured correctly (settings, SSH, abra CLI, connectivity).
|
|
- Run **`/setup-sandbox`** for guidance on setting up a sandboxed Docker environment to run Claude Code with this project — see also `sandbox/` for a reference implementation.
|