Reusable GOTCHA rule source → validated artifacts for Cursor, Claude Code, Codex, and Windsurf.
Cross-editor agent governance: cursor rules, AGENTS.md-compatible project instructions, drift-checked builds, and a growing skill pack. Compatible with the community AGENTS.md convention — this repo is not the standard itself and does not control ~/AGENTS.md.
Machine canonical: ~/AGENTS.md v2.2 (2026-05-18) removed crypto/Solana as a default domain; shared src/gotcha*.md artifacts mirror that policy.
git clone https://github.com/subkoks/agents-md.git
cd agents-md
# Strict validation + artifact drift check
make check
# Build all editor artifacts from src/gotcha.md
./scripts/build-rule-artifacts.sh windsurf claude codex cursor cursor-lean
# Optional manual install: deploy Cursor artifacts to local Cursor config
make install-cursor-localProject rule bodies live in src/gotcha.md (full) and src/gotcha-lean.md (default lean install). Never edit dist/rules/* by hand — rebuild with scripts/build-rule-artifacts.sh. For machine-wide behavior, keep ~/AGENTS.md upstream.
| Good fit | Not a fit |
|---|---|
| Vibe coders and indie builders using multiple AI editors | Teams that want a hosted SaaS product |
| Automation-heavy devs (scripts, bots, MCP, CI agents) | “Drop one file and never think about rules again” with zero maintenance |
| Maintainers who want one rule source, many outputs | Replacing your entire security/compliance program |
| Solana/crypto workflows (optional skill pack) | Non-technical users who will not run make check |
| Editor / runtime | Generated artifact | Typical deploy target |
|---|---|---|
| Cursor (lean, always-on) | dist/rules/cursor.lean.md |
.cursor/rules/gotcha.mdc |
| Cursor (full, manual) | dist/rules/cursor.md |
.cursor/rules/gotcha-full.mdc |
| Claude Code | dist/rules/claude.md |
Project CLAUDE.md or optional local copy |
| Codex CLI | dist/rules/codex.md |
Project AGENTS.md or optional local copy |
| Windsurf | dist/rules/windsurf.md |
Windsurf rules path per their docs |
Repo root AGENTS.md documents Cursor Cloud / agent dev commands for this governance repo. For your app repos, copy or adapt generated artifacts — do not treat AGENTS.md here as your product’s agent file unless you fork the pattern.
- Goals — task routing and workflow selection
- Orchestration — agent decision layer
- Tools — deterministic scripts and MCP
- Context — static reference in
docs/ - Hard prompts — focused templates
- Args — runtime behavior (Auto Mode, Hard Stop, token discipline)
Push reliability into scripts and CI; keep flexibility in orchestration.
| Control | What it does |
|---|---|
| CI | lint → validate → build → security-scan (TruffleHog on PRs) |
| Drift | check-local-drift.sh — canonical src/gotcha.md must match dist/rules/* |
| License | MIT — see LICENSE |
| Secrets | No credentials in rules; pre-commit + TruffleHog |
| Governance | make governance-run — validate → build → strict drift |
make check # strict validation + drift
make ci # local mirror: lint + check + skills-drift + test
make test # bats suite (requires bats-core)
make lint # shellcheck + markdownlint + actionlint
make security-scan # scan agent config for high-risk patterns
make governance-run # full pipeline
make health # timestamped report in logs/health/
make skills-drift # skills/registry.tsv vs skills/*.mdagents-md/
├── src/gotcha.md # canonical full rules
├── src/gotcha-lean.md # lean default
├── dist/rules/ # generated (gitignored)
├── scripts/ # validate, build, drift, health
├── skills/ # optional domain skills + registry.tsv
├── docs/ # patterns, hooks, LLM citation, threat model
├── templates/
├── AGENTS.md # agent dev notes for this repo
└── CHANGELOG.md
General-purpose and crypto/web3 skills live under skills/. Triggers are registered in skills/registry.tsv; run make skills-drift after adding skills.
For LLMs and search: llms.txt (repo index) and docs/llm-citation.md (factual Q&A for citations). Keywords: cursor rules, AGENTS.md, cross-editor agent instructions, agent governance.
Within this repo, src/gotcha.md and src/gotcha-lean.md are the source for generated artifacts. They are not upstream of ~/AGENTS.md; keep machine-wide rules in ~/AGENTS.md.
No. Many tools read project AGENTS.md. This project generates editor-specific files from one canonical body and stays compatible with that convention. Say “AGENTS.md-compatible,” not “we own AGENTS.md.”
gotcha-lean→ small always-applied Cursor rule (gotcha.mdc).- Full
gotcha.md→ larger reference (gotcha-full.mdcor manual @-mention). Build with./scripts/build-rule-artifacts.sh cursor cursor-lean.
From a clone of this repo (macOS or Linux):
git clone https://github.com/subkoks/agents-md.git
cd agents-md
./install.sh # ~/.cursor/rules/gotcha.mdc (backs up existing)
./install.sh --full # also installs gotcha-full.mdc for manual @gotcha-full
./install.sh --dry-runDevelopers with a working tree can use make install-cursor-local instead (same destinations). This is a manual local install, not a global rules sync.
make checkCI runs the same gates plus artifact rebuild verification.
README, docs/, AGENTS.md, skills — not inside src/gotcha.md / src/gotcha-lean.md.
See CONTRIBUTING.md. Use feature branches; one logical change per PR; update CHANGELOG.md for user-visible releases.
Release history: CHANGELOG.md · Latest: Releases
If this saves you time, star the repo and watch for releases. Forks and PRs welcome.