Skip to content

Commit ef06455

Browse files
committed
OEL-5052: Agent Repository - Composer-based delivery of the Drupal AI community baseline.
1 parent 87d953b commit ef06455

41 files changed

Lines changed: 1748 additions & 340 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: CI
2+
on:
3+
pull_request:
4+
push:
5+
branches: [main]
6+
jobs:
7+
php:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v4
11+
- uses: shivammathur/setup-php@v2
12+
with:
13+
php-version: '8.3'
14+
coverage: none
15+
- uses: ramsey/composer-install@v3
16+
- run: composer cs-check
17+
- run: composer phpstan
18+
- run: vendor/bin/phpunit # includes the 200-line steering budget
19+
- run: vendor/bin/agent-skills-validator skills
20+
- run: composer evals # upstream's runner, with --root
21+
smoke-install:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v4
25+
- uses: shivammathur/setup-php@v2
26+
with:
27+
php-version: '8.3'
28+
coverage: none
29+
- run: scripts/ci-smoke-install.sh

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/vendor/
2+
/.php-cs-fixer.cache
3+
/.phpunit.cache/
4+
/composer.lock

‎.php-cs-fixer.dist.php‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
$finder = PhpCsFixer\Finder::create()
6+
->in([__DIR__.'/src', __DIR__.'/tests'])
7+
->name('*.php');
8+
9+
return (new PhpCsFixer\Config())
10+
->setRules([
11+
'@Symfony' => true,
12+
'declare_strict_types' => true,
13+
'global_namespace_import' => ['import_classes' => false, 'import_constants' => false, 'import_functions' => false],
14+
])
15+
->setRiskyAllowed(true)
16+
->setFinder($finder);

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Changelog
2+
3+
## Unreleased
4+
5+
- Skeleton: Composer plugin that requires `drupal/ai_best_practices`, points
6+
its skill sync at `.kiro/skills`, and places four steering files, the
7+
`oe-guardrail` PreToolUse hook and the `oe-reviewer` agent; seed skill
8+
`oe-project-wiki`; CI with an end-to-end smoke install.

‎LICENSE‎

