diff --git a/ai-ready/SKILL.md b/ai-ready/SKILL.md index 746b7bd..3de68f3 100644 --- a/ai-ready/SKILL.md +++ b/ai-ready/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-ready -version: 0.3.0 +version: 0.4.0 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 diff --git a/ai-ready/guidelines.md b/ai-ready/guidelines.md index e8da0c5..a21973e 100644 --- a/ai-ready/guidelines.md +++ b/ai-ready/guidelines.md @@ -15,7 +15,7 @@ Ensure a project has accurate, up-to-date AGENTS.md files and a clean set of AI - 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.) +- 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, etc.) - **No personal names in generated content.** Replace references to individuals from commit history or other source material with role-based descriptions or drop the attribution and state the finding directly. ## Safety @@ -31,6 +31,19 @@ Ensure a project has accurate, up-to-date AGENTS.md files and a clean set of AI - No duplicate content across sections or across files - Content must reflect the current state of the codebase, not a past version +## AGENTS.md Size Limits + +- Target root AGENTS.md under 150 lines +- Treat 300 lines as the absolute maximum for any single AGENTS.md file +- Highly optimized projects can stay under 60 lines by keeping only commands, + boundaries, project geography, and high-signal examples in root AGENTS.md +- When root AGENTS.md would exceed 150 lines, preserve or create hierarchy: + nested AGENTS.md files for monorepos, `.claude/rules/**` for specialized + single-repo concerns, and tool-specific rule directories when they provide + scoped loading that AGENTS.md cannot express +- Prefer references to existing docs over copying long explanations into + AGENTS.md + ## Working With the Project This workflow gets deployed into different projects. Respect the target project: diff --git a/ai-ready/skills/update.md b/ai-ready/skills/update.md index 5262a87..0a034ae 100644 --- a/ai-ready/skills/update.md +++ b/ai-ready/skills/update.md @@ -114,7 +114,13 @@ These apply to both creation and updates: - 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 +- Measure current and final line counts for every AGENTS.md file; target root AGENTS.md under 150 lines and treat 300 lines as the absolute maximum for any single AGENTS.md file +- For monorepos, split project-wide concerns into the root file and package-specific details into nested AGENTS.md files +- When the projected root AGENTS.md would exceed 150 lines, move scoped details into existing hierarchical files or referenced documentation instead of expanding root AGENTS.md +- For root AGENTS.md files between 150 and 300 lines, perform best-effort scoped-hierarchy remediation, then report why the under-150 target was not met +- If any root or nested AGENTS.md already exceeds 300 lines, move scoped guidance into appropriate hierarchical files or referenced documentation, then remeasure +- Do not report completion while any AGENTS.md remains over the 300-line maximum +- Prefer references to detailed docs over copying long explanations into AGENTS.md #### AGENTS.md format reference @@ -128,7 +134,7 @@ AGENTS.md is standard Markdown with no required fields or structure: 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. +**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 or GitHub Copilot instructions) 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. @@ -143,6 +149,18 @@ When merging: - When sources conflict, prefer the most recently modified file - Deduplicate — do not repeat the same instruction in AGENTS.md and another file +Before choosing **Merge**, check size and hierarchy: + +- Estimate the resulting AGENTS.md line count after consolidation +- If merging would push root AGENTS.md over 150 lines, choose **Keep** or **Update** instead of **Merge** +- Preserve clear hierarchical organizations such as `.claude/rules/**`, `.cursor/rules/**`, `.windsurf/rules/**`, `.clinerules/**`, or nested AGENTS.md files when they keep context focused +- Preserve an existing project hierarchy before creating anything new +- If no existing hierarchy applies and root AGENTS.md would exceed 150 lines, choose **Create** and prefer the nearest nested AGENTS.md for the scoped area +- Create tool-specific files such as `.claude/rules/**` or `.cursor/rules/**` only when that convention already exists in the target project +- Do not fabricate generated paths or tool-specific directories that the target project does not already use +- If a hierarchical file is stale, update it in place rather than flattening it into root AGENTS.md +- In the audit report, explain preserved hierarchy with a note such as: "Kept hierarchical structure to maintain AGENTS.md size limits" + **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 @@ -154,9 +172,10 @@ 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 contradictions between AGENTS.md and kept convention files (e.g., `CLAUDE.md` or GitHub Copilot instructions). 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) +- Final AGENTS.md size gate: remeasure every AGENTS.md after Step 3 and all Step 4 changes. If root AGENTS.md is between 150 and 300 lines, perform best-effort scoped-hierarchy remediation and report why the under-150 target was not met. Do not report completion while any AGENTS.md exceeds 300 lines. Completeness — cross-reference Step 2 findings against the final AGENTS.md: @@ -184,7 +203,7 @@ Example format: 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) +- GitHub Copilot instructions → 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