AgentReady Kit

Make your repository ready for AI coding agents.

AgentReady Kit is an open-source CLI toolkit that helps maintainers generate, validate, and synchronize project instruction files for AI coding agents such as OpenAI Codex, Claude Code, GitHub Copilot, Cursor, Aider, and Gemini CLI.

Most repositories keep build commands, test commands, coding rules, security expectations, and pull request guidelines scattered across README.md, CONTRIBUTING.md, team memory, or issue comments. AgentReady Kit creates a single source of truth in .agentready/config.yml and keeps agent-facing instruction files in sync.

---

Why this exists

AI coding agents work better when a repository clearly explains:

• what the project does;
• how to install dependencies;
• how to run, test, lint, and build;
• which files should not be changed;
• which security rules must be respected;
• how pull requests should be prepared;
• which framework-specific conventions should be followed.

AgentReady Kit helps open-source maintainers make those rules explicit, reusable, and easier to validate in CI.

---

Features

• Config-driven instructions: define rules once in .agentready/config.yml.
• Agent file generation: generate AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and Cursor-compatible rules.
• Tech stack templates: start from templates for Next.js, Node.js API, Python FastAPI, Laravel, and generic OSS projects.
• Repository readiness checks: validate required sections such as setup, tests, security rules, PR guidelines, and “do not touch” paths.
• Security scanner: warn about hardcoded secrets, unsafe instructions, bypassed authentication, disabled tests, and dangerous rules.
• AgentReady Score: calculate a 0–100 readiness score for AI-agent context quality.
• CI integration: run checks in GitHub Actions to keep agent instructions safe and up to date.

---

Installation

From source

Clone and build locally to test the latest unreleased changes:

git clone https://github.com/erkininfinity/AgentReadyKit.git
cd AgentReadyKit
npm install
npm run build
node bin/agentready.js check

With npm / npx

npx agentready-kit init

Or install globally:

npm install -g agentready-kit
agentready-kit init

The package is available on npm as agentready-kit.

---

Quick start

Initialize agent instructions in a repository:

agentready-kit init

Validate repository readiness:

agentready-kit check

Sync all instruction files from .agentready/config.yml:

agentready-kit sync

Run diagnostics:

agentready-kit doctor

For local development in this repository, run the full verification suite before opening a pull request:

npm run verify

---

Example output

AgentReady Kit
Repository readiness report

AgentReady Score: 86/100

Generated / detected files:
  ✓ AGENTS.md
  ✓ CLAUDE.md
  ✓ .github/copilot-instructions.md
  ✓ .cursorrules

Checks:
  ✓ Project overview found
  ✓ Install command found
  ✓ Test command found
  ✓ Security rules found
  ✓ Do-not-touch paths found
  ! Add clearer PR review rules
  ! Add framework-specific testing notes

Result:
  Your repository is mostly ready for AI coding agents.

---

Configuration

AgentReady Kit uses .agentready/config.yml as the source of truth.

project:
  name: AgentReady Kit
  type: open-source-tool
  stack:
    - typescript
    - node
  package_manager: npm

commands:
  install: npm install
  dev: npm run dev
  test: npm test
  lint: npm run lint
  typecheck: npm run typecheck
  build: npm run build

agent_rules:
  code_style:
    - Use TypeScript strict mode.
    - Keep changes small and focused.
    - Maintain existing patterns in the codebase.
  security:
    - Do not commit local environment files or credentials.
    - Do not bypass authentication, authorization, tests, or security checks.
  pr:
    - Run verification before proposing changes.
    - Update documentation when behavior changes.
  do_not_touch:
    - .env
    - dist/
    - node_modules/

targets:
  - agents_md
  - claude_md
  - github_copilot
  - cursor_rules

---

Supported instruction files

AgentReady Kit can generate or synchronize:

File	Used for
AGENTS.md	OpenAI Codex and other AI coding agents
CLAUDE.md	Claude Code
.github/copilot-instructions.md	GitHub Copilot repository instructions
.cursorrules / .cursor/rules/*.mdc	Cursor rules

---

Supported templates

Use the --template option to override stack auto-detection:

agentready-kit init --template nextjs

Planned templates:

• Next.js
• Node.js API
• Python FastAPI
• Laravel
• Generic OSS
• Monorepo

---

GitHub Action integration

Add this workflow under .github/workflows/agentready.yml:

name: AgentReady Quality & Safety Check

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  check:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm install

      - name: Run verification
        run: npm run verify

---

Project status

AgentReady Kit is early-stage. The goal of the first public release is to establish:

• the CLI foundation;
• the repository instruction file model;
• validation and scoring rules;
• security guardrails for AI coding agents;
• contribution and release workflows for open-source maintainers.

---

Roadmap

• Add more stack templates.
• Improve validation rules for agent instruction quality.
• Add richer security checks for unsafe agent behavior.
• Add example repositories.
• Add GitHub Action packaging.
• Add optional AI-assisted suggestions for improving AGENTS.md and related files.

---

Maintainer notes

• Contributing guide
• Security policy
• Code of conduct
• OpenAI Codex for OSS notes

---

License

MIT © Erkin Infinity