README

Surge 🌊

a sudden powerful forward or upward movement, especially by a crowd or by a natural force such as the tide.

Drupal Surge: An AI coding standard kit for Drupal development.

It gives AI tools the context they need to work with Drupal, not around it. By combining shared guidelines, discoverable skills, and open standards, Surge helps AI understand your codebase, conventions, and environment from day one.

Surge focuses on open standards and makes them easy to integrate in a flexible way. You can adopt only what you need, extend where it makes sense, and compose your own setup without locking yourself into specific tools or formats.

This is a foundation, not a finished product. A forward movement shaped by shared direction and collective effort within the Drupal ecosystem.

Open Standards

Drupal Surge is built on open standards to stay flexible, transparent, and future-proof.

• Guidelines combine in to the AGENTS.md standard so AI tools can understand your modular setup.
• Skills follow the Agent Skills specification for discoverable, reusable capabilities, you pick the skills you need.

By relying on open standards, Surge stays tool-agnostic and easy to extend as the AI ecosystem evolves.

Installation

composer require drupal/surge --dev

Automatic Setup

Note: You may need to allow the plugin to run by executing:

composer config allow-plugins.drupal/surge true

When you install this package, the Surge commands are automatically available through Composer scripts. The package includes a Composer plugin that automatically registers the necessary scripts in your project's composer.json.

And it will create a surge directory in your root with an example config.php file to help configure the specific features.

Modular Architecture

Drupal Surge is organized into modules under src/:

• Surge (src/Surge/) - Core framework
• Guidelines (src/Guidelines/) - Guidelines scanning and standards management
• Skills (src/Skills/) - Agent Skills discovery and aggregation

Guidelines

We want to shape the Agents.md file, based on your set-up and configurations.

So Surge automatically discovers and merges guidelines from multiple sources:

• Project-level (surge/guidelines/) - Your custom guidelines (highest priority)
• Third-party packages (vendor/*/surge/guidelines/) - Guidelines from Composer packages
• Built-in standards - (TBD)

That way, DDEV users can add DDEV specific guidelines in the future. Those using the Group module, can add specific guidelines for using the Group module. etc.

See src/Guidelines/README.md for detailed documentation.

Skills

Surge aggregates Agent Skills from multiple sources into .claude/skills/ for use with Claude Code, Cursor, and other AI tools.

05 Jan 2026 - Currently there is no standardized folder, see https://github.com/agentskills/agentskills/issues/15 but it seems Cursor and Open Code all support .claude/skills/ as Anthropic developed this standard it makes most sense to support that.

Configuration

Note: Skills are opt-in and require configuration. surge/config.php gets created Automatically, configure it to your needs. It's opt-in for security purposes, as we discover and merge a lot of skills. Enable Skills with $config->enableSkills() to start using Skills commands.

See src/Skills/README.md for detailed documentation.

Usage

After installation and configuration, you can use Surge directly:

Commands

Guidelines

• composer surge agents-install - Installs AGENTS.md with all Guidelines
• composer surge agents-update - Updates AGENTS.md by scanning and merging guidelines from project, third-party packages, and built-in standards

Skills

• composer surge skills-install - Install Agent Skills to .claude/skills/
• composer surge skills-update - Update installed skills from all sources
• composer surge skills-list - List discovered skills with validation status