Skip to content

AI agent orientation

This section is for AI coding agents (Claude, Codex, ChatGPT, Cursor, OpenCode, etc.) working on FedMS — building new features, fixing bugs, refactoring, writing tests, updating documentation.

Human developers can read it too; the conventions described here apply to everyone.

Why a dedicated section?

AI agents have specific operating constraints:

  • They benefit from explicit, addressable information in the documentation rather than tacit team knowledge.
  • They benefit from stable conventions that they can rely on across sessions.
  • They benefit from mapping tables between high-level concepts and concrete file paths.
  • They benefit from explicit do / don't lists to avoid common failure modes.

This section provides those. It complements — and cross-references — the Developer guide without duplicating it.

In this section

Required reading on first contact

Read these, in order, before doing any work on FedMS:

  1. The site's AGENTS.md at the repo root (e.g. fedms/sites/amplius-partners/AGENTS.md) — site-specific conventions and overrides.
  2. The fedms opencode skill at ~/.opencode/skills/fedms/SKILL.md — cross-project FedMS knowledge.
  3. The l3d opencode skill at ~/.opencode/skills/l3d/SKILL.md — how all PHP commands run.
  4. The gitlab opencode skill at ~/.opencode/skills/gitlab/SKILL.md — MR / issue / pipeline workflow.
  5. The drupal-module-development opencode skill — DI and OOP hook patterns for new Drupal 11 code.
  6. The eca-guide opencode skill — when touching ECA models.
  7. This documentation site:
  8. Architecture — the big picture.
  9. Repository layout — where things live.
  10. Modules → index — the seven components.
  11. The module page for whatever you're touching.
  12. Concepts — domain definitions.

Hard rules

The constitutional rules an agent must always honor:

  1. All PHP-related commands go through L3D. Never run php, composer, drush, ahoy, phpunit, phpcs, phpstan, node, npm, glab, drupalorg directly on the host. Always prefix with l3d.
  2. Each fedms_* module is its own git repo. When working on a module, cd into the module directory and run git / glab from there — not from the site root.
  3. US English (en-US) everywhere — code, comments, commits, MRs, issues. The cspell pipeline rejects British English.
  4. Don't hand-edit eca.eca.*.yml. Use the modeler at /admin/config/workflow/eca and re-export.
  5. Don't add Cypress tests — Playwright only.
  6. Don't bypass the federation membership query alter in fedms_federation. It's load-bearing.
  7. Don't run mysql directly. Use docker compose exec mariadb.
  8. Don't commit secrets. Check .gitignore and the system secret-scan tooling before committing.

The full list and reasoning is in Do and don't.

How to think about FedMS

A useful mental model:

  • FedMS is a layered system. The structural layer (fedms_federation, fedms_content, fedms_attachment, fedms_task) defines what exists. The business-logic layer (fedms_eca) defines what happens. Most changes should fit cleanly in one layer.
  • The business logic prefers ECA over PHP. When the rule fits the ECA event-condition-action model, encode it there. PHP is for things ECA can't express (query alters, plugin implementations, performance-critical paths).
  • Each fedms_* module owns a slice of the data model. Don't cross module boundaries unnecessarily — if you're adding a field to an event group, that goes in fedms_federation, not in the module you happen to be in.
  • Federation is a goal, not (yet) a built feature. The data model is federation-ready; the transport is being designed. Don't build features that assume federation works today, but don't block features that will benefit from it later.

When in doubt

  • Read the AGENTS.md at the site root. It always wins.
  • Search the GitLab issues at gitlab.lakedrops.com/fedms for the topic — many questions have been asked already.
  • Use Skill('eca-guide') to access the ECA MCP server — authoritative ECA reference.
  • Ask the user if a non-obvious choice would change the architecture.

Next steps