@synapta/skills 0.1.0 → 0.1.2

package/skills/repo-bootstrap/evals/evals.json

@@ -0,0 +1,385 @@
+{
+  "skill_name": "agent-rules",
+  "evals": [
+    {
+      "id": 1,
+      "eval_name": "generate-agents-go-project",
+      "prompt": "Generate AGENTS.md for this Go project. It's a Docker job scheduler called Ofelia with go-cron integration, integration tests, and GitHub Actions CI.",
+      "expected_output": "A root AGENTS.md with Overview, Setup, Commands (make targets, go test), Architecture sections. Commands should be verified against the actual Makefile/go.mod. File paths should reference real files.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Output file AGENTS.md exists in project root",
+        "Contains a top-level description section explaining the project",
+        "Contains a commands or build section with make targets",
+        "Listed make targets match actual Makefile targets",
+        "Contains go.mod Go version reference",
+        "File paths mentioned in AGENTS.md reference files that actually exist",
+        "Uses tables or structured format (not just prose paragraphs)",
+        "Does not duplicate content from README.md",
+        "Contains CI quality gates from GitHub Actions workflows"
+      ]
+    },
+    {
+      "id": 2,
+      "eval_name": "generate-agents-typo3-extension",
+      "prompt": "Create AGENTS.md for this TYPO3 extension. It's a CKEditor plugin for image handling in the RTE.",
+      "expected_output": "A root AGENTS.md with TYPO3-specific sections. Should detect ext_emconf.php, composer.json with typo3-cms-extension type, Classes/ directory structure. Should list composer scripts and CI commands.",
+      "files": [],
+      "project_path": "/home/cybot/projects/t3x-cowriter/main",
+      "assertions": [
+        "Output file AGENTS.md exists in project root",
+        "Detects TYPO3 extension type",
+        "References ext_emconf.php or composer.json type",
+        "Lists composer scripts that exist in composer.json",
+        "Contains testing or CI section",
+        "Directory references match actual project structure",
+        "Uses Pointer Principle (references files, doesn't duplicate content)"
+      ]
+    },
+    {
+      "id": 3,
+      "eval_name": "generate-agents-skill-repo",
+      "prompt": "Generate AGENTS.md for this skill repository. It provides CLI tool management for AI agents.",
+      "expected_output": "An AGENTS.md appropriate for a skill repo - covering skill structure, SKILL.md location, scripts, references. Should NOT include setup/build sections typical of application projects since skills have no build step.",
+      "files": [],
+      "project_path": "/home/cybot/projects/cli-tools-skill/main",
+      "assertions": [
+        "Output file AGENTS.md exists in project root",
+        "Identifies project as a skill repository",
+        "References skills/cli-tools/SKILL.md",
+        "Lists scripts if any exist in the repo",
+        "Does NOT contain irrelevant build/compile instructions",
+        "Mentions the skill's purpose from SKILL.md description",
+        "Structure is concise (under 150 lines for a simple skill repo)"
+      ]
+    },
+    {
+      "id": 4,
+      "eval_name": "update-outdated-agents",
+      "prompt": "Check if the AGENTS.md in this project is current with the codebase. The project has changed since it was last updated. Identify what's outdated and fix it.",
+      "expected_output": "A freshness analysis identifying outdated sections, followed by an updated AGENTS.md. Should detect new files, changed commands, or removed components.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Runs freshness check before modifying",
+        "Identifies specific outdated sections with evidence",
+        "Updated AGENTS.md preserves correct existing content",
+        "New content references files that actually exist",
+        "Commands listed in updated file actually execute"
+      ]
+    },
+    {
+      "id": 5,
+      "eval_name": "detect-scoped-files-needed",
+      "prompt": "This is a multi-language project with Go backend and TypeScript frontend. Determine if scoped AGENTS.md files are needed and create them if so.",
+      "expected_output": "Detection of distinct tech stacks requiring scoped files. Root AGENTS.md should be thin with pointers. Scoped files should have stack-specific details.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Detects multiple tech stacks or distinct subsystems",
+        "Root AGENTS.md stays thin (under 80 lines)",
+        "Root AGENTS.md links to scoped files",
+        "Scoped files contain stack-specific commands and patterns",
+        "Each scoped file can stand alone for its directory"
+      ]
+    },
+    {
+      "id": 6,
+      "eval_name": "multi-language-hybrid-project",
+      "prompt": "Generate AGENTS.md for this TYPO3 extension that has both PHP backend (composer, PHPUnit, PHPStan) and JavaScript frontend (npm, Vitest, ESLint). Detect both stacks and organize accordingly.",
+      "expected_output": "An AGENTS.md that recognizes both PHP and JS toolchains. Should reference both composer.json and package.json commands. Root should stay focused and not bloated.",
+      "files": [],
+      "project_path": "/home/cybot/projects/t3x-cowriter/main",
+      "assertions": [
+        "Detects PHP stack (composer scripts, PHPUnit, ext_emconf.php)",
+        "Detects JavaScript stack (npm scripts, Vitest, ESLint)",
+        "Lists commands from both composer.json and package.json",
+        "Listed commands actually exist in respective config files",
+        "Root AGENTS.md stays thin and organized (not a wall of text)",
+        "Does not conflate PHP and JS testing commands"
+      ]
+    },
+    {
+      "id": 7,
+      "eval_name": "freshness-check-stale-agents",
+      "prompt": "The AGENTS.md in this project was written months ago. The project has since added new Makefile targets, changed CI workflows, and added new directories. Run a freshness check and update the AGENTS.md to reflect the current state.",
+      "expected_output": "A detailed freshness report identifying which sections are stale, what changed in the repo since AGENTS.md was last modified, and a surgically updated AGENTS.md that fixes only the outdated parts.",
+      "files": [],
+      "project_path": "/home/cybot/projects/t3x-cowriter/main",
+      "assertions": [
+        "Compares AGENTS.md modification time against recent git history",
+        "Identifies specific sections that reference outdated or missing files",
+        "Preserves sections that are still accurate",
+        "Updated content references files and commands that currently exist",
+        "Does not rewrite the entire file when only parts are stale"
+      ]
+    },
+    {
+      "id": 8,
+      "eval_name": "edge-case-minimal-project",
+      "prompt": "Generate AGENTS.md for this minimal project. It has very little structure - just a few files. Produce something useful without fabricating content.",
+      "expected_output": "A minimal but valid AGENTS.md that accurately reflects the sparse project. Should not invent build systems, test frameworks, or architecture that doesn't exist.",
+      "files": [],
+      "project_path": "/home/cybot/projects/agent-rules-skill/main",
+      "assertions": [
+        "Output file AGENTS.md exists and is valid markdown",
+        "Does not fabricate build commands that don't exist in the project",
+        "Does not invent test frameworks or CI pipelines not present",
+        "Accurately reflects actual project structure (skill repo layout)",
+        "Every file path mentioned actually exists in the project"
+      ]
+    },
+    {
+      "id": 9,
+      "eval_name": "verified-commands-principle",
+      "prompt": "Generate AGENTS.md for this project. Every command you list must actually work. After generating, verify each command by attempting to run it (dry-run where possible).",
+      "expected_output": "An AGENTS.md where every shell command, make target, and script listed has been verified to exist. No aspirational or copied-from-template commands.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Every make target listed exists in the Makefile",
+        "Every go command listed is valid (go test, go build, etc.)",
+        "No commands from other projects or templates leak in",
+        "Commands include correct flags and paths for this specific project",
+        "Does not list commands like npm, composer, cargo that don't apply to this Go project"
+      ]
+    },
+    {
+      "id": 10,
+      "eval_name": "cross-platform-copilot-instructions",
+      "prompt": "Generate agent rules for this project. Create both AGENTS.md and .github/copilot-instructions.md. Ensure content is consistent between them but format-appropriate for each platform.",
+      "expected_output": "Two files: AGENTS.md and .github/copilot-instructions.md. Both should describe the same project accurately. copilot-instructions.md should follow GitHub Copilot prose format.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "AGENTS.md exists in outputs",
+        "copilot-instructions.md exists in outputs",
+        "Both files describe the same project with consistent facts",
+        "copilot-instructions.md follows GitHub Copilot prose format",
+        "No contradictions between the two files",
+        "copilot-instructions.md does not just copy AGENTS.md verbatim"
+      ]
+    },
+    {
+      "id": 11,
+      "eval_name": "ci-rules-extraction",
+      "prompt": "Generate AGENTS.md for this Go project. Include CI quality gates, required checks, and version requirements from the GitHub Actions workflows.",
+      "expected_output": "AGENTS.md includes CI/Quality Gates section extracted from .github/workflows/ with specific versions, required checks, and linting configs.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Contains CI quality gates or required checks section",
+        "Lists Go version from CI matrix or go.mod",
+        "References specific CI workflow files",
+        "Mentions golangci-lint or linting configuration if present",
+        "Does not fabricate CI rules that don't exist in workflows"
+      ]
+    },
+    {
+      "id": 12,
+      "eval_name": "architecture-boundaries",
+      "prompt": "Generate AGENTS.md for this Go project. Include module boundaries and architectural constraints from the codebase structure.",
+      "expected_output": "AGENTS.md includes architecture section noting internal/ packages, module boundaries, and dependency patterns.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Documents module or package boundaries from the codebase",
+        "Identifies architecture pattern from directory structure",
+        "References actual directory structure as evidence",
+        "Does not fabricate architectural rules not visible in code"
+      ]
+    },
+    {
+      "id": 13,
+      "eval_name": "adr-extraction",
+      "prompt": "Generate AGENTS.md for this project. Include any architectural decision records found in docs/adr/ or similar locations.",
+      "expected_output": "AGENTS.md includes Key Decisions section listing ADR titles with summaries and file links.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Checks for docs/adr/ or similar ADR directories",
+        "If ADRs exist, lists titles with one-line summaries",
+        "Links to the ADR files rather than duplicating content",
+        "Does not fabricate decisions that don't exist"
+      ]
+    },
+    {
+      "id": 14,
+      "eval_name": "symlink-creation",
+      "prompt": "Generate AGENTS.md for this project with CLAUDE.md and GEMINI.md symlinks for cross-agent compatibility. Verify symlinks are correct at every level.",
+      "expected_output": "Root and scoped AGENTS.md files plus CLAUDE.md and GEMINI.md symlinks at every directory that has an AGENTS.md.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ldap-selfservice-password-changer",
+      "assertions": [
+        "Root CLAUDE.md exists and is a symlink to AGENTS.md",
+        "Root GEMINI.md exists and is a symlink to AGENTS.md",
+        "Subdirectory AGENTS.md files also have CLAUDE.md symlinks",
+        "All symlinks use relative paths (not absolute)",
+        "Root AGENTS.md lists all scoped AGENTS.md paths in an index"
+      ]
+    },
+    {
+      "id": 15,
+      "eval_name": "symlink-safety-no-overwrite",
+      "prompt": "This project already has a CLAUDE.md with custom content (not a symlink). Generate AGENTS.md with --symlinks. Verify that the existing CLAUDE.md is NOT overwritten.",
+      "expected_output": "The existing non-symlink CLAUDE.md should be preserved. A warning should be logged.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ldap-selfservice-password-changer",
+      "assertions": [
+        "Existing non-symlink CLAUDE.md is preserved without --force",
+        "A log message warns that CLAUDE.md exists and is not a symlink",
+        "AGENTS.md itself is not affected by --symlinks flag"
+      ]
+    },
+    {
+      "id": 16,
+      "eval_name": "git-hooks-detection",
+      "prompt": "I'm about to start working on this project -- what git hooks does it use and are they set up?",
+      "expected_output": "Should detect the hook framework (lefthook, husky, captainhook, or pre-commit) and explain how to install. If none exists, should flag the gap.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Checks for lefthook.yml, .husky/, captainhook.json, .pre-commit-config.yaml",
+        "Reports which hook framework is found (or none)",
+        "If hooks exist, explains install command",
+        "If no hooks exist, recommends adding one",
+        "Does not assume a hook framework without evidence"
+      ]
+    },
+    {
+      "id": 17,
+      "eval_name": "pointer-principle-no-duplication",
+      "prompt": "Generate AGENTS.md for this project. The README.md already has extensive setup instructions. Do NOT duplicate README content -- point to it instead.",
+      "expected_output": "AGENTS.md should reference README.md for setup details rather than copying them. Uses the Pointer Principle.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Does not copy setup instructions from README.md verbatim",
+        "Contains 'see README.md' or similar pointer for detailed setup",
+        "Root AGENTS.md stays under 80 lines",
+        "Focuses on agent-specific info (commands, boundaries, heuristics)",
+        "References README.md as a source but adds agent-specific value"
+      ]
+    },
+    {
+      "id": 18,
+      "eval_name": "validate-structure-compliance",
+      "prompt": "Run the validate-structure.sh script on this project and report any structural issues found in the existing AGENTS.md.",
+      "expected_output": "Script output showing which sections pass/fail validation. Should identify missing recommended sections and structural issues.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Runs scripts/validate-structure.sh against the project",
+        "Reports pass/fail for each structural check",
+        "Identifies missing recommended sections",
+        "Does not crash on valid AGENTS.md files",
+        "Output is parseable and actionable"
+      ]
+    },
+    {
+      "id": 19,
+      "eval_name": "python-project-detection",
+      "prompt": "Generate AGENTS.md for this Python project. It uses poetry for dependency management, pytest for testing, and ruff for linting.",
+      "expected_output": "An AGENTS.md with Python-specific sections. Should detect pyproject.toml, poetry.lock, ruff config, and pytest settings.",
+      "files": [],
+      "project_path": "/home/cybot/projects/python-project/main",
+      "assertions": [
+        "Detects Python project from pyproject.toml or setup.py",
+        "Lists poetry commands if poetry.lock exists",
+        "References pytest configuration",
+        "Lists ruff or linting commands",
+        "Does not list npm/composer/go commands for a Python project"
+      ]
+    },
+    {
+      "id": 20,
+      "eval_name": "template-selection-thin-vs-verbose",
+      "prompt": "Generate AGENTS.md for this small Go library. Use the thin template style -- the file should be minimal and focused.",
+      "expected_output": "A thin AGENTS.md under 50 lines with only essential sections: Commands, File Map, Heuristics, Boundaries.",
+      "files": [],
+      "project_path": "/home/cybot/projects/simple-ldap-go/main",
+      "assertions": [
+        "Output is under 50 lines",
+        "Contains Commands section with actual build/test commands",
+        "Contains precedence statement",
+        "Contains index of scoped files if any exist",
+        "Omits verbose sections like full architecture descriptions"
+      ]
+    },
+    {
+      "id": 21,
+      "eval_name": "verify-content-accuracy",
+      "prompt": "Run verify-content.sh on this project. Report any documented files that don't exist and any important undocumented files.",
+      "expected_output": "Content verification showing documented-but-missing files and undocumented-but-important files.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Runs scripts/verify-content.sh against the project",
+        "Reports files referenced in AGENTS.md that don't exist",
+        "Reports important files not mentioned in AGENTS.md",
+        "Does not report false positives for valid paths",
+        "Output clearly distinguishes missing from undocumented"
+      ]
+    },
+    {
+      "id": 22,
+      "eval_name": "heuristics-table-generation",
+      "prompt": "Generate AGENTS.md for this project. Include a Heuristics table with project-specific quick-decision rules based on the codebase conventions.",
+      "expected_output": "A Heuristics section with When/Do table entries derived from actual project patterns (commit style, merge strategy, dependency policy).",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Contains a Heuristics section with table format",
+        "Heuristics are derived from actual project config (not generic)",
+        "Includes commit convention rule if conventional commits detected",
+        "Includes merge strategy if branch protection detected",
+        "Each heuristic is actionable (not vague advice)"
+      ]
+    },
+    {
+      "id": 23,
+      "eval_name": "no-fabrication-unknown-project",
+      "prompt": "Generate AGENTS.md for /tmp/empty-project which contains only a single README.md with 'Hello World'. Do not fabricate any content.",
+      "expected_output": "A minimal AGENTS.md acknowledging the sparse project. No fabricated commands, test frameworks, or architecture.",
+      "files": [],
+      "project_path": "/tmp/empty-project",
+      "assertions": [
+        "Does not list build commands that don't exist",
+        "Does not reference test frameworks not present",
+        "Does not invent CI pipelines",
+        "Produces a valid markdown file",
+        "May suggest next steps but does not pretend they exist"
+      ]
+    },
+    {
+      "id": 24,
+      "eval_name": "scoped-agents-override-root",
+      "prompt": "This project has a root AGENTS.md saying 'use tabs for indentation'. The internal/web/ directory uses TypeScript with prettier configured for 2-space indentation. Generate a scoped AGENTS.md for internal/web/ that correctly overrides the root rule.",
+      "expected_output": "A scoped AGENTS.md that specifies 2-space indentation for TypeScript, overriding the root tab rule for this directory.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ldap-selfservice-password-changer",
+      "assertions": [
+        "Scoped file mentions its own indentation convention",
+        "Does not blindly repeat root conventions that don't apply",
+        "References prettier or editorconfig as source of truth",
+        "Includes a note about scope override or precedence"
+      ]
+    },
+    {
+      "id": 25,
+      "eval_name": "github-rulesets-extraction",
+      "prompt": "Generate AGENTS.md for this project. Extract GitHub repository rulesets and merge rules to document branch protection and required checks.",
+      "expected_output": "AGENTS.md includes repository settings section with merge strategy, branch protection rules, and required status checks.",
+      "files": [],
+      "project_path": "/home/cybot/projects/ofelia/main",
+      "assertions": [
+        "Contains repository settings or merge rules section",
+        "Documents merge strategy (squash/merge/rebase)",
+        "Documents required checks if available",
+        "Information matches actual GitHub settings",
+        "Does not fabricate branch protection rules"
+      ]
+    }
+  ]
+}

