fix(ai-ready): preserve hierarchical agent guidance

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

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:

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