torrust-tracker-deployer

Guide for releasing a new version of the deployer using the standard branch/tag workflow. Covers version bump, signed release commit, pushing main, creating signed tag, creating release branch, and verifying Docker + crate publication workflows. Use when asked to "release", "cut a version", "publish a new version", or "create release vX.Y.Z".

Run a complete local end-to-end test using the LXD provider to verify a feature, fix, or change works as expected from the user's perspective. Covers creating an environment config, provisioning a VM, deploying the tracker, verifying it works, and cleaning up. Use when manually testing changes, validating a new feature locally, running a full deployment smoke test, or checking that the deployer works end-to-end. Triggers on "local e2e", "manual e2e test", "test my changes locally", "run deployer end-to-end", "smoke test", "test on LXD", "verify feature works", or "full deployment test".

Check whether the system has all dependencies required by the deployer (OpenTofu, Ansible, LXD, cargo-machete). Use before running provisioning, E2E tests, or any infrastructure command. Triggers on "check dependencies", "check system dependencies", "are dependencies installed", "verify dependencies", "dependency check", or "missing tools".

Install the system dependencies required by the deployer (OpenTofu, Ansible, LXD, cargo-machete) using the built-in dependency-installer. This is the setup/installer step before using the deployer for the first time. Triggers on "install dependencies", "install system dependencies", "setup deployer", "first time setup", "missing dependency", "install opentofu", "install ansible", "install lxd", or "deployer setup".

Open a pull request from a feature branch using GitHub CLI (preferred) or GitHub MCP tools. Covers pre-flight checks, correct base/head configuration for fork workflows, title/body conventions, and post-creation validation. Use when asked to "open PR", "create pull request", or "submit branch for review".

Guide for updating project dependencies using the update-dependencies.sh automation script. Automates the cargo update workflow including branch creation, commit, push, and optional PR creation. Use when updating dependencies, running cargo update, or automating the dependency lifecycle. Triggers on "update dependencies", "cargo update", "update deps", "bump dependencies", or "run dependency update".

Guide for committing changes in the torrust-tracker-deployer project. Covers conventional commit format, pre-commit verification checks, issue number conventions, and commit quality guidelines. Use when committing code, running pre-commit checks, or following project commit standards. Triggers on "commit", "commit changes", "how to commit", "pre-commit", "commit message", "commit format", or "conventional commits".

Guide for debugging and troubleshooting local LXD VM instances created by the deployer. Covers SSH connectivity failures (too many authentication failures, key issues, connection refused), bypassing SSH with lxc exec, cloud-init problems, networking issues, and general LXD instance inspection. Use when a developer cannot access a deployed LXD VM, encounters SSH errors, or needs to inspect VM state without SSH. Triggers on "lxd troubleshoot", "ssh failed lxd", "can't ssh into vm", "lxd debug", "too many authentication failures", "lxc exec", "vm not reachable", "lxd instance problem", "debug lxd instance", or "lxd networking issue".

Run code quality checks and linters for the deployer project. Includes markdown, YAML, TOML, spell checking, Rust clippy, rustfmt, and shellcheck. Use when user needs to lint code, check formatting, fix code quality issues, or prepare for commit. Triggers on "lint", "run linters", "check code quality", "fix formatting", or "run pre-commit checks".

Guide for debugging and investigating deployer command failures. Covers reading error output, locating trace files, inspecting environment state, examining build artifacts, and running manual verification steps. Use when any deployer command (provision, configure, release, run, etc.) fails. Triggers on "command failed", "debug failure", "investigate error", "why did it fail", "trace", "deployer error", or "command error".

Guide for implementing new CLI commands in the deployer using outside-in development. Covers presentation layer scaffolding, application handler, confirmation prompts, E2E testing, and documentation. Use when adding new commands like validate, render, backup, or any console subcommand. Triggers on "add command", "new command", "implement command", "create subcommand", or "add CLI command".

Guide for error handling in this Rust project. Covers the four principles (clarity, context, actionability, explicit enums over anyhow), the thiserror pattern for structured errors, including what/where/when/why context, writing actionable help text, and avoiding vague errors. Use when writing error types, handling Results, adding error variants, or reviewing error messages. Triggers on "error handling", "error type", "Result", "thiserror", "anyhow", "error enum", "error message", "handle error", or "add error variant".

Guide for creating effective Agent Skills for the torrust-tracker-deployer project. Use when you need to create a new skill (or update an existing skill) that extends AI agent capabilities with specialized knowledge, workflows, or tool integrations. Triggers on "create skill", "add new skill", "how to add skill", or "skill creation".

Guide for producing user-facing output in this Rust project. NEVER use println!, eprintln!, print!, eprint!, or direct stdout/stderr access. Always use UserOutput via the execution context or ProgressReporter in controllers. Covers the sink-based output architecture, stdout vs stderr channel strategy, ProgressReporter for multi-step operations, verbosity control, and themes. Use when writing any user-visible output, progress messages, errors, or results. Triggers on "println", "print output", "user output", "UserOutput", "ProgressReporter", "display result", "output message", or "progress message".

