Improve agent commands/skills

.claude/commands/implement-container-deployment.md

@@ -8,25 +8,52 @@ INSTALL_INSTRUCTIONS_FILE: $ARGUMENTS
 
 Deploy a container-based service by creating and configuring a Docker Compose file.
 Use the application details and deployment instructions from the file: INSTALL_INSTRUCTIONS_FILE
-Follow closely the architectural patterns described in the `docker/guidelines.md` file.
+This file is the PRP produced by `/plan-container-deployment`. Follow closely the architectural
+patterns described in the `docker/guidelines.md` file.
 
-### Part 1 - Create Docker Compose file
+### Part 1 - Create the Docker Compose file
 
-- Read the `docker/guidelines.md` file for the architectural patterns you must follow.
-- Read the INSTALL_INSTRUCTIONS_FILE file and use its content to create the compose file in the required structure. Abort if the file is not specified or does not exist.
+- Read the `docker/guidelines.md` file for the architectural patterns you must follow. In particular note the **"Template for New Services"** section — use it as the starting skeleton.
+- Read the INSTALL_INSTRUCTIONS_FILE and use its content to create the compose file. **Abort if the file is not specified or does not exist.**
+- From the PRP, note the metadata you will need later: `Application name`, `Category`, `Homepage`, `GitHub page`, `Dashboard Icon`, `Dashboard Group`, `Short description`, `Long description`. These are consumed by the header comment and the labels below — do not discard them.
 - If the installation instructions contain steps to fetch the Compose setup and/or environment variables from a git repository:
-  - Shallow clone that repository to /tmp/infra/container/<application>/ and look at the referenced compose and .env files there.
-  - Use the compose and .env files without any changes.
-  - If there are additional configuration files, which are referenced in the compose file, copy them.
+  - Shallow clone that repository to `/tmp/infra/container/<application>/` and look at the referenced compose and `.env` files there.
+  - Use the compose and `.env` files without any changes.
+  - If there are additional configuration files referenced in the compose file, copy them.
   - Keep the cloned repository.
 - For each container image used in the deployment, get the most specific tag (e.g. tag "1.2.0" is more specific than "1.2") by using the `get-most-specific-container-tag` MCP tool. Use the tag(s) returned by the tool in the Compose stack.
