From f50f0fcf9c67e2bd5386987e334d56023850a89c Mon Sep 17 00:00:00 2001 From: Polly Labs Date: Sat, 11 Jul 2026 23:45:08 -0500 Subject: [PATCH 1/3] fix(ai-ready): preserve hierarchical agent guidance --- ai-ready/SKILL.md | 2 +- ai-ready/guidelines.md | 13 +++++++++++++ ai-ready/skills/update.md | 13 ++++++++++++- 3 files changed, 26 insertions(+), 2 deletions(-) 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..5e43e5b 100644 --- a/ai-ready/guidelines.md +++ b/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: diff --git a/ai-ready/skills/update.md b/ai-ready/skills/update.md index 5262a87..cad3d5e 100644 --- a/ai-ready/skills/update.md +++ b/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 From e85a2bf43e9173dcc2723544db65bc9ef6c8d95f Mon Sep 17 00:00:00 2001 From: Polly Labs Date: Sun, 12 Jul 2026 13:45:04 -0500 Subject: [PATCH 2/3] fix(ai-ready): add final agent size gate --- ai-ready/guidelines.md | 2 +- ai-ready/skills/update.md | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/ai-ready/guidelines.md b/ai-ready/guidelines.md index 5e43e5b..11a0924 100644 --- a/ai-ready/guidelines.md +++ b/ai-ready/guidelines.md @@ -38,7 +38,7 @@ Ensure a project has accurate, up-to-date AGENTS.md files and a clean set of AI - 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 + 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 diff --git a/ai-ready/skills/update.md b/ai-ready/skills/update.md index cad3d5e..362d520 100644 --- a/ai-ready/skills/update.md +++ b/ai-ready/skills/update.md @@ -114,9 +114,11 @@ 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 -- Target root AGENTS.md under 150 lines; treat 300 lines as the absolute maximum for any single AGENTS.md 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 -- 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 +- For single repos approaching 150 lines, preserve or create hierarchical files such as `.claude/rules/**` for specialized concerns instead of expanding root AGENTS.md +- 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 @@ -150,7 +152,8 @@ 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 no suitable hierarchy exists and root AGENTS.md would exceed 150 lines, choose **Create** and add a scoped hierarchical file instead of merging into the oversized root file +- Preserve clear hierarchical organizations such as `.claude/rules/**`, `.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" @@ -168,6 +171,7 @@ Accuracy: - 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 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. Do not report success if root AGENTS.md exceeds 150 lines; create or preserve scoped hierarchy and move lower-priority details out of root. Do not report completion while any AGENTS.md exceeds 300 lines. Completeness — cross-reference Step 2 findings against the final AGENTS.md: From 9be1d8d5f382109729b818d549ec1c790ac483ff Mon Sep 17 00:00:00 2001 From: Polly Labs Date: Sun, 12 Jul 2026 13:51:34 -0500 Subject: [PATCH 3/3] fix(ai-ready): clarify size remediation rules --- ai-ready/guidelines.md | 2 +- ai-ready/skills/update.md | 16 ++++++++++------ 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/ai-ready/guidelines.md b/ai-ready/guidelines.md index 11a0924..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 diff --git a/ai-ready/skills/update.md b/ai-ready/skills/update.md index 362d520..0a034ae 100644 --- a/ai-ready/skills/update.md +++ b/ai-ready/skills/update.md @@ -116,7 +116,8 @@ These apply to both creation and updates: - Include specific examples from the codebase when describing patterns - 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 -- For single repos approaching 150 lines, preserve or create hierarchical files such as `.claude/rules/**` for specialized concerns instead of expanding root AGENTS.md +- 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 @@ -133,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. @@ -152,8 +153,11 @@ 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** -- If no suitable hierarchy exists and root AGENTS.md would exceed 150 lines, choose **Create** and add a scoped hierarchical file instead of merging into the oversized root file - 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" @@ -168,10 +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. Do not report success if root AGENTS.md exceeds 150 lines; create or preserve scoped hierarchy and move lower-priority details out of root. Do not report completion while any AGENTS.md exceeds 300 lines. +- 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: @@ -199,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