diff --git a/.agents/agents/.gitkeep b/.agents/agents/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/.agents/rules/.gitkeep b/.agents/rules/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/.agents/settings.json.EXAMPLE b/.agents/settings.json.EXAMPLE
new file mode 100644
index 000000000..866fd757e
--- /dev/null
+++ b/.agents/settings.json.EXAMPLE
@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(obsah)",
+      "Bash(find)",
+      "Bash(grep)",
+      "Bash(ansible-lint)",
+      "Bash(pytest)",
+      "Bash(make)",
+      "Bash(git diff)",
+    ]
+  }
+}
diff --git a/.agents/skills/.gitkeep b/.agents/skills/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/.claude b/.claude
new file mode 120000
index 000000000..c0ca46856
--- /dev/null
+++ b/.claude
@@ -0,0 +1 @@
+.agents
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index b40884fe1..c569a7377 100644
--- a/.gitignore
+++ b/.gitignore
@@ -47,3 +47,7 @@ foremanctl-*.tar.gz
 
 .var
 .tmp
+
+# AI
+.agents/settings.local.json
+.agents/settings.json
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..408db95d4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,184 @@
+# AI Development Guide
+
+This file provides guidance to AI tools and agents when working with code in this repository. It is intentionally tool-agnostic -- it works with Claude Code, Cursor, GitHub Copilot, and any other AI assistant.
+
+## Project Overview
+
+foremanctl is a deployment tool for Foreman and Katello using Podman quadlets and Ansible. It provides a command-line interface built on top of `obsah` (an Ansible wrapper) for managing containerized Foreman deployments.
+
+The repository contains two main wrapper scripts:
+
+- `foremanctl` - Production deployment and management
+- `forge` - Development environment management and testing
+
+Both scripts wrap `obsah`, which provides a structured way to run Ansible playbooks with parameter validation and persistence.
+
+## AI Specifications
+
+Detailed agent, command, rule, and skill specifications live under `.agents/`. These are tool-agnostic Markdown files with YAML frontmatter that any AI tool can parse or ignore.
+
+### Directory Structure
+
+```shell
+.agents/
+  agents/          # Specialist agent personas with defined scopes
+  rules/           # Coding standards and constraints (all agents must follow)
+  skills/          # Domain knowledge references
+```
+
+### Workflow Chains
+
+These pipelines connect skills into end-to-end workflows. Individual skill files don't describe these relationships.
+
+TODO
+
+## Development Setup
+
+See [Development Guide](DEVELOPMENT.md) for the instructions.
+
+This creates a virtualenv and installs all dependencies including ansible-core 2.16+.
+
+## Common Commands
+
+### Development Environment
+
+```bash
+# Start development VM
+./forge vms start
+
+# Deploy Foreman in development mode
+./foremanctl deploy --foreman-initial-admin-password=changeme --tuning development
+
+# Stop development VM
+./forge vms stop
+```
+
+### Testing
+
+```bash
+# Run all tests (requires a deployed environment)
+./forge test
+
+# Run smoker tests
+./forge smoker
+
+# Run specific test file
+python -m pytest tests/foreman_test.py -vv
+
+# Run tests with specific configuration
+python -m pytest --certificate-source=installer --database-mode=external
+```
+
+Tests use pytest with testinfra and connect to VMs via SSH. The test playbook (`development/playbooks/test/test.yaml`) generates `.tmp/ssh-config` from the Ansible inventory before running pytest.
+
+See [docs/developer/testing.md](docs/developer/testing.md) for the full testing guide.
+
+### Linting
+
+```bash
+# Run ansible-lint (configured in .ansible-lint)
+cd src; ansible-lint
+cd development; ansible-lint
+```
+
+## Architecture
+
+### obsah Integration
+
+Both `foremanctl` and `forge` are bash wrappers that set environment variables and execute `obsah`.
+
+The key difference:
+
+- `foremanctl`: Uses `src/` as data directory, targets production deployment
+- `forge`: Uses `development/` as data directory, includes development-specific playbooks
+
+obsah playbooks are discovered via `metadata.obsah.yaml` files which define:
+
+- Command-line parameters and validation
+- Help text
+- Variable definitions with choices and types
+- Included sub-playbooks
+
+See [docs/developer/playbooks-and-roles.md](docs/developer/playbooks-and-roles.md) for the full playbook and role guide.
+
+### Playbook Organization
+
+**Production playbooks** (`src/playbooks/`):
+
+- `deploy/` - Main deployment playbook
+- `checks/` - System requirement checks
+- `features/` - Feature management
+- `pull-images/` - Container image pulling
+- Prefixed with `_` - Internal/included playbooks (e.g., `_certificate_source`, `_database_mode`, `_tuning`, `_flavor_features`)
+
+**Development playbooks** (`development/playbooks/`):
+
+- `vms/` - VM lifecycle management
+- `test/` - Test execution
+- `smoker/` - Smoker test execution
+- `deploy-dev/` - Development deployment variations
+- `security/`, `sos/`, `lock/` - Utilities
+
+### Roles
+
+Roles in `src/roles/` correspond to services and deployment stages:
+
+- Service roles: `foreman`, `pulp`, `candlepin`, `postgresql`, `redis`, `httpd`
+- Feature roles: `hammer`, `foreman_proxy`
+- Infrastructure: `certificates`, `systemd_target`
+- Checks: `check_hostname`, `check_database_connection`, `check_system_requirements`, `check_subuid_subgid`
+- Lifecycle: `pre_install`, `post_install`
+
+### Configuration System
+
+Configuration is managed through:
+
+1. **Vars files** (`src/vars/`):
+   - `defaults.yml` - Base defaults
+   - `flavors/` - Deployment flavors (currently only `katello.yml`)
+   - `tuning/` - Resource profiles (default, development, medium, large, extra-large, extra-extra-large)
+   - `images.yml` - Container image references
+   - `database.yml`, `foreman.yml` - Service-specific configuration
+
+2. **Podman secrets**: See the `Service Configuration` section in the `DEPLOYMENT.md` file.
+
+### Custom Plugins
+
+- `src/callback_plugins/foremanctl.py` - Ansible callback plugin for foremanctl-specific output
+- `src/filter_plugins/foremanctl.py` - Custom Jinja2 filters
+
+### Features and Flavors
+
+Features are modular capabilities that can be enabled. See [docs/developer/how-to-add-a-feature.md](docs/developer/how-to-add-a-feature.md) for the complete feature development guide.
+
+For the list of current features, read the `src/features.yaml` file.
+
+Flavors define the base feature set, see the flavor files in the `src/vars/flavors` directory.
+
+The `enabled_features` variable is computed as: `flavor_features + features`
+
+### Deployment Variables
+
+## Testing Architecture
+
+Tests use pytest with testinfra for infrastructure testing. Key fixtures in `tests/conftest.py`:
+
+- `server_hostname`, `server_fqdn` - Default to `quadlet` / `quadlet.example.com`
+- `client_hostname`, `client_fqdn` - Default to `client` / `client.example.com`
+- `certificates` - Certificate configuration based on `--certificate-source`
+- SSH configuration generated from Ansible inventory at `.tmp/ssh-config`
+
+Test files follow the pattern `tests/<component>_test.py` and use testinfra's server fixture to execute commands and check system state.
+
+## Developer Documentation
+
+- [How to Add a Feature](docs/developer/how-to-add-a-feature.md) - end-to-end feature development
+- [Playbooks and Roles](docs/developer/playbooks-and-roles.md) - playbook structure, naming, metadata
+- [Testing](docs/developer/testing.md) - test infrastructure, fixtures, patterns
+- [Deployment Design](docs/developer/deployment.md) -- deployment architecture
+- [Container Image Builds](docs/developer/container-image-builds.md) - image naming, registries
+- [Development Environment](docs/developer/development-environment.md) - dev setup with git Foreman
+
+## Git Workflow
+
+Main branch: `master`
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 000000000..47dc3e3d8
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file