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's 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 (for example, 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. This lets an agent 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 isn't tracked.

Custom skills

Skills are reusable instruction sets that teach an agent a repeatable, project-specific task, such as 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 tracks .claude/skills/ alongside .claude/settings.json, so a skill is shared with the team as soon as it's committed. Everything else under .claude/ stays ignored, which keeps machine-local Claude state out of the repository.