fourkitchens/drupal-ai-standards

Shared AI agent standards, skills, and instructions for Four Kitchens projects.

dev-main 2026-05-20 20:49 UTC

Requires

• php: >=8.1
• composer-plugin-api: ^2.0

Requires (Dev)

• composer/composer: ^2.0

MIT

README

Composer package: fourkitchens/drupal-ai-standards

A Composer plugin that standardizes AI agent behavior across Four Kitchens Drupal projects. It distributes shared skills, instructions, and prompts — IDE-agnostic Markdown content that works with GitHub Copilot, Claude Code, OpenCode, and any agent that reads standard AI config files.

This package serves two purposes:

1. For consuming Drupal projects — shared AI content is synced automatically on every composer install / composer update, so every project inherits the same baseline without manual setup.
2. For contributors to this repo — contributor AI skills in .agents/skills/ define how agents should behave when working on the package itself (committing, adding skills, updating docs).

What's in the box

Type	What it is	Where it lands in your project
Skills	Task playbooks the AI loads on demand for specific workflows	.agents/skills/_shared/
Instructions	Always-active rules injected into the AI's context automatically	.github/instructions/_shared/
Prompts	IDE-agnostic, one-time or on-demand workflows you invoke manually	.agents/prompts/_shared/
Scaffolds	Scaffold files (AGENTS.md, CLAUDE.md, etc.) generated once on first install	Project root

Installation

composer require --dev fourkitchens/drupal-ai-standards

After install, run composer install in your project — shared content is synced automatically on every install and update.

What it does

Action	When
Copies skills/ → .agents/skills/_shared/	Every composer install / update
Copies instructions/ → .github/instructions/_shared/	Every composer install / update
Copies prompts/ → .agents/prompts/_shared/	Every composer install / update
Ensures .gitignore has the three _shared/ entries	Every composer install / update
Generates scaffold files (AGENTS.md, CLAUDE.md, etc.)	Only once, if the file does not already exist

.gitignore (handled automatically)

The plugin adds the _shared/ entries to your .gitignore on every composer install / update — no manual step needed. If .gitignore does not exist it is created. Existing entries are never duplicated.

# Managed by fourkitchens/drupal-ai-standards — regenerated on composer install
.agents/skills/_shared/
.agents/prompts/_shared/
.github/instructions/_shared/

Ownership model: shared vs project vs personal

The _shared/ directories belong to this package — your project owns everything outside them. This lets you extend or override any standard locally without losing upstream updates.

Layer	Who owns it	Location	Committed?
Shared (org)	fourkitchens/drupal-ai-standards	_shared/ dirs	No — gitignored
Project	Project team	.agents/skills/, .github/instructions/	Yes
Personal	Individual developer	AI tool user-level config	Never

Scaffold files (generated once)

When installed into a project that does not yet have these files, the plugin generates scaffold files:

File	AI tool
AGENTS.md	OpenCode, Claude Code, generic agents
CLAUDE.md	Claude Code
.github/copilot-instructions.md	GitHub Copilot (VS Code)
.github/prompts/setup-agents-md.prompt.md	GitHub Copilot (VS Code) — run with /setup-agents-md
.claude/commands/setup-agents-md.md	Claude Code — run with /setup-agents-md
.opencode/commands/setup-agents-md.md	OpenCode — run with /setup-agents-md
opencode.json	OpenCode — loads shared instructions automatically

Scaffold files are never overwritten — they are yours to customize after generation.

Skills catalog

Skills are task playbooks loaded on demand. The AI picks up a skill when the user's request matches its trigger. Each skill is a self-contained SKILL.md with frontmatter describing when to activate.

Skill	Description	Trigger
create-documentation	Create or update a Drupal project README.md and PULL_REQUEST_TEMPLATE.md. Scaffolds from the Four Kitchens template if none exists; updates existing sections when tooling, versions, or structure changes.	"create README", "set up documentation", "update the README"
draft-pr-description	Draft a GitHub pull request description from the current branch diff: ensures PULL_REQUEST_TEMPLATE.md exists (creates it if missing), analyzes git changes, and outputs a filled template ready to copy into the GitHub PR form.	"draft a PR description", "write the PR description", "fill the PR template", "summarize changes for a pull request"
drupal-bundle-classes	Add typed PHP bundle classes to Drupal entity types (nodes, paragraphs, media, taxonomy terms) with OOP hook auto-discovery, so helper methods are callable directly from Twig.	"add bundle class", "create bundle class", "add typed class to content type", "set up bundle class infrastructure"
drupal-security-update	Apply a Drupal core security update: detect current version, find latest release, update packages, run updb, export config, draft PR description.	"update Drupal core", "apply security patch"
git-commit	Stage changes and create a conventional commit: analyze the diff, infer type and scope, generate a semantic message, and execute the commit.	"commit my changes", "create a git commit", "stage and commit"
update-documentation	Update an existing Drupal project README.md when tools, dependencies, deployment methods, testing frameworks, or features are added, changed, or removed. Also creates .github/PULL_REQUEST_TEMPLATE.md if missing.	"update the README", "tool changed", "version bumped", "add testing docs"

See CONTRIBUTING.md to add or modify skills.

Instructions catalog

Instructions are always-active rules automatically injected into the AI's context. They require no invocation — the AI applies them based on the applyTo glob in the frontmatter.

Instruction	Description	Applies to
a11y.instructions.md	Comprehensive web accessibility standards based on WCAG 2.2 AA, with 38+ anti-patterns, legal enforcement context (EAA, ADA Title II), WAI-ARIA patterns, and framework-specific fixes.	All files

See CONTRIBUTING.md to add or modify instructions.

Prompts catalog

Prompts are reusable, IDE-agnostic workflows you invoke manually in any AI tool — paste them, use /prompt, or reference them by name. They are synced to .agents/prompts/_shared/.

Prompt	Description	When to use
setup-agents-md.md	6-phase guided workflow to auto-fill AGENTS.md placeholders from the codebase (content types, modules, tooling, config paths).	Once, after first composer install

See CONTRIBUTING.md to add prompts.

Contributing

This package is built with its own AI standards. Contributor skills in .agents/skills/ govern how AI agents should behave when adding skills, making commits, or updating documentation in this repo.

See CONTRIBUTING.md for conventions, skill format reference, and the pull request checklist.

Versioning

Follows semantic versioning:

• Patch x.x.1 — fixes within existing skills or instructions
• Minor x.1.0 — new skills or instructions added (non-breaking)
• Major 2.0.0 — breaking changes to skill format or plugin behavior

Local development (path repository)

To test changes before publishing, use composer-link from the consuming project root:

# Works for both standard and DDEV projects (auto-detects DDEV)
composer-link ../drupal-ai-standards fourkitchens/drupal-ai-standards

To unlink when done:

composer-unlink fourkitchens/drupal-ai-standards

See CONTRIBUTING.md for detailed testing steps and manual alternatives.

Acknowledgements

The AGENTS.md stub structure draws inspiration from droptica/drupal-agents-md (MIT). Their template informed the AI Response Requirements section, entity discovery commands, and the Drupal best practices patterns included in the stub.