|
| 1 | +# Adopt a Custom, GitHub-Copilot-Aligned Agent Framework |
| 2 | + |
| 3 | +## Description |
| 4 | + |
| 5 | +As AI coding agents become a more common part of the development workflow, the project needs a |
| 6 | +clear strategy for how agents should interact with the codebase. Several third-party "agent |
| 7 | +frameworks" exist that promise to give agents structure and purpose, but they each come with |
| 8 | +trade-offs that may not fit the tracker's needs. |
| 9 | + |
| 10 | +This ADR records the decision to build a lightweight, first-party agent framework using the |
| 11 | +open standards that GitHub Copilot already supports natively: `AGENTS.md`, Agent Skills, and |
| 12 | +Custom Agent profiles. |
| 13 | + |
| 14 | +## Agreement |
| 15 | + |
| 16 | +We adopt a custom, GitHub-Copilot-aligned agent framework consisting of: |
| 17 | + |
| 18 | +- **`AGENTS.md`** at the repository root (and in key subdirectories) — following the |
| 19 | + [agents.md](https://agents.md/) open standard stewarded by the Agentic AI Foundation under the |
| 20 | + Linux Foundation. Provides AI coding agents with project context, build steps, test commands, |
| 21 | + conventions, and essential rules. |
| 22 | +- **Agent Skills** under `.github/skills/` — following the |
| 23 | + [Agent Skills specification](https://agentskills.io/specification). Each skill is a directory |
| 24 | + containing a `SKILL.md` file with YAML frontmatter and Markdown instructions, covering |
| 25 | + repeatable tasks such as committing changes, running linters, creating ADRs, or setting up the |
| 26 | + development environment. |
| 27 | +- **Custom Agent profiles** under `.github/agents/` — Markdown files with YAML frontmatter |
| 28 | + defining specialised Copilot agents (e.g. `committer`, `implementer`, `complexity-auditor`) |
| 29 | + that can be invoked directly or as subagents. |
| 30 | +- **`copilot-setup-steps.yml`** workflow — prepares the GitHub Copilot cloud agent environment |
| 31 | + before it starts working on any task. |
| 32 | + |
| 33 | +### Alternatives Considered |
| 34 | + |
| 35 | +**[obra/superpowers](https://github.com/obra/superpowers)** |
| 36 | + |
| 37 | +A framework that adds "superpowers" to coding agents through a set of conventions and tools. |
| 38 | +Not adopted for the following reasons: |
| 39 | + |
| 40 | +1. **Complexity mismatch** — introduces abstractions heavier than what tracker development needs. |
| 41 | +1. **Precision requirements** — the tracker involves low-level Rust programming where agent work |
| 42 | + must be reviewed carefully; generic productivity frameworks are not designed for that |
| 43 | + constraint. |
| 44 | +1. **Tooling churn risk** — depending on a third-party framework risks forced refactoring if |
| 45 | + that framework is deprecated or pivots. |
| 46 | + |
| 47 | +**[gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)** |
| 48 | + |
| 49 | +A productivity-oriented agent framework with opinionated workflows. |
| 50 | +Not adopted for the same reasons as above, plus: |
| 51 | + |
| 52 | +1. **GitHub-first ecosystem** — the tracker is hosted on GitHub and makes intensive use of |
| 53 | + GitHub resources (Actions, Copilot, MCP tools). Staying aligned with GitHub Copilot avoids |
| 54 | + unnecessary integration friction. |
| 55 | + |
| 56 | +### Why the Custom Approach |
| 57 | + |
| 58 | +1. **Tailored fit** — shaped precisely to Torrust conventions, commit style, linting gates, and |
| 59 | + package structure from day one. |
| 60 | +1. **Proven in practice** — the same approach has already been validated during the development |
| 61 | + of `torrust-tracker-deployer`. |
| 62 | +1. **Agent-agnostic by design** — expressed as plain Markdown files (`AGENTS.md`, `SKILL.md`, |
| 63 | + agent profiles), decoupled from any single agent product. Migration or multi-agent use is |
| 64 | + straightforward. |
| 65 | +1. **Incremental adoption** — individual skills, custom agents, or patterns from evaluated |
| 66 | + frameworks can still be cherry-picked and integrated progressively if specific value is |
| 67 | + identified. |
| 68 | +1. **Stability** — a first-party approach is more stable than depending on a third-party |
| 69 | + framework whose roadmap we do not control. |
| 70 | + |
| 71 | +## Date |
| 72 | + |
| 73 | +2026-04-20 |
| 74 | + |
| 75 | +## References |
| 76 | + |
| 77 | +- Issue: https://github.com/torrust/torrust-tracker/issues/1697 |
| 78 | +- PR: https://github.com/torrust/torrust-tracker/pull/1699 |
| 79 | +- AGENTS.md specification: https://agents.md/ |
| 80 | +- Agent Skills specification: https://agentskills.io/specification |
| 81 | +- GitHub Copilot — About agent skills: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills |
| 82 | +- GitHub Copilot — About custom agents: https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents |
| 83 | +- Customize the Copilot cloud agent environment: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment |
| 84 | +- obra/superpowers: https://github.com/obra/superpowers |
| 85 | +- gsd-build/get-shit-done: https://github.com/gsd-build/get-shit-done |
| 86 | +- torrust-tracker-deployer (validated reference implementation): https://github.com/torrust/torrust-tracker-deployer |
0 commit comments