-- Based on these patterns and the found examples on the installation instructions page, create the Docker Compose file and save it as `docker/<category>/<application>/<application>.yaml`.
-- Ensure the compose file contains a brief description of the project and links to the homepage, GitHub page, and any Docker or Docker Compose setup example (if available).
-- If the installation guide suggests enhancements (e.g., using an optional external database instead of a built-in one, or enabling SSO), add TODOs at the top of the compose file.
-- If any new environment variables are required for configuration, add them to the `config-example/docker/myhost/.env` file with placeholder values only (do not commit secrets).
-
-### Part 2 - Finishing steps
-
-- After writing the compose file, run `pre-commit run --files <docker-compose-filename>` and resolve any reported issues.
-- Validate the compose file with `scripts/labctl.py service config <category>/<application>` and fix any errors or warnings.
-- Pull the container image(s) with the command `scripts/labctl.py service pull <category>/<application> --quiet` (with 15 minutes timeout) and verify success.
+- Save the Docker Compose file as `docker/<category>/<application>/<application>.yaml`, where `<category>` is the `Category` from the PRP.
+- **Header comment.** Start the file with the comment block from the guidelines template: the `Long description`, then a `Links:` list (Homepage, GitHub/Source, Docs, and any Docker/Compose setup example), then a `TODO:` line.
+- **Networking.** Connect the service to the shared external `proxy` network by default. For sensitive services (password managers, backup, VPN, anything holding secrets), use an isolated network instead, per the "Isolated Networks" section of the guidelines — and add a `TODO` reminding the user that Traefik must be joined to that new network (in `docker/security/traefik/traefik.yaml`).
+- **Traefik labels.** If the service has a web UI, expose it via Traefik labels (`traefik.enable`, the router `Host(...)` rule, the loadbalancer server port, and the access middleware). Choose the access middleware explicitly and state your choice in the summary:
+  - `localaccess@file` — local network only (default)
+  - `localaccess-sso@file` — local network + Authelia authentication
+  - `publicaccess@file` — reachable externally with CrowdSec protection
+- **Homepage dashboard labels.** Add the dashboard labels using the PRP metadata: `homepage.group` = `Dashboard Group`, `homepage.name` = `Application name`, `homepage.icon` = `Dashboard Icon`, `homepage.href` = the service URL, `homepage.description` = `Short description`.
+- If the installation guide suggests enhancements (e.g. using an optional external database instead of a built-in one, or enabling SSO), add them as `TODO` lines in the header comment.
+- **Environment variables.** Reuse the existing common variables (`TIMEZONE`, `PUID`, `PGID`, `MYDOMAIN`, `DOCKER_VOLUMES`) — they are already defined, do not redefine them. For any *new* variable the service needs, add it with a **placeholder value only (never a real secret)** to the correct `.env` example file, following the precedence in the guidelines:
+  - Common, non-secret, same for every host → `config-example/docker/.env`
+  - Host-specific values or secrets/API keys → `config-example/docker/myhost/.env` (the usual case for a new service)
+
+#### AMD GPU acceleration (only if the PRP says the app supports it)
+
+If the PRP's research indicates the application supports AMD GPU acceleration (VAAPI for video decode/transcode, or ROCm for compute/inference), create a **separate compose override file** for it following the **"GPU Acceleration Overrides"** section of `docker/guidelines.md` — do not put GPU config in the base compose file. Name it `docker/<category>/<application>/<application>-amdgpu.yaml`, include only the changed fields, and make its header comment record any manual in-app steps the PRP identified.
+
+### Part 2 - Register the service
+
+A compose file alone is **not** deployable — the service must be registered so `labctl.py` / `task docker:apply` discovers it.
+
+- Add the service to `config-example/docker/myhost/services.yaml`. The file's `services:` key holds a list of single-key category blocks (e.g. `- ai:`, `- tools:`, `- media/video:`); find the block matching its `<category>` and append the entry to that block's list. Create a new `- <category>:` block only if one does not already exist. Use:
+  ```yaml
+  - name: <application>
+    state: up
+  ```
+- Keep the entries within a category grouped together and consistent with the existing formatting.
+
+### Part 3 - Finishing steps
+
+- Run `pre-commit run --files <docker-compose-filename>` and resolve any reported issues.
+- Validate the compose file with `scripts/labctl.py service config <category>/<application>` and fix any errors or warnings (this confirms env-var interpolation resolves).
+- Pull the container image(s) with `scripts/labctl.py service pull <category>/<application> --quiet` (with a 15 minute timeout) and verify success.
+- **If any of these steps still fails after a couple of fix attempts, stop and report the exact error to the user** rather than guessing further or leaving the repo half-changed.
+- Finish with a short summary: the file path created, the category/dashboard group used, the access middleware chosen, any new env vars added (and to which file), and any `TODO`s left for the user (e.g. joining Traefik to a new isolated network).

.claude/commands/improve-github-workflows.md

@@ -4,10 +4,19 @@ description: Analyze GitHub Actions workflows and recommend improvements for spe
 
 Analyze the GitHub Actions workflows in this repository and provide recommendations for improving pipeline execution speed and efficiency.
 
-**IMPORTANT: Token Management**
-- Use small batch sizes for all GitHub API calls to avoid exceeding token limits
-- Be selective: analyze the most important workflows in detail, others only at a high level
-- Get targeted data: use specific API calls for individual runs rather than listing many runs
+**This command only analyzes and reports — do not edit any workflow files.** Show before/after code in the report; leave applying changes to the user.
+
+**Preflight (do this first, abort if it fails):**
+This command uses the GitHub CLI (`gh`) for all run data. Verify it is available and authenticated:
+```bash
+gh --version   # must exist on PATH
+gh auth status # must report a logged-in account with repo/actions access
+```
+If `gh` is not installed or `gh auth status` fails, **stop and tell the user**: report exactly what failed and how to fix it (install `gh`, or run `gh auth login`). Do not attempt `gh auth login` yourself and do not fall back to unauthenticated API calls — without run data this command cannot do its job.
+
+`gh` infers the repository from the git remote; add `-R <owner>/<repo>` only if the wrong repo is picked up.
+
+**Token management:** request only the JSON fields you need (`--json ...`), limit runs to a handful (`--limit 5`), and use `--log-failed` rather than pulling full logs.
 
 Follow these steps:
 
