Agent Ready
hao0401/agent-ready
Prepare repositórios para agentes de IA com contexto, validação e scoring automático
Ver no GitHubFerramenta que prepara repositórios para agentes de IA (Codex, Claude, Cursor, Gemini, Copilot) em um único comando. Gera instruções compartilhadas, pontuação de prontidão, anotações no GitHub e relatórios SARIF para validação de segurança e qualidade do código.
Instalação
npx convez-ai hao0401/agent-ready1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Preparar codebases para uso com GitHub Copilot, Claude Code e outros agentes de IA
- Gerar instruções centralizadas compatíveis com múltiplas plataformas de IA em uma varredura
- Detectar automaticamente comandos de build, teste e lint para documentação de agentes
- Identificar riscos de segurança e injeção de prompt antes que agentes acessem o código
- Medir readiness de repositório com score de 100 pontos e histórico de melhorias
Veredito

Agent Ready é prático e bem focado: automatiza a preparação de repos para agentes de IA com zero dependências de runtime. Útil para equipes que já usam múltiplos agentes (Copilot, Claude, Cursor) e querem garantir contexto consistente e seguro. Recomendado para adoção gradual em projetos existentes.
README
A tradução para o português deste README ainda está na fila.
Agent Ready
Make any repository ready for AI coding agents in one command.
Turn a normal codebase into an agent-friendly workspace with shared instructions, readiness scoring, GitHub annotations, PR artifacts, CI gates, and a public badge.
What It Does
agent-ready scans a repository and writes the context AI coding agents need
before they touch code. It supports Codex, Claude Code, Cursor, Gemini CLI, and
GitHub Copilot from the same repository scan.
It is a repository-readiness tool, not an agent framework or automation platform. It helps agents see project facts, risks, and validation commands more clearly; it does not make model reasoning stronger by itself.
| Problem in a normal repo | What Agent Ready adds |
|---|---|
| Agents guess install, test, build, and lint commands | Detected commands are written into AGENTS.md and reports |
| Tool-specific instruction files drift | Codex, Claude, Gemini, Cursor, and Copilot files share one source scan |
| Risky instructions or fake secrets hide in docs | Prompt-injection and secret-looking findings include file and line context |
| CI failures do not explain what to fix first | Scorecard, summary, PR comment, SARIF, and prioritized fix plan are generated |
| Gradual adoption is hard to measure | Baselines, diffs, and score ratchets distinguish existing debt from regressions |
Honest Limits
| Limit | How Agent Ready handles it |
|---|---|
| New project with limited real-world mileage | Marked Beta, release-gated, and designed for fork-first team adoption |
| Scores can become checklist theater | Score is now strictly 100 points and includes AGENTS.md quality checks, not just file presence |
| Heuristic framework and command detection | Reports "Not detected" instead of pretending certainty; use config overrides and generated plans to correct misses |
| Generated files can add noise | Use --minimal to generate only AGENTS.md and core .agent-ready reports |
| Multi-tool instructions can drift | Keep AGENTS.md as the source of truth; companion files point back to it |
| Lightweight safety scan only | Use it beside TruffleHog, Gitleaks, CodeQL, dependency audit, and normal security review |
validate can execute local commands | Default output is plan-only; pass --execute only after you trust the repository |
Built For
| Use case | Why it fits |
|---|---|
| Open-source maintainers | Give contributors and coding agents one trusted workflow before they edit |
| AI-heavy teams | Keep Codex, Claude, Cursor, Gemini, and Copilot instructions synchronized |
| Platform and DevEx teams | Add a repeatable readiness check to every repo without custom scripts |
| Security-conscious repos | Surface prompt-injection-like docs and secret-looking values before agents read them |
Quick Start
Install from GitHub:
pipx install git+https://github.com/hao0401/agent-ready.git
agent-ready . --all --badge
Prefer the low-noise path when introducing it to an existing repository:
agent-ready . --minimal --badge
Or run from a cloned checkout:
python .\agent-ready.py . --all --badge
python -m agent_ready . --all --badge
On macOS or Linux, use python3 if python is not installed.
That one command creates agent instruction files, score reports, CI artifacts,
PR-ready output, and an Agent Ready badge for your README.md.
Real Demo
The repo includes a reproducible example and generated showcase artifacts.
| Start here | Output |
|---|---|
examples/demo-repo | Example repository before Agent Ready |
examples/demo-output/summary.md | One-page readiness snapshot |
examples/demo-output/scorecard.md | Explainable 0-100 score breakdown |
examples/demo-output/report.md | Full generated readiness report |
examples/demo-output/plan.md | Prioritized P0/P1/P2 fix plan |
examples/demo-output/before-after.md | Before/after transformation |
examples/demo-output/pr-comment.md | PR bot comment body |
examples/demo-output/check.sarif | SARIF output for GitHub code scanning |
Visual assets:
- Static screenshot:
assets/terminal-demo.png - Animated terminal GIF:
assets/terminal-demo.gif - Terminal SVG:
assets/terminal-demo.svg
examples/demo-output/check.mdexamples/demo-output/diff.mdexamples/demo-output/validation-plan.mdexamples/demo-output/PR_BODY.mdexamples/demo-output/agent-ready.ymlexamples/demo-output/agent-ready.config.jsonexamples/demo-output/baseline.jsonexamples/demo-output/mcp-recommendations.md
Regenerate the demo:
python -m pip install Pillow
python .\scripts\build_demo_assets.py --require-images
Example output:
Repo: acme-workbench
Score: 100/100
Files:
- written: AGENTS.md
- written: CLAUDE.md
- written: GEMINI.md
- written: .github/copilot-instructions.md
- written: .cursor/rules/agent-ready.mdc
- written: .agent-ready/report.md
- written: .github/workflows/agent-ready.yml
- updated: README.md
Differentiated Features
| Area | Feature |
|---|---|
| Scoring | Visible Agent Ready score, explainable scorecard, README badge, CI threshold |
| Multi-agent setup | AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, Copilot instructions |
| Safety | Safe-by-default writes, prompt-injection scan, redacted secret-looking findings |
| CI adoption | Baseline mode, baseline diff, score ratchet, GitHub annotations, SARIF |
| Review workflow | PR comment, PR body, patch package, summary, fix plan |
| Local guidance | Doctor mode, plan-only validation, command truthing, monorepo map |
| Extensibility | Project config, MCP recommendations, repo-specific Codex skill generator |
GitHub Action
The root action.yml is a composite action with typed inputs,
outputs, PR comments, workflow summaries, SARIF support, and Marketplace
branding.
name: Agent Ready
on:
pull_request:
push:
branches: [main, master]
permissions:
contents: read
issues: write
security-events: write
jobs:
agent-ready:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: hao0401/agent-ready@v2.0.0
id: agent_ready
with:
path: .
min-score: "80"
format: github
write-report: "true"
write-summary: "true"
write-comment: "true"
write-plan: "true"
write-diff: "true"
sarif: "true"
post-comment: "true"
- name: Upload Agent Ready SARIF
if: always() && steps.agent_ready.outputs.sarif-path != ''
uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: ${{ steps.agent_ready.outputs.sarif-path }}
category: agent-ready
Reusable outputs include passed, score, report-path, summary-path,
comment-path, plan-path, diff-path, sarif-path, config-path,
baseline-path, baseline-score, ratchet, and exit-code.
What It Generates
AGENTS.mdCLAUDE.mdGEMINI.md.github/copilot-instructions.md.cursor/rules/agent-ready.mdc.agent-ready/report.md.agent-ready/agent-ready.json.agent-ready/summary.md.agent-ready/summary.json.agent-ready/pr-comment.md.agent-ready/pr-comment.json.agent-ready/scorecard.md.agent-ready/scorecard.json.agent-ready/check.md.agent-ready/check.json.agent-ready/check.sarif.agent-ready/plan.md.agent-ready/plan.json.agent-ready/diff.md.agent-ready/diff.json.agent-ready/baseline.jsonagent-ready.config.json.agent-ready/demo.md.agent-ready/validation.md.agent-ready/mcp-recommendations.md.agent-ready/skills/<repo>-workflow/SKILL.md.agent-ready/pr/PR_BODY.md.agent-ready/pr/agent-ready.patch.github/workflows/agent-ready.yml
Command Reference
Default one-command path:
python .\agent-ready.py C:\path\to\repo --all --badge
Low-noise path:
python .\agent-ready.py C:\path\to\repo --minimal --badge
Scan only:
python .\agent-ready.py scan C:\path\to\repo
Generate core files:
python .\agent-ready.py generate C:\path\to\repo
Write an explainable score breakdown:
python .\agent-ready.py scorecard C:\path\to\repo
Write a one-page summary:
python .\agent-ready.py snapshot C:\path\to\repo
Create a prioritized fix plan:
python .\agent-ready.py plan C:\path\to\repo --min-score 80
Create a starter config:
python .\agent-ready.py config C:\path\to\repo
Capture and compare a baseline:
python .\agent-ready.py baseline C:\path\to\repo
python .\agent-ready.py diff C:\path\to\repo
python .\agent-ready.py check C:\path\to\repo --baseline
python .\agent-ready.py check C:\path\to\repo --baseline --ratchet
Preview validation commands before running them:
python .\agent-ready.py validate C:\path\to\repo
validate is plan-only by default. Use --dry-run when you want to make that
explicit in scripts, and add --execute only after you trust the repository
commands:
python .\agent-ready.py validate C:\path\to\repo --execute
Run a read-only CI check:
python .\agent-ready.py check C:\path\to\repo --min-score 80
python .\agent-ready.py check C:\path\to\repo --min-score 80 --format github --write-report --write-summary --write-comment --write-scorecard --write-plan
python .\agent-ready.py check C:\path\to\repo --baseline --write-diff
python .\agent-ready.py check C:\path\to\repo --min-score 80 --write-sarif
python .\agent-ready.py check C:\path\to\repo --config agent-ready.config.json
Diagnose local setup:
python .\agent-ready.py doctor C:\path\to\repo
Create a PR-ready package:
python .\agent-ready.py pr C:\path\to\repo
Overwrite existing generated files only when intended:
python .\agent-ready.py C:\path\to\repo --force
Configuration
{
"check": {
"min_score": 80,
"require_agents": true,
"baseline": ".agent-ready/baseline.json",
"ratchet": false
},
"ignore_findings": [
{
"kind": "prompt-injection",
"path": "docs/known-safe-example.md",
"message_contains": "Prompt-injection-like instruction found"
}
],
"overrides": {
"commands": {
"test": ["pnpm -w test"],
"build": ["pnpm -w build"],
"lint": ["pnpm -w lint"]
},
"frameworks": ["Custom Stack"],
"entry_points": ["apps/web/src/main.ts"],
"important_dirs": ["apps/web", "services/api"],
"generated_dirs": ["generated/client"],
"package_managers": ["pnpm"],
"monorepo_hints": ["custom workspace manifest"]
}
}
overrides are prepended to auto-detected facts, so teams can correct heuristic
misses without hiding what Agent Ready found on its own.
Agent Readiness Score
The report gives a 0-100 score based on:
- Detected languages, configs, entry points, and project map.
- Detected run, test, build, lint, and typecheck commands.
- Presence of primary agent instructions.
- Prompt-injection findings.
- Secret-looking findings.
- Conflicting package manager or command guidance across agent files.
Local Development
From the agent-ready directory:
python -B scripts\dev.py test check release clean
python -B scripts\dev.py publish-check
If make is available:
make test
make check
make build
make clean
make publish-check
Project references:
- License:
LICENSE - Changelog:
CHANGELOG.md - Contributing guide:
CONTRIBUTING.md - Security policy:
SECURITY.md - Package config:
pyproject.toml - GitHub Action:
action.yml - GitHub workflows:
.github/workflows
Codex Skill
This repository is also a Codex skill. Install or place the agent-ready folder
in your Codex skills directory, then ask:
Use $agent-ready to scan this repository, generate agent instruction files, and report its agent readiness score.
Design Goals
- No runtime dependencies.
- Safe by default: existing files are skipped unless
--forceis passed. - Useful output even before generation.
- Works on Windows, macOS, and Linux.
- Small enough for agents to understand and modify.