{
  "$schema": "https://agentsstandard.com/schema.json",
  "name": "AGENTS.md",
  "version": "1.4.0",
  "description": "Hierarchical configuration standard for AI coding agents — one convention, all agents",
  "loading_model": "scoped-concatenation",
  "loading_description": "AGENTS.md files are concatenated (not replaced) within a bounded scope. The project root (inherited terminal cwd) acts as a ceiling — agents never traverse above it. Global rules form the immutable base. Each tier within the project appends context-specific rules.",
  "project_root_detection": {
    "method": "shell_inheritance",
    "description": "The project root is the directory the shell was opened in (inherited terminal cwd), not the filesystem root. Agents detect this via the shell's initial $PWD or an AGENTS_ROOT env var. This prevents accidentally reading AGENTS.md files from parent directories (e.g. a github repo management AGENTS.md one level up).",
    "env_var": "AGENTS_ROOT",
    "note": "If AGENTS_ROOT is set, it overrides shell-inherited cwd detection."
  },
  "project_prd": {
    "file": "llms.txt",
    "location": "{project_root}/llms.txt",
    "description": "The globalized Project Requirements Document (PRD) detailing active goals, architecture, feature requirements, and project scope (the 'What' and 'Why'). Loaded as the primary project context layer.",
    "relationship_to_rules": "llms.txt defines what is being built, while AGENTS.md files define the rules and behavior constraints of how the agent should behave."
  },
  "traversal_rules": {
    "never_go_up": "Agents must never traverse above the detected project root. If the user cds .. past the project root, only ~/.agents/AGENTS.md is loaded — no parent directory AGENTS.md files are picked up.",
    "always_read_cwd": "Within the project boundary, the current working directory's AGENTS.md is always read (if it exists). AGENTS.md lives at directory root, inside subdirectories for component rules, or in .agents/ for project base rules.",
    "ceiling": "The project root .agents/AGENTS.md and root AGENTS.md are the highest project-level files loaded. ~/.agents/AGENTS.md is the global ceiling."
  },
  "resolution_order": [
    "~/.agents/AGENTS.md (global base — loaded first, user-specific safety/security/preferences)",
    "Detect project root via inherited terminal cwd or $AGENTS_ROOT",
    "{project_root}/llms.txt (project PRD — loaded second, functional requirements, scope, tech stack)",
    "{project_root}/.agents/AGENTS.md (project base — loaded third, committed rules, static architecture, guidelines)",
    "{project_root}/AGENTS.md (project active rules — loaded fourth, active task/feature constraints, symlinked by CLAUDE.md)",
    "{cwd}/AGENTS.md for any subdirectory within project boundary (folder/component rules, loaded last)"
  ],
  "canonical_global_path": {
    "primary": "~/.agents/AGENTS.md",
    "note": "Some tools currently use ~/.config/AGENTS.md. The standard defines ~/.agents/AGENTS.md as the canonical global path. Tools using ~/.config/ should migrate to ~/.agents/ to join ~/.agents/mcp-settings.json and ~/.agents/skills/**/SKILL.md under one directory. At the project level, .agents/ is for tooling configuration and project base rules (in .agents/AGENTS.md). The root-level AGENTS.md holds active task/PRD rules for easy modification and native tool compatibility. The agents-standard CLI handles migration."
  },
  "dual_layer_mcp": {
    "global": "~/.agents/mcp-settings.json — MCP servers available across all agents and IDEs. Shared foundation.",
    "agent_specific": "Each agent/IDE can also read its own MCP config file (e.g. ~/.claude.json, .cursor/mcp.json) for finer customization. Agent-specific configs extend — not replace — the global set.",
    "note": "This dual-layer model prevents users from duplicating MCP configs across every agent. Shared servers go in ~/.agents/mcp-settings.json. Agent-specific extras go in the agent's own config."
  },
  "agents_directory": {
    "description": "The .agents/ directory holds tooling configuration and project base rules. AGENTS.md lives at directory root for active task instructions, and inside .agents/ for project base rules.",
    "global": {
      "path": "~/.agents/",
      "contents": {
        "AGENTS.md": "Global behavior rules (this standard)",
        "mcp-settings.json": "MCP server configs shared across all agents",
        "skills/": "Global agent skills (**/SKILL.md)"
      }
    },
    "project": {
      "path": "{project_root}/.agents/",
      "contents": {
        "AGENTS.md": "Project base rules (tech stack, deployment, committed guidelines)",
        "mcp-settings.json": "Project-specific MCP server configs",
        "skills/": "Project-specific agent skills (**/SKILL.md)"
      },
      "note": "Project base rules live in .agents/AGENTS.md. Project active task/PRD rules go in {project_root}/AGENTS.md — visible at repo root, compatible with how 23+ tools already read rules."
    }
  },
  "singular_rules_fallback": {
    "description": "If an agent only supports a single rules file, it should use either ~/.agents/AGENTS.md (global) or the project root AGENTS.md. These are the two canonical locations.",
    "note": "Tools that only read one file are first-class citizens — they get the global base or cwd rules without needing to implement the full cascade."
  },
  "agent_specific_files": {
    "CLAUDE.md": "Independent context file — Claude Code reads this directly. Not replaced by AGENTS.md unless user symlinks.",
    "GEMINI.md": "Independent context file — Agy/Gemini CLI reads this directly. Not replaced by AGENTS.md unless user symlinks.",
    "note": "Agent-specific files remain standalone. Users opt in to symlink them to AGENTS.md via the agents-standard CLI. The standard exists so tool creators don't have to manage multiple rules files — they just read their own file (or AGENTS.md natively) and the standard handles the rest."
  },
  "env_vars": {
    "AGENTS_DEPTH": {
      "description": "Controls how many directory levels of AGENTS.md to read from project root downward (never upward)",
      "default": 3,
      "values": {
        "1": "~/.agents/AGENTS.md only (global rules, no project/folder)",
        "2": "global + project base .agents/AGENTS.md",
        "3": "global + project base .agents/AGENTS.md + project root AGENTS.md (default)",
        "4+": "global + project base .agents/AGENTS.md + project root AGENTS.md + cwd sub-folder AGENTS.md"
      }
    },
    "AGENTS_PATH": {
      "description": "Override the global AGENTS.md path (default: ~/.agents/AGENTS.md)",
      "default": "~/.agents/AGENTS.md"
    },
    "AGENTS_ROOT": {
      "description": "Explicitly set the project root directory. Overrides shell-inherited cwd detection.",
      "default": "inherited from shell's initial $PWD at launch time"
    }
  },
  "conflict_policy": "most-specific-wins (folder > project > global)",
  "inheritance": "extend",
  "format": "text/markdown",
  "agents": {
    "pi": {
      "file": "AGENTS.md",
      "global_path": "~/.agents/AGENTS.md",
      "project_path": "AGENTS.md",
      "native": true,
      "mcp_config": { "note": "Uses AGENTS.md convention; MCP servers configured per-project" },
      "docs_url": "https://github.com/nbiish/agents-standard"
    },
    "claude-code": {
      "file": "CLAUDE.md",
      "global_path": "~/.claude/CLAUDE.md",
      "project_path": "CLAUDE.md",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "~/.claude.json",
        "project_path": ".mcp.json",
        "format": "json"
      },
      "docs_url": "https://docs.anthropic.com/en/docs/claude-code"
    },
    "agy": {
      "file": "GEMINI.md",
      "global_path": "~/.gemini/GEMINI.md",
      "project_path": "GEMINI.md",
      "native": false,
      "symlink": true,
      "note": "Formerly Gemini CLI. Uses same gemini CLI tooling and config paths.",
      "mcp_config": {
        "global_path": "~/.gemini/settings.json",
        "project_path": ".gemini/settings.json",
        "format": "json"
      },
      "docs_url": "https://github.com/google-gemini/gemini-cli"
    },
    "codex": {
      "file": "AGENTS.md",
      "global_path": "~/.codex/instructions.md",
      "project_path": "AGENTS.md",
      "native": false,
      "symlink": true,
      "note": "Also reads instructions.md globally. Project-level reads AGENTS.md.",
      "mcp_config": {
        "global_path": "~/.codex/config.toml",
        "project_path": null,
        "format": "toml"
      },
      "docs_url": "https://github.com/openai/codex"
    },
    "cursor": {
      "file": ".cursorrules",
      "global_path": "~/.cursor/rules/",
      "project_path": ".cursorrules",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "~/.cursor/mcp.json",
        "project_path": ".cursor/mcp.json",
        "format": "json"
      },
      "docs_url": "https://docs.cursor.com/context/rules-for-ai"
    },
    "github-copilot": {
      "file": "copilot-instructions.md",
      "global_path": null,
      "project_path": ".github/copilot-instructions.md",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "Settings UI",
        "project_path": ".github/copilot-mcp.json",
        "format": "json"
      },
      "docs_url": "https://docs.github.com/en/copilot/customizing-copilot"
    },
    "windsurf": {
      "file": ".windsurfrules",
      "global_path": "~/.codeium/windsurf/",
      "project_path": ".windsurfrules",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "~/.codeium/windsurf/mcp_config.json",
        "project_path": null,
        "format": "json"
      },
      "docs_url": "https://docs.windsurf.com/windsurf/cascade"
    },
    "cline": {
      "file": ".clinerules",
      "global_path": "~/.cline/cline_rules",
      "project_path": ".clinerules",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "VS Code globalStorage/cline_mcp_settings.json",
        "project_path": null,
        "format": "json"
      },
      "docs_url": "https://github.com/cline/cline"
    },
    "roo": {
      "file": ".roorules",
      "global_path": "~/.roo/rules/",
      "project_path": ".roorules",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "Extension settings",
        "project_path": ".roo/mcp.json",
        "format": "json"
      },
      "docs_url": "https://docs.roocode.com/features/mcp/using-mcp-in-roo"
    },
    "kiro": {
      "file": "kiro.md",
      "global_path": "~/.kiro/kiro.md",
      "project_path": ".kiro/kiro.md",
      "native": false,
      "symlink": true,
      "roles_path": {
        "global_path": "~/.kiro/steering/",
        "project_path": ".kiro/steering/"
      },
      "mcp_config": {
        "global_path": "~/.kiro/settings/mcp.json",
        "project_path": ".kiro/settings/mcp.json",
        "format": "json"
      },
      "docs_url": "https://kiro.dev/docs/guides/learn-by-playing/07-extending-kiro-with-mcp/"
    },
    "kilocode": {
      "file": "AGENTS.md",
      "global_path": null,
      "project_path": "AGENTS.md",
      "native": true,
      "note": "Kilo Code is a VS Code extension / CLI. Native AGENTS.md support at project root. Also reads .kilo/agents/*.md for custom agents.",
      "roles_path": {
        "global_path": null,
        "project_path": ".kilo/agents/"
      },
      "mcp_config": {
        "global_path": "Extension settings",
        "project_path": "kilo.jsonc",
        "format": "jsonc"
      },
      "docs_url": "https://kilo.ai/docs/customize/agents-md"
    },
    "augment": {
      "file": ".augment-guidelines",
      "global_path": "~/.augment/guidelines",
      "project_path": ".augment-guidelines",
      "native": false,
      "symlink": true,
      "roles_path": {
        "global_path": null,
        "project_path": ".augment/rules/"
      },
      "mcp_config": {
        "global_path": "~/.augment/settings.json",
        "project_path": null,
        "format": "json"
      },
      "docs_url": "https://docs.augmentcode.com/setup-augment/mcp"
    },
    "goose": {
      "file": "goosehints",
      "global_path": "~/.config/goose/goosehints",
      "project_path": ".goosehints",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "~/.config/goose/config.yaml",
        "project_path": null,
        "format": "yaml"
      },
      "docs_url": "https://block.github.io/goose/docs"
    },
    "junie": {
      "file": "guidelines.md",
      "global_path": "~/.junie/guidelines.md",
      "project_path": ".junie/guidelines.md",
      "native": false,
      "symlink": true,
      "note": "Also reads .junie-rules at project root for coding conventions.",
      "mcp_config": {
        "global_path": "~/.junie/mcp.json",
        "project_path": ".junie/mcp/mcp.json",
        "format": "json"
      },
      "docs_url": "https://www.jetbrains.com/help/junie/mcp-settings.html"
    },
    "trae": {
      "file": ".trae/rules/",
      "global_path": "~/.trae/rules/",
      "project_path": ".trae/rules/",
      "native": false,
      "symlink": true,
      "roles_path": {
        "global_path": "~/.trae/rules/user_rules.md",
        "project_path": ".trae/rules/project_rules.md"
      },
      "mcp_config": {
        "global_path": "~/Library/Application Support/Trae/User/mcp.json",
        "project_path": null,
        "format": "json"
      },
      "docs_url": "https://docs.trae.ai/en/agent"
    },
    "aider": {
      "file": ".aider.conf.yml",
      "global_path": "~/.aider.conf.yml",
      "project_path": ".aider.conf.yml",
      "native": false,
      "symlink": true,
      "note": "YAML format, not markdown. Symlink still works if Aider reads symlink targets.",
      "mcp_config": { "note": "No dedicated MCP config file. MCP servers configured via .aider.conf.yml convention scripts." },
      "docs_url": "https://aider.chat/docs/config.html"
    },
    "continue": {
      "file": "config.json",
      "global_path": "~/.continue/config.json",
      "project_path": ".continue/config.json",
      "native": false,
      "symlink": true,
      "note": "JSON format, not markdown. MCP servers in .continue/mcpServers/ directory.",
      "mcp_config": {
        "global_path": "~/.continue/config.yaml",
        "project_path": ".continue/mcpServers/",
        "format": "yaml"
      },
      "docs_url": "https://docs.continue.dev/customize/deep-dives/mcp"
    },
    "codestral": {
      "file": "CODESTRAL.md",
      "global_path": null,
      "project_path": "CODESTRAL.md",
      "native": false,
      "symlink": true,
      "mcp_config": { "note": "No dedicated MCP config file. Mistral API key in environment variables." },
      "docs_url": "https://docs.mistral.ai/agents/mcp/"
    },
    "qwen-code": {
      "file": "QWEN.md",
      "global_path": null,
      "project_path": "QWEN.md",
      "native": false,
      "symlink": true,
      "note": "Configure global support via QWEN_HOME environment variable pointing to ~/.agents.",
      "mcp_config": {
        "global_path": "~/.qwen/settings.json",
        "project_path": ".qwen/settings.json",
        "format": "json"
      },
      "docs_url": "https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/"
    },
    "devin": {
      "file": "instructions.md",
      "global_path": null,
      "project_path": ".devin/instructions.md",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "Settings UI / MCP Marketplace",
        "project_path": null,
        "format": null
      },
      "docs_url": "https://docs.devin.ai/work-with-devin/mcp"
    },
    "warp": {
      "file": "warp.md",
      "global_path": null,
      "project_path": "WARP.md",
      "native": false,
      "symlink": true,
      "note": "Compatible with AGENTS.md, CLAUDE.md, .cursorrules. Also reads .warp/ directory.",
      "roles_path": {
        "global_path": null,
        "project_path": ".warp/"
      },
      "mcp_config": {
        "global_path": "Settings UI (Warp Drive → MCP Servers)",
        "project_path": ".warp/mcp.json",
        "format": "json"
      },
      "docs_url": "https://github.com/warpdotdev/Warp"
    },
    "crush": {
      "file": "AGENTS.md",
      "global_path": "~/.config/crush/crush.md",
      "project_path": "CRUSH.md",
      "native": false,
      "symlink": true,
      "mcp_config": {
        "global_path": "~/.config/crush/crush.json",
        "project_path": "crush.json",
        "format": "json"
      },
      "docs_url": "https://github.com/charmbracelet/crush"
    },
    "opencode": {
      "file": "AGENTS.md",
      "global_path": null,
      "project_path": "AGENTS.md",
      "native": true,
      "note": "Native AGENTS.md support. Also reads .cursorrules, CLAUDE.md, .github/copilot-instructions.md via contextPaths.",
      "roles_path": {
        "global_path": null,
        "project_path": ".opencode/agent/"
      },
      "mcp_config": {
        "global_path": "~/.config/opencode/opencode.json",
        "project_path": "opencode.json",
        "format": "jsonc"
      },
      "docs_url": "https://github.com/anomalyco/opencode"
    },
    "dcode": {
      "file": "AGENTS.md",
      "global_path": "~/.deepagents/AGENTS.md",
      "project_path": ".deepagents/AGENTS.md",
      "native": true,
      "note": "Deep Agents Code by LangChain. Native AGENTS.md support. Also reads project-root AGENTS.md.",
      "mcp_config": {
        "global_path": "~/.deepagents/.mcp.json",
        "project_path": null,
        "format": "json"
      },
      "docs_url": "https://docs.langchain.com/oss/javascript/deepagents/code/overview"
    },
    "codewhale": {
      "file": "AGENTS.md",
      "global_path": "~/.agents/AGENTS.md",
      "project_path": "AGENTS.md",
      "native": true,
      "note": "CodeWhale by Hmbown. DeepSeek-first terminal agent with ACP support. Natively loads ~/.agents/AGENTS.md.",
      "docs_url": "https://github.com/Hmbown/CodeWhale"
    },
    "hermes-agent": {
      "file": "AGENTS.md",
      "global_path": "~/.hermes/SOUL.md",
      "project_path": "AGENTS.md",
      "native": false,
      "symlink": true,
      "note": "Hermes Agent by NousResearch. SOUL.md is the global identity file. Also reads AGENTS.md per project.",
      "mcp_config": {
        "global_path": "~/.hermes/config.yaml",
        "project_path": null,
        "format": "yaml"
      },
      "docs_url": "https://github.com/NousResearch/hermes-agent"
    },
    "agent-zero": {
      "file": "AGENTS.md",
      "global_path": null,
      "project_path": "AGENTS.md",
      "native": false,
      "symlink": true,
      "note": "Agent Zero (a0) by agent0ai. Docker-based with Web UI. Per-project config in .a0proj/ directory.",
      "roles_path": {
        "global_path": null,
        "project_path": ".a0proj/instructions/"
      },
      "mcp_config": { "note": "Docker/Web UI based. Use Agent Zero Settings UI for MCP configuration." },
      "docs_url": "https://github.com/agent0ai/agent-zero"
    },
    "mini": {
      "file": "AGENTS.md",
      "global_path": "~/.minicc/AGENTS.md",
      "project_path": "AGENTS.md",
      "native": false,
      "symlink": true,
      "note": "MiniCC — a minimal AI coding agent CLI. Reads AGENTS.md globally and per project.",
      "mcp_config": {
        "global_path": "~/.minicc/mcp.json",
        "project_path": ".minicc/mcp.json",
        "format": "json"
      },
      "docs_url": "https://github.com/TokenRollAI/minicc"
    },
    "zed": {
      "file": "AGENTS.md",
      "global_path": "~/.config/zed/AGENTS.md",
      "project_path": "AGENTS.md",
      "native": true,
      "note": "Zed IDE. Reads AGENTS.md, .cursorrules, and .zed/ configuration. Native AGENTS.md support.",
      "roles_path": {
        "global_path": null,
        "project_path": ".zed/"
      },
      "docs_url": "https://zed.dev/docs"
    },
    "fcc-claude": {
      "file": "AGENTS.md",
      "global_path": "~/.fcc/.env",
      "project_path": null,
      "native": false,
      "symlink": true,
      "note": "FreeCodeCamp Claude — ACP agent routing through fcc-server. Global config via ~/.fcc/.env with model routing. Project rules via AGENTS.md.",
      "docs_url": "https://github.com/nbiish/agents-standard"
    }
  }
}