Skip to content

Latest commit

 

History

History
303 lines (252 loc) · 16.1 KB

README.md

File metadata and controls

303 lines (252 loc) · 16.1 KB

OpenEuropa AI DevKit

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.

Requirements

  • PHP 8.3+ and Composer 2.
  • Kiro CLI v3 for the agent itself. Node is not needed.

Install (Drupal project)

composer require --dev drupal/ai_best_practices:1.0.x-dev@dev openeuropa/ai-devkit

Then 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.lock

Once a project adds its own skills, commit skills/ too.

Notes:

  • Both plugins must be allowed. If drupal/ai_best_practices is not in allow-plugins, no skills are synced; if openeuropa/ai-devkit is not, the Kiro files are missing and skills land in .agents/skills. Run interactively, composer require asks about each plugin and adds them to allow-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: stable must 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.

What happens on install and update

  1. This plugin creates ai_best_practices.yaml from upstream's template, with skills.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.
  2. 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.
  3. drupal/ai_best_practices then syncs skills from every Composer package (including this one) and from the project's skills/ into .kiro/skills/, updates its region in AGENTS.md, adds CLAUDE.md / GEMINI.md when missing, and registers composer drupal-ai in composer.json.

Re-sync skills at any time with composer drupal-ai skills-sync; list them with composer drupal-ai skills-list.

What lands in a project

.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.

Using it

  • 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 --v3 each time, as in kiro-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 loads AGENTS.md, the steering files and the skill names automatically.

  • Run the reviewer with kiro-cli chat --agent oe-reviewer (or pick it with /agent in a session). It runs on claude-opus-5, reads, runs git 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 the oe-automated-testing skill and flags only those tests, not existing ones. To review with another model, start it with kiro-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 include claude-opus-5, Kiro falls back to the default model with a warning.

  • Add project skills under skills/<prefix>-<name>/SKILL.md and run composer drupal-ai skills-sync. A project skill with the same name as an upstream or devkit skill replaces it.

Skills

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.

Project wiki (optional)

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.md and that page, using the skill's references/ 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-reviewer flags 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-add note 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.

Configuration and switches

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")

Known limitations

  • The guardrail is a tripwire, not a sandbox. It blocks commands that name a credential file or an .aiignore path in any argument (whichever program reads it), Kiro's own read_file and list_directory tools 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 .aiignore entry. The guardrail recognises the conventional Drupal layout (sites/<dir>/settings*.php, at any depth under sites/). 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 under sites/ — add its glob to .aiignore so the guardrail blocks it too.

  • Search results are not filtered. The hook sees a search tool's arguments, not its results, so grep_search and file_search can 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 .aiignore and 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 run kiro-cli once 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 php or vendor/ 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 path repository 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 require can end up with an invalid composer.json. Upstream rewrites composer.json through 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-dir assumed. The guardrail hook runs vendor/bin/oe-guardrail. With a custom bin-dir, copy .kiro/hooks/oe-guardrails.json to a project hook with the right path.

  • Upstream's AGENTS.md text 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, set skills.output_directory: .kiro/skills yourself and run composer drupal-ai skills-sync; the plugin warns until you do.

Troubleshooting

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

Uninstall

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.

Developing this package

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 runner

Behavioral 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 kiro

Upstream 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.