Agents-MD Optimizer

Optimize agent context files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) by applying the discoverability filter: remove information agents can discover from code, keep only non-discoverable operational knowledge (gotchas, landmines, non-standard conventions), and mine source code for undocumented gotchas.

Research shows redundant context (directory trees, data flow diagrams) degrades agent performance by 15-20%, while human-authored operational knowledge reduces runtime by ~28%.

Flag Parsing

Parse $ARGUMENTS for optional flags:

If --help is present, display available flags and a brief description of the workflow, then stop.

Workflow

Phase 0: Setup

Language Detection: Detect the user's language from conversation history. Present all analysis results and messages in the user's language.

Target File Resolution (when --path is not specified):

Search for the first existing file in this priority order:

1. AGENTS.md
2. CLAUDE.md
3. .cursorrules
4. CURSOR.md
5. .github/copilot-instructions.md
6. .windsurfrules
7. codex.md

If none found, ask the user to specify the target file path.

Small File Check: If the target file has fewer than 20 lines, inform the user that the file is already minimal and optimization is unnecessary. Stop unless the user explicitly requests to proceed.

Step 1: Baseline Analysis

Read the target file. Collect line statistics.

Script Location: Find the line-count script by searching for it:

# Search in common skill installation paths
SCRIPT_PATH=$(find ~/.claude/skills ~/.codex/skills ~/.cursor/skills ~/skills 2>/dev/null -path "*/agents-md-optimizer/scripts/line-count.mjs" | head -1)
if [ -z "$SCRIPT_PATH" ]; then
  # Fallback: search in current directory
  SCRIPT_PATH=$(find . -path "*/agents-md-optimizer/scripts/line-count.mjs" 2>/dev/null | head -1)
fi

Run the script if found:

node "$SCRIPT_PATH" '<TARGET_PATH>'

Fallback (if script not found): Count lines manually using Bash:

wc -l '<TARGET_PATH>'
grep -c '^##' '<TARGET_PATH>'

Then classify each ##/### section into one of three categories:

To classify, actually read the source files referenced in each section. Verify whether the information is truly discoverable. Detailed classification criteria are in references/methodology.md.

Present results as a table:

## Baseline Analysis — <filename>

Total: XXX lines (YY sections)

| Section | Lines | Category | Rationale |
|---------|-------|----------|-----------|
| Directory Structure | 63 | discoverable | Glob **/* reveals this instantly |
| Design Rules | 8 | operational | Non-standard constraints, not in code |
| Config & State | 24 | verbose | Operational but compressible to ~6 lines |

Removal candidates: XX lines (XX%)

If --report-only, stop here.

Step 2: Gotcha Mining

Scan project source code to find non-obvious operational knowledge missing from the target file. Use the systematic checklist in references/gotcha-mining.md.

Key Grep patterns to run on the codebase:

MUST|WARNING|HACK|TODO|FIXME          → developer-flagged gotchas
catch.*exit\(0\)|process\.exit        → error exit policies
setTimeout|setInterval|deadline       → timing constraints
=== null|== null|delete result        → implicit semantics
process\.platform|/proc/version       → platform detection quirks
cooldown|throttle|lastNotified        → rate limiting scope

Present findings:

## Discovered Gotchas

| # | Category | Description | Source | Already documented? |
|---|----------|-------------|--------|---------------------|
| 1 | Timing | 5s→4s→2s budget | _common.mjs:21,52 | No → Add |
| 2 | Implicit | null = key deletion | config.mjs:157 | No → Add |

Step 3: Generate Optimized File

Use AskUserQuestion to confirm before modifying:

Based on the analysis:

• Remove: X lines of discoverable content (Y sections)
• Compress: X lines → ~Y lines (Z sections)
• Add: X new gotcha items

Options:

1. Apply all — Remove discoverable, compress verbose, add gotchas
2. Item by item — Review each change individually
3. Cancel — No changes

Apply the selected changes using Edit (prefer surgical edits over full rewrite).

If --dry-run, show the diff but do not write.

Structure for optimized file (recommended section order):

1. Project description (1-2 lines)
2. Development Commands
3. Design Rules (non-negotiable constraints)
4. Gotchas & Landmines (categorized subsections)
5. Conventions (non-standard project patterns)
6. Version/Release Management
7. Testing

Detailed anti-pattern examples with before/after are in references/anti-patterns.md.

Step 4: Verification

Re-run statistics (using the same script or fallback method from Step 1) and present before/after comparison:

## Optimization Results

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Total lines | 182 | 90 | -51% |
| Discoverable lines | 80 | 0 | Removed |
| Operational lines | 60 | 55 | Kept |
| Gotcha items | 0 | 25 | Added |

Discoverability filter: all remaining lines pass "not discoverable from code" check.

Reference Files

• references/methodology.md — Discoverability filter decision tree, category classification criteria, compression techniques, efficiency research data
• references/anti-patterns.md — 6 anti-pattern catalog with real before/after examples
• references/gotcha-mining.md — 8-category mining checklist with Grep patterns and source code analysis techniques