Bug: /ai-ready consolidates hierarchical AGENTS.md files into a single 300+ line file

[amej]

Summary

The /ai-ready skill is incorrectly consolidating hierarchical AGENTS.md files (e.g., .claude/rules/*.md, nested module-specific files) into a single root AGENTS.md, resulting in files exceeding 300 lines. This contradicts best practices for AGENTS.md size and context window efficiency.

Expected behavior: Preserve hierarchical file structure with specialized AGENTS.md files in subdirectories
Actual behavior: All instructions get merged into root AGENTS.md and hierarchical files are deleted
Impact: Creates bloated AGENTS.md files that degrade AI performance through instruction dilution, increased latency, and higher costs

Why This Matters

AGENTS.md is a configuration file injected into the context window of AI coding agents (Cursor, Claude Code, GitHub Copilot, Windsurf) at the start of every session. Treating it like a sprawling wiki degrades AI performance.

Performance Impact of Large Files

When AGENTS.md becomes too long:

1. Instruction Dilution: Critical constraints (e.g., "never modify the database schema") get buried and deprioritized among generic advice
2. Increased Costs and Latency: Loading massive context files increases inference costs by 20%+ and slows response times
3. Redundancy: Duplicating information from README.md or codebase wastes tokens without adding value

Recommended Guidelines

How to Spend Your 150 Lines

Include (High Value):

• Executable Commands: Exact terminal commands to build, lint, test (e.g., npm run test -- --testPathPattern=<filename>)
• Strict Boundaries: What the agent should never touch (e.g., "Do not modify files in /vendor" or "Ask for approval before git push")
• Project Geography: Brief map of key architectural files (e.g., src/api/ for endpoints, src/db/ for schemas)
• Concrete Code Examples: 2–3 lines demonstrating specific formatting or state management preferences

Exclude (Low Value):

• Generic Engineering Principles: "Write clean, scalable code" or "Use DRY principles" (AI models already know this)
• Auto-generated LLM Summaries: Using AI to write massive repo summaries increases bugs
• Extensive Documentation: Don't paste API docs—point to them instead: "API documentation lives in /docs/api.md—read it before making endpoint changes"

Hierarchical Files for Large Monorepos

If 150 lines isn't enough for a large monorepo, use hierarchical AGENTS.md files:

• Place smaller, specialized AGENTS.md files inside specific subdirectories (frontend/backend folders)
• Localized rules override or merge with root rules
• Keeps active context window clean and relevant

Current Behavior (Bug Report)

What Happened

When running /ai-ready:update on an osac-project repository:

1. Existing hierarchical files (e.g., .claude/rules/*.md) were discovered in Step 1
2. Codebase analysis in Step 2 gathered all project information
3. In Step 4 (Audit AI Convention Files), the skill chose Merge action for hierarchical files
4. All content was consolidated into root AGENTS.md
5. Hierarchical files were deleted
6. Result: AGENTS.md exceeded 300 lines

Root Cause

skills/update.md Step 4 lacks logic to:

• Detect when merging would exceed size limits (150 ideal / 300 max)
• Preserve hierarchical organization for large codebases
• Recommend creating nested AGENTS.md files instead of consolidating

The skill has monorepo awareness (Step 4, paragraph starting "Monorepo awareness:") but only checks for workspace configurations. It doesn't prevent consolidation of existing hierarchical files or enforce size limits.

Affected Files

• ai-ready/skills/update.md — Step 4 (Audit AI Convention Files) needs hierarchical file preservation logic
• ai-ready/guidelines.md — Should include size limit guidelines

Proposed Fix

1. Add Size Limit Guidelines

Add to ai-ready/guidelines.md:

## AGENTS.md Size Limits

- **Ideal:** Under 150 lines
- **Maximum:** 300 lines
- **Highly optimized:** Under 60 lines

When AGENTS.md would exceed 150 lines, use hierarchical files:
- Monorepo: nested AGENTS.md in subdirectories (already supported)
- Single repo: `.claude/rules/*.md` for specialized concerns
- Cross-cutting: Keep root AGENTS.md minimal, delegate details to referenced files

2. Update Step 4 Logic in skills/update.md

Before choosing Merge action in Step 4, check:

1. Size projection: If merging would push AGENTS.md over 150 lines, choose Keep instead
2. Hierarchical structure detection: If files follow a clear organizational pattern (e.g., .claude/rules/security.md, .claude/rules/testing.md), preserve the hierarchy
3. Recommendation: When keeping hierarchical files, add a note to the audit report: "Kept hierarchical structure to maintain AGENTS.md under 150 lines"

Add to Step 4 after the "When merging:" section:

**Before merging, check size limits:**

- Calculate projected AGENTS.md line count after merge
- If projection exceeds 150 lines, choose **Keep** instead of **Merge**
- For hierarchical organizations (`.claude/rules/*.md`, nested AGENTS.md), preserve structure
- In the audit report, note: "Kept hierarchical structure to maintain size limits"

3. Update Step 3 Writing Rules

Change from:

- Aim for under 500 lines per AGENTS.md file

To:

- **Target under 150 lines** (absolute maximum 300 lines)
- For monorepos, split project-wide concerns into root file and package-specific details into nested files
- For single repos approaching 150 lines, preserve or create hierarchical files (e.g., `.claude/rules/*.md`)

Current State

The ai-workflows repository's own AGENTS.md is 172 lines and does not mention size constraints. The /ai-ready skill it contains generates AGENTS.md files but lacks size limit enforcement.