From 43cc1e0ebb83e287ed412119af43f0e8979af669 Mon Sep 17 00:00:00 2001
From: Luis Lavena <luislavena@gmail.com>
Date: Wed, 21 Jan 2026 22:25:58 -0300
Subject: [PATCH 1/2] Add project instructions for AI agents

Make it easy for AI agents to operate on this repository.
---
 AGENTS.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..734d645
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,98 @@
+# AGENTS.md
+
+Guidance for AI agents and contributors working on Drift.
+
+## Project overview
+
+Drift is a SQL-driven schema migration tool for Crystal. Framework-agnostic, works standalone (CLI) or as embedded library. Uses plain SQL files with migration markers instead of a DSL. Supports batch tracking for atomic rollback operations.
+
+## Repository structure
+
+```
+src/
+├── cli.cr                  # CLI entry point
+├── drift.cr                # Main module and public API
+└── drift/
+    ├── migration.cr        # SQL parser
+    ├── migrator.cr         # Migration orchestrator
+    ├── context.cr          # Migration collection manager
+    ├── embed.cr            # Macro for embedding migrations
+    ├── commands/           # CLI commands (migrate, rollback, reset, status, new, version)
+    └── support/migrations_loader.cr
+
+spec/                       # Tests (spec_helper.cr, drift_spec.cr, drift/*_spec.cr)
+```
+
+## Core components
+
+**Migration** (`src/drift/migration.cr`): Parses SQL files with markers:
+
+```sql
+-- drift:up
+CREATE TABLE users (id INTEGER PRIMARY KEY);
+
+-- drift:down
+DROP TABLE users;
+```
+
+Multi-statement blocks use `-- drift:begin` and `-- drift:end`.
+
+**Context** (`src/drift/context.cr`): Manages migration collection with lazy-loading and hash-like access.
+
+**Migrator** (`src/drift/migrator.cr`): Orchestrates migrations against database, manages `drift_migrations` table, supports callbacks.
+
+## Development
+
+Requires: Crystal >= 1.4.0, < 2.0.0 | SQLite3 dev libs | Docker
+
+```bash
+make setup      # Initialize and install dependencies
+make dev        # Start with hot reload
+make console    # Interactive session
+make stop       # Stop containers
+```
+
+All commands run in container via `docker compose run --rm app --`:
+
+```bash
+# Build
+shards build drift              # Debug
+shards build --release drift    # Release (outputs to bin/drift)
+
+# Test
+crystal spec                           # All tests
+crystal spec spec/drift/migration_spec.cr  # Specific file
+crystal spec --verbose                 # Verbose
+
+# Format (enforced by CI)
+crystal tool format src/ spec/         # Apply
+crystal tool format --check src/ spec/ # Check only
+```
+
+## Pull request guidelines
+
+**Branch naming:** Use dashes, not slashes (`feature-add-postgres-support`).
+
+**Changelog:** Required for every PR (use `changie`):
+
+```bash
+changie new --kind <kind> --body "<description>" [--custom issue=N]
+```
+
+Kinds: `added`, `improved`, `changed`, `deprecated`, `removed`, `fixed`, `security`, `internal`
+
+**Commits:** Imperative mood, 50-char subject, 72-char body wrap. Explain what/why, not how.
+
+**Before submitting:**
+1. Tests pass
+2. Code formatted
+3. Changelog entry added
+4. Rebased on main
+
+**CI checks:** Format, tests, changelog.
+
+## Contribution policy
+
+- Bug fixes welcome via PR
+- New features require GitHub issue discussion first
+- Database adapters welcome but discuss first

From 961182faeb11a9c09fde01628f7e49c26564b5c5 Mon Sep 17 00:00:00 2001
From: Luis Lavena <luislavena@gmail.com>
Date: Wed, 21 Jan 2026 22:46:13 -0300
Subject: [PATCH 2/2] Add missing entry for CHANGELOG

---
 .changes/unreleased/internal-20260121-224605.yaml | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changes/unreleased/internal-20260121-224605.yaml

diff --git a/.changes/unreleased/internal-20260121-224605.yaml b/.changes/unreleased/internal-20260121-224605.yaml
new file mode 100644
index 0000000..659201c
--- /dev/null
+++ b/.changes/unreleased/internal-20260121-224605.yaml
@@ -0,0 +1,5 @@
+kind: internal
+body: Add project instructions for AI agents
+time: 2026-01-21T22:46:05.774281-03:00
+custom:
+    Issue: ""