agent-ready

# Agent-Ready: Repo Setup Best Practices A curated collection of best practices for standard high-quality GitHub repos and AI coding agent workflows. Read this to learn what to set up — then use your own intelligence to generate project-specific configs. ## Workflow 1. **Analyze the project** — read package.json/pyproject.toml, understand language/framework/structure 2. **Check what's missing** — call `check_repo_readiness` MCP tool or run `npx agent-ready check .` 3. **Read the relevant reference** — for each missing area, read the reference doc below 4. **Generate project-specific configs** — use your understanding of THIS project, not generic templates 5. **Verify** — run linters, tests, check CI workflows are valid ## The 9 Areas | Area | Reference | What It Covers | |------|-----------|---------------| | Agent Guidance | `references/agent-guidance.md` | AGENTS.md, CLAUDE.md, copilot-instructions, cursor rules | | Code Quality | `references/code-quality.md` | Linters, formatters, type checkers, .editorconfig | | Testing | `references/testing/` | BDT methodology, test scaffolds, coverage (6 detailed refs) | | CI/CD | `references/ci-cd.md` | GitHub Actions: ci.yml, claude.yml, copilot-setup-steps.yml | | Hooks | `references/hooks.md` | Git pre-commit (Lefthook/Husky) + Claude PostToolUse hooks | | Branch Rulesets | `references/branch-rulesets.md` | GitHub rulesets via API (require PR, reviews, status checks) | | Repo Templates | `references/repo-templates.md` | Issue forms, PR template, CODEOWNERS, CONTRIBUTING, SECURITY | | DevContainer | `references/devcontainer.md` | .devcontainer for reproducible agent environments | | Security | `references/security.md` | Dependabot, push protection, CodeQL, secret scanning | ## Quick Reference: Files a Repo Should Have ### Agent guidance (all tools) - `AGENTS.md` — cross-tool standard (Claude, Copilot, Cursor, Gemini) - `CLAUDE.md` — Claude Code specific (can import AGENTS.md via @AGENTS.md) - `.github/copilot-instructions.md` — GitHub Copilot - `.github/workflows/copilot-setup-steps.yml` — Copilot coding agent environment - `.cursor/rules/*.mdc` — Cursor IDE ### Code quality - Linter + formatter config (biome.json or ruff in pyproject.toml) - Type checker config (tsconfig.json strict or mypy) - `.editorconfig` ### Testing - Test directory structure (tests/unit/, tests/integration/, tests/e2e/) - Test runner config - Coverage config with thresholds ### CI/CD - `.github/workflows/ci.yml` — lint, typecheck, test, build - `.github/workflows/claude.yml` — Claude Code Action for PR review ### Hooks - Pre-commit: lefthook.yml or .husky/ - Claude: `.claude/settings.json` with PostToolUse hooks ### Branch rulesets - Require PR before merge - Require reviews + status checks - Prevent force push and branch deletion ### Repo templates - `.github/ISSUE_TEMPLATE/*.yml` — YAML forms (not Markdown) - `.github/PULL_REQUEST_TEMPLATE.md` - `.github/CODEOWNERS` - `CONTRIBUTING.md`, `SECURITY.md`, `LICENSE` - `.gitignore`, `.gitattributes` ### DevContainer - `.devcontainer/devcontainer.json` ### Security - `.github/dependabot.yml` — grouped updates - Push protection enabled - CodeQL default setup enabled