drevops · AlexSkrypnyk · Feb 11, 2026 · Feb 11, 2026 · coderabbitai · Feb 11, 2026
diff --git a/.vortex/docs/content/development/ai.mdx b/.vortex/docs/content/development/ai.mdx
@@ -0,0 +1,53 @@
+---
+sidebar_label: AI
+sidebar_position: 7
+---
+
+# AI
+
+**Vortex** provides built-in support for AI coding agents. The integration is
+configured through structured markdown files that give agents the context they
+need to work effectively within the project.
+
+## How it works
+
+The AI integration follows the same two-tier documentation pattern used
+throughout **Vortex**:
+
+- **What** applies to the project is defined in the `docs/` directory. The
+  agent reads all files in `docs/` to understand project-specific decisions
+  such as testing conventions, CI configuration, deployment rules, and
+  release processes.
+- **How** to perform operations is sourced from the
+  https://www.vortextemplate.com/docs (this site). The
+  `AGENTS.md` file instructs agents to fetch operational guides from the
+  website and cache them locally in `.data/ai-artifacts/`.
+
+This means AI agents receive the same layered guidance as human developers:
+project-level decisions first, then Vortex-level procedures.
+
+## Configuration files
+
+### `AGENTS.md`
+
+The [`AGENTS.md`](https://github.com/drevops/vortex/blob/main/AGENTS.md) file
+in the project root is the primary configuration for AI coding agents. It is
+an agent-agnostic file that any AI tool can use.
+
+Key sections include:
+
+- **Daily development tasks** — a reference of `ahoy` commands for building,
+  testing, and managing the local environment.
+- **Critical rules** — constraints that agents must always follow (e.g., never
+  modify `scripts/vortex/`, always export config after admin UI changes).
+- **Key directories** — the project's directory layout.
+- **Documentation** — instructions for agents to check `docs/` files for
+  project-specific decisions and to fetch operational documentation from
+  https://www.vortextemplate.com/docs. Fetched documentation is cached locally so
+  that agents can reuse it across sessions without repeated requests.
+
+### `CLAUDE.md`
+
+The [`CLAUDE.md`](https://github.com/drevops/vortex/blob/main/CLAUDE.md) file
+is automatically loaded by Claude Code at the start of every session. It
+references `AGENTS.md` for the full development guide.
diff --git a/.vortex/installer/src/Prompts/Handlers/AiCodeInstructions.php b/.vortex/installer/src/Prompts/Handlers/AiCodeInstructions.php
@@ -4,41 +4,29 @@
 
 namespace DrevOps\VortexInstaller\Prompts\Handlers;
 
-class AiCodeInstructions extends AbstractHandler {
-
-  const NONE = 'none';
+use DrevOps\VortexInstaller\Utils\File;
 
-  const CLAUDE = 'claude';
+class AiCodeInstructions extends AbstractHandler {
 
   /**
    * {@inheritdoc}
    */
   public function label(): string {
-    return 'AI code assistant instructions';
+    return 'Provide AI agent instructions?';
   }
 
   /**
    * {@inheritdoc}
    */
   public function hint(array $responses): ?string {
-    return 'Provides AI coding assistants with better context about the project.';
-  }
-
-  /**
-   * {@inheritdoc}
-   */
-  public function options(array $responses): ?array {
-    return [
-      self::CLAUDE => 'Anthropic Claude',
-      self::NONE => 'None',
-    ];
+    return 'Provides AI coding agents with better context about the project.';
   }
 
   /**
    * {@inheritdoc}
    */
   public function default(array $responses): null|string|bool|array {
-    return self::CLAUDE;
+    return TRUE;
   }
 
   /**
@@ -49,21 +37,18 @@ public function discover(): null|string|bool|array {
       return NULL;
     }
 
-    if (is_readable($this->dstDir . '/CLAUDE.md')) {
-      return self::CLAUDE;
-    }
-
-    return self::NONE;
+    return File::exists($this->dstDir . '/AGENTS.md') || File::exists($this->dstDir . '/CLAUDE.md');
   }
 
   /**
    * {@inheritdoc}
    */
   public function process(): void {
-    $v = $this->getResponseAsString();
+    $v = $this->getResponseAsBool();
     $t = $this->tmpDir;
 
-    if ($v !== self::CLAUDE) {
+    if (!$v) {
+      @unlink($t . '/AGENTS.md');
       @unlink($t . '/CLAUDE.md');
-  public function process(): void {
-    $v = $this->getResponseAsString();
-    $v = $this->getResponseAsBool();
-    $t = $this->tmpDir;
-
-    if ($v !== self::CLAUDE) {
-    if (!$v) {
-      @unlink($t . '/AGENTS.md');
-      @unlink($t . '/CLAUDE.md');
+  public function process(): void {
+    try {
+      $v = $this->getResponseAsBool();
+    }
+    catch (\RuntimeException $e) {
+      // Backward compatibility for legacy string values (e.g. "claude"/"none").
+      $legacy = $this->getResponseAsString();
+      $v = !in_array(strtolower($legacy), ['none', 'false', '0', 'no'], true);
+    }
+    $t = $this->tmpDir;
+
+    if (!$v) {
+      `@unlink`($t . '/AGENTS.md');
+      `@unlink`($t . '/CLAUDE.md');
-  public function process(): void {
-    $v = $this->getResponseAsString();
-    $v = $this->getResponseAsBool();
-    $t = $this->tmpDir;
-
-    if ($v !== self::CLAUDE) {
-    if (!$v) {
-      @unlink($t . '/AGENTS.md');
-      @unlink($t . '/CLAUDE.md');
+  public function process(): void {
+    try {
+      $v = $this->getResponseAsBool();
+    }
+    catch (\RuntimeException $e) {
+      // Backward compatibility for legacy string values (e.g. "claude"/"none").
+      $legacy = $this->getResponseAsString();
+      $v = !in_array(strtolower($legacy), ['none', 'false', '0', 'no'], true);
+    }
+    $t = $this->tmpDir;
+
+    if (!$v) {
+      `@unlink`($t . '/AGENTS.md');
+      `@unlink`($t . '/CLAUDE.md');
     }
   }

diff --git a/.vortex/installer/src/Prompts/Handlers/Tools.php b/.vortex/installer/src/Prompts/Handlers/Tools.php
@@ -286,7 +286,7 @@ public static function getToolDefinitions(string $filter = 'all'): array {
         ],
         'strings' => ['/^.*phpunit.*\n?/m'],
         'lines' => [
-          'CLAUDE.md' => [
+          'AGENTS.md' => [
             '# PHPUnit testing',
             'ahoy test            # Run PHPUnit tests',
             'ahoy test-unit',
@@ -334,7 +334,7 @@ public static function getToolDefinitions(string $filter = 'all'): array {
           '/^.*\bgherkinlint\b.*\n?/m',
         ],
         'lines' => [
-          'CLAUDE.md' => [
+          'AGENTS.md' => [
             '# Behat testing',
             'ahoy test-bdd',
           ],

diff --git a/.vortex/installer/src/Prompts/PromptManager.php b/.vortex/installer/src/Prompts/PromptManager.php
@@ -205,7 +205,7 @@ public function runPrompts(): void {
       ->add(fn($r, $pr, $n): bool => confirm(...$this->args(PreserveDocsProject::class)), PreserveDocsProject::id())
 
       ->intro('AI')
-      ->add(fn($r, $pr, $n): int|string => select(...$this->args(AiCodeInstructions::class)), AiCodeInstructions::id());
+      ->add(fn($r, $pr, $n): bool => confirm(...$this->args(AiCodeInstructions::class)), AiCodeInstructions::id());
 
     // @formatter:on
     // phpcs:enable Generic.Functions.FunctionCallArgumentSpacing.TooMuchSpaceAfterComma
@@ -468,7 +468,7 @@ public function getResponsesSummary(): array {
     $values['Preserve project documentation'] = Converter::bool($responses[PreserveDocsProject::id()]);
 
     $values['AI'] = Tui::LIST_SECTION_TITLE;
-    $values['AI code assistant instructions'] = $responses[AiCodeInstructions::id()];
+    $values['AI agent instructions'] = Converter::bool($responses[AiCodeInstructions::id()]);
 
     $values['Locations'] = Tui::LIST_SECTION_TITLE;
     $values['Current directory'] = $this->config->getRoot();

diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/AGENTS.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/AGENTS.md
@@ -0,0 +1,85 @@
+# star wars - Development Guide
+
+## Daily Development Tasks
+
+```bash
+# Environment
+ahoy up     # Start containers
+ahoy down   # Stop containers
+ahoy info   # Show URLs and status
+ahoy login  # Get admin login URL
+
+# Build & Database
+ahoy download-db  # Download fresh database from remote
+ahoy build        # Complete site rebuild
+ahoy provision    # Re-provision (import DB + apply config)
+ahoy import-db    # Import database from file without applying config
+ahoy export-db    # Export current local database
+
+# Drush commands
+ahoy drush cr     # Clear cache
+ahoy drush updb   # Run database updates
+ahoy drush cex    # Export configuration to code
+ahoy drush cim    # Import configuration from code
+ahoy drush uli    # Get one-time login link
+ahoy drush status # Check site status
+
+# Composer
+ahoy composer install
+ahoy composer require drupal/[module_name]
+
+# Code quality
+ahoy lint     # Check code style
+ahoy lint-fix # Auto-fix code style
+
+# PHPUnit testing
+ahoy test            # Run PHPUnit tests
+ahoy test-unit       # Run PHPUnit Unit tests
+ahoy test-kernel     # Run PHPUnit Kernel tests
+ahoy test-functional # Run PHPUnit Functional tests
+ahoy test -- --filter=TestClassName  # Run specific PHPUnit test class
+
+# Behat testing
+ahoy test-bdd # Run Behat tests
+ahoy test-bdd -- --tags=@tagname  # Run Behat tests with specific tag
+```
+
+## Critical Rules
+
+- **Never modify** `scripts/vortex/` - use `scripts/custom/` for your scripts
+- **Never use** `ahoy drush php:eval` - use `ahoy drush php:script` instead
+- **Always export config** after admin UI changes: `ahoy drush cex`
+
+## Key Directories
+
+- `web/modules/custom/` - Custom modules
+- `web/themes/custom/` - Custom themes
+- `config/default/` - Drupal configuration
+- `scripts/custom/` - Project scripts
+- `patches/` - Module patches
+
+## Documentation
+
+This project uses two documentation sources:
+
+### Project-specific documentation (`docs/`)
+
+The `docs/` directory contains **what** applies to this project:
+
+- `docs/testing.md` - Testing conventions and agreements
+- `docs/ci.md` - CI provider and configuration
+- `docs/deployment.md` - Hosting provider and deployment rules
+- `docs/releasing.md` - Version scheme and release process
+- `docs/faqs.md` - Project-specific FAQs
+
+**Always check these files first** to understand project-specific decisions.
+
+### Vortex documentation (vortextemplate.com)
+
+For **how** to perform operations, fetch from https://www.vortextemplate.com/docs.
+
+Use the sitemap to discover available pages: https://www.vortextemplate.com/sitemap.xml
+
+**Caching:** Save fetched docs to `.data/ai-artifacts/docs-[topic].md` with header
+`<!-- Source: [URL] | Cached: [YYYY-MM-DD] -->`.
+Re-fetch if user reports docs are outdated.
diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/CLAUDE.md
@@ -1,91 +1,3 @@
-# star wars - Development Guide
+# AI Agent Configuration
 
-<!-- CLAUDE_CONTEXT
-Drupal project built with Vortex template. Uses Docker locally, ahoy commands.
-For detailed guides, fetch from https://www.vortextemplate.com and cache in .claude/artifacts/.
--->
-
-## Daily Development Tasks
-
-```bash
-# Environment
-ahoy up     # Start containers
-ahoy down   # Stop containers
-ahoy info   # Show URLs and status
-ahoy login  # Get admin login URL
-
-# Build & Database
-ahoy download-db  # Download fresh database from remote
-ahoy build        # Complete site rebuild
-ahoy provision    # Re-provision (import DB + apply config)
-ahoy import-db    # Import database from file without applying config
-ahoy export-db    # Export current local database
-
-# Drush commands
-ahoy drush cr     # Clear cache
-ahoy drush updb   # Run database updates
-ahoy drush cex    # Export configuration to code
-ahoy drush cim    # Import configuration from code
-ahoy drush uli    # Get one-time login link
-ahoy drush status # Check site status
-
-# Composer
-ahoy composer install
-ahoy composer require drupal/[module_name]
-
-# Code quality
-ahoy lint     # Check code style
-ahoy lint-fix # Auto-fix code style
-
-# PHPUnit testing
-ahoy test            # Run PHPUnit tests
-ahoy test-unit       # Run PHPUnit Unit tests
-ahoy test-kernel     # Run PHPUnit Kernel tests
-ahoy test-functional # Run PHPUnit Functional tests
-ahoy test -- --filter=TestClassName  # Run specific PHPUnit test class
-
-# Behat testing
-ahoy test-bdd # Run Behat tests
-ahoy test-bdd -- --tags=@tagname  # Run Behat tests with specific tag
-```
-
-## Critical Rules
-
-- **Never modify** `scripts/vortex/` - use `scripts/custom/` for your scripts
-- **Never use** `ahoy drush php:eval` - use `ahoy drush php:script` instead
-- **Always export config** after admin UI changes: `ahoy drush cex`
-
-## Key Directories
-
-- `web/modules/custom/` - Custom modules
-- `web/themes/custom/` - Custom themes
-- `config/default/` - Drupal configuration
-- `scripts/custom/` - Project scripts
-- `patches/` - Module patches
-
-## Documentation
-
-This project uses two documentation sources:
-
-### Project-specific documentation (`docs/`)
-
-The `docs/` directory contains **what** applies to this project:
-
-- `docs/testing.md` - Testing conventions and agreements
-- `docs/ci.md` - CI provider and configuration
-- `docs/deployment.md` - Hosting provider and deployment rules
-- `docs/releasing.md` - Version scheme and release process
-- `docs/faqs.md` - Project-specific FAQs
-
-**Always check these files first** to understand project-specific decisions.
-
-### Vortex documentation (vortextemplate.com)
-
-For **how** to perform operations, fetch from https://www.vortextemplate.com.
-
-Use the sitemap to discover available pages:
-https://www.vortextemplate.com/sitemap.xml
-
-**Caching:** Save fetched docs to `.claude/artifacts/docs-[topic].md` with header
-`<!-- Source: [URL] | Cached: [YYYY-MM-DD] -->`.
-Re-fetch if user reports docs are outdated.
+@AGENTS.md
diff --git a/...r_process/ai_instructions_none/-CLAUDE.md → ...ocess/ai_instructions_disabled/-AGENTS.md b/...r_process/ai_instructions_none/-CLAUDE.md → ...ocess/ai_instructions_disabled/-AGENTS.md
diff --git a/...ex/installer/tests/Fixtures/handler_process/ai_instructions_disabled/-CLAUDE.md b/...ex/installer/tests/Fixtures/handler_process/ai_instructions_disabled/-CLAUDE.md
diff --git a/...ocess/ai_instructions_none/.ignorecontent → ...s/ai_instructions_disabled/.ignorecontent b/...ocess/ai_instructions_none/.ignorecontent → ...s/ai_instructions_disabled/.ignorecontent
diff --git a/.../handler_process/hosting_acquia/CLAUDE.md → .../handler_process/hosting_acquia/AGENTS.md b/.../handler_process/hosting_acquia/CLAUDE.md → .../handler_process/hosting_acquia/AGENTS.md
@@ -1,4 +1,4 @@
-@@ -57,8 +57,8 @@
+@@ -52,8 +52,8 @@
 
  ## Key Directories
 

diff --git a/...s/hosting_project_name___acquia/CLAUDE.md → ...s/hosting_project_name___acquia/AGENTS.md b/...s/hosting_project_name___acquia/CLAUDE.md → ...s/hosting_project_name___acquia/AGENTS.md
@@ -1,4 +1,4 @@
-@@ -57,8 +57,8 @@
+@@ -52,8 +52,8 @@
 
  ## Key Directories
 

diff --git a/.vortex/installer/tests/Fixtures/handler_process/names/AGENTS.md b/.vortex/installer/tests/Fixtures/handler_process/names/AGENTS.md
@@ -0,0 +1,6 @@
+@@ -1,4 +1,4 @@
+-# star wars - Development Guide
++# New hope - Development Guide
+
+ ## Daily Development Tasks
+
diff --git a/.vortex/installer/tests/Fixtures/handler_process/names/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/names/CLAUDE.md
diff --git a/...ures/handler_process/tools_none/CLAUDE.md → ...rocess/tools_groups_no_be_tests/AGENTS.md b/...ures/handler_process/tools_none/CLAUDE.md → ...rocess/tools_groups_no_be_tests/AGENTS.md
@@ -1,4 +1,4 @@
-@@ -37,16 +37,6 @@
+@@ -32,16 +32,6 @@
  ahoy lint     # Check code style
  ahoy lint-fix # Auto-fix code style
 

diff --git a/...ols_groups_no_be_tests_circleci/CLAUDE.md → ...ols_groups_no_be_tests_circleci/AGENTS.md b/...ols_groups_no_be_tests_circleci/CLAUDE.md → ...ols_groups_no_be_tests_circleci/AGENTS.md
@@ -1,4 +1,4 @@
-@@ -37,16 +37,6 @@
+@@ -32,16 +32,6 @@
  ahoy lint     # Check code style
  ahoy lint-fix # Auto-fix code style
 

diff --git a/.../handler_process/tools_no_behat/CLAUDE.md → .../handler_process/tools_no_behat/AGENTS.md b/.../handler_process/tools_no_behat/CLAUDE.md → .../handler_process/tools_no_behat/AGENTS.md
@@ -1,4 +1,4 @@
-@@ -44,9 +44,6 @@
+@@ -39,9 +39,6 @@
  ahoy test-functional # Run PHPUnit Functional tests
  ahoy test -- --filter=TestClassName  # Run specific PHPUnit test class
 

diff --git a/...process/tools_no_behat_circleci/CLAUDE.md → ...process/tools_no_behat_circleci/AGENTS.md b/...process/tools_no_behat_circleci/CLAUDE.md → ...process/tools_no_behat_circleci/AGENTS.md
@@ -1,4 +1,4 @@
-@@ -44,9 +44,6 @@
+@@ -39,9 +39,6 @@
  ahoy test-functional # Run PHPUnit Functional tests
  ahoy test -- --filter=TestClassName  # Run specific PHPUnit test class
 

diff --git a/...andler_process/tools_no_phpunit/CLAUDE.md → ...andler_process/tools_no_phpunit/AGENTS.md b/...andler_process/tools_no_phpunit/CLAUDE.md → ...andler_process/tools_no_phpunit/AGENTS.md
@@ -1,4 +1,4 @@
-@@ -37,13 +37,6 @@
+@@ -32,13 +32,6 @@
  ahoy lint     # Check code style
  ahoy lint-fix # Auto-fix code style