Adopt AGENTS.md as single source of truth, reduce tool-specific files to thin bridges

[lindner]

Problem

contextdocs currently generates 7 context files as co-equal outputs from a single codebase scan. Each file receives the same core conventions (commands, naming, constraints, structure) duplicated into tool-specific templates. This works today but creates structural problems:

1. Duplication at scale: Core conventions are replicated 7 times. When the /ai-context update drift detection patches files, it must apply the same logical change to each variant independently.

2. Drift between files: Even with the context-quality rule enforcing cross-file consistency, the 7-file model makes drift the default state rather than the exception. Each update cycle risks introducing subtle inconsistencies.

3. Industry convergence on AGENTS.md: AGENTS.md is now an open standard governed by the Linux Foundation's Agentic AI Foundation, with 60,000+ repositories and 25+ tools supporting it natively. Windsurf has deprecated .windsurfrules in favor of AGENTS.md. Cursor is moving from .cursorrules to AGENTS.md. GitHub Copilot, Gemini CLI, Codex, and others read it natively. The only notable holdout is Claude Code, which supports it via @AGENTS.md import in CLAUDE.md (native support tracked here).

4. Monorepo support gap: AGENTS.md supports hierarchical nested files (nearest file wins), enabling per-package conventions in monorepos. Most tool-specific files (CLAUDE.md, .cursorrules, .windsurfrules) are root-only. This is an increasingly important distinction as monorepo adoption grows.

Proposal

Restructure the generation pipeline so that AGENTS.md is the single source of truth for shared project conventions, and tool-specific files become thin bridges that reference AGENTS.md plus add only features unique to that tool.

Proposed architecture

AGENTS.md                          <- Source of truth (all shared conventions)
CLAUDE.md                          <- @AGENTS.md + Claude-specific features
.github/copilot-instructions.md   <- Subset/reference (for Code Review context)
.cursorrules                       <- Reference + Cursor MDC metadata (if needed)
.windsurfrules                     <- Reference (deprecated by Windsurf, retain for compat)
.clinerules                        <- Reference + Cline-specific checklist
GEMINI.md                          <- Reference (Gemini reads AGENTS.md natively)

What stays in AGENTS.md (shared)

• Project identity and description
• Build, test, lint, deploy commands
• Naming conventions and code style
• Hard constraints and rules
• Directory structure conventions
• Security considerations

What stays in tool-specific files (unique features)

Tool	Unique features that can't live in AGENTS.md
CLAUDE.md	@AGENTS.md import directive, .claude/rules/ path-scoped rules references, Claude-specific key files table
.cursorrules	MDC frontmatter (description, globs, alwaysApply), Cursor-specific rule scoping
.clinerules	"Before Committing" checklist, Cline autonomous task boundaries
.github/copilot-instructions.md	GitHub Code Review context, PR-specific instructions
GEMINI.md	May become unnecessary if Gemini reads AGENTS.md natively (candidate for deprecation)
.windsurfrules	Deprecated by Windsurf in favor of AGENTS.md (candidate for deprecation)

Impact on existing contextdocs components

• ai-context skill: Generation pipeline changes from "scan once, template 7 times" to "generate AGENTS.md as canonical, then generate thin bridges that reference it"
• context-verify skill: Cross-file consistency checks simplify — verify bridges reference AGENTS.md correctly rather than checking 7 files agree on the same content
• context-updater agent: Sync matrix simplifies — structural changes update AGENTS.md, bridges only need updating when their tool-specific features change
• context-quality rule: Consistency enforcement shifts from "all files must agree" to "bridges must not contradict AGENTS.md"
• Signal Gate: Budget enforcement remains, but AGENTS.md gets the primary budget allocation (~120 lines) while bridges should be minimal (10-20 lines each)

Benefits

• Single edit point: Convention changes happen in one file, not seven
• Reduced drift surface: Bridges are so thin there's little to drift
• Standards-aligned: Follows the direction every major tool vendor is moving
• Simpler maintenance: context-updater agent does less work, context-verify has fewer dimensions to check
• Future-proof: As tools deprecate their proprietary formats (Windsurf already has, Cursor is moving), contextdocs naturally converges

References

• AGENTS.md specification
• GitHub: How to write a great AGENTS.md
• Claude Code AGENTS.md support request
• Windsurf AGENTS.md adoption