agent-ready

agent-ready is a skill-first, MCP-powered repository transformation kit.

It helps an AI agent inspect an existing repository, preserve and merge current project rules, create shared AI project context, configure agent-specific entry files, recommend skills and MCP servers, and validate the result with an Agent Ready Score.

The transformed repository should improve day-to-day AI coding across Codex, Claude Code, Kiro, Cursor, GitHub Copilot, Windsurf, and similar tools without requiring every developer to learn a new workflow.

Product Shape

The project is intentionally not a simple scaffolder.

Skill orchestrates.
MCP executes.
CLI automates.
Repo artifacts persist.

• skills/agent-ready-transformer/ defines the AI-operated transformation workflow.
• src/ contains the deterministic CLI/core used by humans, CI, and future MCP tools.
• presets/ defines default, frontend, backend, and large-repo recommendations.
• templates/ contains short adapter files for each target agent.
• .ai/ and agent adapters are the durable outputs generated inside a target repository, not this source repository.

Intended User Flow

1. A project owner asks their coding agent to run agent-ready: goal.
2. The skill emits a standard transformation goal that can be edited.
3. The owner confirms or adjusts target agents, presets, safety rules, and MCP policy.
4. The agent runs agent-ready: plan to scan the repo and produce a safe transformation plan.
5. After approval, the agent runs agent-ready: transform to create .ai/, adapters, reports, and recommendations.
6. Future developers use their normal IDE or coding agent. Baseline benefits come from committed repo files; enhanced benefits come from optional MCP and skill setup.
7. Before releases or periodically, agent-ready sync refreshes generated indexes and graph artifacts without calling AI.

Current v0.1 Scope

This repository currently provides the foundation:

• A working CLI with goal, scan, sync, and doctor.
• A transformer skill with command-oriented workflow references.
• Presets for default, frontend, backend, and large-repo projects.
• Adapter templates for Codex, Claude Code, Kiro, Cursor, Copilot, and Windsurf.
• Research-backed method notes and MCP tool contract draft.

The CLI does not perform full AI transformation by itself. That is deliberate: semantic rule merging and curated context writing should be performed by an AI agent using the skill, with deterministic CLI/MCP tools supplying facts and safe write primitives.

Quick Start With npm Alpha

After the alpha package is published:

npx -p @taoqiupo/agent-ready@alpha agent-ready goal
npx -p @taoqiupo/agent-ready@alpha agent-ready scan --cwd /path/to/project
npx -p @taoqiupo/agent-ready@alpha agent-ready sync --cwd /path/to/project --check
npx -p @taoqiupo/agent-ready@alpha agent-ready doctor --cwd /path/to/project

For day-to-day maintenance, the low-friction path is:

npx -p @taoqiupo/agent-ready@alpha agent-ready sync --cwd /path/to/project --release
npx -p @taoqiupo/agent-ready@alpha agent-ready sync --cwd /path/to/project --check --fail-on-stale
npx -p @taoqiupo/agent-ready@alpha agent-ready doctor --cwd /path/to/project --min-score 75

sync is deterministic. It does not call AI and does not rewrite curated .ai/*.md context.

Local Development Commands

npm install
npm run build

node dist/cli.js goal
node dist/cli.js scan --json
node dist/cli.js sync --check
node dist/cli.js doctor --json
node dist/mcp/server.js

During development:

npm run dev -- goal
npm run dev -- scan
npm run dev -- sync --changed-only
npm run dev -- doctor --min-score 75

MCP stdio entrypoint after install/build:

agent-ready-mcp

Exposed tools:

• standard_goal
• scan_repo
• sync_repo
• doctor_repo

Skill Installation From GitHub

The npm package is for low-friction CLI/MCP usage. The AI-operated transformation flow can still be installed directly from GitHub:

npx skills add https://github.com/<owner>/agent-ready \
  --skill agent-ready-transformer \
  --full-depth \
  -g \
  -y

Then ask your coding agent:

agent-ready: goal

Repository Outputs Created In Target Projects

An adopted repository is expected to contain:

.ai/
  project.md
  architecture.md
  repo-map.md
  conventions.md
  workflows.md
  quality-gates.md
  troubleshooting.md
  domain-glossary.md
  integration-contracts.md
  generated/

.agent-ready/
  config.json
  inventory.json
  index/
  reports/
  mcp/
  skills/

AGENTS.md
CLAUDE.md
.kiro/steering/
.cursor/rules/
.github/copilot-instructions.md
.windsurfrules
.mcp.example.json

Baseline vs Enhanced Readiness

Baseline readiness requires no MCP installation:

• Short adapter files route agents to .ai/.
• .ai/ contains project context, workflows, quality gates, and generated summaries.
• agent-ready sync keeps generated facts fresh.

Enhanced readiness is opt-in:

• Serena for symbol-level retrieval.
• Context7 for current library documentation.
• Playwright MCP or CLI for browser verification.
• ast-grep for structural search and codemods.
• Repomix for targeted handoff packs.
• ccusage for token/cost measurement.
• Graph backends for large repositories.

See docs/research-backed-method.md and docs/transformation-flow.md.