agent-ready

What this skill does

# Agent-Ready

Scaffold the documentation and structural artifacts that make a codebase legible to AI agents. This skill is the **remediation companion** to codebase-readiness -- it does not score, it builds.

---

## Startup: Check for Prior Assessment

Before entering any mode, check if `AGENT_READY_ASSESSMENT.md` exists in the project root.

If it exists:
1. Read it and extract dimension scores
2. Auto-suggest a mode based on the weakest dimensions:
   - Documentation & Context < 50 -> suggest **claude-md** first
   - Architecture Clarity < 50 -> suggest **architecture** first
   - Both < 50 -> suggest **scaffold** (full setup)
3. Tell the user: "I found an existing assessment. Based on your scores, I recommend starting with [mode]. Want to proceed, or choose a different mode?"

If it does not exist, proceed with mode detection.

---

## Mode Detection

Determine which mode to run based on user intent:

| User Intent | Mode | Trigger Phrases |
|-------------|------|-----------------|
| Full documentation setup | **scaffold** | "make this agent-ready", "full setup", "scaffold docs" |
| Generate architecture doc | **architecture** | "create ARCHITECTURE.md", "architecture doc", "codemap" |
| Create/refactor AGENTS.md | **agents-md** | "set up AGENTS.md", "create AGENTS.md", "refactor AGENTS.md" |
| Check existing artifacts | **audit** | "audit docs", "are my docs up to date", "check agent readiness" |

If intent is ambiguous, ask the user which mode they want.

---

## Mode: scaffold

Full documentation setup. This is the comprehensive mode that creates everything a codebase needs for agent legibility.

### Step 1: Reconnaissance

Gather project metadata:

```bash
# Language and framework detection
ls package.json Gemfile requirements*.txt pyproject.toml go.mod Cargo.toml build.sbt pom.xml *.csproj 2>/dev/null

# Directory structure
find . -maxdepth 3 -type d 2>/dev/null | grep -v node_modules | grep -v .git | grep -v vendor | grep -v ".bundle" | grep -v __pycache__ | sort | head -50

# Existing documentation
find . -maxdepth 2 -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "ARCHITECTURE.md" -o -name "README.md" -o -name "CONTRIBUTING.md" 2>/dev/null | grep -v node_modules | grep -v .git
ls -la docs/ doc/ 2>/dev/null
find docs/ doc/ -name "*.md" 2>/dev/null | head -20

# Build/test/lint commands
cat package.json 2>/dev/null | grep -A5 '"scripts"'
cat Makefile 2>/dev/null | grep -E "^[a-zA-Z_-]+:" | head -10
cat Rakefile 2>/dev/null | head -20
ls .eslintrc* .rubocop.yml .prettierrc* pyproject.toml ruff.toml .golangci.yml 2>/dev/null

# CI configuration
ls .github/workflows/*.yml .circleci/config.yml .buildkite/*.yml Jenkinsfile 2>/dev/null

# ADRs
find . -type d -name "decisions" -o -name "adr" -o -name "adrs" 2>/dev/null | grep -v node_modules | grep -v .git
```

### Step 2: Report Inventory

Present a clear inventory to the user:

```
## Documentation Inventory

### Exists
- [List each existing artifact with path and line count]

### Missing
- [List each missing artifact that will be created]

### Will Create
- docs/ directory structure
- docs/README.md (documentation index)
- ARCHITECTURE.md (codemap, invariants, boundaries)
- docs/DOMAIN.md (business domain knowledge, terminology, workflows)
- AGENTS.md (progressive disclosure entry point)
- CLAUDE.md (symlink to AGENTS.md for Claude Code compatibility)
- docs/decisions/001-agent-ready-documentation.md (starter ADR)
```

### Step 3: Create docs/ Structure

Read `assets/docs-structure-template.md` for the recommended layout.

Create the directory structure:
```bash
mkdir -p docs/architecture docs/guides docs/references docs/decisions
```

Create `docs/README.md` as an index. Populate it based on what documentation exists and what will be created.

