Skip to content

Orientation

Five-minute orientation

If you have five minutes and need to make a small change:

  1. Read the site's AGENTS.md at the repo root.
  2. Read the l3d skill — every PHP command runs through it.
  3. Identify the right repo for the change using Where things live.
  4. Make the change.
  5. Run the appropriate l3d ahoy test ... commands.
  6. Commit, push, open an MR.

Thirty-minute orientation

If you have thirty minutes and are going to do real work:

  1. Read the site's AGENTS.md.
  2. Load the fedms opencode skill.
  3. Load the l3d opencode skill.
  4. Load the gitlab opencode skill.
  5. Read Architecture.
  6. Read Repository layout.
  7. Read Modules → index.
  8. Skim Entities.
  9. For the area you'll touch, read the corresponding module page and the relevant ECA model page(s).
  10. Read Do and don't.

When you'll touch ECA models

Load the eca-guide skill before opening any model. It gives you the events / conditions / actions vocabulary and access to the public ECA MCP server.

Read the per-model page under Developer guide → ECA models for the specific model.

Read the eca-guide skill's referenced modules page to see which ECA sub-modules are available.

When you'll touch PHP code

Load the drupal-module-development skill. It covers:

  • The #[Hook] attribute-based hook style (Drupal 11).
  • Constructor dependency injection for services.
  • Locating modules from namespaced classes.
  • Common DI patterns.

Read the relevant module's page in Developer guide → Modules.

Read the existing source code in the module to see the patterns it already follows.

When you'll touch tests

Load the relevant test-runner context:

  • For phpunit / phpcs / phpstan, just use the L3D ahoy wrappers documented in Testing.
  • For Playwright, read the README in tests/playwright/ and the examples under tests/playwright/e2e/.

When you'll touch GitLab issues / MRs

Load the gitlab skill. It covers the glab CLI and the FedMS issue conventions.

When you'll touch the documentation (this site)

You are on the FedMS documentation site. Reading order:

  1. Read Concepts for the domain model.
  2. Read the section adjacent to where you're making the change.
  3. Honor the page-level template (frontmatter with title and description, hierarchical structure, cross-links to related pages, "Next steps" section at the bottom).

To preview the doc site locally, see mkdocs/README.md and mkdocs/.ahoy.yml. The standard tooling is mkdocs-material; the plugins and theme config are in mkdocs.yml.

How to verify your work

For most changes, verify by running:

1
2
3
4
5
6
7
8
9
# Static checks
l3d ahoy test phpcsmodule fedms_<module>
l3d ahoy test phpstanmodule fedms_<module>

# Unit/integration tests
l3d ahoy test phpunitmodule fedms_<module>

# For E2E-affecting changes
cd tests/playwright && l3d npx playwright test

For documentation changes, build the docs and check the diff:

1
2
cd mkdocs
l3d ahoy mkdocs build

(See mkdocs/.ahoy.yml for the exact commands available.)

Where to put your output

The standard agent output is:

  1. Code changes — committed to the right repo on a feature branch.
  2. MR description — concise, links to the issue, lists the test plan.
  3. Documentation updates — committed to fedms/documentation in the same MR series as the code change.

Don't leave changes uncommitted, don't open MRs without descriptions, and don't claim a feature is "done" without verifying.

When to ask the user

Ask the user when:

  • The choice would change the architecture materially.
  • The choice would change a public contract (API, URL, config schema).
  • The choice involves a dependency upgrade that isn't trivially isolated.
  • The right behavior is ambiguous in the documentation and the issue is silent on it.

Don't ask the user for trivia (formatting, where to put a file when the convention is clear) — the conventions in this section answer that.

Next steps