AGENTS.md

1# AGENTS.md
2 
3This document describes how changes should be approached in Matomo, what quality bar is expected, and how agents should route work to Matomo-specific skills when those skills are available.
4 
5It is intended for:
6 
7- AI coding agents
8- Matomo core engineers
9- Reviewers looking for a shared baseline
10 
11This is not a generic PHP guide. It captures Matomo-specific priorities, trade-offs, and review instincts.
12 
13## Matomo Agent Skills
14 
15Detailed operational rules for Matomo agent work live in the `matomo-agent-skills` repository:
16 
17- SSH: `git@github.com:matomo-org/matomo-agent-skills.git`
18- HTTPS: `https://github.com/matomo-org/matomo-agent-skills`
19 
20`AGENTS.md` can instruct capable agents to use those skills, but it cannot install or enable external skills by itself. Agents with skill support should install the Matomo skills from that repository and use the relevant skill before planning, editing, reviewing, or validating work. Agents without skill support should still follow the high-level rules in this file and consult the project documentation listed below.
21 
22At the start of Matomo work, agents with skill support should check which Matomo skills are installed. If one or more relevant skills are missing, warn the user before continuing and offer to install or update the missing skills from `matomo-agent-skills`. If the user declines or installation is not possible, continue with the high-level rules in this file and explicitly note which skill guidance could not be applied.
23 
24Use the most specific applicable skill:
25 
26| Work type | Skill |
27| --- | --- |
28| PHPStan, PHPCS, PHPCBF, PHP style/static analysis | `matomo-code-quality` |
29| Running PHP, UI, or Vue/Jest tests | `matomo-test-runner` |
30| Branch, PR, or git-range review | `matomo-review` |
31| In-development debt or maintainability review | `matomo-debt-check` |
32| Security-sensitive changes: access control, CSRF, SQL, request parsing, tokens, secrets | `matomo-security-rules` |
33| Public API methods or request-facing contracts in `plugins/*/API.php` | `matomo-api-development-rules` |
34| Plugin structure, layering, event registration, cross-plugin boundaries | `matomo-plugin-architecture` |
35| Vue source, Vue build workflow, Vue template sinks | `matomo-vue-development-rules` |
36| Twig templates, escaping, raw output, template nonce patterns | `matomo-twig-development-rules` |
37| Translation keys, placeholders, translation files | `matomo-i18n-development-rules` |
38| Core or plugin update migrations | `matomo-migrations-workflow` |
39| Deprecations and compatibility transitions | `matomo-deprecation-rules` |
40| PHPDoc, public API docs, posted event docs | `matomo-documentation` |
41| Auditing screenshot-based UI tests | `matomo-ui-screenshot-audit` |
42| Applying an approved screenshot UI-test audit | `matomo-ui-screenshot-patch` |
43 
44When more than one skill applies, use the narrow layer-specific skill for implementation details and the cross-cutting skill for broader policy. For example, use `matomo-twig-development-rules` for a concrete Twig `|raw` change and `matomo-security-rules` for the trust-boundary implications.
45 
46## Repo Entrypoints
47 
48- PHPCS ruleset: `phpcs.xml`
49- PHPStan config and baseline: `phpstan.neon`, `phpstan-baseline.neon`
50- PHPUnit config: `tests/PHPUnit/phpunit.xml.dist`
51- Test layout: `tests/PHPUnit/Unit`, `tests/PHPUnit/Integration`, `tests/PHPUnit/System`, `tests/UI`, `tests/javascript`
52- Stylelint config: `.stylelintrc.json`
53- Dev/test docs: `CONTRIBUTING.md`, `tests/README.md`, `tests/README.screenshots.md`, `tests/client/README.md`, `.ddev/README.md`
54 
55## How Changes Should Be Approached
56 
57Be pragmatic, not dogmatic.
58 
59- Prefer simple, local changes over architectural purity.
60- Respect existing patterns in the area you are modifying.
61- Avoid drive-by refactors unless the change genuinely requires them.
62- If you touch code, you own its quality, including tests and relevant checks.
63- Assume your change will run on very large Matomo instances.
64 
65## Quality And Validation
66 
67- Run the relevant local checks for files you touch.
68- Use the existing project configuration and baselines; do not lower the bar or add new ignores casually.
69- PHPCS and PHPStan findings in touched code should be fixed properly.
70- New features require tests.
71- Behavior changes should include regression coverage where reasonable.
72- No tests requires an explicit explanation.
73- Choose the lightest test that proves the behavior.
74 
75For exact Matomo command selection, use `matomo-code-quality` and `matomo-test-runner`.
76 
77## Compatibility And Public Surface
78 
79Matomo has a large plugin ecosystem. Assume the following are public and relied upon unless clearly marked otherwise:
80 
81- Public PHP APIs
82- Public methods, even if not marked `@internal`
83- Database schemas, especially log tables
84- HTTP and JavaScript tracker APIs
85- Posted events and their parameter contracts
86 
87Do not silently break plugin-facing behavior. Compatibility transitions, removals, renames, dependency updates, and public API documentation should be routed through the relevant skills.
88 
89## Performance, Security, And Privacy
90 
91High-risk areas require extra care:
92 
93- Tracking must remain fast and predictable. Avoid additional database queries, remote calls, heavy parsing, or per-request complexity growth.
94- Archiving changes must avoid N+1 queries, unbounded memory growth, and logic that scales poorly with visits or sites.
95- Large-table schema changes, especially `log_*` tables, are risky and need a migration strategy.
96- Security-sensitive code must account for XSS, injection, CSRF, permission checks, request trust boundaries, and secret exposure.
97- Privacy-sensitive code must not leak sensitive data, bypass configured privacy settings, re-identify users unexpectedly, or ignore opt-out or consent mechanisms.
98 
99Use `matomo-security-rules`, `matomo-migrations-workflow`, and the relevant layer-specific skill when changes touch these areas.
100 
101## UI And Frontend
102 
103- Prefer Vue for new UI work where it fits the surrounding code.
104- Legacy JavaScript, Twig, and mixed approaches still exist and may need to be extended.
105- Avoid mixing frameworks unnecessarily.
106- Prefer DOM-based UI test assertions where they prove the behavior.
107- Add screenshot tests only for visual regressions or interactions that cannot be asserted reliably through DOM state.
108 
109Use the Vue, Twig, test-runner, and screenshot-audit skills for detailed rules and workflows.
110 
111## Review Smells
112 
113Reviewers will slow down or push back when they see:
114 
115- No tests and no explanation.
116- Tests that duplicate existing coverage or mirror implementation details.
117- Screenshot-heavy UI tests where DOM assertions would suffice.
118- Over-engineered solutions to simple problems.
119- Drive-by refactors unrelated to the task.
120- Silent public API or plugin compatibility breaks.
121- Tracking, archiving, migration, privacy, or security risks that are not acknowledged.
122- Ignoring PHPCS, PHPStan, or failing tests and expecting CI to sort it out.
123 
124Optimize for maintainability, safety, and predictable behavior on large Matomo instances.
125