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

提交前确认 · Pre-submission checklist

• 我已搜索过现有 issue，确认这不是重复提议 / I searched existing issues and confirmed this isn't a duplicate.
• 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.

问题类别 · Category

其他 / 不确定 · Other / Not sure

涉及的 Agent 框架 · Agent framework

不涉及框架 · Not framework-specific

使用场景 · Use case

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/
.zcode/
...

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

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/
    zcode/
    plugins/
    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.

预期价值 · Expected value

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.

你认为的优先级 · Your perceived priority

高 · High

你使用的 ZCode 版本 / 环境 · ZCode version / environment

No response

补充材料 · Additional context

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.

Start by reading CONTRIBUTING.md and mapping the repository's current agent-resource discovery conventions against the proposed .agents/ layout and manifest examples. Define what backward compatibility requires for existing top-level directories, then verify that shared-directory and manifest-based discovery can be specified with clear resource paths and acceptance criteria.