@@ -0,0 +1,88 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# AGENTS.md
+
+This file provides guidance to AI coding agents when working with code in this repository.
+
+## Development Commands
+
+- **Build**: `just build` (outputs binary as `formatted-commit`)
+- **Run during development**: `just run [flags]`
+- **Format code**: `just fmt`
+- **Update dependencies**: `go mod tidy`
+- **Test**: `go test ./...`
+
+Example usage:
+
+```bash
+just run -t feat -m "add validation" -T "Co-authored-by: Name <email>"
+```
+
+## Project Purpose
+
+This is a CLI tool that formats git commit messages according to Conventional Commits specification and pipes them directly to `git commit -F -`. It enforces:
+
+1. Subject length: max 50 characters in format `type(scope): message`
+2. Body wrapping: strictly 72 columns using Markdown formatter
+3. Trailer validation: follows git's trailer specification
+
+## Architecture
+
+Single-file CLI application (`main.go`) using:
+
+- **cobra**: CLI framework for flags and commands
+- **fang**: Charmbracelet's execution wrapper (provides version handling, etc.)
+- Future: Will need a Markdown formatter for body text (likely from Charmbracelet ecosystem based on dependencies)
+
+## Critical Implementation Details
+
+### Subject Validation (50 char limit)
+
+The subject is constructed as `type(scope): message` or `type: message` (when scope is empty). Breaking changes add a `!` after the type/scope like `type(scope)!: message`.
+
+When validation fails, clearly mark where the subject exceeds 50 characters in error output.
+
+### Body Formatting
+
+The body (`-b` flag) must be:
+
+1. Sanitised because it should only be basic text and bullets
+2. Formatted as Markdown, properly wrapping bullets with hanging indents on
+ following lines like this
+3. Strictly wrapped to 72 columns using a pure-Go formatter
+4. Separated from subject by one blank line
+5. Separated from trailers by one blank line
+
+### Trailer Formatting (Critical)
+
+Trailers follow git's specification precisely:
+
+- Format: `Key: value` (newline-delimited pairs)
+- No whitespace before or inside the key
+- Any number of spaces/tabs allowed between key and separator `:`
+- Values can be multiline with continuation lines starting with whitespace (RFC 822 folding)
+- The trailer group must be:
+ - At the end of input, OR
+ - The last non-whitespace lines before a line starting with `---`
+ - Preceded by one or more empty/whitespace-only lines
+
+Example valid trailer:
+
+```
+Co-authored-by: This is a very long value, with spaces and
+ newlines in it.
+```
+
+### Flag Nuance
+
+- `-B` / `--breaking`: Boolean flag for breaking changes (adds `!` to subject)
+- `-b` / `--body`: String flag for commit body text
+- `-T` / `--trailer`: Repeatable flag for trailers
+
+### Final Output
+
+The formatted commit message must be piped to `git commit -F -` to read from stdin.