Initial conventions for AI agents and humans: AGENTS.md, SKILLS.md, instructions.md (#8478)

Not stable yet, but initial structure
https://agents.md
https://agentskills.io/specification
https://code.visualstudio.com/docs/copilot/customization/custom-instructions
https://code.visualstudio.com/docs/copilot/customization/agent-skills

.github/instructions/_general.instructions.md

@@ -0,0 +1,23 @@
+---
+applyTo: "**"
+description: General instructions
+---
+
+# FreshRSS General instructions
+
+## KISS principle: Keep It Simple
+
+* Prioritise simplicity, brevity, and clarity in code and documentation.
+* Avoid premature abstractions or over-engineering.
+* Reuse and adapt existing code where possible, avoiding duplication.
+* Keep changes minimal and focused.
+* Favour vanilla solutions: avoid adding third-party dependencies and frameworks.
+* Overall, reduce the number of lines and quantity of code (including dependencies).
+
+## Style and formatting
+
+* When editing files, obey indentation and white-space as defined in [`.editorconfig`](../../.editorconfig) (some of it can be automatically fixed with `make fix-all`).
+
+## Spelling
+
+* Favour British English spelling and conventions in code, comments, and documentation.

.github/instructions/css.instructions.md

@@ -0,0 +1,31 @@
+---
+applyTo: "**/*.css"
+description: Editing CSS files
+---
+
+# CSS files
+
+* Obey formatting rules defined in [`.stylelintrc.json`](../../.stylelintrc.json)
+* Automatic fixes can be done with:
+	```sh
+	npm run stylelint_fix
+	# or (targeting more than just CSS)
+	make fix-all
+	```
+* Validation can be done with:
+	```sh
+	npm run stylelint
+	# or (targeting more than just CSS)
+	make test-all
+	```
+
+## Right-to-left CSS files
+
+* Do not edit RTL CSS `*.rtl.css` files manually.
+* RTL CSS files are auto-generated from LTR CSS files using the `rtlcss` tool.
+* Run the following command to regenerate the RTL files:
+	```sh
+	npm run rtlcss
+	# or
+	make rtl
+	```

.github/instructions/i18n.instructions.md

@@ -0,0 +1,55 @@
+---
+applyTo: "app/i18n/*/*.php"
+description: Editing FreshRSS translations
+---
+
+# FreshRSS translations (i18n)
+
+* Favour commands over manual edits to add, move, or delete translation keys:
+	* Use the `cli/manipulate.translation.php` script or the corresponding `make` commands.
+
+## Commands
+
+### Add a new translation key
+
+To add a new translatable string across all languages:
+
+```sh
+./cli/manipulate.translation.php --action add --key 'example.of.key' --value 'Example of text'
+# or
+make i18n-add-key key='example.of.key' value='Example of text'
+```
+
+This will:
+1. Add the key to English (`app/i18n/en/gen.php`) with the provided value
+2. Add the key to all other languages marked as `// TODO` for translators
+
+You should then:
+1. Remove the `// TODO` comment in English `en/`
+2. Update to `// IGNORE` comment in US English `en-US/` or adapt the string in case of regional differences
+
+### Delete a translation key
+
+To delete a translation key from all languages:
+
+```sh
+./cli/manipulate.translation.php --action delete --key 'old.key.path'
+```
+
+### Other commands
+
+See all available commands with:
+
+```sh
+./cli/manipulate.translation.php -a --help
+```
+
+## Post-fixing
+
+After manipulating translation, you should call the following to reformat and ensure consistency:
+
+```sh
+composer run-script translations
+# or (targeting more than just translations)
+make fix-all
+```

.github/instructions/javascript.instructions.md

@@ -0,0 +1,21 @@
+---
+applyTo: "**/*.js"
+description: Editing JavaScript files
+---
+
+# JavaScript files
+
+* Obey formatting rules defined in [`eslint.config.js`](../../eslint.config.js)
+* Automatic fixes can be done with:
+	```sh
+	npm run eslint_fix
+	# or (targeting more than just JavaScript)
+	make fix-all
+	```
+* Validation can be done with:
+	```sh
+	npm run eslint
+	# or (targeting more than just JavaScript)
+	make test-all
+	```
+* Check [`package.json`](../../package.json) scripts for details about available individual commands.

.github/instructions/markdown.instructions.md

@@ -0,0 +1,19 @@
+---
+applyTo: "**/*.md"
+description: Editing Markdown
+---
+
+# Markdown files
+
+* Obey formatting rules defined in [`.markdownlint.json`](../../.markdownlint.json)
+* For fenced code blocks:
+	* Use language identifiers as much as possible, e.g., `php`, `js`, `css`
+	* Favour `sh` over `bash`
+* Automatic fixes can be done with:
+	```sh
+	npm run markdownlint_fix
+	```
+* Validation can be done with:
+	```sh
+	npm run markdownlint
+	```

.github/instructions/php.instructions.md

@@ -0,0 +1,37 @@
+---
+applyTo: "**/*.php"
+description: Editing PHP files
+---
+
+# PHP files
+
+* See minimum PHP version and available PHP extensions in [`composer.json`](../../composer.json)
+* Obey formatting rules defined in [`phpcs.xml`](../../phpcs.xml)
+* Automatic fixes can be done with:
+	```sh
+	composer run-script fix
+	# or (targeting more than just PHP)
+	make fix-all
+	```
+* Validation can be done with:
+	```sh
+	composer test
+	# or (targeting more than just PHP)
+	make test-all
+	```
+* Check [`composer.json`](../../composer.json) scripts for details about available individual commands.
+* For instance, running a single unit test can be done with:
+	```sh
+	composer run-script phpunit -- tests/app/Models/SearchTest.php
+	```
+
+## Autoloader
+
+* `spl_autoload_register` is defined in [`lib/lib_rss.php`](../../lib/lib_rss.php)
+
+Minimal example:
+
+```php
+require dirname(__DIR__) . '/constants.php';
+require LIB_PATH . '/lib_rss.php';	//Includes class autoloader
+```

.github/skills/freshrss-git/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: freshrss-git
+description: FreshRSS version control, git workflow, branching strategy (edge/latest), diff/compare, PR changes.
+allowed-tools: Bash(git:*) Read Grep
+---
+
+# FreshRSS working with version control (git)
+
+FreshRSS uses a rolling-release approach with a main branch called `:edge`.
+This is the branch to target for most pull requests.
+
+Releases are tracked in a branch called `:latest`.
+
+## Check changes made in the current branch
+
+Also useful to locally check the state of a pull-request (PR).
+
+```sh
+git diff edge...HEAD
+```
+
+## Before commiting
+
+```sh
+make fix-all
+make test-all
+```

.github/skills/freshrss-i18n/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: freshrss-i18n
+description: Add, move, or format translation strings in FreshRSS. Use when modifying UI text that needs translation (i18n). Handles all supported languages automatically.
+allowed-tools: Bash(php:*) Bash(composer:*) Bash(make:*) Read Grep
+---
+
+# FreshRSS translation management (i18n)
+
+For instructions and commands to work with translations, make sure to obey [i18n.instructions.md](../../instructions/i18n.instructions.md).
+
+Translations strings are in `app/i18n/{lang}/` as PHP arrays, used with:
+
+```php
+_t('key.subkey')
+```
+
+## When to use this skill
+
+- Adding new user-facing text to the application
+- Moving/renaming or deleting existing translation keys
+- Adding a new translation file for a new feature area
+- Formatting translation files after manual edits
+
+## Workflow example
+
+When adding a new UI element:
+
+1. Identify the appropriate i18n file and section, in proximity of existing strings, avoiding duplication
+2. Add a key if an appropriate string does not already exist, using `cli/manipulate.translation.php` or the corresponding `make` commands as defined in the [instructions](../../instructions/i18n.instructions.md).
+3. Use in the code:
+	```php
+	<button><?= _t('gen.action.my_new_button') ?></button>
+	```

AGENTS.md

@@ -0,0 +1,112 @@
+---
+description: FreshRSS introduction and conventions for AI agents and human contributors
+---
+
+# FreshRSS introduction and conventions
+
+FreshRSS is an open-source news aggregator supporting RSS/ATOM/WebSub and also Web scraping.
+
+The market segment is mostly self-hosting, although multiple user accounts are supported.
+It is supposed to be installed on a modest server (mostly, but not limited to, Linux) and can be accessed through a Web UI and an API.
+
+It is written in PHP to make it easy to deploy and easy to contribute to.
+
+More information can be found in [README](README.md) and in the [documentation](docs/en/) published at <https://freshrss.github.io/FreshRSS/en/>
+
+## Instruction structure for AI agents and humans
+
+* [`.github/instructions/`](.github/instructions/) contain the instructions that primarily match filename patterns.
+* [`.github/skills/`](.github/skills/) contain the skills to achieve higher-level goals, potentially combining multiple instructions.
+* **`AGENTS.md`** is the entry point description for AI coding agents and contributors, referencing other documents such as instructions and skills.
+* Favour standard conventions over vendor-specific ones.
+* To reduce duplication, refer to enforceable configuration files instead of excessive free-text repetitions.
+
+## Code structure
+
+* `app/Controllers/` – Controllers extend `FreshRSS_ActionController`, named as `{name}Controller.php` with class `FreshRSS_{name}_Controller`
+* `app/Models/` – Domain models extend `Minz_Model`.
+	* DAOs may have some database-specific inheritance, e.g.: `*DAO.php` (base or MySQL), `*DAOSQLite.php` (SQLite), `*DAOPGSQL.php` (PostgreSQL)
+* `app/views/{controller}/` – View templates are `.phtml` files mixing PHP and HTML
+* `app/views/helpers/` – Reusable view elements with `$this->partial('name')`
+* `lib/core-extensions/` or `extensions/` – FreshRSS extensions
+* `lib/Minz/` – Core framework: routing, sessions, translations, extensions, PDO abstraction
+* `lib/lib_rss.php` – Contain `spl_autoload_register` and other global functions
+* `p/` – Public Web root. Only the content of this folder should be exposed if possible (`p/` should not be visible in the public URL)
+	* Only the `p/i/` path should be access controlled. The main entry point is `p/i/index.php`
+	* `p/api/greader.php` – Primary API for mobile clients
+	* `p/api/pshb.php` – Receive realtime pushes via WebSub
+	* `p/themes/` – UI themes
+
+### Configuration data
+
+* Constants: [`constants.php`](constants.php) overridden in `constants.local.php`
+* System config: [`config.default.php`](config.default.php) overridden in `data/config.php`
+* User config: [`config-user.default.php`](config-user.default.php) overridden in `data/users/{username}/config.php`
+
+> ℹ Access via `FreshRSS_Context::systemConf()` and `FreshRSS_Context::userConf()`
+
+## Database patterns
+
+Three database backends supported: SQLite, PostgreSQL, MySQL/MariaDB.
+The SQL differences are implemented through inheritance:
+
+```php
+// Base DAO with common queries
+class FreshRSS_EntryDAO extends Minz_ModelPdo { }
+// Database-specific overrides
+class FreshRSS_EntryDAOSQLite extends FreshRSS_EntryDAO { }
+class FreshRSS_EntryDAOPGSQL extends FreshRSS_EntryDAO { }
+```
+
+A factory pattern selects the correct DAO, e.g.:
+
+```php
+FreshRSS_Factory::createEntryDao();
+```
+
+**Important**: in database, VARCHAR/TEXT fields are HTML-encoded, except `attributes` fields, which contain JSON, and which sub-strings are not HTML-encoded.
+
+## Main development commands
+
+> ℹ Recommended before committing
+
+```sh
+# Runs all tests: PHPUnit, PHPCS, PHPStan, typos
+make test-all
+
+# Auto-fix all trivial issues: whitespace, RTL CSS, translations
+make fix-all
+
+# See a list of commands:
+make help
+```
+
+CI/CD is defined in [`.github/workflows/tests.yml`](.github/workflows/tests.yml)
+
+A Dev Container is available under [`.devcontainer/`](.devcontainer/).
+
+## Docker
+
+> ℹ Check [Docker documentation](Docker/README.md).
+
+## CLI Tools
+
+There are scripts in `cli/` for admin tasks, such as:
+
+```sh
+./cli/list-users.php
+```
+
+> ℹ Check [CLI documentation](cli/README.md).
+
+When possible, it is best to run as Web server user:
+
+```sh
+sudo -u www-data cli/actualize-user.php --user alice
+```
+
+or at least re-apply the file permissions after CLI operations:
+
+```sh
+cli/access-permissions.sh
+```

CONTRIBUTING.md

@@ -35,6 +35,8 @@ Did you want to fix a bug? To keep a great coordination between collaborators, y
 
 If you have to write code, please follow [our coding style recommendations](https://freshrss.github.io/FreshRSS/en/developers/02_First_steps.html).
 
+> ℹ Check [`AGENTS.md`](AGENTS.md) for detailed coding conventions (both for humans and AI agents).
+
 **Tip:** if you are searching for bugs easy to fix, have a look at the « [Good first issue](https://github.com/FreshRSS/FreshRSS/issues?q=label%3A%22good+first+issue+%3Ababy%3A%22) » and/or « [Help wanted](https://github.com/FreshRSS/FreshRSS/issues?q=label%3A%22help+wanted+%3Aoctocat%3A%22) » ticket labels.
 
 ## Submit an idea

Makefile

@@ -63,7 +63,7 @@ lint-fix: bin/phpcbf ## Fix the errors detected by the linter
 	$(PHP) bin/phpcbf . -p -s
 
 .PHONY: test
-test: bin/phpunit ## Run the test suite
+test: bin/phpunit ## Run the PHP test suite
 	$(PHP) bin/phpunit --bootstrap ./tests/bootstrap.php ./tests
 
 bin/composer:
@@ -94,6 +94,34 @@ node_modules/.bin/eslint:
 node_modules/.bin/rtlcss:
 	npm install
 
+# TODO: Add composer install
+.PHONY: composer-test
+composer-test: bin/phpstan bin/composer
+	bin/composer run-script test
+
+.PHONY: composer-fix
+composer-fix: bin/composer
+	bin/composer run-script fix
+
+.PHONY: npm-test
+npm-test: node_modules/.bin/eslint
+	npm test
+
+.PHONY: npm-fix
+npm-fix: node_modules/.bin/eslint
+	npm run fix
+
+.PHONY: typos-test
+typos-test: bin/typos
+	bin/typos
+
+# TODO: Add shellcheck, shfmt, hadolint
+.PHONY: test-all
+test-all: composer-test npm-test typos-test ## Run all tests
+
+.PHONY: fix-all
+fix-all: composer-fix npm-fix ## Run all fixes
+
 ##@ I18n
 .PHONY: i18n-add-file
 i18n-add-file: ## Add a new translation file to all supported languages
@@ -200,39 +228,6 @@ refresh: ## Refresh feeds by fetching new messages
 rtl: node_modules/.bin/rtlcss ## Generate RTL CSS files
 	npm run-script rtlcss
 
-###############################
-## New commands aligned on CI #
-##     Work in progress       #
-###############################
-
-# TODO: Add composer install
-.PHONY: composer-test
-composer-test: bin/phpstan bin/composer
-	bin/composer run-script test
-
-.PHONY: composer-fix
-composer-fix: bin/composer
-	bin/composer run-script fix
-
-.PHONY: npm-test
-npm-test: node_modules/.bin/eslint
-	npm test
-
-.PHONY: npm-fix
-npm-fix: node_modules/.bin/eslint
-	npm run fix
-
-.PHONY: typos-test
-typos-test: bin/typos
-	bin/typos
-
-# TODO: Add shellcheck, shfmt, hadolint
-.PHONY: test-all
-test-all: composer-test npm-test typos-test
-
-.PHONY: fix-all
-fix-all: composer-fix npm-fix
-
 ##@ Help
 .PHONY: help
 help: ## Display this help

README.fr.md

@@ -54,6 +54,7 @@ FreshRSS n’est fourni avec aucune garantie.
 * La [documentation administrateurs](https://freshrss.github.io/FreshRSS/fr/users/01_Installation.html) pour l’installation et la maintenance de FreshRSS.
 * La [documentation développeurs](https://freshrss.github.io/FreshRSS/fr/developers/01_First_steps.html) pour savoir comment contribuer et mieux comprendre le code source de FreshRSS.
 * Le [guide de contribution](https://freshrss.github.io/FreshRSS/fr/contributing.html) pour nous aider à développer FreshRSS.
+	* Voir [`AGENTS.md`](AGENTS.md) pour les conventions de code (à la fois pour les humains et agents IA).
 
 ## Prérequis
 

README.md

@@ -54,6 +54,7 @@ FreshRSS comes with absolutely no warranty.
 * [Administrator documentation](https://freshrss.github.io/FreshRSS/en/admins/01_Index.html) for detailed installation and maintenance related tasks
 * [Developer documentation](https://freshrss.github.io/FreshRSS/en/developers/01_Index.html) to guide you in the source code of FreshRSS and to help you if you want to contribute
 * [Contributor guidelines](https://freshrss.github.io/FreshRSS/en/contributing.html) for those who want to help improve FreshRSS
+	* Check [`AGENTS.md`](AGENTS.md) for coding conventions (both for humans and AI agents).
 
 # Requirements
 

docs/en/contributing.md

@@ -33,6 +33,8 @@ Would you like to fix a bug? For optimum coordination between collaborators, you
 
 If you have to write code, please follow [our coding style recommendations](developers/02_First_steps.md).
 
+> ℹ Check [`AGENTS.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/AGENTS.md) for detailed coding conventions (both for humans and AI agents).
+
 **Tip:** if you’re searching for easy-to-fix bugs, please have a look at the “[good first issue](https://github.com/FreshRSS/FreshRSS/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)” ticket label.
 
 ## Submit an idea

docs/en/developers/02_First_steps.md

@@ -112,10 +112,14 @@ apk add git make npm php-cli php-curl php-ctype php-dom php-mbstring php-openssl
 
 ### Tests summary
 
+> ℹ Check [`AGENTS.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/AGENTS.md) for detailed coding conventions (both for humans and AI agents).
+
 A short (not complete) summary:
 
 #### PHP
 
+> ℹ Check [`php.instructions.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/instructions/php.instructions.md) for detailed coding conventions (both for humans and AI agents).
+
 - Syntax of `php` and `phtml` files is checked.
 - translation files (`i18n`) are checked ([more information about i18n files](internationalization.html)).
 - unit test (`tests`) are run by [PHPunit](https://phpunit.de/).
@@ -125,6 +129,8 @@ A short (not complete) summary:
 
 ### CSS
 
+> ℹ Check [`css.instructions.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/instructions/css.instructions.md) for detailed coding conventions (both for humans and AI agents).
+
 - Linter:
   - [PHP_Codesniffer (phpcs)](https://github.com/squizlabs/PHP_CodeSniffer)
   - via npm `.styleintrc.json`
@@ -132,16 +138,22 @@ A short (not complete) summary:
 
 ### JavaScript
 
+> ℹ Check [`javascript.instructions.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/instructions/javascript.instructions.md) for detailed coding conventions (both for humans and AI agents).
+
 - Linter:
   - via npm `.styleintrc.json` ([ECMAScript 2017](https://en.wikipedia.org/wiki/ECMAScript#8th_Edition_%E2%80%93_ECMAScript_2017))
 
 ### Markdown
 
+> ℹ Check [`markdown.instructions.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/instructions/markdown.instructions.md) for detailed coding conventions (both for humans and AI agents).
+
 - Linter:
   - via npm `.markdownlint.json`
 
 ## Spaces, tabs and other whitespace characters
 
+> ℹ Check [`_general.instructions.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/instructions/_general.instructions.md) for detailed coding conventions (both for humans and AI agents).
+
 ### Indentation
 
 Code indentation must use tabs.

docs/en/internationalization.md

@@ -43,6 +43,8 @@ Each value can be referenced by a key: it consists of a series of identifiers se
 
 You should not have to write the array by yourself and we provide several commands to ease the manipulation of these files. Let’s see some common use cases.
 
+> ℹ Check [`freshrss-i18n/SKILL.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/skills/freshrss-i18n/SKILL.md) for detailed coding conventions (both for humans and AI agents).
+
 ## Add support for a new language
 
 If you want to add support for a language which isn’t supported by FreshRSS yet, you can run this command:

docs/fr/contributing.md

@@ -1,13 +1,7 @@
 ## Rejoignez-nous sur les listes de mailing
 
 S’il vous manque des informations, n’hésitez pas à fouiller un peu la
-documentation ou venir nous poser directement vos questions sur [la mailing
-list des développeurs](https://freshrss.org/mailman/listinfo/dev).
-
-* Le premier mailing est destiné à l’information générique, il doit être adapté aux utilisateurs.
-	[Rejoignez mailing@freshrss.org](https://freshrss.org/mailman/listinfo/mailing).
-* Le deuxième mailing s’adresse principalement aux développeurs.
-	[Rejoignez dev@freshrss.org](https://freshrss.org/mailman/listinfo/dev)
+documentation ou venir nous [poser directement vos questions](https://github.com/FreshRSS/FreshRSS/discussions/categories/q-a).
 
 ## Signaler un bug
 
@@ -30,7 +24,7 @@ suivants :
 
 Nous avons aussi besoin de quelques informations :
 
-* Votre version de FreshRSS (sur la page A propos) ou le fichier `constants.php`)
+* Votre version de FreshRSS (sur la page A propos) ou le fichier `constants.php`
 * Votre configuration de serveur : type d’hébergement, version PHP
 * Quelle base de données : SQLite, PostgreSQL, MariaDB, MySQL ? Quelle version ?
 * Si possible, les logs associés (logs PHP et logs FreshRSS sous `data/users/your_user/log.txt`)
@@ -52,6 +46,8 @@ les collaborateurs, vous devrez suivre ces indications :
 Si vous devez écrire du code, veuillez suivre [nos recommandations de style
 de codage](developers/01_First_steps.md).
 
+> ℹ Voir [`AGENTS.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/AGENTS.md) pour les conventions de code (à la fois pour les humains et agents IA).
+
 **Conseil :** si vous cherchez des bugs faciles à corriger, jetez un coup d’oeil à la vignette « [good first issue](https://github.com/FreshRSS/FreshRSS/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) ».
 
 ## Soumettre une idée

docs/fr/developers/01_First_steps.md

@@ -94,15 +94,16 @@ Si vous souhaitez créer votre propre extension FreshRSS, consultez la
 
 ## Style de codage
 
+> ℹ Voir [`AGENTS.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/AGENTS.md) pour les conventions de code (à la fois pour les humains et agents IA).
+
 Si vous désirez contribuer au code, il est important de respecter le style
 de codage suivant. Le code actuel ne le respecte pas entièrement mais il est
 de notre devoir à tous de le changer dès que l’occasion se présente.
 
-Aucune nouvelle contribution ne respectant pas ces règles ne sera acceptée
-tant que les corrections nécessaires ne sont pas appliquées.
-
 ### Espaces, tabulations et autres caractères blancs
 
+> ℹ Voir [`_general.instructions.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/instructions/_general.instructions.md) pour les conventions de code (à la fois pour les humains et agents IA).
+
 #### Indentation
 
 L’indentation du code doit être faite impérativement avec des tabulations.

docs/fr/internationalization.md

@@ -79,3 +79,5 @@ supérieur. C’est assez dur à expliquer mais très simple à comprendre. Dans
 l’exemple donné plus haut, un `_` est associé à la valeur `FreshRSS` : cela
 signifie qu’il n’y a pas besoin d’écrire `_t('gen.freshrss._')` mais
 `_t('gen.freshrss')` suffit.
+
+> ℹ Voir [`freshrss-i18n/SKILL.md`](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/skills/freshrss-i18n/SKILL.md) pour les conventions de code (à la fois pour les humains et agents IA).