agent-ready

# 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 **agents-md** first - Architecture Clarity < 50 -> suggest **architecture** first - Both < 50 -> suggest **scaffold** (full setup) - Quality gates at L0-L2 in the snapshot (or Code Clarity / Change Safety < 50 with no debt gate in the evidence) -> suggest **quality-gates** 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" | | Install regression-aware quality gates | **quality-gates** | "set up quality gates", "block new complexity", "baseline our tech debt", "stop agents adding dead code", "regression gate" | | Upgrade a prior agent-ready scaffold | **migrate** | "migrate agent-ready", "upgrade our agent docs", "modernize agent-ready" | | 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. --- ## Startup: Recommend Project Skills After selecting a mode and before making project changes, read `references/recommended-skills.md` and inspect the repository for its documented framework signals. When one or more catalog entries match: 1. Check project-local skills and exclude any that are already installed 2. Present core matches under **Recommended** and qualifying UI matches under **Optional**, with the detected signal, skill, source, and short rationale 3. Ask once whether to install recommended skills only, recommended plus optional skills, a selected subset, or none; do not select optional skills by default 4. Wait for explicit confirmation; never install a skill based only on detection 5. Install confirmed skills from the repository root with the catalog commands, which omit `--global` to preserve project scope 6. Report install results and continue the selected agent-ready mode even if an install fails When nothing matches or all matching skills are installed, continue without prompting. Do not recommend uncataloged skills merely because they seem related. --- ## 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 # Domain documentation and ADRs find . -maxdepth 3 \( -name "CONTEXT.md" -o -name "CONTEXT-MAP.md" -o -name "DOMAIN.md" \) 2>/dev/null | grep -v node_modules | grep -v .git find . -type d \( -name "decisions" -o -name "adr" -o -name "adrs" \) 2>/dev/null | grep -v node_modules | grep -v .git # Compatibility signals for the Matt Pocock design workflow find .agents .claude -maxdepth 3 -type d \( -name "grill-with-docs" -o -name "domain-modeling" -o -name "grilling" \) 2>/dev/null ``` ### 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, and dependency rules) - docs/DOMAIN.md (business workflows, relationships, and compliance context) - AGENTS.md (progressive disclosure entry point) - AGENTS.md (also recognized by Claude Code 2.1.277+; no CLAUDE.md alias needed) - docs/adr/ (only when a qualifying decision is made; no starter ADR) - Documentation check: scripts/docs-check.py, CI job, and a Definition of Done directive - Quality gate: scripts/quality-gate.py, .quality-gate.json, CI job, docs/guides/quality-gates.md, gate self-test (baseline created only after review -- see Step 7) ``` ### Step 3: Create docs/ Structure Read `assets/docs-structure-template.md` for the recommended layout. Create only the directories needed now: ```bash mkdir -p docs/architecture docs/guides docs/references scripts .github/workflows cp "<skill-dir>/assets/docs-check.py" scripts/docs-check.py cp "<skill-dir>/assets/docs-check-ci-template.yml" .github/workflows/docs-check.yml chmod +x scripts/docs-check.py ``` Create `docs/README.md` as an index. Populate it based on what documentation exists and what will be created. Link `CONTEXT.md` only if it already exists. Do not create `docs/adr/` or `CONTEXT.md` until they have content. Before generating domain or architecture documentation, present a **documentation design checkpoint**. Separate facts discovered in reconnaissance from the decisions only the team can make: whether domain terminology is already settled, whether a multi-context map is needed, and whether any durable architectural decision is being made. If compatible `grill-with-docs`, `grilling`, or `domain-modeling` skills are installed and terminology or trade-offs remain unsettled, recommend that workflow. Do not invoke it automatically or block scaffolding that does not need it. ### 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. Do not create or infer glossary entries. If `CONTEXT.md` or `CONTEXT-MAP.md` exists, read the relevant context and use its vocabulary. 2. Sketch relationships only where code associations or existing documentation supports them; mark inferences for review. 3. Leave workflow and regulatory sections as template placeholders if not enough context exists. Write the result to `docs/DOMAIN.md`. Link `CONTEXT.md` if it exists, but do not create it speculatively. Recommend a domain-modeling workflow when the team needs to resolve new canonical terms. ### Step 6: Generate AGENTS.md Execute the **agents-md** mode logic (see below) inline. Do not launch a separate agent. ### Step 7: Install Quality Gates Execute the **quality-gates** mode logic (see below) inline. The Definition of Done written in Step 6 must reference the gate's `check` command, so if Step 6 ran before the command name was known, update AGENTS.md now. Do not skip the baseline review protocol to keep scaffold moving: if the user is not ready to review the baseline, install the engine, config, CI, docs, and tests, leave the baseline uncreated, and record in the summary that `check` will fail until a baseline is created and approved. ### Step 8: Summary Present everything created with file paths, and suggest next steps: - Review `docs/DOMAIN.md` and verify every inferred workflow or relationship - Resolve domain terminology through `CONTEXT.md` only when terms are actually decided - Create an ADR only when the decision is hard to reverse, surprising without context, and the result of a real trade-off - Run `python3 scripts/docs-check.py` after changing Markdown links or documentation paths - Review and approve the quality-gate baseline PR, then add `.quality-baseline.json` to CODEOWNERS - 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>/dev/null \ | grep -v node_modules | grep -v .git | grep -v vendor | grep -v spec | grep -v test \ | xargs wc -l 2>/dev/null | sort -rn | head -15 ``` ### Step 2: Detect Patterns Read source files to identify: - **Layers:** controllers/handlers, services, repositories/models, utilities - **Domains:** distinct business domains grouped in the filesystem - **Entry points:** where the application starts, what the main interfaces are - **Configuration:** how the app is configured, environment handling - **Cross-cutting:** logging, auth, error handling, middleware ### Step 3: Read Existing Context Read README.md and any existing documentation for project context. Before mapping a domain, read the relevant `CONTEXT.md`, or resolve it through `CONTEXT-MAP.md` when present. Read ADRs that affect the area from `docs/adr/`, `docs/decisions/`, or the project's established ADR location. Use canonical domain vocabulary and explicitly surface an ADR conflict rather than silently overriding it. Do not duplicate what README already covers -- ARCHITECTURE.md complements it. ### Step 4: Load References Read `references/architecture-guide.md` for matklad's principles. Read `assets/architecture-md-template.md` for the output template. ### Step 5: Generate ARCHITECTURE.md Using the template and principles, generate an ARCHITECTURE.md with: - **Overview:** One paragraph describing the problem domain (not the tech stack) - **Codemap:** Every significant top-level directory with one-line descriptions. Name important files and types. - **Invariants:** Rules that hold across the codebase. **Always include absences** -- things that deliberately do not exist. - **Boundaries:** Public vs internal APIs. Layer dependency rules. Which modules can import which. - **Cross-cutting concerns:** How logging, auth, errors, and config work across the system. - **Domain terminology:** Use the applicable `CONTEXT.md` vocabulary when one exists. Do not invent a competing glossary. ### Step 6: Present and Confirm Show the draft to the user. Write to `ARCHITECTURE.md` in the project root on confirmation. --- ## Mode: agents-md Create a new AGENTS.md or refactor an existing one for progressive disclosure. Claude Code 2.1.277+ reads AGENTS.md directly, so do not create or require a CLAUDE.md symlink. ### Step 1: Assess Current State Check if AGENTS.md or CLAUDE.md exists: ```bash find . -name "AGENTS.md" -o -name "CLAUDE.md" 2>/dev/null | grep -v node_modules | grep -v .git ``` **If AGENTS.md exists**, analyze it: ```bash wc -l AGENTS.md # Code block percentage echo "Code block lines: $(sed -n '/^```/,/^```/p' AGENTS.md | wc -l)" # Directive density echo "Directive keywords: $(grep -ci 'must\|never\|always\|avoid\|prefer' AGENTS.md)" # Doc links echo "Doc links: $(grep -coE '\[.*\]\([^)]+\.md\)' AGENTS.md)" # Section count echo "Sections: $(grep -c '^##' AGENTS.md)" ``` Read the existing AGENTS.md fully. Identify: - Sections that are bloated (>30 lines on one topic) - Code examples that are too long (>10 lines) - Content that belongs in topic docs, not AGENTS.md - Missing directives (build, test, lint commands) - Missing links to supporting docs **If CLAUDE.md exists but not AGENTS.md**, analyze CLAUDE.md the same way and plan to migrate it to AGENTS.md. **If neither exists**, proceed to generation. ### Step 2: Load References Read `references/progressive-disclosure.md` for Harness Engineering principles. Read `assets/agent-ready-template.md` for the output template that generates AGENTS.md content. ### Step 3: Detect Project Signals Gather the information needed to populate AGENTS.md: ```bash # Build/test/lint commands cat package.json 2>/dev/null | grep -A10 '"scripts"' cat Makefile 2>/dev/null | grep -E "^[a-zA-Z_-]+:" | head -10 ls .eslintrc* .rubocop.yml .prettierrc* ruff.toml .golangci.yml 2>/dev/null # CI config (for workflow hints) ls .github/workflows/*.yml 2>/dev/null # Existing docs to link find docs/ doc/ -name "*.md" 2>/dev/null | head -20 ls ARCHITECTURE.md CONTRIBUTING.md 2>/dev/null # Domain context and ADRs find . -maxdepth 4 \( -name "CONTEXT.md" -o -name "CONTEXT-MAP.md" \) 2>/dev/null | grep -v node_modules | grep -v .git