Modern development practices — clean code, SOLID, DRY — were designed for human cognition: long-term memory, implicit context, and the ability to read between the lines.
AI agents operate under fundamentally different constraints:
- No memory between sessions
- Limited context windows
- Strict dependence on what is explicitly written
DOTAGENT bridges this gap. It defines a repository structure that maximizes agent effectiveness without sacrificing human maintainability.
| Concept | Description |
|---|---|
.agent/ directory |
Centralized agent configuration: commands, skills, personas, and hooks |
AGENTS.md hierarchy |
Layered instructions from project-wide rules to module-specific overrides, following a locality principle |
| ADRs | Structured capture of the why behind decisions — critical for agents that lack cross-session memory |
| System invariants | Hard boundaries that must never be violated, with concrete code examples |
| TDD-first workflow | Tests as verifiable contracts that anchor agent reasoning and prevent functional hallucinations |
| Automatic review loop | After every change, the agent self-reviews and iterates until approved or a max limit is reached |
| Security boundaries | Protected files, forbidden patterns, and operational limits |
Run this in your project root:
curl -fsSL https://raw.githubusercontent.com/sgmonda/dotagent/main/install.sh | bashThat's it. Everything is installed under .dotagent/ with symlinks so all agent tools find what they need:
your-project/
├── .dotagent/ # All DOTAGENT files live here
│ ├── skills/ # Agent skills
│ ├── agent/ # Agent config (config.yaml, commands, hooks, personas)
│ ├── update.sh # Run this to update DOTAGENT
│ └── VERSION # Installed version
├── .agent → .dotagent/agent # Symlink (for agent tools)
├── .claude/skills → … # Symlink (for Claude Code)
├── AGENTS.md → .dotagent/… # Symlink (project-wide agent rules)
├── docs → .dotagent/docs # Symlink (ADRs, invariants)
└── ...
Then ask your agent:
/dotagent-bootstrap # New project: scaffold structure + configure
/dotagent-onboard # Existing project: analyze + generate agent briefing
The first run installs everything and scaffolds project template files (AGENTS.md, docs/, etc.). Subsequent runs only update skills and agent configuration.
Supported stacks: Python + FastAPI · Go + Gin · TypeScript + Node · Deno + Fresh · Rust · Java + Spring
Note
The /dotagent-onboard skill may be automatically loaded by your agent on startup or when addressing a complex task. It can also be invoked manually at any time.
Tip
Updating: Just ask your agent to run /dotagent-upgrade. It will fetch the latest version and apply any spec changes automatically.
dotagent/
├── install.sh # One-line installer
├── doc/
│ └── DOTAGENT.md # Full specification
├── skills/
│ ├── dotagent-bootstrap/SKILL.md
│ ├── dotagent-onboard/SKILL.md
│ └── dotagent-upgrade/SKILL.md
└── templates/ # Reference project structure
The complete specification is available at doc/DOTAGENT.md. It covers directory structure, agent configuration, documentation standards, testing strategy, TDD enforcement, automatic review loops, and security boundaries.
This project is open source. See LICENSE for details.