### Step 4: Generate ARCHITECTURE.md

Execute the **architecture** mode logic (see below) inline. Do not launch a separate agent.

### Step 5: Generate docs/DOMAIN.md

Read `assets/domain-knowledge-template.md` for the template.

Seed the template by scanning the codebase:

```bash
# Find model/entity/type names
find . -type f \( -name "*.rb" -o -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" -o -name "*.java" \) 2>/dev/null \
  | grep -v node_modules | grep -v .git | grep -v vendor \
  | xargs grep -lE "class |model |entity |type |interface |struct " 2>/dev/null | head -20

# Look for model directories
find . -type d \( -name "models" -o -name "entities" -o -name "types" -o -name "schemas" -o -name "domain" \) 2>/dev/null \
  | grep -v node_modules | grep -v .git | grep -v vendor

# Read README for business context
cat README.md 2>/dev/null | head -80
```

Using the discovered model/entity names and README context:
1. Populate the glossary with discovered terms, even if definitions are thin -- mark them with `<!-- TODO: needs domain expert review -->`
2. Sketch domain relationships based on model associations or naming patterns
3. Leave workflow and regulatory sections as template placeholders if not enough context exists

Write the result to `docs/DOMAIN.md`. Note in the output that this file should be reviewed and filled in by domain experts on the team -- it is seeded from code analysis and will have gaps.

### Step 6: Generate AGENTS.md

Execute the **agents-md** mode logic (see below) inline. Do not launch a separate agent.

### Step 7: Create Starter ADR

Create `docs/decisions/001-agent-ready-documentation.md`:

```markdown
# 1. Agent-Ready Documentation Structure

**Date:** [today's date]
**Status:** Accepted

## Context
This codebase is being prepared for AI agent work. Agents need structured, discoverable documentation to work effectively -- they cannot access knowledge that lives outside the repository.

## Decision
Adopt a progressive disclosure documentation structure:
- AGENTS.md as a concise entry point (~100 lines) with markdown links to detailed docs
- CLAUDE.md as a symlink to AGENTS.md for Claude Code compatibility
- ARCHITECTURE.md as a codemap with invariants and boundaries
- docs/DOMAIN.md for business domain knowledge, terminology, and workflows
- docs/ directory for guides, references, and decision records
- Nested AGENTS.md files for major domain directories (as needed)

## Consequences
- All project knowledge must live in-repo (not in Slack, Confluence, or heads)
- Documentation changes should be reviewed like code changes
- AGENTS.md must stay concise; bloat gets extracted to docs/
- ADRs should be written for significant architectural decisions going forward

## Alternatives Considered
- Single large AGENTS.md -- rejected because it crowds agent context and rots quickly
- No structured docs, rely on code comments -- rejected because agents need navigational aids beyond inline comments
```

### Step 8: Summary

Present everything created with file paths, and suggest next steps:
- Review `docs/DOMAIN.md` and add business domain definitions -- this is the most valuable file for human and AI onboarding
- Add domain-specific nested AGENTS.md files for major directories
- Start writing ADRs for future architectural decisions
- Set up CI checks for documentation freshness
- Run `agent-ready audit` periodically to check for drift

---

## Mode: architecture

Generate an ARCHITECTURE.md from actual codebase analysis.

### Step 1: Map the Codebase

```bash
# Top-level structure
find . -maxdepth 2 -type d 2>/dev/null | grep -v node_modules | grep -v .git | grep -v vendor | grep -v ".bundle" | grep -v __pycache__ | sort

# Identify major modules and entry points
find . -maxdepth 2 -type f -name "*.ts" -o -name "*.js" -o -name "*.rb" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.scala" 2>/dev/null | grep -v node_modules | grep -v .git | grep -v vendor | head -50

# Entry points
ls src/index.* src/main.* app/main.* main.* cmd/ 2>/dev/null
ls config/ 2>/dev/null

# Largest files (potential god objects)
find . -name "*.ts" -o -name "*.js" -o -name "*.rb" -o -name "*.py" -o -name "*.go" -o -name "*.java" 2>/de