robotlearning123/agent-ready: agent ready for repo

The missing production control layer for AI-written software.

Without it: even a single coding agent can slowly destroy a large codebase through behavioral drift and uncontrolled patches.

With it: 1000 imperfect agents can work in parallel safely.

┌─────────────────────────────────────────────────────────────────┐
│                    AGENT-DRIVEN DEVELOPMENT                      │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
│  │  SPEC    │ -> │  TASKS   │ -> │  AGENTS  │ -> │  VERIFY  │  │
│  │  .md     │    │  Queue   │    │  Execute │    │  Gates   │  │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              FROZEN CONTRACTS (types, schemas)            │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    CI GATEKEEPING                         │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

# Scan any repository
npx agent-ready scan .

# See what's needed for the next level
agent-ready init --dry-run

# Generate missing files
agent-ready init --level L2

Level	Name	What Agents Can Do
L1	Agent-Readable	Agents can understand the codebase (CLAUDE.md, README)
L2	Agent-Configurable	Agents have tool configurations (.cursorrules, settings)
L3	Agent-Executable	Agents can run tasks (MCP, commands, SPEC.md)
L4	Agent-Coordinated	Multiple agents can work together (contracts, ownership)
L5	Agent-Autonomous	Agents can self-improve (feedback loops, conflict resolution)

Pillar	What It Checks
Documentation	README, AGENTS.md, SPEC.md, CONTRIBUTING
Code Style	Linters, formatters, EditorConfig
Build System	Package manifest, CI/CD, build scripts
Testing	Test framework, contract tests, coverage
Security	CODEOWNERS, secrets, Dependabot, SAST
Observability	Logging, tracing, metrics
Environment	.env.example, devcontainer
Task Discovery	Issue templates, TASKS.md
Product	Feature flags, analytics
Agent Config	.claude/, MCP, boundaries, ownership
Code Quality	Coverage, complexity, tech debt tracking

Agent Control Surface Checks

Beyond “file exists” checks, agent-ready verifies production control mechanisms:

# What agents CAN and CANNOT modify
.claude/boundaries.json
.agent-boundaries.yml
.github/CODEOWNERS  # with agent assignments

# How agents find work
TASKS.md
tasks.yaml
.github/ISSUE_TEMPLATE/*agent*.md

# Interfaces that must not change
contracts/**/*.ts
schemas/**/*.json
*.contract.test.ts

# Multi-agent collaboration
.agent-ownership.json
AGENTS.md  # with ownership mapping
.github/workflows/*conflict*.yml

Agent-ready supports GitHub’s spec-kit methodology:

Check	File	Level
Project Constitution	`CONSTITUTION.md`	L3
Feature Specifications	`SPEC.md`, `specs/**/spec.md`	L3
Implementation Plans	`PLAN.md`, `specs/**/plan.md`	L4
API Contracts	`openapi.yaml`, `swagger.json`	L4
Task Lists	`TASKS.md`, `specs/**/tasks.md`	L3

# Use npx (no install required)
npx agent-ready scan .

# Or install globally
npm install -g agent-ready

name: Agent Ready

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Agent Ready
        uses: robotlearning123/agent-ready@v1
        with:
          fail-below-level: 'L2'
          comment-on-pr: 'true'

Input	Description	Default
`path`	Path to scan	`.`
`profile`	Profile to use	`factory_compat`
`output-format`	`json`, `markdown`, or `both`	`both`
`fail-below-level`	Fail if below level	`none`
`comment-on-pr`	Post PR comment	`false`

Output	Description
`level`	Achieved level (`L1`–`L5`)
`score`	Overall score (0-100)
`project-type`	`cli`, `library`, `webapp`, `web-service`, `monorepo`
`passed`	Whether threshold was met

# Submit a scan
curl -X POST https://agent-ready.org/api/scan \
  -H "Content-Type: application/json" \
  -d '{"repo_url":"https://github.com/owner/repo"}'

# Check status
curl https://agent-ready.org/api/scan/{scan_id}

# Scan with verbose output
agent-ready scan . --verbose

# Use specific profile
agent-ready scan --profile factory_compat

# Output JSON only
agent-ready scan --output json

# Initialize missing files
agent-ready init --level L3 --dry-run

Agent Readiness Report
══════════════════════════════════════════════════
Repository: owner/repo
Profile:    factory_compat v1.0.0

┌─────────────────────────────────────────────────┐
│          Level: L3                              │
│          Score: 78%                             │
│          Type:  webapp                          │
└─────────────────────────────────────────────────┘

Pillar Summary
──────────────────────────────────────────────────
  Documentation       L4   90%  ████████░░
  Agent Config        L3   75%  ███████░░░
  Testing             L3   80%  ████████░░
  ...

Action Items (Next Level)
──────────────────────────────────────────────────
  [L4] Create contract tests for API
  [L4] Add agent ownership mapping
  [L4] Define frozen contracts

A codebase is truly agent-ready when:

1000 imperfect AI agents can work on it in parallel without destroying it.

This requires:

Clear specifications (what to build)
Frozen contracts (what not to break)
Strict CI gates (catch all mistakes)
Agent boundaries (who owns what)
Verification loops (continuous checking)

See VISION.md for the complete philosophy.

# profiles/my_profile.yaml
name: my_profile
version: "1.0.0"

checks:
  - id: custom.spec_exists
    name: SPEC.md exists
    type: file_exists
    pillar: docs
    level: L3
    path: SPEC.md

  - id: custom.contract_tests
    name: Contract tests
    type: path_glob
    pillar: test
    level: L4
    pattern: "**/*.contract.test.ts"
    min_matches: 1

agent-ready scan --profile my_profile

npm install        # Install dependencies
npm run dev        # Run in development
npm test           # Run tests
npm run build      # Build for production

agent-ready/
├── src/
│   ├── index.ts          # CLI entry
│   ├── checks/           # Check implementations
│   ├── engine/           # Level gating, project type detection
│   └── utils/            # FS, git, YAML utilities
├── profiles/
│   └── factory_compat.yaml   # Default profile (11 pillars, 5 levels)
├── templates/            # Init command templates
├── examples/workflows/   # GitHub Action examples
├── VISION.md             # Agent-driven development philosophy
└── test/                 # Tests and fixtures

MIT

Agent-Ready: From entropy generator to scalable production worker.

Source link

Agent Control Surface Checks

Leave a Reply Cancel reply