DotContext

Portable context template for AI-assisted projects.

English | Português (Brasil)

DotContext is an open specification that ships with a context folder template (.context/) and an agent file template (AGENT.md).

The folder and file are intentionally generic in this repository. In real projects, you must rename both manually to match the IDE/assistant convention you use (for example: .github for GitHub Copilot, .claude for Claude).

Quick Navigation

• Why DotContext
• Structure of the Template
• How to Use
• File Reference
• Consistency Checklist
• Principles
• License

Why DotContext

DotContext is a lightweight, portable way to give AI-assisted projects a reliable operating context. Instead of restarting from zero in every chat, it organizes project identity, technical constraints, and prior decisions into a clear structure that agents can reuse across sessions. This reduces prompt repetition, lowers token waste, and improves response consistency.

It avoids the common "single giant context file" (for example, CLAUDE.md-style setups) problem by splitting information into focused, task-oriented files and loading only what is relevant for each job.

Structure of the Template

A compact context pack + agent instructions file:

.context/ (rename manually for your IDE)
├── README.md          → Governance: permissions and structure
├── index.toml         → Router: what the AI reads/writes per task
├── project.toml       → Identity: name, stack, URLs, design tokens
├── rules.md           → Standards: non-negotiable technical rules
├── soul.md            → Persona: AI behavior and restrictions
├── .contextignore     → Filter: files the AI should not read
├── memory/
│   ├── progress.md    → State: what has been built and current status
│   ├── issues.md      → Problems: bugs, workarounds, fragile areas
│   └── decisions.md   → ADR: architecture decision records
├── specs/
│   └── *.md           → Feature specifications
└── skills/
    └── *.md           → Reusable task guides

AGENT.md (rename manually for your IDE)

index.toml is the routing and permission contract for agents. AGENT.md is the compatibility entrypoint for IDEs that require an explicit instruction file.

Instead of one giant context file, DotContext splits context into focused files (identity, rules, memory, specs, skills) and routes them by task. This gives agents persistent, auditable memory while keeping active context lean.

Baseline estimated: ~300 lines (compact enough for most context windows).

How to Use

Quick Start (minimal path)

1. Copy .context/ + AGENT.md to your project root.
2. Rename both manually to your IDE/assistant convention.
3. Update path prefixes in index.toml.
4. Fill project.toml, rules.md, and soul.md.
5. Start working with specs/ + memory/ files.

1. Copy the template assets to your project root

# Clone the template
git clone https://github.com/gmasson/dotcontext.git
cp -r dotcontext/.context/ your-project/
cp dotcontext/AGENT.md your-project/

2. Rename folder and AGENT.md manually (required)

Use your tool's native naming convention.

IDE / Assistant	Rename folder to	Rename AGENT.md to	Example final location
GitHub Copilot	.github	copilot-instructions.md	.github/copilot-instructions.md
Claude	.claude	CLAUDE.md	.claude/CLAUDE.md
Other tools	tool-specific folder	tool-specific instruction file	tool-specific path

Always confirm the official naming required by your IDE/assistant version.

After renaming the folder, update path prefixes in index.toml (replace .context/ with your chosen folder).

Optional quick rename commands:

# Unix-like
mv .context .github
mv AGENT.md .github/copilot-instructions.md

# Windows PowerShell
Rename-Item .context .github
Rename-Item AGENT.md copilot-instructions.md
Move-Item copilot-instructions.md .github/

3. Fill in the essential files

Start with these three (loaded on every interaction):

File	What to fill in
project.toml	Name, version, stack, URLs, design tokens
rules.md	Code standards, architecture, naming, security
soul.md	How the AI should behave in your project

4. Use on demand

The remaining files are loaded as needed:

When	Relevant files
Code / Implement	memory/progress.md + specs/ + skills/
Debug / Fix	memory/issues.md + memory/progress.md
Plan / Architect	memory/decisions.md + memory/progress.md + specs/
Review / Audit	memory/issues.md + rules.md + specs/

File Reference

File	Purpose	Change when
index.toml	Routing contract ([always] + task sections with read/write)	You add/reorganize files or task categories
AGENT.md	IDE compatibility entrypoint (no route duplication)	Tool naming/compatibility changes
project.toml	Project identity (name, stack, URLs, tokens)	Infra, branding, or stack changes
rules.md	Non-negotiable technical standards	Team conventions or architecture evolve
soul.md	AI behavior/persona for this project	You need a different assistant posture
.contextignore	File exclusion filter (like .gitignore)	New build/cache/secret paths appear
memory/progress.md	Current project status	Work status changes
memory/issues.md	Known bugs + workarounds	Issues are found/fixed
memory/decisions.md	Append-only ADR log	New architectural decisions
specs/*.md	Feature contracts + acceptance criteria	New/updated feature scope
skills/*.md	Reusable project-specific procedures	Recurring process is standardized

If instructions conflict, prioritize index.toml routing and rules.md constraints.

Consistency Checklist

Before using in production, confirm:

• Folder and instruction file were renamed to your IDE convention
• index.toml path prefixes match your renamed folder
• project.toml, rules.md, and soul.md are filled
• AGENT instructions do not conflict with rules.md

Principles

1. Token-first — Every line must justify its token cost
2. Modular — Load only what's needed for each task
3. Portable — Same template, renamed manually to each IDE convention
4. Tool-agnostic — Any AI that reads files can use DotContext
5. Human-readable — Markdown and TOML are readable by both humans and machines

License

MIT — Use, modify, and distribute freely.