{"id":44350745,"url":"https://github.com/bgreenwell/dotagents","last_synced_at":"2026-02-11T15:05:17.902Z","repository":{"id":335682533,"uuid":"1146699855","full_name":"bgreenwell/dotagents","owner":"bgreenwell","description":"A proposed standard for the .agents/ directory to prevent context bloat and improve agent reasoning in complex codebases.","archived":false,"fork":false,"pushed_at":"2026-01-31T15:17:45.000Z","size":13,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-01T02:13:29.021Z","etag":null,"topics":["agent-memory","agents-md","ai-agents","claude-code","coding-assistant","context","context-window","dotagents","gemini-cli","standard"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bgreenwell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-31T14:35:57.000Z","updated_at":"2026-01-31T17:39:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bgreenwell/dotagents","commit_stats":null,"previous_names":["bgreenwell/dotagents"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bgreenwell/dotagents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreenwell%2Fdotagents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreenwell%2Fdotagents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreenwell%2Fdotagents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreenwell%2Fdotagents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bgreenwell","download_url":"https://codeload.github.com/bgreenwell/dotagents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreenwell%2Fdotagents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29336064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T14:34:07.188Z","status":"ssl_error","status_checked_at":"2026-02-11T14:34:06.809Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agents-md","ai-agents","claude-code","coding-assistant","context","context-window","dotagents","gemini-cli","standard"],"created_at":"2026-02-11T15:05:16.891Z","updated_at":"2026-02-11T15:05:17.889Z","avatar_url":"https://github.com/bgreenwell.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dotagents\n\n**A directory-as-context standard for AI agents.**\n\n\u003e **Status:** Proposal / Draft 0.1.0\n\n\u003e **Inspiration:** Based on experience, emerging patterns in agentic coding, and [Issue #71 in agentsmd/agents.md](https://github.com/agentsmd/agents.md/issues/71).\n\n---\n\n## The problem: Context file manageability\n\nAs AI agents become integral to development, single context files (e.g., `AGENTS.md`, `CLAUDE.md`, `.cursorrules`) can become difficult to manage.\n\nA monolithic file often leads to:\n1.  **Inefficient token usage:** Agents read irrelevant information (e.g., database schemas when working on CSS).\n2.  **Conflicting instructions:** Mixing behavioral rules with static knowledge can confuse priority.\n3.  **Tool noise:** Multiple vendor-specific folders (`.claude/`, `.gemini/`, `.cursor/`) clutter the root directory.\n\n## The solution: Organization via `AGENTS.md`\n\nThe **dotagents** standard is a philosophy of organization. It proposes using a slim `AGENTS.md` file in your project root to act as a **router**, directing agents to deeper context only when they need it.\n\nWhile you can organize your project context however you like, we recommend using a hidden `.agents/` directory to keep your root clean and provide a predictable structure for different types of agent data.\n\n### Recommended directory structure\n\nThis structure is a starting point—feel free to adapt it to your project's needs.\n\n```text\n.\n├── AGENTS.md             # Entry point \u0026 router (Required)\n└── .agents/              # Recommended context directory\n    ├── rules/            # Invariant behavioral guidelines\n    │   ├── coding.md     # e.g. \"No `any` types\"\n    │   └── comms.md      # e.g. \"Be concise\"\n    ├── context/          # Static reference data (read-only)\n    │   ├── schema.sql    # Database structure\n    │   └── api.ts        # API interfaces\n    ├── logs/             # Agent activity logs \u0026 audit trails\n    │   └── session_1.md\n    ├── memory/           # Persistent project knowledge (read/write)\n    │   ├── decisions.md  # ADRs (why we chose X over Y)\n    │   └── user.md       # Learned user preferences\n    ├── personas/         # Specialized agent profiles\n    │   └── qa.md         # e.g. \"QA Engineer\" hat\n    ├── skills/           # Executable capabilities (agentskills.io compliant)\n    │   └── database-migration/\n    │       ├── SKILL.md\n    │       └── scripts/\n    │           └── migrate.sh\n    └── specs/            # Current task requirements\n        └── feature_x.md\n```\n\n---\n\n## Usage\n\n### 1. The root file (`AGENTS.md`)\n\nThe heart of the standard. This file defines the agent's identity and provides instructions on where to find specific information. By keeping this file small, you save tokens and maintain clarity.\n\n**Example `AGENTS.md`:**\n\n```markdown\n# AGENTS.md\n\n## Identity\nYou are a Senior Rust Engineer focused on safety and performance.\n\n## Context routing\n- **If working on database:** READ `.agents/context/schema.sql`\n- **If writing new features:** CHECK `.agents/specs/` for active PRDs.\n- **If facing a decision:** CONSULT `.agents/memory/decisions.md` to ensure consistency.\n\n## Capabilities\n- You may execute scripts found in `.agents/skills/` to validate your work.\n```\n\n### 2. The `.agents/` directory (Ideas for organization)\n\nThis directory is where you store the \"heavy\" context. By organizing it logically, you enable **Progressive Disclosure**—loading only what is necessary for the task at hand.\n\n#### Personas\n*Recommended for: Specialized roles.*\nStore specialized agent \"hats\" (e.g., `qa.md`, `architect.md`) here. You can instruct your agent to \"adopt the QA persona found in `.agents/personas/qa.md`\" when it's time to test.\n\n#### Logs\n*Recommended for: Audit \u0026 Debugging.*\nKeep a clean root by storing session logs, agent thought traces, or execution history in a dedicated folder.\n\n#### Memory\n*Recommended for: Long-term knowledge.*\nA place for agents to persist what they've learned about your preferences or the project's history (e.g., `.agents/memory/decisions.md`).\n\n#### Skills\n*Recommended for: Executable capabilities.*\nThis directory is a perfect home for [agentskills.io](https://agentskills.io) compliant skills. Place your `SKILL.md` folders here alongside their supporting scripts.\n\n#### Context \u0026 Specs\n*Recommended for: Static \u0026 Active data.*\nKeep your database schemas, API specs, and current feature requirements organized so the agent knows exactly where to look.\n\n---\n\n## Relation to Agent Skills (agentskills.io)\n\n**dotagents** and the **Agent Skills** standard are complementary. **Agent Skills** defines the *format* (how a skill is written), while **dotagents** defines the *architecture* (where it lives in your project).\n\n| Feature | Agent Skills (agentskills.io) | dotagents |\n| :--- | :--- | :--- |\n| **Primary Goal** | **Standardize Behavior.** Defines the `SKILL.md` format for specific workflows. | **Standardize Organization.** Defines a unified directory structure for *all* agent data. |\n| **Scope** | **Skill-Local.** References are specific to the skill. | **Project-Wide.** Context is global to the project. |\n| **Implementation** | **Vendor-Fragmented.** Can lead to duplication across `.claude/`, `.cursor/`, etc. | **Vendor-Agnostic.** A single source of truth for all tools. |\n\n---\n\n## FAQ\n\n**Why not use `.github/`?**\n`.github` is platform-specific. `dotagents` is designed to be platform-agnostic, usable by local LLMs, IDE agents, and CLI agents alike.\n\n**Should `.agents/` be committed?**\nGenerally, yes. This context is valuable for team alignment. Personal preferences (e.g., `.agents/memory/user.md`) should usually be gitignored.\n\n**Is this related to `iannuttall/dotagents`?**\nWhile they share a name, they serve different purposes. [iannuttall/dotagents](https://github.com/iannuttall/dotagents) is a tool for managing personal agent configurations across projects via symlinks. This project is an **architectural standard** for organizing project-specific context within a repository.\n\n**Why use this standard?**\nIt's about **efficiency** and **cleanliness**. It encourages referencing files only when needed (\"context routing\") and prevents the explosion of vendor-specific configuration folders in your project root.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgreenwell%2Fdotagents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbgreenwell%2Fdotagents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgreenwell%2Fdotagents/lists"}