@@ -16,19 +25,20 @@ Follow these steps:
    - Read each workflow file to understand the structure
    - If there are more than 5 workflows, prioritize the most critical ones (CI, deployments) for detailed analysis
 
-2. **Analyze recent workflow executions**:
-   - Use `mcp__github__list_workflows` to get workflow IDs
-   - For each workflow, use `mcp__github__list_workflow_runs` to get recent runs (use parameter: perPage=3)
-   - Focus on the most frequently run workflows first
-   - Use `mcp__github__get_workflow_run` to get details for 1-2 representative runs per workflow
-   - Use `mcp__github__list_workflow_jobs` to examine job execution (use parameter: perPage=10)
-   - Use `mcp__github__get_job_logs` with `failed_only: true` to identify common failure patterns
-   - Analyze execution times, bottlenecks, and patterns across runs
+2. **Analyze recent workflow executions** (via `gh`):
+   - List workflows: `gh workflow list`
+   - For each workflow, get recent runs (timing + status):
+     `gh run list --workflow <workflow-file-or-name> --limit 5 --json databaseId,status,conclusion,createdAt,updatedAt,event`
+   - Focus on the most frequently run workflows first.
+   - For 1-2 representative runs, get per-job/step timings:
+     `gh run view <run-id> --json jobs` (each job has `startedAt`/`completedAt` and a `steps` array with the same)
+   - For failing runs, inspect only the failed logs: `gh run view <run-id> --log-failed`
+   - Compute execution times from the `startedAt`/`completedAt` timestamps; look for bottlenecks and patterns across runs.
 
 3. **Examine workflow configuration**:
    - Job dependencies and sequencing
    - Matrix strategies
-   - Caching configuration (actions/cache, Docker layer caching, etc.)
+   - Caching configuration (actions/cache, Docker layer caching, etc.) — note what caching **already exists** so you don't recommend adding caching a job already has
    - Concurrency settings
    - Conditional execution
    - Runner types (ubuntu-latest, self-hosted, etc.)

.claude/commands/plan-container-deployment.md

@@ -2,13 +2,18 @@
 
 ## Variables
 
-APPLICATION_NAME: $ARGUMENTS
-INSTALL_INSTRUCTIONS_URL: $ARGUMENTS
+$ARGUMENTS contains both of the following; split it as described:
+- INSTALL_INSTRUCTIONS_URL: the token that looks like a URL (starts with `http`).
+- APPLICATION_NAME: the remaining text. If only a URL was given, derive the name from the URL / the page's title once fetched.
+
+If `$ARGUMENTS` is empty or no URL can be identified, ask the user for the application name and the installation-instructions URL before continuing.
 
 ## Instructions
 
 Your task is to collect all necessary know-how for deploying a containerized application using Docker Compose.
 
+**First, check the application is not already deployed:** use the `get-container-categories` MCP tool and/or run `find docker -iname '*<application>*'`. If a matching service already exists, stop and tell the user rather than producing a duplicate PRP.
+
 ### Part 1 - Look for installation details
 
 Visit the installation instructions page for APPLICATION_NAME at INSTALL_INSTRUCTIONS_URL and search for Docker Compose deployment examples in this priority order:
@@ -18,6 +23,7 @@ Visit the installation instructions page for APPLICATION_NAME at INSTALL_INSTRUC
 3. Plain docker setup (`docker run ...`)
 
 Gather all information relevant to container deployment.
+Also research whether the application supports **AMD GPU acceleration** — e.g. VAAPI for video decode/transcode or ROCm for compute/inference. Note the type of acceleration, whether the vendor ships a GPU-specific image tag, and any manual in-app configuration it requires. Record findings only; do not design the compose files here (that is done in the implementation step).
 ABORT your work if no container-based installation method is found.
 
 ### Part 2 - Gather application metadata
@@ -48,7 +54,7 @@ Long description: <Describe the application in 1–3 sentences. Optimally use th
 
 ## Container deployment
 
-<Put ALL information relevant for container-based deployment: Compose-based example (when found - or at least a docker run command), description of the environment variables, security considerations, possible further improvements. Organize information into sub-sections>
+<Put ALL information relevant for container-based deployment: Compose-based example (when found - or at least a docker run command), description of the environment variables, security considerations, AMD GPU acceleration support (type, GPU-specific image tag, manual in-app steps - or state "none"), possible further improvements. Organize information into sub-sections>
 
 ```