From 483ec3ac17a2a57cf53536c0875ccfc660f7351e Mon Sep 17 00:00:00 2001
From: Damien Retzinger <damienwebdev@gmail.com>
Date: Thu, 7 May 2026 09:25:39 -0400
Subject: [PATCH] docs: add AGENTS.md and CLAUDE.md

---
 AGENTS.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |   1 +
 2 files changed, 112 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b29acae
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,111 @@
+# AGENTS.md
+
+## Project Overview
+
+`github-actions-magento2` — a GitHub Actions toolkit for Magento 2 development. Provides reusable composite actions and reusable workflows that Magento module and store developers call from their own CI pipelines.
+
+## Repository Structure
+
+```
+.github/workflows/          # Reusable workflows and internal CI workflows
+_test/demo-package/         # Test fixture used by internal CI workflows
+docs/                       # General documentation
+other-root-level-folders    # Individual GitHub Actions (all are external/public)
+```
+
+Most actions are **composite** (bash scripts in `action.yml`). Two are **TypeScript bundled**: `supported-version` and `setup-install`.
+
+## Commands
+
+```bash
+# Run all tests
+npm ci
+npm test
+
+# Run tests for a single package
+cd actionName && npm test
+
+# Build a TypeScript action (must be committed after source changes)
+cd supported-version && npm run build
+cd setup-install && npm run build
+```
+
+Build uses `esbuild` and outputs `dist/index.js`. The `dist/` file **must be committed** — GitHub Actions runs the bundled output directly.
+
+## Code Style
+
+- TypeScript with strict settings
+- ESLint: `eslint:recommended` + `@typescript-eslint/recommended`
+- No comments unless the "why" is non-obvious
+- Conventional commits
+
+## Hard Rules (all agents)
+
+- Never edit `CHANGELOG.md` — managed by release-please
+- Never commit TypeScript source changes without also committing the rebuilt `dist/index.js`
+- Never add external runtime dependencies to TypeScript actions without flagging bundle size impact
+- Never call `_internal-*` workflows from external repositories
+
+---
+
+## @test-agent
+
+Writes and updates Jest specs for TypeScript actions (`supported-version`, `setup-install`). Scope is limited to `**/*.spec.ts` files.
+
+### Style
+
+Test observable behavior, not implementation details. No filesystem mocks — use real temp dirs if needed. No network access.
+
+```ts
+import { validateKind } from "./validate-kinds";
+
+describe('validateKind', () => {
+    it('returns `true` if its a valid kind', () => {
+        expect(validateKind("latest")).toBe(true);
+    });
+
+    it('throws a helpful exception if its an invalid kind', () => {
+        expect(() => validateKind(<any>"taco")).toThrowError();
+    });
+});
+```
+
+### Never
+
+- Test implementation details
+- Mock the filesystem
+- Write tests that require network access
+
+---
+
+## @supported-version-agent
+
+Manages the Magento/Mage-OS version compatibility data in `supported-version/src/versions/`. Scope is limited to those JSON files.
+
+### After every edit
+
+Run `npm test` inside `supported-version/` before declaring done.
+
+### Never
+
+- Remove a version entry — only add or mark end-of-life
+- Guess version compatibility — only use data from official Magento/Mage-OS release notes
+- Edit TypeScript source in `supported-version/src/`
+
+---
+
+## @workflow-agent
+
+Owns all externally-facing aspects of the repo: every root-level composite action and the three public reusable workflows (`integration.yaml`, `check-extension.yaml`, `check-store.yaml`). Changes here affect downstream callers.
+
+### Boundaries
+
+**Free to act** — implementation changes that do not alter the public interface (inputs, outputs, default behavior)
+
+**Ask first** — any change to inputs, outputs, or default behavior of an external action or reusable workflow
+
+**Never**
+- Remove or rename an existing input/output without a major version bump
+- Change the default value of an existing input
+- Modify `_internal-*` workflows (out of scope)
+- Add a runtime dependency to a TypeScript action without flagging bundle size impact
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md