docs(issues): add issue spec for #1697 (AI agent configuration)

Author: josecelano

docs/issues/1697-ai-agent-configuration.md

@@ -0,0 +1,334 @@
+# Set Up Basic AI Agent Configuration
+
+## Goal
+
+Set up the foundational configuration files in this repository to enable effective collaboration with AI coding agents. This includes adding an `AGENTS.md` file to guide agents on project conventions, adding agent skills for repeatable specialized tasks, and defining custom agents for project-specific workflows.
+
+## References
+
+- **AGENTS.md specification**: https://agents.md/
+- **Agent Skills specification**: https://agentskills.io/specification
+- **GitHub Copilot — About agent skills**: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+- **GitHub Copilot — About custom agents**: https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents
+
+## Background
+
+### AGENTS.md
+
+`AGENTS.md` is an open, plain-Markdown format stewarded by the [Agentic AI Foundation](https://aaif.io/) under the Linux Foundation. It acts as a "README for agents": a single, predictable file where coding agents look first for project-specific context (build steps, test commands, conventions, security considerations) that would otherwise clutter the human-focused `README.md`.
+
+It is supported by a wide ecosystem of tools including GitHub Copilot (VS Code), Cursor, Windsurf, OpenAI Codex, Claude Code, Jules (Google), Warp, and many others. In monorepos, nested `AGENTS.md` files can be placed inside each package; the closest file to the file being edited takes precedence.
+
+### Agent Skills
+
+Agent Skills (https://agentskills.io/specification) are directories of instructions, scripts, and resources that an agent can load to perform specialized, repeatable tasks. Each skill lives in a folder named after the skill and contains at minimum a `SKILL.md` file with YAML frontmatter (`name`, `description`, optional `license`, `compatibility`, `metadata`, `allowed-tools`) followed by Markdown instructions.
+
+GitHub Copilot supports:
+
+- **Project skills** stored in the repository at `.github/skills/`, `.claude/skills/`, or `.agents/skills/`
+- **Personal skills** stored in the home directory at `~/.copilot/skills/`, `~/.claude/skills/`, or `~/.agents/skills/`
+
+### Custom Agents
+
+Custom agents are specialized versions of GitHub Copilot that can be tailored to project-specific workflows. They are defined as Markdown files with YAML frontmatter (agent profiles) stored at:
+
+- **Repository level**: `.github/agents/CUSTOM-AGENT-NAME.md`
+- **Organization/enterprise level**: `/agents/CUSTOM-AGENT-NAME.md` inside a `.github-private` repository
+
+An agent profile includes a `name`, `description`, optional `tools`, and optional `mcp-servers` configurations. The Markdown body of the file acts as the agent's prompt (it is not a YAML frontmatter key). The main Copilot agent can run custom agents as subagents in isolated context windows, including in parallel.
+
+## Tasks
+
+### Task 0: Create a local branch
+
+- Approved branch name: `<issue-number>-ai-agent-configuration`
+- Commands:
+  - `git fetch --all --prune`
+  - `git checkout develop`
+  - `git pull --ff-only`
+  - `git checkout -b <issue-number>-ai-agent-configuration`
+- Checkpoint: `git branch --show-current` should output `<issue-number>-ai-agent-configuration`.
+
+---
+
+### Task 1: Add `AGENTS.md` at the repository root
+
+Provide AI coding agents with a clear, predictable source of project context so they can work
+effectively without requiring repeated manual instructions.
+
+**Inspiration / reference AGENTS.md files from other Torrust projects**:
+
+- https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/AGENTS.md
+- https://raw.githubusercontent.com/torrust/torrust-linting/refs/heads/main/AGENTS.md
+
+Create `AGENTS.md` in the repository root, adapting the above files to the tracker. At minimum
+the file must cover:
+
+- [ ] Repository link and project overview (language, license, MSRV, web framework, protocols, databases)
+- [ ] Tech stack (languages, frameworks, databases, containerization, linting tools)
+- [ ] Key directories (`src/`, `src/bin/`, `packages/`, `console/`, `contrib/`, `tests/`, `docs/`, `share/`, `storage/`, `.github/workflows/`)
+- [ ] Package catalog (all workspace packages with their layer and description)
+- [ ] Package naming conventions (`axum-*`, `*-server`, `*-core`, `*-protocol`)
+- [ ] Key configuration files (`.markdownlint.json`, `.yamllint-ci.yml`, `.taplo.toml`, `cspell.json`, `rustfmt.toml`, etc.)
+- [ ] Build & test commands (`cargo build`, `cargo test --doc`, `cargo test --all-targets`, E2E runner, benchmarks)
+- [ ] Lint commands (`linter all` and individual linters; how to install the `linter` binary)
+- [ ] Dependencies check (`cargo machete`)
+- [ ] Code style (rustfmt rules, clippy policy, import grouping, per-format rules)
+- [ ] Collaboration principles (no flattery, push back on weak ideas, flag blockers early)
+- [ ] Essential rules (linting gate, GPG commit signing, no `storage/`/`target/` commits, `cargo machete`)
+- [ ] Git workflow (branch naming, Conventional Commits, branch strategy: `develop` → `staging/main` → `main`)
+- [ ] Development principles (observability, testability, modularity, extensibility; Beck's four rules)
+- [ ] Container / Docker (key commands, ports, volume mount paths)
+- [ ] Auto-invoke skills placeholder (to be filled in when `.github/skills/` is populated)
+- [ ] Documentation quick-navigation table
+- [ ] Add a brief entry to `docs/index.md` pointing contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`
+
+Commit message: `docs(agents): add root AGENTS.md`
+
+Checkpoint:
+
+- `linter all` exits with code `0`.
+- At least one AI agent (GitHub Copilot, Cursor, etc.) can be confirmed to pick up the file.
+
+**References**:
+
+- https://agents.md/
+- https://github.com/openai/codex/blob/-/AGENTS.md (real-world example)
+- https://github.com/apache/airflow/blob/-/AGENTS.md (real-world monorepo example)
+
+---
+
+### Task 2: Add Agent Skills
+
+Define reusable, project-specific skills that agents can load to perform specialized tasks on
+this repository consistently.
+
+- [ ] Create `.github/skills/` directory
+- [ ] Review and confirm the candidate skills listed below (add, remove, or adjust before starting implementation)
+- [ ] For each skill, create a directory with:
+  - `SKILL.md` — YAML frontmatter (`name`, `description`, optional `license`, `compatibility`) + step-by-step instructions
+  - `scripts/` (optional) — executable scripts the agent can run
+  - `references/` (optional) — additional reference documentation
+- [ ] Validate skill files against the Agent Skills spec (name rules: lowercase, hyphens, no consecutive hyphens, max 64 chars; description: max 1024 chars)
+
+**Candidate initial skills** (ported / adapted from `torrust-tracker-deployer`):
+
+The skills below are modelled on the skills already proven in
+[torrust-tracker-deployer](https://github.com/torrust/torrust-tracker-deployer)
+(`.github/skills/`). Deployer-specific skills (Ansible, Tera templates, LXD, SDK,
+deployer CLI architecture) are excluded because they have no equivalent in the tracker.
+
+Directory layout to mirror the deployer structure:
+
+```text
+.github/skills/
+  add-new-skill/
+  dev/
+    git-workflow/
+    maintenance/
+    planning/
+    rust-code-quality/
+    testing/
+```
+
+**`add-new-skill`** — meta-skill: guide for creating new Agent Skills for this repository.
+
+**`dev/git-workflow/`**:
+
+- `commit-changes` — commit following Conventional Commits; pre-commit verification checklist.
+- `create-feature-branch` — branch naming convention and lifecycle.
+- `open-pull-request` — open a PR via GitHub CLI or GitHub MCP tool; pre-flight checks.
+- `release-new-version` — version bump, signed release commit, signed tag, CI verification.
+- `review-pr` — review a PR against Torrust quality standards and checklist.
+- `run-linters` — run the full linting suite (`linter all`); fix individual linter failures.
+- `run-pre-commit-checks` — mandatory quality gates before every commit.
+
+**`dev/maintenance/`**:
+
+- `update-dependencies` — run `cargo update`, create branch, commit, push, open PR.
+
+**`dev/planning/`**:
+
+- `create-adr` — create an Architectural Decision Record in `docs/adrs/`.
+- `create-issue` — draft and open a GitHub issue following project conventions.
+- `write-markdown-docs` — GFM pitfalls (auto-links, ordered list numbering, etc.).
+- `cleanup-completed-issues` — remove issue doc files and update roadmap after PR merge.
+
+**`dev/rust-code-quality/`**:
+
+- `handle-errors-in-code` — `thiserror`-based structured errors; what/where/when/why context.
+- `handle-secrets` — wrapper types for tokens/passwords; never use plain `String` for secrets.
+
+**`dev/testing/`**:
+
+- `write-unit-test` — `it_should_*` naming, AAA pattern, `MockClock`, `TempDir`, `rstest`.
+
+Commit message: `docs(agents): add initial agent skills under .github/skills/`
+
+Checkpoint:
+
+- `linter all` exits with code `0`.
+- At least one skill can be successfully activated by GitHub Copilot.
+
+**References**:
+
+- https://agentskills.io/specification
+- https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+- https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills
+- https://github.com/anthropics/skills (community skills examples)
+- https://github.com/github/awesome-copilot (community collection)
+
+---
+
+### Task 3: Add Custom Agents
+
+Define custom GitHub Copilot agents tailored to Torrust project workflows so that specialized
+tasks can be delegated to focused agents with the right prompt context.
+
+- [ ] Create `.github/agents/` directory
+- [ ] Identify workflows that benefit from a dedicated agent (e.g. issue implementation planner, code reviewer, documentation writer, release drafter)
+- [ ] For each agent, create `.github/agents/<agent-name>.md` with:
+  - YAML frontmatter: `name` (optional), `description`, optional `tools`
+  - Prompt body: role definition, scope, constraints, and step-by-step instructions
+- [ ] Test each custom agent by assigning it to a task or issue in GitHub Copilot CLI
+
+**Candidate initial agents**:
+
+- `committer` — commit specialist: reads branch/diff, runs pre-commit checks (`linter all`),
+  proposes a GPG-signed Conventional Commit message, and creates the commit only after scope and
+  checks are clear. Reference:
+  [`torrust-tracker-demo/.github/agents/commiter.agent.md`](https://raw.githubusercontent.com/torrust/torrust-tracker-demo/refs/heads/main/.github/agents/commiter.agent.md)
+- `issue-planner` — given a GitHub issue, produces a detailed implementation plan document (like the ones in `docs/issues/`) including branch name, task breakdown, checkpoints, and commit message suggestions
+- `code-reviewer` — reviews PRs against Torrust coding conventions, clippy rules, and security considerations
+- `docs-writer` — creates or updates documentation files following the existing docs structure
+
+Commit message: `docs(agents): add initial custom agents under .github/agents/`
+
+Checkpoint:
+
+- `linter all` exits with code `0`.
+- At least one custom agent can be assigned to a task in GitHub Copilot CLI.
+
+**References**:
+
+- https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents
+- https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
+- https://docs.github.com/en/copilot/reference/customization-cheat-sheet
+
+---
+
+### Task 4 (optional / follow-up): Add nested `AGENTS.md` files in packages
+
+Once the root file is stable, evaluate whether any workspace packages have sufficiently different
+conventions or setup to warrant their own `AGENTS.md`. This can be tracked as a separate follow-up
+issue.
+
+---
+
+### Task 5: Add `copilot-setup-steps.yml` workflow
+
+Create `.github/workflows/copilot-setup-steps.yml` so that the GitHub Copilot cloud agent gets a
+fully prepared development environment before it starts working on any task. Without this file,
+Copilot discovers and installs dependencies itself via trial-and-error, which is slow and
+unreliable.
+
+The workflow must contain a single `copilot-setup-steps` job (the exact job name is required by
+Copilot). Steps run in GitHub Actions before Copilot starts; the file is also automatically
+executed as a normal CI workflow whenever it changes, providing built-in validation.
+
+**Reference example** (from `torrust-tracker-deployer`):
+https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/.github/workflows/copilot-setup-steps.yml
+
+Minimum steps to include:
+
+- [ ] Trigger on `workflow_dispatch`, `push` and `pull_request` (scoped to the workflow file path)
+- [ ] `copilot-setup-steps` job on `ubuntu-latest`, `timeout-minutes: 30`, `permissions: contents: read`
+- [ ] `actions/checkout@v5` — check out the repository (verify this is still the latest stable
+      version on the GitHub Marketplace before merging)
+- [ ] `dtolnay/rust-toolchain@stable` — install the stable Rust toolchain (pin MSRV if needed)
+- [ ] `Swatinem/rust-cache@v2` — cache `target/` and `~/.cargo` between runs
+- [ ] `cargo build` warm-up — build the workspace (or key packages) so incremental compilation is
+      ready when Copilot starts editing
+- [ ] Install the `linter` binary —
+      `cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter`
+- [ ] Install `cargo-machete` — `cargo install cargo-machete`; ensures Copilot can run unused
+      dependency checks (`cargo machete`) as required by the essential rules
+- [ ] Smoke-check: run `linter all` to confirm the environment is healthy before Copilot begins
+
+Commit message: `ci(copilot): add copilot-setup-steps workflow`
+
+Checkpoint:
+
+- The workflow runs successfully via the repository's **Actions** tab (manual dispatch or push to
+  the file).
+- `linter all` exits with code `0` inside the workflow.
+
+**References**:
+
+- https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment
+- https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/.github/workflows/copilot-setup-steps.yml
+
+---
+
+### Task 6: Create an ADR for the AI agent framework approach
+
+> **Note**: This task documents the decision that underlies the whole issue. It can be done
+> before Tasks 1–5 if preferred — recording the decision first and then implementing it is
+> the conventional ADR practice.
+
+Document the decision to build a custom, GitHub-Copilot-aligned agent framework (AGENTS.md +
+Agent Skills + Custom Agents) rather than adopting one of the existing pre-defined agent
+frameworks that were evaluated.
+
+**Frameworks evaluated and not adopted**:
+
+- [obra/superpowers](https://github.com/obra/superpowers)
+- [gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)
+
+**Reasons for not adopting them**:
+
+1. Complexity mismatch — they introduce abstractions that are heavier than what tracker
+   development needs.
+2. Precision requirements — the tracker involves low-level programming where agent work must be
+   reviewed carefully; generic productivity frameworks are not designed around that constraint.
+3. GitHub-first ecosystem — the tracker is hosted on GitHub and makes intensive use of GitHub
+   resources (Actions, Copilot, MCP tools, etc.). Staying aligned with GitHub Copilot avoids
+   unnecessary integration friction.
+4. Tooling churn — the AI agent landscape is evolving rapidly; depending on a third-party
+   framework risks forced refactoring when that framework is deprecated or pivots. A first-party
+   approach is more stable.
+5. Tailored fit — a custom solution can be shaped precisely to Torrust conventions, commit style,
+   linting gates, and package structure from day one.
+6. Proven in practice — the same approach has already been validated during the development of
+   `torrust-tracker-deployer`.
+7. Agent-agnostic by design — keeping the framework expressed as plain Markdown files
+   (AGENTS.md, SKILL.md, agent profiles) decouples it from any single agent product, making
+   migration or multi-agent use straightforward.
+8. Incremental adoption — individual skills, custom agents, or patterns from those frameworks can
+   still be cherry-picked and integrated progressively if specific value is identified.
+
+- [ ] Create `docs/adrs/<YYYYMMDDHHMMSS>_ai-agent-framework-approach.md` using the `create-adr` skill
+- [ ] Record the decision, the alternatives considered, and the reasoning above
+
+Commit message: `docs(adrs): add ADR for AI agent framework approach`
+
+Checkpoint:
+
+- `linter all` exits with code `0`.
+
+**References**:
+
+- `docs/adrs/README.md` — ADR naming convention for this repository
+- https://adr.github.io/
+
+---
+
+## Acceptance Criteria
+
+- [ ] `AGENTS.md` exists at the repo root and contains accurate, up-to-date project guidance.
+- [ ] At least one skill is available under `.github/skills/` and can be successfully activated by GitHub Copilot.
+- [ ] At least one custom agent is available under `.github/agents/` and can be assigned to a task.
+- [ ] `copilot-setup-steps.yml` exists, the workflow runs successfully in the **Actions** tab, and `linter all` exits with code `0` inside it.
+- [ ] An ADR exists in `docs/adrs/` documenting the decision to use a custom GitHub-Copilot-aligned agent framework.
+- [ ] All files pass spelling checks (`cspell`) and markdown linting.
+- [ ] A brief entry in `docs/index.md` points contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`.

project-words.txt

@@ -36,6 +36,7 @@ clippy
 cloneable
 codecov
 codegen
+commiter
 completei
 Condvar
 connectionless
@@ -117,6 +118,7 @@ nonroot
 Norberg
 numwant
 nvCFlJCq7fz7Qx6KoKTDiMZvns8l5Kw7
+obra
 oneshot
 ostr
 Pando
@@ -166,6 +168,7 @@ tdyne
 Tebibytes
 tempfile
 testcontainers
+Tera
 thiserror
 tlsv
 Torrentstorm
@@ -250,3 +253,9 @@ mysqladmin
 setgroups
 taplo
 trixie
+adrs
+Agentic
+agentskills
+frontmatter
+MSRV
+rustup