Regenerate machine-readable CLI documentation JSON after modifying the CLI interface. Use when adding/removing commands, changing arguments, updating help text, or when CLI structure changes. Triggers on "regenerate CLI docs", "update CLI documentation", "generate CLI JSON", or "refresh commands.json".

Guide for creating feature branches following the torrust-tracker-deployer branching conventions. Covers branch naming format, lifecycle, and common patterns. Use when creating branches for issues, starting work on tasks, or setting up development branches. Triggers on "create branch", "new branch", "checkout branch", "branch for issue", or "start working on issue".

Review a pull request against the project's quality standards. Covers the full checklist from the PR review guide — branching, commits, code quality, testing, documentation, and template conventions — and how to provide constructive feedback. Use when reviewing a pull request, checking if a PR meets project standards, or providing feedback on changes. Triggers on "review PR", "review pull request", "check PR", "PR checklist", "code review", or "approve PR".

Run the mandatory pre-commit verification script before committing changes. Executes all quality gates including cargo machete, linters, tests, documentation builds, and E2E tests. Use when preparing to commit code, ensuring all quality checks pass, or verifying changes meet project standards. Triggers on "pre-commit", "run pre-commit", "pre-commit checks", "before commit", "verify before commit", "quality checks", or "commit verification".

Guide for adding Ansible playbooks to this project. Covers the atomic playbook rule (one playbook = one responsibility), the correct pattern for conditional enablement (in Rust commands/steps, NOT Ansible when: clauses), registering static playbooks in copy_static_templates(), the centralized variables.yml.tera pattern, and a checklist before adding. Use when creating new Ansible playbooks, adding Ansible tasks, or modifying the Ansible infrastructure. Triggers on "ansible playbook", "new playbook", "ansible task", "playbook", "add ansible", "copy_static_templates", or "infrastructure playbook".

Guide for adding new templates to this project. Covers the Project Generator pattern, the difference between dynamic templates (.tera, automatically discovered) and static templates (must be explicitly registered in copy_static_templates()), and the two-level indirection design (embedded binary → external extraction → build directory rendering). Use when adding infrastructure templates, Ansible playbooks, OpenTofu files, or configuration templates. Triggers on "add template", "new template", "static template", "register template", "copy_static_templates", "project generator", or "template system".

Guide for creating and naming environment variables in this project. All project environment variables must use the TORRUST_TD_ prefix. Covers the condition-based vs action-based naming decision framework, when to use each approach, and practical examples. Use when adding new environment variables, changing existing env var names, or deciding how to name a toggle or flag. Triggers on "environment variable", "env var", "TORRUST_TD_", "variable naming", "feature flag", "feature toggle", "configuration flag", or "add env var".

Developer reference for the environment configuration DTO architecture, Rust type system, validation logic, and JSON schema. Use when modifying config DTOs, adding new config sections, debugging validation errors in Rust code, or understanding the TryFrom conversion pattern. Triggers on "config DTO", "environment config types", "config validation logic", "TryFrom implementation", or "config architecture".

Fast workflow for verifying Tera template modifications using the render command without provisioning infrastructure. Use when modifying templates in templates/, testing template rendering, iterating on template development, or running E2E template verification. Triggers on "verify template", "test template changes", "template iteration", "render template", or "template development".

Guide for working with Tera template files (.tera extension) in this project. Covers correct variable syntax (double curly braces without spaces inside), avoiding Prettier IDE interference, the difference between dynamic .tera templates and static templates, and template file registration. Use when creating or editing .tera files, adding template variables, or troubleshooting template rendering. Triggers on "tera template", ".tera file", "template variable", "template syntax", "template rendering", "Tera", or "template file".

Guide for cleaning up completed and closed issues in the torrust-tracker-deployer project. Covers removing issue documentation files, updating the roadmap, and syncing the GitHub roadmap issue. Supports single issue cleanup or batch cleanup. Use when cleaning up closed issues, removing issue docs, updating roadmap after PR merge, or maintaining docs/issues/ folder. Triggers on "cleanup issue", "remove issue", "clean completed issues", "delete closed issue", "update roadmap after merge".

Guide for completing feature specifications in the torrust-tracker-deployer project. Covers moving entries from active to completed features, updating status, and preserving documentation. Use when finishing feature implementation, marking features as done, or updating the features index. Triggers on "complete feature", "finish feature", "feature done", "mark feature complete", or "feature completed".

Guide for completing and archiving refactoring plans in the torrust-tracker-deployer project. Covers moving entries from active to completed, updating documentation, and cleanup procedures. Use when finishing refactorings, archiving plans, or marking refactor work as done. Triggers on "complete refactor", "finish refactor plan", "archive refactor", "mark refactor done", or "refactor cleanup".