package/skills/repo-bootstrap/references/ai-contribution-guidelines.md

@@ -0,0 +1,63 @@
+# AI Agent Contribution Guidelines
+
+Guidelines for AI agents contributing to projects with AGENTS.md files. Based on the "3 Cs" framework from GitHub's open source mentorship research (March 2026).
+
+## The 3 Cs
+
+### Comprehension
+
+Before submitting any code change, the agent must demonstrate understanding of the problem:
+
+- Read the linked issue fully — understand the *why*, not just the symptoms
+- Check if the issue is already assigned to someone
+- Understand the trade-offs involved (performance vs readability, backwards compatibility, etc.)
+- If the issue is unclear, ask for clarification rather than guessing
+
+**Red flag**: Submitting code that "looks right" without understanding why the current behavior exists.
+
+### Context
+
+Every PR must provide enough context for efficient review:
+
+- Link to the issue being addressed (Fixes #NNN)
+- Explain the approach taken and alternatives considered
+- If AI tools assisted the contribution, disclose this if the project requires it
+- Include test evidence (test output, before/after screenshots)
+- Note any side effects or breaking changes
+
+**Red flag**: A PR with only "Fixes the bug" as description.
+
+### Continuity
+
+Contributions are not fire-and-forget:
+
+- Respond to review comments within a reasonable timeframe
+- Be willing to iterate on feedback
+- Don't submit to many projects simultaneously without capacity to follow up
+- If you can't continue, say so — maintainers prefer honesty over silence
+
+**Red flag**: Opening a PR and never responding to review feedback.
+
+## Detection Patterns
+
+The agent-rules skill detects contribution requirements from:
+
+| Source | What's extracted |
+|--------|-----------------|
+| `CONTRIBUTING.md` | Issue-first requirements, AI disclosure policy |
+| PR templates (`.github/pull_request_template.md`) | Required fields (issue links, test plans) |
+| Branch protection rules | Linked issue requirements |
+| `AGENTS.md` | Agent-specific boundaries and conventions |
+
+## What AGENTS.md Signals
+
+Having an AGENTS.md file signals:
+- The project is AI-contribution-ready
+- Agents should follow the conventions documented in the file
+- The closest AGENTS.md to the files being changed takes precedence
+- Explicit user instructions override AGENTS.md
+
+## References
+
+- [Rethinking open source mentorship in the AI era](https://github.blog/open-source/maintainers/rethinking-open-source-mentorship-in-the-ai-era/) (GitHub Blog, March 2026)
+- [agents.md convention](https://agents.md/) — the standard our skill implements

package/skills/repo-bootstrap/references/ai-tool-compatibility.md

@@ -0,0 +1,223 @@
+# AI Tool Compatibility
+
+How AGENTS.md integrates with different AI coding tools, and what mitigations are needed for each.
+
+## Compatibility Matrix (March 2026)
+
+| Agent | Native AGENTS.md | Subdirectory Auto-Load | Own Format | Mitigation |
+|-------|:-:|:-:|---|---|
+| **Codex CLI** | Yes (creator) | Yes (best-in-class) | `AGENTS.md` | None |
+| **GitHub Copilot** | Yes | Yes | `.github/copilot-instructions.md` | None |
+| **Cursor** | Yes | Yes | `.cursor/rules/*.mdc` | None |
+| **Windsurf** | Yes | Yes (auto-scoped) | `.windsurf/rules/` | None |
+| **Devin** | Yes | Yes | AGENTS.md primary | None |
+| **Augment Code** | Yes | Yes (hierarchical) | `.augment/rules/` | None |
+| **Roo Code** | Yes | Partial (recursive) | `.roo/rules/` | None |
+| **JetBrains Junie** | Yes | Needs config path | `.junie/guidelines.md` | Set Guidelines path for monorepos |
+| **Gemini CLI** | Via config | Yes (excellent) | `GEMINI.md` | Symlink or settings.json config |
+| **Aider** | Via config | No auto-discovery | `CONVENTIONS.md` | `.aider.conf.yml` config |
+| **Claude Code** | **No** | On-demand (CLAUDE.md only) | `CLAUDE.md` | **Auto-created when `.claude/` detected** |
+| **Continue.dev** | **No** | No | `.continue/rules/` | Copy/link into rules dir |
+| **Amazon Q** | **No** | No | `.amazonq/rules/` | Copy into rules dir |
+| **Cline** | **No** | No | `.clinerules/` | Copy/link into dir |
+| **Sourcegraph Cody** | **No** | No | `.sourcegraph/*.rule.md` | Copy content |
+| **Tabnine** | **No** | No | `.tabnine/guidelines/` | Copy content |
+
+## Symlink Strategy (Recommended)
+
+The most reliable cross-agent solution is to **symlink** agent-specific files to AGENTS.md.
+This keeps AGENTS.md as the single source of truth while enabling native loading in each tool.
+
+### What to create
+
+At **every level** where an AGENTS.md exists (root AND subdirectories):
+
+```bash
+# For each directory containing AGENTS.md:
+ln -s AGENTS.md CLAUDE.md    # Claude Code on-demand loading
+ln -s AGENTS.md GEMINI.md    # Gemini CLI on-demand loading
+```
+
+### Why subdirectory symlinks matter (verified behavior)
+
+Claude Code loads CLAUDE.md files **on demand** when the agent reads files in that directory.
+Without a CLAUDE.md symlink, subdirectory AGENTS.md files are **never auto-loaded** — even if
+the root AGENTS.md explicitly links to them and says "read nearest AGENTS.md."
+
+**Tested scenarios (March 2026):**
+
+| Setup | Result |
+|-------|--------|
+| Root CLAUDE.md symlink only, no subdirectory symlinks | Subdirectory AGENTS.md NOT loaded. Agent sees root links but does not proactively read them. |
+| Root + subdirectory CLAUDE.md symlinks | Subdirectory AGENTS.md auto-loaded when agent works in that directory. |
+| Root instructions say "read nearest AGENTS.md" | Agent acknowledges instruction but does NOT act on it without explicit prompting. |
+
+### Commit symlinks to git
+
+Symlinks are tiny (9 bytes each) and should be committed:
+
+```bash
+git add CLAUDE.md GEMINI.md
+git add internal/CLAUDE.md internal/GEMINI.md    # etc.
+```
+
+They work on all platforms (Linux, macOS, Windows with `core.symlinks=true`).
+
+## Claude Code
+
+Claude Code only reads `CLAUDE.md` files natively. AGENTS.md is not recognized.
+
+**Feature request**: [anthropics/claude-code#6235](https://github.com/anthropics/claude-code/issues/6235) (3,294+ upvotes, no official response as of March 2026).
+
+### Loading behavior
+
+- **Root CLAUDE.md**: Auto-loaded at session start (always in context)
+- **Subdirectory CLAUDE.md**: Loaded on demand when agent reads/edits files in that directory
+- **AGENTS.md**: Never loaded natively — requires symlink
+
+### Auto-detection (default behavior)
+
+When `generate-agents.sh` detects a `.claude/` directory in the project, it **automatically creates
+CLAUDE.md symlinks** at every level where an AGENTS.md is generated. No flags required.
+
+This means Claude Code users get working agent instructions out of the box, without needing to
+remember `--symlinks` or `--claude-shim` flags.
+
+To opt out, pass `--no-symlinks` explicitly.
+
+### Manual symlinks (if not using the generator)
+
+```bash
+# Root
+ln -s AGENTS.md CLAUDE.md
+
+# Every subdirectory with its own AGENTS.md
+ln -s AGENTS.md src/CLAUDE.md
+ln -s AGENTS.md internal/CLAUDE.md
+ln -s AGENTS.md internal/web/CLAUDE.md
+```
+
+### Alternative: @import shim (root only, legacy)
+
+If you need Claude-specific overrides on top of AGENTS.md:
+
+```markdown
+<!-- CLAUDE.md -->
+@AGENTS.md
+
+<!-- Claude-specific overrides below -->
+```
+
+Note: `@import` only works at root level. Subdirectories still need symlinks for on-demand loading.
+
+### Alternative: SessionStart hook
+
+For skill users only — auto-create symlinks at session start:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "find . -name AGENTS.md -not -path './.git/*' | while read f; do dir=$(dirname \"$f\"); [ ! -e \"$dir/CLAUDE.md\" ] && ln -s AGENTS.md \"$dir/CLAUDE.md\"; done",
+        "timeout": 5
+      }]
+    }]
+  }
+}
+```
+
+This only helps users who have the hook installed. Committed symlinks are more reliable.
+
+## Google Gemini CLI
+
+Gemini CLI reads `GEMINI.md` natively with excellent hierarchical support (global, project, subdirectory).
+
+### Mitigation options
+
+**Option A: Symlink** (recommended)
+```bash
+ln -s AGENTS.md GEMINI.md    # At every level
+```
+
+**Option B: settings.json config**
+```json
+{
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"]
+  }
+}
+```
+
+## OpenAI Codex
+
+Codex is the creator of the AGENTS.md standard and has the best support.
+
+- **Concatenation order**: `~/.codex/AGENTS.md` → root → nested directories → current dir
+- **Override files**: `AGENTS.override.md` at any level temporarily replaces the base file
+- **Size limit**: Default 32 KiB combined (`project_doc_max_bytes`)
+- **Fallback filenames**: Configurable via `~/.codex/config.toml`
+
+**Best practices:**
+- Keep root AGENTS.md under 4 KiB (leaves room for 7+ nested files)
+- Use `--style=thin` template for optimal Codex compatibility
+- Use AGENTS.override.md for directory-specific behavior changes
+
+## Aider
+
+Aider reads `CONVENTIONS.md` by default. AGENTS.md requires explicit configuration.
+
+### Mitigation: .aider.conf.yml
+
+```yaml
+# .aider.conf.yml
+read:
+  - AGENTS.md
+  - internal/AGENTS.md        # No auto-discovery — list each file explicitly
+  - internal/web/AGENTS.md
+```
+
+Or via CLI: `aider --read AGENTS.md`
+
+## GitHub Copilot
+
+Full native support for AGENTS.md including subdirectories (announced August 2025).
+Also reads CLAUDE.md and GEMINI.md as fallbacks.
+
+Additionally supports its own format:
+- `.github/copilot-instructions.md` — repository-wide instructions
+- `.github/instructions/*.instructions.md` — path-scoped via YAML frontmatter `applyTo` globs
+
+## Agents Without Native Support
+
+For **Continue.dev**, **Amazon Q**, **Cline**, **Sourcegraph Cody**, and **Tabnine**:
+
+These agents use proprietary directory formats. The only mitigation is to copy or symlink
+AGENTS.md content into their respective directories:
+
+| Agent | Target |
+|-------|--------|
+| Continue.dev | `.continue/rules/agents.md` |
+| Amazon Q | `.amazonq/rules/agents.md` |
+| Cline | `.clinerules/agents.md` |
+| Sourcegraph Cody | `.sourcegraph/agents.rule.md` |
+| Tabnine | `.tabnine/guidelines/agents.md` |
+
+Feature requests are open for most of these tools.
+
+## Generation Script Integration
+
+`generate-agents.sh` creates `CLAUDE.md` and `GEMINI.md` symlinks **by default** at every
+level where an AGENTS.md is generated. Additionally, when a `.claude/` directory is detected
+in the project (indicating a Claude Code environment), CLAUDE.md symlink creation is
+**automatically enabled** even if `--no-symlinks` was passed.
+
+```bash
+scripts/generate-agents.sh /path/to/project              # Symlinks created by default
+scripts/generate-agents.sh /path/to/project --no-symlinks # Skip symlinks (unless .claude/ detected)
+```
+
+The `--claude-shim` flag creates a root-only CLAUDE.md with `@import` (legacy behavior).
+Use the default symlink behavior instead for full subdirectory support.