AGENTS.md

AGENTS.md - AI Agent Instructions

Instructions for AI agents working with the agent-ready codebase.

Project Overview

agent-ready is a repo infrastructure setup tool for agent-guided development. One command to make any repo agent-ready — everything except the code.

Version: 0.1.0 Language: TypeScript Runtime: Node.js >= 20

Quick Commands

npm install                    # Install dependencies
npm run dev -- scan .          # Scan current directory
npm test                       # Run tests (152 tests)
npm run test:coverage          # Coverage with c8
npm run typecheck              # Type check (tsc --noEmit)
npm run lint                   # ESLint
npm run format                 # Prettier
npm run check                  # All gates: typecheck + lint + format
npm run build                  # Build for production

Project Structure

agent-readiness/
├── src/
│   ├── index.ts           # CLI entry (Commander.js)
│   ├── scanner.ts         # Main orchestrator
│   ├── types.ts           # TypeScript interfaces
│   ├── checks/            # Check implementations
│   │   ├── index.ts       # Check registry
│   │   ├── file-exists.ts
│   │   ├── path-glob.ts
│   │   ├── any-of.ts
│   │   ├── github-workflow.ts
│   │   ├── github-action.ts
│   │   ├── build-command.ts
│   │   ├── log-framework.ts
│   │   └── dependency-detect.ts
│   ├── engine/
│   │   ├── index.ts       # Execution engine
│   │   ├── level-gate.ts  # Level gating logic
│   │   └── context.ts     # Scan context
│   ├── output/
│   │   ├── json.ts        # JSON output
│   │   └── markdown.ts    # Terminal output
│   ├── profiles/
│   │   └── index.ts       # Profile loader
│   ├── commands/
│   │   └── init.ts        # Init command
│   └── utils/
│       ├── fs.ts
│       ├── git.ts
│       └── yaml.ts
├── profiles/
│   └── factory_compat.yaml # Default profile (35+ checks)
├── templates/              # Init command templates
├── skill/                  # Claude Code skill
│   └── agent-ready/
│       └── SKILL.md
├── docs/
│   └── index.html         # Landing page
├── test/
│   ├── *.test.ts
│   ├── fixtures/
│   └── VALIDATION_REPORT.md
└── agent-ready.skill      # Packaged skill

Key Concepts

9 Setup Categories (Providers)

Provider	What It Sets Up
Agent Guidance	AGENTS.md, CLAUDE.md, copilot-instructions.md, cursor rules
Code Quality	Biome (JS/TS) or Ruff+mypy (Python), .editorconfig
Testing	Test scaffold, BDT branch matrix, coverage config
CI/CD	ci.yml, claude.yml, copilot-setup-steps.yml
Hooks	Lefthook/Husky pre-commit + Claude PostToolUse hooks
Branch Ruleset	GitHub rulesets via API (require PR, reviews, status checks)
Templates	Issue forms (YAML), PR template, CODEOWNERS, SECURITY.md
DevContainer	.devcontainer/devcontainer.json
Security	dependabot.yml, push protection, CodeQL

Code Conventions

TypeScript

• Strict mode enabled
• Use interfaces over types
• Export types from types.ts
• Avoid any - use unknown

Naming

• Files: kebab-case.ts
• Interfaces: PascalCase
• Functions: camelCase
• Constants: SCREAMING_SNAKE_CASE
• Check IDs: pillar.check_name

Check Implementation

export async function executeMyCheck(
  check: MyCheckConfig,
  context: ScanContext
): Promise<CheckResult> {
  return {
    check_id: check.id,
    passed: true,
    message: 'Check passed',
    suggestions: []
  };
}

Common Tasks

Add New Check Type

1. Add to CheckType union in types.ts
2. Create interface extending BaseCheckConfig
3. Add to CheckConfig union
4. Implement in src/checks/new-check.ts
5. Register in src/checks/index.ts

Add Check to Profile

# profiles/factory_compat.yaml
- id: pillar.check_name
  name: Human Readable Name
  type: file_exists
  path: FILENAME.md
  pillar: docs
  level: L2
  required: false

Run Tests

npm test                    # All tests
npm test -- --grep "file"  # Filter tests

Scan Repository

npm run dev -- scan .                    # Current dir
npm run dev -- scan /path/to/repo        # Specific path
npm run dev -- scan . --output json      # JSON only
npm run dev -- scan . --verbose          # Full output

Files to Know

File	Purpose
src/types.ts	All TypeScript interfaces
src/checks/index.ts	Check registry
src/engine/level-gate.ts	80% gating logic
profiles/factory_compat.yaml	Default profile
test/VALIDATION_REPORT.md	Factory.ai comparison

Dependencies

Runtime: commander, chalk, glob, js-yaml Dev: typescript, tsx, eslint, prettier

Do's and Don'ts

Do

• Keep checks simple and focused
• Add suggestions for failed checks
• Use context.root_path for paths
• Test with fixtures

Don't

• Add external API calls (keep scanning local)
• Modify types.ts without updating consumers
• Hardcode absolute paths
• Skip the required field