Skip to content

docs: restructure AI guidance for progressive disclosure - #966

Open
hypnotoad08 wants to merge 1 commit into
Listenarrs:canaryfrom
hypnotoad08:docs/progressive-ai-guidance
Open

hypnotoad08 wants to merge 1 commit into
Listenarrs:canaryfrom
hypnotoad08:docs/progressive-ai-guidance

Conversation

@hypnotoad08

Copy link
Copy Markdown

Summary

Restructures the repository's AI/agent guidance from ~20 overlapping, tool-specific files into a
small set of docs organized around progressive disclosure.
The idea: give an agent a short entry point plus a map, and let it pull in deeper detail only for
the area it's actually touching, instead of front-loading everything for every task.

The old set loaded the same guidance five-plus times under different vendor filenames
(ANTHROPIC.md, BEDROCK.md, BARD.md, COHERE.md, AZURE_OPENAI.md, HUGGINGFACE.md,
OpenAI.md), split further across per-editor rule files (.cursorrules, clinerules,
windsurfrules). An agent reading one of these had no way to know which of the ~20 files
actually applied to it, and a task touching one subsystem (e.g. linting) still had to wade
through unrelated content to find the relevant paragraph. Routing by concern instead of by tool
means each doc only surfaces when it's relevant to what's being touched.

Changes

Added

  • AGENTS.md: concise root entrypoint with project overview, layering rules, and a
    table routing to deeper docs by task ("touching persistence? read X"; "touching frontend?
    read Y").
  • fe/AGENTS.md: scoped frontend conventions (Composition API, Pinia,
    SignalR/HTTP state handling, a11y, test commands).
  • SECURITY_RULES.md: consolidated secure-coding guidance (OWASP/CWE),
    separate from SECURITY.md's vulnerability-reporting policy.

Changed

Removed

  • ~2,170 lines of duplicated/per-vendor instruction files: ANTHROPIC.md, BEDROCK.md,
    BARD.md, COHERE.md, AZURE_OPENAI.md, HUGGINGFACE.md, OpenAI.md, .cursorrules,
    clinerules, windsurfrules, WARP.md, .github/CLAUDE.md, .github/AGENTS.md,
    .github/RULES.md, .github/CONVENTIONS.md, and the stray vuejs.md/.mdc/NET_ASP.NET Core_rules.mdc files. Each one said roughly the same thing to a different tool. The unique
    review, testing, linting, and compatibility rules they carried are preserved, folded into the
    docs above rather than dropped.

    The provider files (ANTHROPIC.md, BEDROCK.md, BARD.md, COHERE.md, AZURE_OPENAI.md,
    HUGGINGFACE.md, OpenAI.md) were never auto-discovered by anything; they were hand-linked
    reference docs with duplicate boilerplate, so there's no tool-side loss from removing them.
    The per-editor files are a different case, and I checked each one against current docs before
    removing it:

    • Cursor reads AGENTS.md natively as a documented alternative to .cursor/rules.
    • Cline reads AGENTS.md alongside .clinerules/, shown together in its Rules panel.
    • Windsurf infers rules from AGENTS.md per its current (Cognition/Devin-owned) docs;
      .windsurf/rules still works as the legacy path.
    • Warp's own docs say AGENTS.md is now the recommended default, with WARP.md still
      supported and only taking priority if both files exist in the same directory. We deleted
      WARP.md outright rather than keeping a thin pointer, which is intentional here: it makes
      AGENTS.md unambiguously authoritative instead of leaving two files Warp could pick between.

Testing

Documentation-only change; no application tests run.

  • Read the new and modified files end-to-end against the deleted files to confirm the durable
    rules (security, testing, linting, compatibility) were carried forward, not dropped.
  • Confirmed every Markdown link added or changed by this PR resolves to a real file (AGENTS.md,
    fe/AGENTS.md, copilot-instructions.md, SECURITY_RULES.md).
  • Verified against each tool's current documentation that Cursor, Cline, Windsurf, and Warp all
    discover AGENTS.md without needing their previous vendor-specific filename.

Notes

If any contributor still uses a tool that hasn't picked up AGENTS.md support yet, its old rules
file can be restored as a thin pointer to AGENTS.md (same pattern as
.github/copilot-instructions.md)

@hypnotoad08
hypnotoad08 requested a review from a team September 12, 2026 17:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant