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

@@ -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/*.md` 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,10 @@ 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
+- Target root AGENTS.md under 150 lines; 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
+- For single repos approaching 150 lines, preserve or create hierarchical files such as `.claude/rules/*.md` for specialized concerns instead of expanding root AGENTS.md
+- Prefer references to detailed docs over copying long explanations into AGENTS.md
 
 #### AGENTS.md format reference
 
@@ -143,6 +146,14 @@ 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/*.md`, `.cursor/rules/**`, `.windsurf/rules/**`, `.clinerules/**`, or nested AGENTS.md files when they keep context focused
+- 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