Lines changed: 190 additions & 339 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 217 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,217 @@
1-
# ai-devkit
1+
# OpenEuropa AI DevKit
2+
3+
The OpenEuropa layer on top of
4+
[`drupal/ai_best_practices`](https://www.drupal.org/project/ai_best_practices):
5+
OpenEuropa skills, Kiro steering, a guardrail hook and a read-only reviewer
6+
agent. The Drupal community package does the skill sync; this package adds
7+
what is specific to OpenEuropa and Kiro.
8+
9+
## Requirements
10+
11+
- PHP 8.3+ and Composer 2.
12+
- [Kiro CLI](https://kiro.dev/docs/cli/) v3 for the agent itself. Node is not
13+
needed.
14+
15+
## Install (Drupal project)
16+
17+
```bash
18+
composer require --dev drupal/ai_best_practices:1.0.x-dev@dev openeuropa/ai-devkit
19+
```
20+
21+
Then commit what the install produced. You add nothing by hand; these are
22+
the files the two plugins wrote:
23+
24+
```bash
25+
git add .kiro .aiignore AGENTS.md CLAUDE.md GEMINI.md ai_best_practices.yaml composer.json composer.lock
26+
```
27+
28+
Once a project adds its own skills, commit `skills/` too.
29+
30+
Notes:
31+
32+
- **Both plugins must be allowed.** If `drupal/ai_best_practices` is not in
33+
`allow-plugins`, no skills are synced; if `openeuropa/ai-devkit` is not,
34+
the Kiro files are missing and skills land in `.agents/skills`. Run
35+
interactively, `composer require` asks about each plugin and adds them to
36+
`allow-plugins`. In non-interactive runs (CI, an agent) Composer stops with
37+
an error instead of asking, so run these first:
38+
39+
```bash
40+
composer config allow-plugins.drupal/ai_best_practices true
41+
composer config allow-plugins.openeuropa/ai-devkit true
42+
```
43+
- **Upstream has no stable release yet.** A project on
44+
`minimum-stability: stable` must require its dev version explicitly
45+
(`drupal/ai_best_practices:1.0.x-dev@dev`, as above); otherwise Composer
46+
cannot resolve the devkit.
47+
- **Commit `.kiro/skills/`.** It is generated, but committing it gives every
48+
teammate and CI job the same skills without running Composer first, and
49+
shows skill changes in merge requests.
50+
51+
## What happens on install and update
52+
53+
1. This plugin creates `ai_best_practices.yaml` from upstream's template, with
54+
`skills.output_directory: .kiro/skills` (Kiro reads skills only from
55+
there), when the file does not exist yet. It never edits an existing file;
56+
if yours points elsewhere it prints a warning.
57+
2. It places its Kiro files in `.kiro/` (see below). Files it manages are
58+
refreshed on every install; files you add next to them are not touched.
59+
3. `drupal/ai_best_practices` then syncs skills from every Composer package
60+
(including this one) and from the project's `skills/` into `.kiro/skills/`,
61+
updates its region in `AGENTS.md`, adds `CLAUDE.md` / `GEMINI.md` when
62+
missing, and registers `composer drupal-ai` in `composer.json`.
63+
64+
Re-sync skills at any time with `composer drupal-ai skills-sync`; list them
65+
with `composer drupal-ai skills-list`.
66+
67+
## What lands in a project
68+
69+
```
70+
.kiro/skills/ synced by drupal/ai_best_practices (generated; do not edit)
71+
.kiro/steering/oe-*.md always-on rules: working style, guardrails, RTK, writing conventions
72+
.kiro/steering/project-guardrails.md created once, yours: this project's extra guardrails
73+
.kiro/steering/project-rtk.md created once, yours: this project's commands, prefixed with rtk
74+
.kiro/oe-guardrail-patterns.txt created once, yours: extra commands the guardrail blocks
75+
.aiignore created once, yours: files the guardrail never lets a command read
76+
.kiro/hooks/ oe-guardrails.json, the PreToolUse guardrail
77+
.kiro/agents/ oe-reviewer.json + prompt, the read-only reviewer sub-agent
78+
.kiro/.gitignore created once, yours afterwards
79+
ai_best_practices.yaml upstream's settings file, created once pointing at .kiro/skills
80+
AGENTS.md upstream's managed region; everything outside the markers is yours
81+
```
82+
83+
Managed by this devkit (refreshed on every install): `.kiro/steering/oe-*.md`,
84+
`.kiro/hooks/oe-guardrails.json`, `.kiro/agents/oe-reviewer.*`. Do not edit
85+
those; add your own files beside them instead.
86+
87+
When a devkit release changes a template, `composer update` rewrites the
88+
managed files and `.kiro/skills/`, and the change shows up in the merge
89+
request like any other diff. Files created once (marked "yours" above) are
90+
never rewritten, so a project keeps its own version; compare it with the
91+
devkit's `templates/` if you want a later example.
92+
93+
`project-guardrails.md` and `project-rtk.md` are where a project adds its own
94+
guardrails and its [RTK](https://github.com/rtk-ai/rtk) command list.
95+
`oe-guardrails.md` and `oe-rtk.md` reference them. The devkit creates both once and never overwrites them; commit
96+
them. They are always-on, because Kiro CLI v3 does not expand the references
97+
in steering files.
98+
99+
## Using it
100+
101+
- Use Kiro's v3 engine. Until Kiro CLI 3.0, planned for the end of October
102+
2026, Kiro CLI starts its older v2 engine by default, and that engine skips
103+
the devkit's reviewer agent and its guardrail hook without a message. Make v3
104+
your default once, on your machine:
105+
106+
```bash
107+
kiro-cli settings chat.agentEngine v3
108+
```
109+
110+
Or pass `--v3` each time, as in `kiro-cli chat --v3`. From CLI 3.0, v3 is
111+
the default and this step is no longer needed.
112+
- Start Kiro in the project root: `kiro-cli chat`. Kiro reads `.kiro/` only
113+
from the folder it starts in, so a session started in a subfolder gets none
114+
of the steering, guardrails or skills. The default agent loads `AGENTS.md`,
115+
the steering files and the skill names automatically.
116+
- Run the reviewer with `kiro-cli chat --agent oe-reviewer` (or pick it with
117+
`/agent` in a session). It runs on `claude-sonnet-5`, a different model from
118+
the one that wrote the change, reads, runs `git diff` / phpcs / phpstan, and
119+
reports without editing. To review with another model, start it with
120+
`kiro-cli chat --agent oe-reviewer --model <id>`; your own default model
121+
does not replace the pin. The default agent can also hand it a review ("have
122+
oe-reviewer check this"); the reviewer keeps its own permissions when it runs
123+
that way. If your Kiro Enterprise model allow-list does not include
124+
`claude-sonnet-5`, Kiro falls back to the default model with a warning.
125+
- Add project skills under `skills/<prefix>-<name>/SKILL.md` and run
126+
`composer drupal-ai skills-sync`. A project skill with the same name as an
127+
upstream or devkit skill replaces it.
128+
129+
## Configuration and switches
130+
131+
| Setting | Where | Effect |
132+
|---|---|---|
133+
| `skills.output_directory` | `ai_best_practices.yaml` | Must be `.kiro/skills` for Kiro |
134+
| `skills.exclude_skills` | `ai_best_practices.yaml` | Drop a skill, e.g. `drupal/ai_best_practices:drupal-accessibility` |
135+
| `OE_AI_DEVKIT_SKIP_SYNC=1` | environment | Skip this devkit's step (no Kiro files, no yaml) |
136+
| `AI_BEST_PRACTICES_SKIP_PACKAGE_SYNC=1` | environment | Skip upstream's skill sync and `AGENTS.md` update |
137+
| `AI_BEST_PRACTICES_SKIP_COMPOSER_MUTATION=1` | environment | Stop upstream adding the `drupal-ai` script to `composer.json` |
138+
| `.kiro/oe-guardrail-patterns.txt` | project | Extra PCRE patterns the guardrail blocks, one per line. Created once with commented examples |
139+
| `.aiignore` | project | Globs of files the guardrail never lets a shell command read. Created once with commented examples |
140+
141+
## Known limitations
142+
143+
- **The guardrail is a tripwire, not a sandbox.** It blocks commands that
144+
name a credential file or an `.aiignore` path in any argument (whichever
145+
program reads it), network recon tools, curl and wget to hosts outside the
146+
allowlist, and pushes to protected branches. A path assembled at run time,
147+
or another program that opens a connection, gets past it. Network egress
148+
is enforced by the DevOps image's firewall, not by the hook.
149+
150+
- **Symlinked installs hide the devkit's skills.** Upstream's skill scanner
151+
skips symlinked directories. A Composer `path` repository symlinks by
152+
default, so when you install the devkit from a local checkout (for example
153+
while developing it), disable that:
154+
155+
```bash
156+
composer config repositories.devkit '{"type": "path", "url": "../ai-devkit", "options": {"symlink": false}}'
157+
```
158+
159+
Installs from Packagist or a VCS repository are not affected.
160+
- **Default `bin-dir` assumed.** The guardrail hook runs
161+
`vendor/bin/oe-guardrail`. With a custom `bin-dir`, copy
162+
`.kiro/hooks/oe-guardrails.json` to a project hook with the right path.
163+
- **Upstream's `AGENTS.md` text** says skills are installed into
164+
`.agents/skills/`; with this devkit they are in `.kiro/skills/`. The text
165+
comes from upstream's template and cannot be changed here.
166+
- **Existing `ai_best_practices.yaml`.** If the project already had one
167+
before installing the devkit, set `skills.output_directory: .kiro/skills`
168+
yourself and run `composer drupal-ai skills-sync`; the plugin warns until
169+
you do.
170+
171+
## Troubleshooting
172+
173+
| Symptom | Cause and fix |
174+
|---|---|
175+
| No `oe-*` skill in `.kiro/skills/` | Devkit installed through a symlinked `path` repository; see "Known limitations" |
176+
| 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` |
177+
| No skills at all | `drupal/ai_best_practices` not in `allow-plugins`, or `AI_BEST_PRACTICES_SKIP_PACKAGE_SYNC` is set |
178+
| `composer require` cannot resolve | Stable-only project without `drupal/ai_best_practices:1.0.x-dev@dev` |
179+
| Sync aborts with a YAML error | `ai_best_practices.yaml` is malformed; upstream refuses to fall back to defaults. Fix the file |
180+
181+
## Uninstall
182+
183+
`composer remove openeuropa/ai-devkit` removes the package only. The files it
184+
placed in `.kiro/` and `ai_best_practices.yaml` are project-owned and stay;
185+
delete them yourself if you no longer want them.
186+
187+
## Developing this package
188+
189+
```bash
190+
composer install # upstream's plugin is disabled in this repository on purpose
191+
composer test # PHPUnit, including the 200-line steering budget
192+
composer cs-fix # php-cs-fixer (@Symfony), the same style tool and rules as upstream
193+
composer phpstan # PHPStan, level 8
194+
vendor/bin/agent-skills-validator skills
195+
scripts/ci-smoke-install.sh # end-to-end install into a throwaway project; needs network access to Packagist
196+
composer evals # static evals for this repository's skills, with upstream's runner
197+
```
198+
199+
Behavioral evals run against Kiro CLI 2.31 or later, agent engine v3 (log in with
200+
`kiro-cli login` first). Each call runs with an empty `KIRO_HOME`, so your own
201+
`~/.kiro` steering and skills stay out of the results:
202+
203+
```bash
204+
python3 vendor/drupal/ai_best_practices/evals/run-evals.py --behavioral --root . --provider kiro
205+
```
206+
207+
**Upstream pin.** Upstream has no tagged release yet, so `composer.json` pins
208+
`drupal/ai_best_practices` to the 1.0.x commit that added the Kiro provider
209+
([#3589004](https://git.drupalcode.org/project/ai_best_practices/-/work_items/3589004))
210+
as `1.0.x-dev#<commit>`. Composer honours a commit reference only in the root
211+
package, so the pin holds in this repository and its CI, while projects that
212+
install the devkit still resolve `1.0.x-dev` themselves. Move the pin
213+
deliberately after reviewing upstream changes, or drop it once upstream tags a
214+
release.
215+
216+
Every skill ships `evals/<name>/`; a skill change needs an eval change.
217+
Steering stays under 200 lines in total. Licence: EUPL-1.2.

‎agents/oe-reviewer.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"name": "oe-reviewer",
3+
"description": "Read-only reviewer for OpenEuropa merge requests. Reports findings against the oe-qa-gate checks; never edits files.",
4+
"prompt": "file://./oe-reviewer.prompt.md",
5+
"model": "claude-sonnet-5",
6+
"tools": ["read", "shell"],
7+
"permissions": {
8+
"rules": [
9+
{ "capability": "fs_write", "match": ["**"], "effect": "deny" },
10+
{ "capability": "shell", "match": ["git diff *", "git log *", "git status*", "git show *", "vendor/bin/phpcs *", "vendor/bin/phpstan *", "rtk git diff *", "rtk git log *", "rtk vendor/bin/phpcs *", "rtk vendor/bin/phpstan *"], "effect": "allow" },
11+
{ "capability": "shell", "match": ["*"], "exclude": ["git diff *", "git log *", "git status*", "git show *", "vendor/bin/phpcs *", "vendor/bin/phpstan *", "rtk git diff *", "rtk git log *", "rtk vendor/bin/phpcs *", "rtk vendor/bin/phpstan *"], "effect": "deny" }
12+
]
13+
},
14+
"resources": [
15+
"file://AGENTS.md",
16+
"skill://.kiro/skills/oe-qa-gate/SKILL.md",
17+
"skill://.kiro/skills/drupal-*/SKILL.md"
18+
],
19+
"includeMcpJson": false,
20+
"welcomeMessage": "oe-reviewer: tell me which branch or diff to review. I report; I do not edit."
21+
}

‎agents/oe-reviewer.prompt.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
You are the OpenEuropa code reviewer. You review a diff or branch and report
2+
findings; you never change files and never run commands other than read-only
3+
git, phpcs and phpstan invocations.
4+
5+
Procedure:
6+
1. Identify the change set (`git diff <base>...HEAD` or the diff the user gives).
7+
2. Load the oe-qa-gate skill and check the change against its order of checks.
8+
3. For each finding give: file and line, what is wrong, why it matters, and
9+
the smallest fix. Mark severity: blocker, should-fix, nit.
10+
4. Flag unrequested changes (refactors, reformatting, unrelated clean-ups)
11+
as should-fix: the working style forbids them.
12+
5. End with a one-line verdict: "ready", "ready after should-fix items" or
13+
"not ready".
14+
15+
Do not praise. Do not restate the diff. If the diff is empty or the base
16+
branch is unclear, ask one question and stop.

‎bin/oe-guardrail‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
#!/usr/bin/env php
2+
<?php
3+
// Kiro PreToolUse hook command, registered in .kiro/hooks/oe-guardrails.json (from hooks/ in this package).
4+
// Exit 2 with a reason on stderr to block, 0 to allow.
5+
declare(strict_types=1);
6+
7+
// Runs on every agent shell command: load only the one dependency-free class, not the project autoloader.
8+
require __DIR__.'/../src/Guardrail/Guardrail.php';
9+
10+
$lines = static function (string $path): array {
11+
if (!is_file($path)) {
12+
return [];
13+
}
14+
15+
return array_values(array_filter(array_map('trim', file($path) ?: []), fn (string $l) => '' !== $l && !str_starts_with($l, '#')));
16+
};
17+
18+
// Projects may add their own deny patterns (one PCRE per line) and list files that must never be read.
19+
$extra = $lines(getcwd().'/.kiro/oe-guardrail-patterns.txt');
20+
$aiignore = $lines(getcwd().'/.aiignore');
21+
22+
$reason = OpenEuropa\AiDevkit\Guardrail\Guardrail::decide((string) stream_get_contents(STDIN), $extra, $aiignore);
23+
if (null !== $reason) {
24+
fwrite(STDERR, 'oe-guardrail: '.$reason.". Ask the user before retrying.\n");
25+
exit(2);
26+
}
27+
exit(0);

0 commit comments

Comments
 (0)