Add AI-Ready workflow documentation and guidelines for creating or updating AGENTS.md files

ai-ready/README.md

@@ -0,0 +1,62 @@
+# AI-Ready
+
+Keep a project AI-friendly by maintaining accurate `AGENTS.md` files and a clean set of AI convention files.
+
+## What It Does
+
+The `/update` command scans a codebase and:
+
+1. **Creates or updates `AGENTS.md`** at the project root with project-specific instructions for AI coding agents — build commands, test procedures, code style, architecture, and conventions.
+2. **Audits AI convention files** (`.cursorrules`, `CLAUDE.md`, `.github/copilot-instructions.md`, etc.) — keeps tool-specific ones that are auto-loaded by their tools, merges redundant ones into `AGENTS.md`, updates stale ones, or creates missing ones.
+3. **Detects monorepos** and recommends nested `AGENTS.md` files for subprojects.
+
+## Usage
+
+### Cursor
+
+Reference the workflow or run the command directly:
+
+```text
+@ai-ready                    # triggers the workflow
+@ai-ready/commands/update    # runs /update explicitly
+```
+
+### Claude Code
+
+```text
+@ai-ready/commands/update
+```
+
+## When to Run
+
+- **First time:** When onboarding a project that doesn't have an `AGENTS.md` yet
+- **After changes:** After significant codebase changes (new dependencies, restructured directories, changed build/test commands)
+- **Periodic audit:** To verify AI convention files are still accurate and not redundant
+
+## Directory Layout
+
+```text
+ai-ready/
+  SKILL.md              # Entry point — workflow overview
+  guidelines.md         # Principles, limits, safety, quality standards
+  README.md             # This file
+  commands/
+    update.md           # /update command — loads guidelines + skill
+  skills/
+    update.md           # The scan and update skill
+```
+
+## How It Works
+
+1. Checks for an existing `AGENTS.md` (reads it as the baseline if found) and scans for all AI convention files in the project
+2. Analyzes the codebase: package manifests, CI configs, linting, tests, build scripts, directory structure
+3. Creates `AGENTS.md` from scratch or applies surgical updates to the existing one
+4. Audits other AI convention files — keeps tool-specific ones (e.g., `CLAUDE.md`, `.cursor/rules/`), merges redundant ones into `AGENTS.md`, flags stale ones
+5. Validates all file paths and commands referenced in `AGENTS.md`
+6. Presents a summary of all changes
+
+## AGENTS.md Spec
+
+This workflow follows the [AGENTS.md](https://agents.md/) convention — a standard Markdown file that gives AI coding agents the context they need to work effectively in a codebase. It complements `README.md` by providing agent-specific instructions: build steps, test commands, code conventions, and architecture details.
+
+`AGENTS.md` is supported by Cursor, Claude Code, GitHub Copilot, OpenAI Codex, Google Jules, Windsurf, JetBrains Junie and many others.

ai-ready/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ai-ready
+description: Scans a codebase structure, audits AI convention files, and creates or updates AGENTS.md with project-specific build commands, test patterns, and coding standards. Use when onboarding a project for AI agents, setting up AI instructions, after significant codebase changes, or to audit AI convention files like AGENTS.md or .cursorrules.
+---
+# AI-Ready Workflow
+
+Ensure a project is AI-ready by maintaining accurate AGENTS.md files.
+
+## Usage
+
+Run `/update` to execute the full workflow. See `skills/update.md` for detailed steps.
+
+## Commands
+
+Commands are in `commands/`.
+
+- `/update` → `commands/update.md` — Scan codebase, audit AI convention files, create or update AGENTS.md. Accepts optional arguments for targeted updates (e.g., a subdirectory or focus area).

ai-ready/commands/update.md

@@ -0,0 +1,9 @@
+# /update
+
+Read `../guidelines.md`, then read `../skills/update.md` and follow it.
+
+Arguments are optional. If provided, they are passed as additional context (e.g., a target subdirectory or specific area to focus on).
+
+User-provided arguments (substituted by the tool runtime):
+
+$ARGUMENTS

ai-ready/guidelines.md

@@ -0,0 +1,39 @@
+# AI-Ready Workflow
+
+Ensure a project has accurate, up-to-date AGENTS.md files and a clean set of AI convention files.
+
+## Principles
+
+- Accuracy over completeness: only document what you can verify from the codebase
+- Project-specific over generic: no "write tests" or "handle errors" advice — document THIS project's actual approaches
+- Surgical updates: change only what needs changing, preserve everything else
+- Idempotent: running the workflow twice in a row produces no additional changes
+- Show code, not concepts: reference specific file paths, not abstract descriptions
+
+## Hard Limits
+
+- Never delete a file without first consolidating its unique content into AGENTS.md
+- Never fabricate file paths, commands, or conventions that don't exist in the codebase
+- Never add generic or aspirational advice — if it's not discoverable, don't document it
+- Never modify source code, tests, or non-AI configuration — this workflow only touches documentation and AI convention files (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md, etc.)
+
+## Safety
+
+- Show your plan before making destructive changes (file deletions, merges)
+- When merging AI convention files, display what will be consolidated before deleting originals
+- Flag uncertainty: if you're unsure whether a pattern is intentional or accidental, ask rather than document it
+
+## Quality
+
+- Every file path referenced in AGENTS.md must exist in the project
+- Every command referenced must be runnable
+- No duplicate content across sections or across files
+- Content must reflect the current state of the codebase, not a past version
+
+## Working With the Project
+
+This workflow gets deployed into different projects. Respect the target project:
+
+- Adopt the project's existing terminology and naming conventions
+- Preserve the project's existing AGENTS.md structure and voice when updating
+- When in doubt about project conventions, check git history and existing code

ai-ready/skills/update.md

@@ -0,0 +1,193 @@
+---
+name: update
+description: Scan the codebase, audit AI convention files and create or update AGENTS.md.
+---
+
+# Update AI-Readiness
+
+You are making this project AI-ready by ensuring it has accurate, up-to-date AGENTS.md files and a clean set of AI convention files.
+
+## Process
+
+### Step 1: Discover Current State
+
+Check whether an AGENTS.md exists at the project root.
+
+- **If it exists:** Read it in full. This is your baseline — every section is assumed correct unless the codebase proves otherwise.
+- **If it does not exist:** You will create one from scratch in Step 3.
+
+Then scan for all AI convention files in the project (one glob search):
+
+```text
+**/{.github/copilot-instructions.md,AGENT.md,AGENTS.md,CLAUDE.md,.cursorrules,.windsurfrules,.cursor/rules/**,.windsurf/rules/**,.clinerules,.clinerules/**}
+```
+
+Note every file found and its path.
+
+### Step 2: Analyze the Codebase
+
+Gather the information needed to write or update AGENTS.md. Inspect these concrete signals — skip any that don't exist in the project:
+
+- **Directory tree** (top 2–3 levels) — project layout and architecture
+- **Package manifests** (package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, etc.) — dependencies, scripts, build commands
+- **CI/CD configs** (.github/workflows/, .gitlab-ci.yml, Jenkinsfile) — build, test, and lint steps as actually run in CI
+- **Linting/formatting configs** (.eslintrc, .prettierrc, ruff.toml, .editorconfig, .pre-commit-config.yaml) — code style rules
+- **Test directories** (test/, tests/, \_\_tests\_\_/, spec/) — framework, naming conventions, how to run tests
+- **Build/task runners** (Makefile, justfile, Taskfile.yml, scripts/) — available commands
+- **Container configs** (Dockerfile, docker-compose.yml) — environment setup
+- **Entry points** (main.\*, index.\*, src/app.\*) — where execution starts
+- **Developer docs** (README.md, CONTRIBUTING.md, DEVELOPMENT.md, HACKING.md) — existing conventions and instructions
+
+Also check recent git history (`git log --oneline -20`) to spot recently changed areas that may need documentation.
+
+Only collect information that is **concrete and verifiable**. Do not infer or assume anything you cannot confirm from the codebase.
+
+If analysis yields fewer than 2 concrete sections worth of content, report that the project has insufficient signals for a useful AGENTS.md and ask the user for guidance before proceeding.
+
+### Step 3: Create or Update AGENTS.md
+
+#### If creating from scratch
+
+Use the section template below. Only include sections where you found concrete, project-specific content. Omit sections that would be empty or generic.
+
+```markdown
+# Project Name
+
+One-line description of what this project is.
+
+## Dev Environment
+
+Prerequisites, install steps, environment variables.
+
+## Build
+
+Build commands and what they produce.
+
+## Test
+
+How to run tests: framework, commands, patterns for test file naming/placement.
+
+## Code Style
+
+Linter, formatter, naming conventions, file organization patterns.
+
+## Architecture
+
+Key directories, components, data flow, important abstractions.
+
+## PR and Commit Conventions
+
+Branch naming, commit message format, review process.
+
+## Security
+
+Areas where AI agents should exercise caution (e.g., "auth logic lives in `src/auth/` — changes here require manual review"). Do NOT document internal mechanisms, credentials, token formats, or implementation details of security controls.
+```
+
+#### If updating an existing AGENTS.md
+
+Compare what you found in Step 2 against the current content. Focus on what has **changed** or is **missing**. Apply minimal, surgical updates:
+
+- Do NOT rewrite or rephrase sections that are still accurate — leave them exactly as they are
+- Preserve existing structure, section ordering, and formatting
+- Place new content in the most logical existing section rather than creating new sections
+- Remove or update references to files, directories, commands, or dependencies that no longer exist
+- Verify every file path mentioned in the existing AGENTS.md still resolves
+
+#### Writing rules
+
+These apply to both creation and updates:
+
+- Write in imperative, second-person voice: "Run X", "Use Y", "See `path/to/file`"
+- Include specific file paths and commands from THIS project — no placeholders
+- Avoid generic advice ("write tests", "handle errors") — document this project's actual approaches
+- Document only discoverable patterns, not aspirational practices
+- Reference key files and directories that exemplify important patterns
+- Keep it concise: prefer a command over a paragraph
+- Include specific examples from the codebase when describing patterns
+- Aim for under 500 lines per AGENTS.md file. For monorepos, split project-wide concerns into the root file and package-specific details into nested files rather than writing one large file
+
+#### AGENTS.md format reference
+
+AGENTS.md is standard Markdown with no required fields or structure:
+
+- Any headings work — agents parse the full text
+- In monorepos, the closest AGENTS.md to the edited file takes precedence
+- Explicit user prompts override AGENTS.md instructions
+
+### Step 4: Audit AI Convention Files
+
+For each AI convention file found in Step 1, choose one action. For directory-based conventions (`.cursor/rules/`, `.windsurf/rules/`, `.clinerules/`), evaluate each file within the directory individually — different files may warrant different actions:
+
+**Keep** — The file serves a tool-specific purpose that AGENTS.md cannot replace. This includes files that are auto-loaded by their respective tools (e.g., `CLAUDE.md` by Claude Code, `.github/copilot-instructions.md` by GitHub Copilot) or files with capabilities AGENTS.md can't express (e.g., `.cursor/rules/` with glob-scoped rules). Merging these into AGENTS.md would lose the tool integration. Leave them untouched.
+
+**Merge** — The file contains generic agent instructions that belong in AGENTS.md. Consolidate its unique content into AGENTS.md, then delete the original file.
+
+**Update** — The file is tool-specific but contains stale or inaccurate content. Update it in place.
+
+**Create** — A useful file is missing. Create it (e.g., nested AGENTS.md for a monorepo subproject).
+
+When merging:
+
+- Show the user what content will be consolidated and which file will be deleted before proceeding
+- Before deleting any file, ensure all its unique content is captured in AGENTS.md
+- When sources conflict, prefer the most recently modified file
+- Deduplicate — do not repeat the same instruction in AGENTS.md and another file
+
+**Monorepo awareness:** If the project uses workspaces (package.json workspaces, pnpm-workspace.yaml, Cargo `[workspace]`, multiple go.mod files), check whether subprojects have their own AGENTS.md. Root AGENTS.md covers project-wide concerns; nested files cover package-specific details. For existing nested AGENTS.md files, apply the same create-or-update logic from Step 3 scoped to the subproject. Recommend creating nested files where they're missing.
+
+### Step 5: Validate
+
+Before finishing, verify **accuracy** and **completeness**.
+
+Accuracy:
+
+- Every file path referenced in AGENTS.md exists in the project
+- Every command referenced is runnable (appears in package.json scripts, Makefile, CI config, etc.)
+- No contradictions between sections
+- No contradictions between AGENTS.md and kept convention files (e.g., `CLAUDE.md`, `.github/copilot-instructions.md`). If a kept file conflicts with AGENTS.md, update the kept file to align — AGENTS.md is the source of truth
+- No content duplicated across sections
+- Running this skill again would produce no further changes (idempotency check)
+
+Completeness — cross-reference Step 2 findings against the final AGENTS.md:
+
+- If the project has a build system, AGENTS.md documents how to build
+- If the project has tests, AGENTS.md documents how to run them
+- If the project uses a linter or formatter, AGENTS.md documents the commands
+- If the project has CI, AGENTS.md reflects what CI checks
+- If the project has environment setup steps, AGENTS.md covers prerequisites
+
+A missing section is acceptable only when the codebase provides no concrete information for it. If the information exists in the codebase but is absent from AGENTS.md, add it.
+
+Fix any issues you find before proceeding to Step 6.
+
+### Step 6: Report
+
+Present a summary to the user with two parts:
+
+**1. AGENTS.md changes** — What was added, modified, or removed. If created from scratch, summarize the sections written and key content in each.
+
+**2. AI convention file audit** — List every AI convention file found (and any created), the action taken, and why. Always include every file — even tool-auto-loaded ones that were kept unchanged — so the user has a complete picture.
+
+Example format:
+
+```text
+AI convention file audit:
+- AGENTS.md                          → Created (new file with 6 sections)
+- CLAUDE.md                          → Kept (auto-loaded by Claude Code)
+- .github/copilot-instructions.md    → Kept (auto-loaded by GitHub Copilot)
+- .windsurfrules                     → Merged (generic instructions moved to AGENTS.md)
+- .cursor/rules/                     → Kept (contains glob-scoped rules AGENTS.md can't express)
+- packages/api/                      → Recommended: add nested AGENTS.md for API-specific conventions
+```
+
+## Output
+
+- AGENTS.md created or updated at the project root
+- AI convention files merged, updated, or flagged as recommendations
+- Summary of all changes presented to the user
+- All changes are applied and ready to commit
+
+## When Done
+
+Present your report to the user. All changes should already be applied and ready to commit.