Skip to main content

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 tracks .claude/skills/ alongside .claude/settings.json, so a skill is shared with the team as soon as it is committed. Everything else under .claude/ stays ignored, which keeps machine-local Claude state out of the repository.