|
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. |
0 commit comments