iamfakeguru/agent-md

Production-grade agent directives for autonomous coding agents: Claude Code, Codex, Cursor, Windsurf, Aider.

agent‑md – Portable contracts for coding‑agents

What it is – agent‑md is a tiny, language‑agnostic framework that lets you embed formal, enforceable contracts inside a code‑base so that AI‑powered coding assistants (Claude Code, Codex, Cursor, Windsurf, etc.) can be guided, verified, and held accountable. It does this by installing a set of rule files, git‑hooks, and helper scripts that turn the usual free‑form prompts into a reproducible, auditable workflow.

Why it matters – As LLM‑based pair‑programmers become common, developers lose visibility into what the model actually did. agent‑md gives a single source of truth (AGENT.md) for the agent’s instructions and couples that with hard‑enforced checks (type‑checking, linting, test runs, visual screenshots) that can block the model from finishing a task until the required evidence is present.

Core concepts

Concept	Role	How it’s enforced
Rules files (`AGENT.md`, `AGENTS.md`, `CLAUDE.md`)	Human‑written guidance on style, planning, safety, etc.	Advisory – the model must read them, but they are not automatically blocked.
Hooks / artifacts	Concrete checks (type‑check, lint, tests, visual evidence, state updates)	Enforced by agent‑specific hook scripts (e.g., `.claude/hooks/block‑destructive.sh`) or fallback git pre‑commit hooks.
Memory files (`memory/*.md`)	Persistent hand‑off between sessions – plan, progress, verification criteria, gotchas.	Hooks verify that these files are updated; missing updates cause a hard block.
Helper scripts (`.agent‑md/bin/*`)	Small shell utilities (discover helpers, run Playwright screenshots, doctor diagnostics) that any agent can invoke.	Executed directly by the model; they return deterministic results used by later hooks.

What you get after running the installer

your‑project/
├─ AGENT.md               # single source of truth for the agent
├─ AGENTS.md              # copies for Codex / Cursor / Windsurf
├─ CLAUDE.md              # wrapper that imports AGENT.md for Claude Code
├─ agent‑md.toml.example  # template for deterministic verification config
├─ .claude/               # Claude‑specific settings & hooks
├─ .codex/                # Codex‑specific hooks & config
├─ .agents/skills/        # native Codex skills (verify, visual‑evidence)
├─ .cursor/… .windsurf/…  # rule files for those agents
├─ .agent‑md/bin/         # helper scripts (discover_helpers.sh, doctor.sh, …)
├─ memory/                # durable state files (plan.md, progress.md, …)
└─ .githooks/pre‑commit   # optional generic fallback hook

All of these are installed with a single curl … | bash command or the provided install.sh script.

How verification works

Configure checks – copy agent‑md.toml.example to agent‑md.toml and fill in commands for typecheck, lint, test, and visual‑artifact requirements.
Run the agent – the model writes code as usual.
Hooks fire – when the model signals completion, the appropriate hook runs the configured commands.
Block or allow – if any command fails, or required visual evidence is missing/old, the hook aborts the model’s finish step and returns an error message. Only when all checks pass does the model’s output get accepted.

Typical workflow

# 1. Install into a fresh repo
curl -sL https://raw.githubusercontent.com/iamfakeguru/agent-md/main/install.sh | bash

# 2. Edit AGENT.md with your project‑specific guidelines
vim AGENT.md

# 3. Define verification commands
cp agent‑md.toml.example agent‑md.toml
# edit the toml to point at your test runner, linter, etc.

# 4. Start coding with Claude Code (or Codex, Cursor, …)
#    The agent will see the rules and, on finish, the hooks will run.

# 5. If UI work is involved, capture a screenshot
./.agent‑md/bin/playwright‑capture.sh http://localhost:3000 .agent/visual/home.png
# write a markdown note describing the visual check

If any step fails, the hook prints a clear message and the model must redo the work.

Who should use it

Teams that rely on LLM‑based code generation and need reproducible, auditable outputs.
Security‑conscious developers who want to block destructive Bash commands or ensure state files are updated.
Product teams building UI who require visual regression evidence in addition to unit tests.
Open‑source maintainers who want a lightweight, language‑agnostic way to embed “contracts” for AI contributors.

Limitations (as documented)

The rules (AGENT.md) are advisory; only the hooks can enforce.
Enforcement is limited to events exposed by the host agent – e.g., Cursor and Windsurf only get optional git‑hook fallback.
Pre‑commit hooks can be bypassed with git commit --no‑verify.
Bash safety hooks are guardrails, not a full sandbox.

Development & CI

Tests are written in Bats (Bash Automated Testing System).
Linting with ShellCheck and JSON validation for hook files.
CI runs the test suite, ShellCheck, alias‑sync checks, and installer smoke tests.

License

MIT – free to use, modify, and redistribute.

Bottom line – agent‑md is a practical, minimal‑dependency toolkit that turns the often‑unstructured interaction with AI coding assistants into a contract‑driven process, giving teams a way to require type‑checks, tests, visual proof, and state updates before the model’s work is considered complete.