The OpenEuropa layer on top of
drupal/ai_best_practices:
OpenEuropa skills, Kiro steering, a guardrail hook and a read-only reviewer
agent. The Drupal community package does the skill sync; this package adds
what is specific to OpenEuropa and Kiro.
- PHP 8.3+ and Composer 2.
- Kiro CLI v3 for the agent itself. Node is not needed.
composer require --dev drupal/ai_best_practices:1.0.x-dev@dev openeuropa/ai-devkitThen commit what the install produced. You add nothing by hand; these are the files the two plugins wrote:
git add .kiro .aiignore AGENTS.md CLAUDE.md GEMINI.md ai_best_practices.yaml composer.json composer.lockOnce a project adds its own skills, commit skills/ too.
Notes:
-
Both plugins must be allowed. If
drupal/ai_best_practicesis not inallow-plugins, no skills are synced; ifopeneuropa/ai-devkitis not, the Kiro files are missing and skills land in.agents/skills. Run interactively,composer requireasks about each plugin and adds them toallow-plugins. In non-interactive runs (CI, an agent) Composer stops with an error instead of asking, so run these first:composer config allow-plugins.drupal/ai_best_practices true composer config allow-plugins.openeuropa/ai-devkit true
-
Upstream has no stable release yet. A project on
minimum-stability: stablemust require its dev version explicitly (drupal/ai_best_practices:1.0.x-dev@dev, as above); otherwise Composer cannot resolve the devkit. -
Commit
.kiro/skills/. It is generated, but committing it gives every teammate and CI job the same skills without running Composer first, and shows skill changes in merge requests.
- This plugin creates
ai_best_practices.yamlfrom upstream's template, withskills.output_directory: .kiro/skills(Kiro reads skills only from there), when the file does not exist yet. It never edits an existing file; if yours points elsewhere it prints a warning. - It places its Kiro files in
.kiro/(see below). Files it manages are refreshed on every install; files you add next to them are not touched. drupal/ai_best_practicesthen syncs skills from every Composer package (including this one) and from the project'sskills/into.kiro/skills/, updates its region inAGENTS.md, addsCLAUDE.md/GEMINI.mdwhen missing, and registerscomposer drupal-aiincomposer.json.
Re-sync skills at any time with composer drupal-ai skills-sync; list them
with composer drupal-ai skills-list.
.kiro/skills/ synced by drupal/ai_best_practices (generated; do not edit)
.kiro/steering/oe-*.md always-on rules: working style, guardrails, RTK, writing conventions
.kiro/steering/project-guardrails.md created once, yours: this project's extra guardrails
.kiro/steering/project-rtk.md created once, yours: this project's commands, prefixed with rtk
.kiro/oe-guardrail-patterns.txt created once, yours: extra commands the guardrail blocks
.aiignore created once, yours: files the guardrail never lets a command or file-read tool read
.kiro/hooks/ oe-guardrails.json, the PreToolUse guardrail
.kiro/agents/ oe-reviewer.json + prompt, the read-only reviewer sub-agent
.kiro/.gitignore created once, yours afterwards
ai_best_practices.yaml upstream's settings file, created once pointing at .kiro/skills
AGENTS.md upstream's managed region; everything outside the markers is yours
Managed by this devkit (refreshed on every install): .kiro/steering/oe-*.md,
.kiro/hooks/oe-guardrails.json, .kiro/agents/oe-reviewer.*. Do not edit
those; add your own files beside them instead.
When a devkit release changes a template, composer update rewrites the
managed files and .kiro/skills/, and the change shows up in the merge
request like any other diff. Files created once (marked "yours" above) are
never rewritten, so a project keeps its own version; compare it with the
devkit's templates/ if you want a later example.
project-guardrails.md and project-rtk.md are where a project adds its own
guardrails and its RTK command list.
oe-guardrails.md and oe-rtk.md reference them. The devkit creates both once and never overwrites them; commit
them. They are always-on, because Kiro CLI v3 does not expand the references
in steering files.
-
Use Kiro's v3 engine. From Kiro CLI 3.0 it is the default, so a current CLI runs the devkit's reviewer agent and guardrail hook out of the box; no setup is needed. On an older 2.x CLI the v2 engine runs by default and skips both without a message, so either upgrade to 3.0 or select v3 yourself:
kiro-cli settings chat.agentEngine v3
Or pass
--v3each time, as inkiro-cli chat --v3. -
Start Kiro in the project root:
kiro-cli chat. Kiro reads.kiro/only from the folder it starts in, so a session started in a subfolder gets none of the steering, guardrails or skills. The default agent loadsAGENTS.md, the steering files and the skill names automatically. -
Run the reviewer with
kiro-cli chat --agent oe-reviewer(or pick it with/agentin a session). It runs onclaude-opus-5, reads, runsgit diff/ phpcs / phpstan, and reports without editing. It never runs PHPUnit, and it cannot read credential files (settings*.php,runner.yml,.env*, database dumps). When the branch adds or changes tests, it reviews them against theoe-automated-testingskill and flags only those tests, not existing ones. To review with another model, start it withkiro-cli chat --agent oe-reviewer --model <id>; your own default model does not replace the pin. The default agent can also hand it a review ("have oe-reviewer check this"); the reviewer keeps its own permissions when it runs that way. If your Kiro Enterprise model allow-list does not includeclaude-opus-5, Kiro falls back to the default model with a warning. -
Add project skills under
skills/<prefix>-<name>/SKILL.mdand runcomposer drupal-ai skills-sync. A project skill with the same name as an upstream or devkit skill replaces it.
Besides the community skills synced from drupal/ai_best_practices, the
devkit ships two OpenEuropa skills. The always-on working-style steering tells
the agent when to load each one:
| Skill | The agent loads it | What it does |
|---|---|---|
oe-project-wiki |
Before starting a ticket | Reads docs/wiki/index.md when the project has one; see "Project wiki" |
oe-automated-testing |
When you ask for tests, or a change needs one | Builds on upstream's drupal-automated-testing; where they disagree, it wins |
oe-automated-testing enforces the OpenEuropa test conventions:
- Tests run in the project's Docker Compose stack, not DDEV.
- On a site, the default test type is ExistingSite. Never write a new Behat feature: update existing scenarios, and put new coverage in ExistingSite or ExistingSiteJavascript tests.
- No negative tests, unless the denial is itself the feature.
- One test per behaviour, at one level.
- External services are mocked through the existing mock modules.
- In a project whose CI batches tests, every new test carries its
@group batchN. - A failing test is never made to pass by changing its assertion, skipping it or excluding its group.
The rules apply to new tests only; existing tests are not rewritten.
The oe-project-wiki skill gives the agent a place to keep durable project
knowledge — decisions, conventions, patterns, pitfalls — under docs/wiki/,
read before the source code. It is opt-in and off by default:
-
The devkit never creates
docs/wiki/. A fresh install writes no wiki files; a project with no wiki is simply not using the feature, and the agent stays quiet about it. -
A project opts in by having
docs/wiki/index.md. Its presence is the whole signal — there is no flag to set. Once it exists, the agent reads it at the start of a ticket and opens the pages for the area it is about to touch. -
The agent offers to set one up when it pays off. If, during a ticket in a project with no wiki, the work turns up something durable (a non-obvious dependency, why a decision was taken, a trap worth recording), the agent offers at the end to create
docs/wiki/index.mdand that page, using the skill'sreferences/as templates. It never creates files unasked, and it does not offer when nothing durable came up. -
The reviewer checks the wiki only when one exists.
oe-reviewerflags an architectural change that ships without its wiki update only in a project that has a wiki; in a project without one it says nothing. -
A project that uses kenkeep (
.ai/kenkeep/exists) keeps its facts there instead: the agent proposes a/kk-addnote rather than a wiki page.
To opt in by hand instead, copy the skeleton the skill ships at
.kiro/skills/oe-project-wiki/references/ into docs/wiki/ and edit it.
| Setting | Where | Effect |
|---|---|---|
skills.output_directory |
ai_best_practices.yaml |
Must be .kiro/skills for Kiro |
skills.exclude_skills |
ai_best_practices.yaml |
Drop a skill, e.g. drupal/ai_best_practices:drupal-accessibility |
OE_AI_DEVKIT_SKIP_SYNC=1 |
environment | Skip this devkit's step (no Kiro files, no yaml) |
AI_BEST_PRACTICES_SKIP_PACKAGE_SYNC=1 |
environment | Skip upstream's skill sync and AGENTS.md update |
AI_BEST_PRACTICES_SKIP_COMPOSER_MUTATION=1 |
environment | Stop upstream adding the drupal-ai script to composer.json |
.kiro/oe-guardrail-patterns.txt |
project | Extra PCRE patterns the guardrail blocks, one per line. Created once with commented examples |
.aiignore |
project | Globs of files the guardrail never lets a shell command or Kiro's file-read tools read. Created once with commented examples |
docs/wiki/index.md |
project | Opt-in to the project wiki; present means on. The agent offers to create it when a ticket turns up something durable (see "Project wiki") |
-
The guardrail is a tripwire, not a sandbox. It blocks commands that name a credential file or an
.aiignorepath in any argument (whichever program reads it), Kiro's ownread_fileandlist_directorytools when they open such a path, network recon tools, curl and wget to hosts outside the allowlist, and pushes to protected branches. A path assembled at run time, or another program that opens a connection, gets past it. Network egress is enforced by the DevOps image's firewall, not by the hook. -
Credential files in non-standard locations need an
.aiignoreentry. The guardrail recognises the conventional Drupal layout (sites/<dir>/settings*.php, at any depth undersites/). If your project keeps a settings or credential file somewhere else — for example a settings file symlinked from another repository, or a path that does not sit undersites/— add its glob to.aiignoreso the guardrail blocks it too. -
Search results are not filtered. The hook sees a search tool's arguments, not its results, so
grep_searchandfile_searchcan still surface a line from a credential file. Closing that needs a project.kiroignore(Kiro v3 applies it to reads and to search results); shipping one is a new installed file and is tracked as a follow-up, pending a spec change. Until then, keep credential files in.aiignoreand do not widen a search to pull in their contents. -
Standalone hooks need a trusted workspace. Kiro CLI runs a repository's
.kiro/hooks/only in a workspace you have trusted. On a fresh clone, confirm the trust prompt (or runkiro-clionce in the project root and accept it) so the guardrail fires; an untrusted workspace skips the hook without a message. -
The guardrail fails open. Kiro blocks a command only when the hook exits with code 2. When
phporvendor/is missing, or the guardrail crashes, Kiro runs the command without a message. -
Symlinked installs hide the devkit's skills. Upstream's skill scanner skips symlinked directories. A Composer
pathrepository symlinks by default, so when you install the devkit from a local checkout (for example while developing it), disable that:composer config repositories.devkit '{"type": "path", "url": "../ai-devkit", "options": {"symlink": false}}'Installs from Packagist or a VCS repository are not affected.
-
A project with an empty
requirecan end up with an invalidcomposer.json. Upstream rewritescomposer.jsonthrough PHP arrays, so an empty"require": {}can come back as"require": [], which Composer rejects on the next run. The devkit's smoke test avoids it by requiring a package. If you hit it, change[]back to{}; the bug is upstream's. -
Default
bin-dirassumed. The guardrail hook runsvendor/bin/oe-guardrail. With a custombin-dir, copy.kiro/hooks/oe-guardrails.jsonto a project hook with the right path. -
Upstream's
AGENTS.mdtext says skills are installed into.agents/skills/; with this devkit they are in.kiro/skills/. The text comes from upstream's template and cannot be changed here. -
Existing
ai_best_practices.yaml. If the project already had one before installing the devkit, setskills.output_directory: .kiro/skillsyourself and runcomposer drupal-ai skills-sync; the plugin warns until you do.
| Symptom | Cause and fix |
|---|---|
No oe-* skill in .kiro/skills/ |
Devkit installed through a symlinked path repository; see "Known limitations" |
Skills in .agents/skills/ instead |
ai_best_practices.yaml points elsewhere, or the devkit plugin is not allowed; fix and run composer drupal-ai skills-sync |
| No skills at all | drupal/ai_best_practices not in allow-plugins, or AI_BEST_PRACTICES_SKIP_PACKAGE_SYNC is set |
composer require cannot resolve |
Stable-only project without drupal/ai_best_practices:1.0.x-dev@dev |
| Sync aborts with a YAML error | ai_best_practices.yaml is malformed; upstream refuses to fall back to defaults. Fix the file |
composer remove openeuropa/ai-devkit removes the package only. The files it
placed in .kiro/ and ai_best_practices.yaml are project-owned and stay;
delete them yourself if you no longer want them.
composer install # upstream's plugin is disabled in this repository on purpose
composer test # PHPUnit, including the 200-line steering budget
composer cs-fix # php-cs-fixer (@Symfony), the same style tool and rules as upstream
composer phpstan # PHPStan, level 8
vendor/bin/agent-skills-validator skills
scripts/ci-smoke-install.sh # end-to-end install into a throwaway project; needs network access to Packagist
composer evals # static evals for this repository's skills, with upstream's runnerBehavioral evals run against Kiro CLI 3.0 or later, whose default engine is v3
(on a 2.x CLI, select v3 first, as in "Using it"; log in with
kiro-cli login first). Each call runs with an empty KIRO_HOME, so your own
~/.kiro steering and skills stay out of the results:
python3 vendor/drupal/ai_best_practices/evals/run-evals.py --behavioral --root . --provider kiroUpstream pin. Upstream has no tagged release yet, so composer.json pins
drupal/ai_best_practices to the 1.0.x commit that added the Kiro provider
(#3589004)
as 1.0.x-dev#<commit>. Composer honours a commit reference only in the root
package, so the pin holds in this repository and its CI, while projects that
install the devkit still resolve 1.0.x-dev themselves. Move the pin
deliberately after reviewing upstream changes, or drop it once upstream tags a
release.
Every skill ships evals/<name>/; a skill change needs an eval change.
Steering stays under 200 lines in total. Licence: EUPL-1.2.