[FEATURE]: Support a Shared .agents/ Directory and Manifest-Based Discovery

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

As more development agents emerge, repositories are increasingly accumulating tool-specific top-level directories such as:

.claude/
.claude-plugin/
.config/
.cursor/
.devcontainer/
.eslint-plugin-local/
.github/
.opencode/
.vscode/
...

Each tool introduces its own conventions, fixed directory names, and sometimes additional companion directories outside its own namespace. This approach does not scale well for repositories that need to support multiple agents over time.

Proposal 1: Support a Shared .agents/ Directory

Instead of requiring every agent to create its own top-level directory, consider also supporting the following layout:

.agents/
    claude/
    cursor/
    codex/
    devcontainer/
    eslint/
      plugin-local/
    gemini/
    github/
    human/
    vscode/
    opencode/
    skills/
    README.md
    ...

Each agent remains free to organize its own internal files however it prefers, but all agent-related resources live under a single shared root. This keeps repositories organized while allowing every agent to evolve independently.

This proposal is not asking to replace the current layout. It simply asks to also support discovering configuration under .agents/<agent>/, preserving full backward compatibility with existing repositories.

Benefits

• Keeps the repository root clean and predictable.
• Prevents namespace pollution.
• Makes repositories easier to navigate.
• Provides a single location for all agent-related resources.
• Simplifies supporting multiple agents simultaneously.
• Allows future agents to coexist without introducing additional top-level directories.

---

Proposal 2: Prefer Manifest-Based Discovery Over Fixed Directory Layouts

Many tools currently require resources to exist in hard-coded filesystem locations. For example, an agent may require directories such as:

skills/
prompts/
commands/

to exist beside its configuration directory. These assumptions unnecessarily couple repository layout to a particular implementation. Instead, consider allowing a manifest file to explicitly declare resource locations. For example:

skills:
  - /.agents/skills

prompts:
  - /.agents/prompts

commands:
  - /.agents/commands

references:
  - /docs/

The manifest becomes the contract rather than the directory structure. This allows repositories to organize their files according to their own architecture while remaining fully compatible with the agent. It also enables future resource types without introducing new fixed filesystem conventions.

---

Project Documentation

Agent instructions and project documentation serve different audiences and should remain clearly separated. A natural convention is:

.agents/    # Instructions and resources intended for agents (How)
/docs/      # Project documentation intended for any agents as humans, tools, AIs (Why)

Project documentation should not be tied to a specific agent. Whether the consumer is a human, an IDE, a CLI tool, or an AI model, the same documentation should remain accessible from a predictable location.

---

Why This Matters

Repository structure should not become coupled to individual tools. Agents are broader than AI models. IDEs, automation tools, CI systems, documentation generators, and even humans can all be considered agents interacting with a repository. A repository should be able to support many different agents simultaneously without each one requiring its own top-level directory structure or filesystem conventions.

Supporting a shared .agents/ directory together with manifest-based discovery would improve interoperability, reduce repository clutter, and make the ecosystem easier to extend while remaining fully backward compatible.