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 www.vortextemplate.com/docs (this site). The AGENTS.md file instructs agents to fetch operational guides from the website and cache them locally in .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 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 vendor/drevops/vortex-tooling/src/, 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 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 file is automatically loaded by Claude Code at the start of every session. It references AGENTS.md for the full development guide.

.claude/settings.json

The .claude/settings.json file is a checked-in Claude Code settings file that pre-approves the stack commands, so an agent can build, provision, lint and test through ahoy without asking for confirmation on every call:

{
  "permissions": {
    "allow": [
      "Bash(ahoy:*)"
    ],
    "deny": []
  }
}

Personal, machine-local settings belong in .claude/settings.local.json, which is not tracked.

Custom skills

Skills are reusable instruction sets that teach an agent a repeatable, project-specific task - for example, a release checklist or a legacy content import procedure.

Add a skill by creating a SKILL.md file in its own directory under .claude/skills/:

.claude/
└── skills/
    └── import-legacy-content/
        └── SKILL.md

---
name: import-legacy-content
description: Use when importing legacy content from the CSV exports
---

Instructions the agent follows when the skill is invoked.

The shipped .gitignore ignores everything under .claude/ except settings.json, so new skills stay local by default. To share skills with your team, un-ignore the directory in your .gitignore:

!.claude/skills/