convez.ai
AgenteDevOps & InfraestruturaIntermediário
hao0401

Agent Ready

hao0401/agent-ready

Prepare repositórios para agentes de IA com contexto, validação e scoring automático

Ver no GitHub
BomPluginScore · de 0 a 100

Ferramenta 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-ready

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 5 meses
Versão
v2.0.0
Issues abertas
0
Contribuidores
1

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 repoWhat Agent Ready adds
Agents guess install, test, build, and lint commandsDetected commands are written into AGENTS.md and reports
Tool-specific instruction files driftCodex, Claude, Gemini, Cursor, and Copilot files share one source scan
Risky instructions or fake secrets hide in docsPrompt-injection and secret-looking findings include file and line context
CI failures do not explain what to fix firstScorecard, summary, PR comment, SARIF, and prioritized fix plan are generated
Gradual adoption is hard to measureBaselines, diffs, and score ratchets distinguish existing debt from regressions

Honest Limits

LimitHow Agent Ready handles it
New project with limited real-world mileageMarked Beta, release-gated, and designed for fork-first team adoption
Scores can become checklist theaterScore is now strictly 100 points and includes AGENTS.md quality checks, not just file presence
Heuristic framework and command detectionReports "Not detected" instead of pretending certainty; use config overrides and generated plans to correct misses
Generated files can add noiseUse --minimal to generate only AGENTS.md and core .agent-ready reports
Multi-tool instructions can driftKeep AGENTS.md as the source of truth; companion files point back to it
Lightweight safety scan onlyUse it beside TruffleHog, Gitleaks, CodeQL, dependency audit, and normal security review
validate can execute local commandsDefault output is plan-only; pass --execute only after you trust the repository

Built For

Use caseWhy it fits
Open-source maintainersGive contributors and coding agents one trusted workflow before they edit
AI-heavy teamsKeep Codex, Claude, Cursor, Gemini, and Copilot instructions synchronized
Platform and DevEx teamsAdd a repeatable readiness check to every repo without custom scripts
Security-conscious reposSurface 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 hereOutput
examples/demo-repoExample repository before Agent Ready
examples/demo-output/summary.mdOne-page readiness snapshot
examples/demo-output/scorecard.mdExplainable 0-100 score breakdown
examples/demo-output/report.mdFull generated readiness report
examples/demo-output/plan.mdPrioritized P0/P1/P2 fix plan
examples/demo-output/before-after.mdBefore/after transformation
examples/demo-output/pr-comment.mdPR bot comment body
examples/demo-output/check.sarifSARIF output for GitHub code scanning

Visual assets:

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

AreaFeature
ScoringVisible Agent Ready score, explainable scorecard, README badge, CI threshold
Multi-agent setupAGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, Copilot instructions
SafetySafe-by-default writes, prompt-injection scan, redacted secret-looking findings
CI adoptionBaseline mode, baseline diff, score ratchet, GitHub annotations, SARIF
Review workflowPR comment, PR body, patch package, summary, fix plan
Local guidanceDoctor mode, plan-only validation, command truthing, monorepo map
ExtensibilityProject 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.md
  • CLAUDE.md
  • GEMINI.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.json
  • agent-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:

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 --force is passed.
  • Useful output even before generation.
  • Works on Windows, macOS, and Linux.
  • Small enough for agents to understand and modify.
Ver o original no GitHub

Bom para

Relacionados