Guide for creating Architectural Decision Records (ADRs) in the torrust-tracker-deployer project. Covers the ADR template, file naming, index registration, and commit workflow. Use when documenting architectural decisions, recording design choices, or adding decision records. Triggers on "create ADR", "add ADR", "new decision record", "architectural decision", "document decision", or "add decision".

Guide for creating feature specifications in the torrust-tracker-deployer project. Covers folder structure, document templates, questions for stakeholders, and workflow for registering new features. Use when specifying new features, documenting feature requirements, or adding entries to the active features list. Triggers on "create feature spec", "new feature", "feature specification", "specify feature", or "feature document".

Guide for creating GitHub issues in the torrust-tracker-deployer project. Covers the full workflow from specification drafting, user review, to GitHub issue creation with proper documentation, linking, and file naming. Supports task, bug, feature, and epic issue types. Use when creating issues, opening tickets, filing bugs, proposing tasks, or adding features. Triggers on "create issue", "open issue", "new issue", "file bug", "add task", "create epic", or "open ticket".

Guide for creating refactoring plans in the torrust-tracker-deployer project. Covers plan structure, proposal organization by impact/effort, progress tracking, and workflow. Use when planning refactorings, documenting improvements, or organizing technical debt work. Triggers on "create refactor", "new refactor plan", "refactoring plan", "plan refactor", or "refactor document".

Guide for writing Markdown documentation in this project. Covers GitHub Flavored Markdown pitfalls, especially the critical

Guide for handling sensitive data (secrets) in this Rust project. NEVER use String for API tokens, passwords, private keys, or database credentials. Use ApiToken or Password wrapper types from src/shared/secrets/, and PlainApiToken/PlainPassword at DTO boundaries. Call .expose_secret() only when the actual value is needed. Prevents accidental exposure through Debug output and logs. Use when working with credentials, API keys, tokens, passwords, or any sensitive configuration. Triggers on "secret", "API token", "password", "credential", "sensitive data", "ApiToken", "secrecy", or "expose secret".

Guide for implementing domain types (value objects and entities) with invariants in this Rust project. Covers the "always valid" pattern with private fields and validated constructors, custom Deserialize implementations to prevent bypass, and expressive error types with actionable help text. Use when creating or modifying domain value objects, entities, or types with business rules. Triggers on "domain type", "value object", "entity", "invariant", "validated constructor", "domain entity", "DDD practices", "domain model", or "implement domain".

Guide for organizing Rust modules and imports in this project. Covers import ordering (std → external crates → internal crate), preferring short imported names over fully-qualified paths, top-down module organization (public items first, high-level abstractions before low-level details), and placing error types at the end. Use when creating new Rust files, organizing module contents, adding imports, or reviewing code structure. Triggers on "module organization", "import order", "use statement", "Rust imports", "organize module", "code structure", or "module structure".

Guide for placing code in the correct DDD (Domain-Driven Design) layer in this Rust project. Covers the four-layer architecture (Domain, Application, Infrastructure, Presentation), dependency rules, what belongs in each layer, red flags for wrong placement, and a decision flowchart. Use when writing new code, refactoring, or moving code between layers. Triggers on "DDD layer", "which layer", "where does this code go", "domain layer", "application layer", "infrastructure layer", "presentation layer", "place code", or "layer placement".

Guide for adding a runnable example to the Deployer SDK, covering file creation in packages/sdk/examples/, the [[example]] entry in Cargo.toml, public-API-only imports, the sdk_ naming prefix, and CI verification. Triggers on "add sdk example", "sdk example", "new sdk example", "demonstrate sdk usage", "sdk usage example", "add example to sdk", or "show sdk in action".

Guide for adding a new public method to the Deployer SDK facade, covering delegation in deployer.rs, the SdkError variant, re-exports in lib.rs, and a matching integration-test module. Triggers on "add sdk method", "new deployer method", "extend the sdk", "add method to deployer", "implement sdk operation", or "expose new operation in sdk".

Guide for writing SDK integration tests using the module-per-command structure in packages/sdk/tests/local_operations/, covering shared helpers, the it_should_* naming convention, test isolation, and module registration. Triggers on "sdk integration test", "write sdk test", "test sdk method", "add sdk test", "integration test for sdk", "test deployer method", or "sdk test module".

Emergency cleanup of orphaned LXD deployment environments when normal 'destroy' and 'purge' commands cannot be used. Use ONLY when environment data is missing or corrupted, or E2E tests left orphaned resources. This is NOT for normal cleanup - always try 'destroy' + 'purge' first. Triggers on "clean lxd", "cleanup orphaned lxd", "remove lxd vms", "emergency cleanup", "lxd cleanup", "stuck lxd resources", or "orphaned vms".