Proposal: Standardize a .agent Directory for Comprehensive Project Context

[haoranba]

Summary

This proposal suggests establishing a standardized .agent directory within project repositories to serve as a single, version-controlled source of truth for AI agents. The goal is to provide them with accurate, comprehensive, and up-to-date context that goes beyond just the source code, enabling more complex and reliable autonomous operations.

The Problem

Currently, AI agents often lack a standardized mechanism for accessing comprehensive project-wide context. Their understanding is typically limited to the code they can read and any context provided in a prompt. They struggle to access critical non-code assets in a structured way, such as:

• Product requirements (PRDs)
• Technical design documents and architecture diagrams
• UI/UX mockups (e.g., Figma links)
• Project management tasks (e.g., Jira tickets)
• Live system monitoring dashboards and configurations

This information gap forces agents to make assumptions, leads to outputs that are misaligned with project goals, and limits their ability to perform high-level tasks like validating code against specifications or performing root cause analysis.

The Proposal: The .agent Standard

We propose the adoption of a "Directory as Context" strategy, centered around a .agent directory at the root of a project. This directory would act as a centralized, standardized index for all project-related assets, both textual and external.

Reference Directory Structure

Here is a proposed reference model for the structure:

├── AGENT.md       # A core file guiding the Agent's behavior, defining coding standards, the directory structure, and context consumption meta-rules.
└── .agent/
    ├── spec/          # The project's "blueprint": formal, version-controlled specification documents.
    │   ├── requirement.md # PRD, user stories, business rules.
    │   ├── design.md      # Technical design, architecture, API definitions, links to UI/UX mockups.
    │   └── tasks.md       # Development tasks broken down from requirements.
    │
    ├── wiki/          # The project's "encyclopedia": stable, global guides for knowledge accumulation.
    │   ├── architecture.md # System architecture, core components, and interactions.
    │   └── domain.md       # Core business domain concepts, processes, etc.
    │
    ├── links/         # The project's "address book": manages all external asset links.
    │   └── resources.md   # Lists external URIs and the tools (e.g., MCPs) required to access them.
    │
    └── ... (Extensible with other directories like middleware/, integrations/, tests/, etc.)

How It Works

The agent would consume this context in a hybrid model:

• Agent's "Long-Term Memory": The AGENT.md file serves as a meta-guide, loaded by default. It instructs the agent on how to behave, what coding standards to follow, and how to interpret and utilize the rest of the .agent directory.

• Local Context Consumption: The agent uses its built-in file system tools (search, grep, read_file) to directly read text-based assets within .agent/ (e.g., spec/requirement.md, wiki/architecture.md). This allows it to build a "mental model" of the project, much like a human engineer reading documentation.

• External Context Consumption: The agent parses links/resources.md to discover URIs for non-textual or dynamic assets. It then uses the appropriate tools (or "MCPs") to fetch external information, such as reading metadata from a Figma design, getting the latest status of a Jira task, or pulling data from a monitoring dashboard.

Why This Matters for the openai/agents Initiative

Interoperability & Standardization: This creates a common standard that any agent (from any developer or organization) can rely on. An agent could clone any compliant repository and immediately know where to find the project's foundational context.

• Enhanced Agent Capabilities: With access to this rich context, agents can perform significantly more advanced tasks:

• Validate code against requirements in spec/requirement.md.

• Generate code that adheres to the architecture described in wiki/architecture.md.

• Analyze the impact of a change by understanding component interactions.

• Perform root cause analysis by correlating a bug with recent PRs and links to monitoring data.

Extensibility: The structure is not rigid. Teams can add custom directories (security/, performance/) to suit their specific needs, making the standard adaptable.

Improved Human-Agent Collaboration: It provides a clear, version-controlled contract between human developers and AI agents. Humans provide the context in a structured way, and agents consume it reliably.

Next Steps

We believe that establishing a context standard like this would be a massive leap forward for the entire AI agent ecosystem. We would like to open a discussion with the community and the maintainers of this project on the feasibility and potential adoption of the .agent directory as a recommended best practice or formal standard.

We welcome feedback, suggestions, and further discussion.

[BradKML]

Duplicate? https://github.com/openai/agents.md/issues/9

[ecki]

I think that goes too far, especially having stuff like a wiki in the .agents folder.

If You have Specs just mention the directories in a table in agents.md, that also helps with human Discovery of them.

[OriNachum]

Thank you @BradKML @ecki, .agent is very similar to Agent Skills, which Anthropic recently announced. I think we can align with that. It has the folders: scripts (Code used by the agent), references (Documentation and the like), assets (Code examples, or templates, etc.)

I don't care about the ego of which issue is used, and I generally prefer alignment (And Agent Skills is adopted by Codex now as well). I think it should be a standard so that other agentic tools, like Gemini CLI, align as well.

Edit: I was also referring to my own ticket: https://github.com/agentsmd/agents.md/issues/3