|
| 1 | +# Set Up Basic AI Agent Configuration |
| 2 | + |
| 3 | +## Goal |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +## References |
| 8 | + |
| 9 | +- **AGENTS.md specification**: https://agents.md/ |
| 10 | +- **Agent Skills specification**: https://agentskills.io/specification |
| 11 | +- **GitHub Copilot — About agent skills**: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills |
| 12 | +- **GitHub Copilot — About custom agents**: https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents |
| 13 | + |
| 14 | +## Background |
| 15 | + |
| 16 | +### AGENTS.md |
| 17 | + |
| 18 | +`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`. |
| 19 | + |
| 20 | +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. |
| 21 | + |
| 22 | +### Agent Skills |
| 23 | + |
| 24 | +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. |
| 25 | + |
| 26 | +GitHub Copilot supports: |
| 27 | + |
| 28 | +- **Project skills** stored in the repository at `.github/skills/`, `.claude/skills/`, or `.agents/skills/` |
| 29 | +- **Personal skills** stored in the home directory at `~/.copilot/skills/`, `~/.claude/skills/`, or `~/.agents/skills/` |
| 30 | + |
| 31 | +### Custom Agents |
| 32 | + |
| 33 | +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: |
| 34 | + |
| 35 | +- **Repository level**: `.github/agents/CUSTOM-AGENT-NAME.md` |
| 36 | +- **Organization/enterprise level**: `/agents/CUSTOM-AGENT-NAME.md` inside a `.github-private` repository |
| 37 | + |
| 38 | +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. |
| 39 | + |
| 40 | +## Tasks |
| 41 | + |
| 42 | +### Task 0: Create a local branch |
| 43 | + |
| 44 | +- Approved branch name: `<issue-number>-ai-agent-configuration` |
| 45 | +- Commands: |
| 46 | + - `git fetch --all --prune` |
| 47 | + - `git checkout develop` |
| 48 | + - `git pull --ff-only` |
| 49 | + - `git checkout -b <issue-number>-ai-agent-configuration` |
| 50 | +- Checkpoint: `git branch --show-current` should output `<issue-number>-ai-agent-configuration`. |
| 51 | + |
| 52 | +--- |
| 53 | + |
| 54 | +### Task 1: Add `AGENTS.md` at the repository root |
| 55 | + |
| 56 | +Provide AI coding agents with a clear, predictable source of project context so they can work |
| 57 | +effectively without requiring repeated manual instructions. |
| 58 | + |
| 59 | +**Inspiration / reference AGENTS.md files from other Torrust projects**: |
| 60 | + |
| 61 | +- https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/AGENTS.md |
| 62 | +- https://raw.githubusercontent.com/torrust/torrust-linting/refs/heads/main/AGENTS.md |
| 63 | + |
| 64 | +Create `AGENTS.md` in the repository root, adapting the above files to the tracker. At minimum |
| 65 | +the file must cover: |
| 66 | + |
| 67 | +- [ ] Repository link and project overview (language, license, MSRV, web framework, protocols, databases) |
| 68 | +- [ ] Tech stack (languages, frameworks, databases, containerization, linting tools) |
| 69 | +- [ ] Key directories (`src/`, `src/bin/`, `packages/`, `console/`, `contrib/`, `tests/`, `docs/`, `share/`, `storage/`, `.github/workflows/`) |
| 70 | +- [ ] Package catalog (all workspace packages with their layer and description) |
| 71 | +- [ ] Package naming conventions (`axum-*`, `*-server`, `*-core`, `*-protocol`) |
| 72 | +- [ ] Key configuration files (`.markdownlint.json`, `.yamllint-ci.yml`, `.taplo.toml`, `cspell.json`, `rustfmt.toml`, etc.) |
| 73 | +- [ ] Build & test commands (`cargo build`, `cargo test --doc`, `cargo test --all-targets`, E2E runner, benchmarks) |
| 74 | +- [ ] Lint commands (`linter all` and individual linters; how to install the `linter` binary) |
| 75 | +- [ ] Dependencies check (`cargo machete`) |
| 76 | +- [ ] Code style (rustfmt rules, clippy policy, import grouping, per-format rules) |
| 77 | +- [ ] Collaboration principles (no flattery, push back on weak ideas, flag blockers early) |
| 78 | +- [ ] Essential rules (linting gate, GPG commit signing, no `storage/`/`target/` commits, `cargo machete`) |
| 79 | +- [ ] Git workflow (branch naming, Conventional Commits, branch strategy: `develop` → `staging/main` → `main`) |
| 80 | +- [ ] Development principles (observability, testability, modularity, extensibility; Beck's four rules) |
| 81 | +- [ ] Container / Docker (key commands, ports, volume mount paths) |
| 82 | +- [ ] Auto-invoke skills placeholder (to be filled in when `.github/skills/` is populated) |
| 83 | +- [ ] Documentation quick-navigation table |
| 84 | +- [ ] Add a brief entry to `docs/index.md` pointing contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/` |
| 85 | + |
| 86 | +Commit message: `docs(agents): add root AGENTS.md` |
| 87 | + |
| 88 | +Checkpoint: |
| 89 | + |
| 90 | +- `linter all` exits with code `0`. |
| 91 | +- At least one AI agent (GitHub Copilot, Cursor, etc.) can be confirmed to pick up the file. |
| 92 | + |
| 93 | +**References**: |
| 94 | + |
| 95 | +- https://agents.md/ |
| 96 | +- https://github.com/openai/codex/blob/-/AGENTS.md (real-world example) |
| 97 | +- https://github.com/apache/airflow/blob/-/AGENTS.md (real-world monorepo example) |
| 98 | + |
| 99 | +--- |
| 100 | + |
| 101 | +### Task 2: Add Agent Skills |
| 102 | + |
| 103 | +Define reusable, project-specific skills that agents can load to perform specialized tasks on |
| 104 | +this repository consistently. |
| 105 | + |
| 106 | +- [ ] Create `.github/skills/` directory |
| 107 | +- [ ] Review and confirm the candidate skills listed below (add, remove, or adjust before starting implementation) |
| 108 | +- [ ] For each skill, create a directory with: |
| 109 | + - `SKILL.md` — YAML frontmatter (`name`, `description`, optional `license`, `compatibility`) + step-by-step instructions |
| 110 | + - `scripts/` (optional) — executable scripts the agent can run |
| 111 | + - `references/` (optional) — additional reference documentation |
| 112 | +- [ ] Validate skill files against the Agent Skills spec (name rules: lowercase, hyphens, no consecutive hyphens, max 64 chars; description: max 1024 chars) |
| 113 | + |
| 114 | +**Candidate initial skills** (ported / adapted from `torrust-tracker-deployer`): |
| 115 | + |
| 116 | +The skills below are modelled on the skills already proven in |
| 117 | +[torrust-tracker-deployer](https://github.com/torrust/torrust-tracker-deployer) |
| 118 | +(`.github/skills/`). Deployer-specific skills (Ansible, Tera templates, LXD, SDK, |
| 119 | +deployer CLI architecture) are excluded because they have no equivalent in the tracker. |
| 120 | + |
| 121 | +Directory layout to mirror the deployer structure: |
| 122 | + |
| 123 | +```text |
| 124 | +.github/skills/ |
| 125 | + add-new-skill/ |
| 126 | + dev/ |
| 127 | + git-workflow/ |
| 128 | + maintenance/ |
| 129 | + planning/ |
| 130 | + rust-code-quality/ |
| 131 | + testing/ |
| 132 | +``` |
| 133 | + |
| 134 | +**`add-new-skill`** — meta-skill: guide for creating new Agent Skills for this repository. |
| 135 | + |
| 136 | +**`dev/git-workflow/`**: |
| 137 | + |
| 138 | +- `commit-changes` — commit following Conventional Commits; pre-commit verification checklist. |
| 139 | +- `create-feature-branch` — branch naming convention and lifecycle. |
| 140 | +- `open-pull-request` — open a PR via GitHub CLI or GitHub MCP tool; pre-flight checks. |
| 141 | +- `release-new-version` — version bump, signed release commit, signed tag, CI verification. |
| 142 | +- `review-pr` — review a PR against Torrust quality standards and checklist. |
| 143 | +- `run-linters` — run the full linting suite (`linter all`); fix individual linter failures. |
| 144 | +- `run-pre-commit-checks` — mandatory quality gates before every commit. |
| 145 | + |
| 146 | +**`dev/maintenance/`**: |
| 147 | + |
| 148 | +- `update-dependencies` — run `cargo update`, create branch, commit, push, open PR. |
| 149 | + |
| 150 | +**`dev/planning/`**: |
| 151 | + |
| 152 | +- `create-adr` — create an Architectural Decision Record in `docs/adrs/`. |
| 153 | +- `create-issue` — draft and open a GitHub issue following project conventions. |
| 154 | +- `write-markdown-docs` — GFM pitfalls (auto-links, ordered list numbering, etc.). |
| 155 | +- `cleanup-completed-issues` — remove issue doc files and update roadmap after PR merge. |
| 156 | + |
| 157 | +**`dev/rust-code-quality/`**: |
| 158 | + |
| 159 | +- `handle-errors-in-code` — `thiserror`-based structured errors; what/where/when/why context. |
| 160 | +- `handle-secrets` — wrapper types for tokens/passwords; never use plain `String` for secrets. |
| 161 | + |
| 162 | +**`dev/testing/`**: |
| 163 | + |
| 164 | +- `write-unit-test` — `it_should_*` naming, AAA pattern, `MockClock`, `TempDir`, `rstest`. |
| 165 | + |
| 166 | +Commit message: `docs(agents): add initial agent skills under .github/skills/` |
| 167 | + |
| 168 | +Checkpoint: |
| 169 | + |
| 170 | +- `linter all` exits with code `0`. |
| 171 | +- At least one skill can be successfully activated by GitHub Copilot. |
| 172 | + |
| 173 | +**References**: |
| 174 | + |
| 175 | +- https://agentskills.io/specification |
| 176 | +- https://docs.github.com/en/copilot/concepts/agents/about-agent-skills |
| 177 | +- https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills |
| 178 | +- https://github.com/anthropics/skills (community skills examples) |
| 179 | +- https://github.com/github/awesome-copilot (community collection) |
| 180 | + |
| 181 | +--- |
| 182 | + |
| 183 | +### Task 3: Add Custom Agents |
| 184 | + |
| 185 | +Define custom GitHub Copilot agents tailored to Torrust project workflows so that specialized |
| 186 | +tasks can be delegated to focused agents with the right prompt context. |
| 187 | + |
| 188 | +- [ ] Create `.github/agents/` directory |
| 189 | +- [ ] Identify workflows that benefit from a dedicated agent (e.g. issue implementation planner, code reviewer, documentation writer, release drafter) |
| 190 | +- [ ] For each agent, create `.github/agents/<agent-name>.md` with: |
| 191 | + - YAML frontmatter: `name` (optional), `description`, optional `tools` |
| 192 | + - Prompt body: role definition, scope, constraints, and step-by-step instructions |
| 193 | +- [ ] Test each custom agent by assigning it to a task or issue in GitHub Copilot CLI |
| 194 | + |
| 195 | +**Candidate initial agents**: |
| 196 | + |
| 197 | +- `committer` — commit specialist: reads branch/diff, runs pre-commit checks (`linter all`), |
| 198 | + proposes a GPG-signed Conventional Commit message, and creates the commit only after scope and |
| 199 | + checks are clear. Reference: |
| 200 | + [`torrust-tracker-demo/.github/agents/commiter.agent.md`](https://raw.githubusercontent.com/torrust/torrust-tracker-demo/refs/heads/main/.github/agents/commiter.agent.md) |
| 201 | +- `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 |
| 202 | +- `code-reviewer` — reviews PRs against Torrust coding conventions, clippy rules, and security considerations |
| 203 | +- `docs-writer` — creates or updates documentation files following the existing docs structure |
| 204 | + |
| 205 | +Commit message: `docs(agents): add initial custom agents under .github/agents/` |
| 206 | + |
| 207 | +Checkpoint: |
| 208 | + |
| 209 | +- `linter all` exits with code `0`. |
| 210 | +- At least one custom agent can be assigned to a task in GitHub Copilot CLI. |
| 211 | + |
| 212 | +**References**: |
| 213 | + |
| 214 | +- https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents |
| 215 | +- https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli |
| 216 | +- https://docs.github.com/en/copilot/reference/customization-cheat-sheet |
| 217 | + |
| 218 | +--- |
| 219 | + |
| 220 | +### Task 4 (optional / follow-up): Add nested `AGENTS.md` files in packages |
| 221 | + |
| 222 | +Once the root file is stable, evaluate whether any workspace packages have sufficiently different |
| 223 | +conventions or setup to warrant their own `AGENTS.md`. This can be tracked as a separate follow-up |
| 224 | +issue. |
| 225 | + |
| 226 | +--- |
| 227 | + |
| 228 | +### Task 5: Add `copilot-setup-steps.yml` workflow |
| 229 | + |
| 230 | +Create `.github/workflows/copilot-setup-steps.yml` so that the GitHub Copilot cloud agent gets a |
| 231 | +fully prepared development environment before it starts working on any task. Without this file, |
| 232 | +Copilot discovers and installs dependencies itself via trial-and-error, which is slow and |
| 233 | +unreliable. |
| 234 | + |
| 235 | +The workflow must contain a single `copilot-setup-steps` job (the exact job name is required by |
| 236 | +Copilot). Steps run in GitHub Actions before Copilot starts; the file is also automatically |
| 237 | +executed as a normal CI workflow whenever it changes, providing built-in validation. |
| 238 | + |
| 239 | +**Reference example** (from `torrust-tracker-deployer`): |
| 240 | +https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/.github/workflows/copilot-setup-steps.yml |
| 241 | + |
| 242 | +Minimum steps to include: |
| 243 | + |
| 244 | +- [ ] Trigger on `workflow_dispatch`, `push` and `pull_request` (scoped to the workflow file path) |
| 245 | +- [ ] `copilot-setup-steps` job on `ubuntu-latest`, `timeout-minutes: 30`, `permissions: contents: read` |
| 246 | +- [ ] `actions/checkout@v5` — check out the repository (verify this is still the latest stable |
| 247 | + version on the GitHub Marketplace before merging) |
| 248 | +- [ ] `dtolnay/rust-toolchain@stable` — install the stable Rust toolchain (pin MSRV if needed) |
| 249 | +- [ ] `Swatinem/rust-cache@v2` — cache `target/` and `~/.cargo` between runs |
| 250 | +- [ ] `cargo build` warm-up — build the workspace (or key packages) so incremental compilation is |
| 251 | + ready when Copilot starts editing |
| 252 | +- [ ] Install the `linter` binary — |
| 253 | + `cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter` |
| 254 | +- [ ] Install `cargo-machete` — `cargo install cargo-machete`; ensures Copilot can run unused |
| 255 | + dependency checks (`cargo machete`) as required by the essential rules |
| 256 | +- [ ] Smoke-check: run `linter all` to confirm the environment is healthy before Copilot begins |
| 257 | + |
| 258 | +Commit message: `ci(copilot): add copilot-setup-steps workflow` |
| 259 | + |
| 260 | +Checkpoint: |
| 261 | + |
| 262 | +- The workflow runs successfully via the repository's **Actions** tab (manual dispatch or push to |
| 263 | + the file). |
| 264 | +- `linter all` exits with code `0` inside the workflow. |
| 265 | + |
| 266 | +**References**: |
| 267 | + |
| 268 | +- https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment |
| 269 | +- https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/.github/workflows/copilot-setup-steps.yml |
| 270 | + |
| 271 | +--- |
| 272 | + |
| 273 | +### Task 6: Create an ADR for the AI agent framework approach |
| 274 | + |
| 275 | +> **Note**: This task documents the decision that underlies the whole issue. It can be done |
| 276 | +> before Tasks 1–5 if preferred — recording the decision first and then implementing it is |
| 277 | +> the conventional ADR practice. |
| 278 | +
|
| 279 | +Document the decision to build a custom, GitHub-Copilot-aligned agent framework (AGENTS.md + |
| 280 | +Agent Skills + Custom Agents) rather than adopting one of the existing pre-defined agent |
| 281 | +frameworks that were evaluated. |
| 282 | + |
| 283 | +**Frameworks evaluated and not adopted**: |
| 284 | + |
| 285 | +- [obra/superpowers](https://github.com/obra/superpowers) |
| 286 | +- [gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done) |
| 287 | + |
| 288 | +**Reasons for not adopting them**: |
| 289 | + |
| 290 | +1. Complexity mismatch — they introduce abstractions that are heavier than what tracker |
| 291 | + development needs. |
| 292 | +2. Precision requirements — the tracker involves low-level programming where agent work must be |
| 293 | + reviewed carefully; generic productivity frameworks are not designed around that constraint. |
| 294 | +3. GitHub-first ecosystem — the tracker is hosted on GitHub and makes intensive use of GitHub |
| 295 | + resources (Actions, Copilot, MCP tools, etc.). Staying aligned with GitHub Copilot avoids |
| 296 | + unnecessary integration friction. |
| 297 | +4. Tooling churn — the AI agent landscape is evolving rapidly; depending on a third-party |
| 298 | + framework risks forced refactoring when that framework is deprecated or pivots. A first-party |
| 299 | + approach is more stable. |
| 300 | +5. Tailored fit — a custom solution can be shaped precisely to Torrust conventions, commit style, |
| 301 | + linting gates, and package structure from day one. |
| 302 | +6. Proven in practice — the same approach has already been validated during the development of |
| 303 | + `torrust-tracker-deployer`. |
| 304 | +7. Agent-agnostic by design — keeping the framework expressed as plain Markdown files |
| 305 | + (AGENTS.md, SKILL.md, agent profiles) decouples it from any single agent product, making |
| 306 | + migration or multi-agent use straightforward. |
| 307 | +8. Incremental adoption — individual skills, custom agents, or patterns from those frameworks can |
| 308 | + still be cherry-picked and integrated progressively if specific value is identified. |
| 309 | + |
| 310 | +- [ ] Create `docs/adrs/<YYYYMMDDHHMMSS>_ai-agent-framework-approach.md` using the `create-adr` skill |
| 311 | +- [ ] Record the decision, the alternatives considered, and the reasoning above |
| 312 | + |
| 313 | +Commit message: `docs(adrs): add ADR for AI agent framework approach` |
| 314 | + |
| 315 | +Checkpoint: |
| 316 | + |
| 317 | +- `linter all` exits with code `0`. |
| 318 | + |
| 319 | +**References**: |
| 320 | + |
| 321 | +- `docs/adrs/README.md` — ADR naming convention for this repository |
| 322 | +- https://adr.github.io/ |
| 323 | + |
| 324 | +--- |
| 325 | + |
| 326 | +## Acceptance Criteria |
| 327 | + |
| 328 | +- [ ] `AGENTS.md` exists at the repo root and contains accurate, up-to-date project guidance. |
| 329 | +- [ ] At least one skill is available under `.github/skills/` and can be successfully activated by GitHub Copilot. |
| 330 | +- [ ] At least one custom agent is available under `.github/agents/` and can be assigned to a task. |
| 331 | +- [ ] `copilot-setup-steps.yml` exists, the workflow runs successfully in the **Actions** tab, and `linter all` exits with code `0` inside it. |
| 332 | +- [ ] An ADR exists in `docs/adrs/` documenting the decision to use a custom GitHub-Copilot-aligned agent framework. |
| 333 | +- [ ] All files pass spelling checks (`cspell`) and markdown linting. |
| 334 | +- [ ] A brief entry in `docs/index.md` points contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`. |
0 commit comments