One
.agent/folder. Every AI coding tool in sync. A navigation manifest that points every AI agent (Claude Code, Cursor, Copilot, OpenCode) at the same canonical context — bug registry, anti-patterns, DB hotspots, Redis keys, feature docs, ops references. Plus a dev↔QA cycle, durable business-intent capture, and a project-management layer with mandatory rationale on every decision.
Every AI coding agent reads its own config file (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, AGENTS.md). dotagent generates all of them from a single canonical schema, with the body identical across every tool.
The body is a navigation manifest (~3K–40K tokens depending on schema size): four invariant layers (reading protocol · workflow contract · hard policy · navigation index) followed by schema-driven pointers at your docs/ and .agent/ files. Tools read the manifest first, then chase pointers on demand. No 80K-token compendia.
pipx install "git+https://github.com/dilawarabbas1/dotagent"
cd ~/code/your-repo
dotagent init # scaffolds .agent/, renders CLAUDE.md + sister adapters
dotagent doctor # self-checkOpen Claude Code (or Cursor, or VS Code with Copilot, or OpenCode) in that repo. The generated CLAUDE.md is the navigation manifest. Edit docs/*.md and run dotagent sync (or let the pre-commit hook do it).
Layer 1 — How to read this file (invariant reading protocol)
Layer 2 — Workflow contract (invariant; carries OWNERSHIP RULE)
Layer 3 — Hard policy (invariant never-violate list)
Layer 4 — Navigation manifest (schema-driven per tier)
The OWNERSHIP RULE is the load-bearing sentence:
- dotagent writes GENERATED files (CLAUDE.md, SCOPE.md, CONTRACTS.md, git.md, PLAN.md, contract.frozen.md, contracts.md, docs/service-registry.md, .agent/dashboard.md, per-module HISTORY.md). Hand-edits get wiped on next sync.
- YOU write CONTENT files (
docs/*.md+ cycle artifacts). dotagent never writes there.
Files carry a <!-- generated by dotagent --> banner if and only if dotagent owns them.
dotagent recognises three project shapes; the manifest auto-adapts.
| Tier | Detected by | Use case |
|---|---|---|
| project-root | .agent/git.yaml present |
Multi-service meta repo (the parent) |
| service-repo | parent: in config.yaml |
A service repo inside a layered project — manifest carries ../-prefixed INHERITED pointers |
| single-repo | Neither | Standalone project (default for new installs) |
Same renderer, schema entries differ. See docs/SERVICE_REPO_CLAUDE_MD.md for the service-repo specifics.
| File | Source | Tier |
|---|---|---|
CLAUDE.md, .cursorrules, .github/copilot-instructions.md, AGENTS.md |
canonical schema + workflow templates | any |
.agent/git.md |
.agent/git.yaml |
project-root |
.agent/project/SCOPE.md |
plan.yaml + brief |
any with plan |
.agent/project/CONTRACTS.md |
walking modules + cycles | any with modules |
.agent/project/modules/<id>/PLAN.md |
module.yaml |
any with modules |
.agent/project/modules/<id>/cycles/<NN>/contract.frozen.md |
post-freeze snapshot | any with cycles |
.agent/project/modules/<id>/HISTORY.md |
walking cycles + completion | any with modules |
.agent/dashboard.md |
project state + episodic + doc mtimes | any |
contracts.md (project-root only) |
cross-repo rollup | project-root |
docs/service-registry.md (project-root only) |
git.yaml repos: |
project-root |
Every generated file carries a <!-- generated by dotagent · do not hand-edit --> banner. See docs/DERIVED_FILES_DESIGN.md.
A canonical hand-maintained documentation convention is supported (and surfaced in CLAUDE.md as navigation pointers) without ever touching the content:
docs/
├── feature_master.md Entry-point feature index
├── feature_master/FM-###-<slug>.md Per-feature record
├── db-impact-map-{master,tenant,vector}.md Deep DB dependency
├── redis-key-registry-{tenant,global,events}.md Deep Redis dependency
├── anti-patterns.md AP-### rules
├── bug-registry-{infrastructure,agents, DA-BUG history (sharded)
│ orchestrator}.md
├── ARCHITECTURE.md System design narrative
└── ops/
├── service-registry.md pm2 / port / host (NOT the generated git-repo table)
├── server-dependencies.md
├── tuning.md
└── tls-and-env.md
The single-file conventions (docs/bug-registry.md, docs/redis-keys.md, docs/db-impact-map.md) also work — sharded variants are additive. See docs/HAND_MAINTAINED_DOCS_CONVENTION.md for the boundary contract.
dotagent doc-coverage --files X,Y,Z returns the required-doc checklist for a changed-file set, severity-tagged (HARD / SUGGESTED / CHECK). See docs/DOC_COVERAGE_CLI.md.
| Memory | When | Stored at | Shared? |
|---|---|---|---|
| Working | now | .agent/memory/working/<actor>/current.json |
local only |
| Episodic | every event | .agent/memory/episodic/YYYY/MM/DD/<actor>__<session>.jsonl |
committed; no merge conflicts by design |
| Semantic | patterns + rules | .agent/memory/semantic/{rules,patterns}/.../<sha>-<slug>.md |
committed; content-hashed |
| Personal | per-actor style | .agent/memory/personal/<actor>/profile.yaml |
per-actor; never merged into other devs' adapters |
Every recorded event has actor, tool, host, session. Filenames namespace by actor + session → zero merge conflicts when two teammates edit the same day.
# Core
dotagent status # what dotagent knows about this repo
dotagent context # exactly what an AI agent sees
dotagent sync # rebuild adapters + derived files
dotagent sync --dry-run # unified diff; no writes
dotagent doctor # self-check
dotagent update # self-upgrade
# Manifest preview
dotagent manifest # render v3 manifest to stdout
dotagent manifest --tier service-repo # force a tier
dotagent manifest --diff CLAUDE.md # show what would change
# Hand-maintained doc coverage
dotagent doc-coverage --files "src/a.py,src/b.py" --format json
dotagent doc-coverage --files ... --commit-msg "DA-BUG-INFRA-042"
dotagent doc-coverage --files ... --severity hard # FM-### gates only
# Visibility
dotagent who --file path/to/file.py # who touched this file with which AI
dotagent timeline path/to/file.py
dotagent activity --since 7d --by alice --tool claude_code
dotagent feed --limit 50
dotagent leaderboard --since 30d
# Project management
dotagent project init # interactive scope-builder
dotagent project add-module "<name>" # per-module Q&A
dotagent project start <id> # open a dev cycle
dotagent project handoff <id> # writes cycles/<NN>/dev-handoff.md
dotagent project qa-record <id> --result pass|fail --rationale "..." # rationale REQUIRED
dotagent project resolve <id> # ship after qa-pass
dotagent project regenerate # refresh derived files; no state change
dotagent project status # source-of-truth completion %
# Brief + contracts
dotagent project brief init # interactive Q&A → project_brief.md
dotagent project brief check # OBJ → FEAT → Module → Contract audit
dotagent project contract round --actor <dev|qa>
dotagent project contract score # 11-signal rubric
dotagent project contract freeze # rejects on non-convergence
# Auto-Dream (graduated rules)
dotagent dream run --since 30d
dotagent dream graduate <id> --rationale "..." # rationale REQUIRED
dotagent dream reject <id> --rationale "..."
# Git layout (project-root only)
dotagent git init / status / push / pull
dotagent git clone-services
dotagent git scaffold-protection # GitHub Actions workflow
# Tools
dotagent tool debug "$(cat trace.txt)" # stack trace → past failures
dotagent tool checklist --since 14d # pre-deploy gate
dotagent tool memory "BUG-001" # search the four memoriesModules are tracked end-to-end via interactive Q&A then a strict dev↔QA cycle. Documents wire the handoff in both directions:
project add-module "Auth" → interactive Q&A → PLAN.md
project start 01-auth → cycle 1 opens
... dev work ...
project handoff 01-auth → writes cycles/01/dev-handoff.md (QA reads this)
project qa-record 01-auth → if FAIL: writes qa-findings.md (dev reads next round)
--result fail --rationale "..."
project start 01-auth → cycle 2 opens automatically
... fixes ...
project handoff 01-auth → cycles/02/dev-handoff.md
project qa-record --result pass --rationale "..."
project resolve 01-auth → SHIPPED; completion.md written; HISTORY.md updated
Rationale on qa-record is mandatory. The contract negotiation runs rounds between dev and QA with a built-in S1–S11 scoring rubric (max 33; ready ≥30 · polish ≥24 · rework ≥18 · not_ready ≤17). Frozen contracts are immutable.
Multi-service projects have a project-root layer holding cross-cutting business intent + hard rules + shared docs, with each service repo inheriting via parent: in its .agent/config.yaml:
Project Root/ (own git repo, e.g. aigent-meta)
├── .agent/
│ ├── project_brief.md ← business OBJs + FEATs + RULEs
│ ├── git.yaml ← repo manifest + branch rules
│ └── project/plan.yaml ← FEAT → Module mapping
├── docs/ ← cross-cutting source docs
├── contracts.md ← Tier-1 cross-repo rollup (generated)
│
├── backend/ ← service repo
│ └── .agent/config.yaml ← parent: ../..
├── customer-portal/
└── admin-portal/
Each service repo's CLAUDE.md carries ../-prefixed INHERITED pointers at the parent's project_brief, rules, git.md, architecture, style, patterns, plan.yaml, etc. — surfaced in the same navigation manifest as the service-local context.
dotagent git.yaml is project-root-scope only; service-repos read the rendered git.md dashboard, never the YAML.
Every contract cites the brief IDs it serves. dotagent project brief check audits the full chain:
OBJ-01 ──► FEAT-02 ──► M02-password-reset ──► cycles/01/contract.frozen.md
<!-- anchor: business-traceability -->
**Feature(s):** FEAT-02
**Objective(s):** OBJ-01, OBJ-02
The contract-scoring rubric includes S11 — Business traceability (0-3), making the total max 33.
pip install 'dotagent[ml]' # sentence-transformers + sklearn → semantic clustering for Auto-Dream
pip install 'dotagent[server]' # FastAPI + uvicorn → `dotagent serve`
pip install 'dotagent[watch]' # watchdog → `dotagent watch cursor`
pip install 'dotagent[all]' # everything aboveBase install stays small (~5 MB).
docs/*.md ─────────────────────┐
(hand-maintained truth) │
▼
┌─────────────────────────────────┐
│ Source Indexer (sources.py) │
└─────────────┬───────────────────┘
│ structured entries
▼
.agent/*.md ──┐ ┌───────────────────┐ ┌── memory/working (now)
├─▶│ Context Resolver │◀─┼── memory/episodic (before)
config.yaml ──┘ │ (context.py) │ ├── memory/semantic (patterns)
└─────────┬─────────┘ └── memory/personal (per-actor)
│
▼
┌─────────────────────────────────┐
│ Manifest Renderer (v3) │
│ schema-driven, tier-aware │
└─────────────┬───────────────────┘
│ identical body, multiple targets
▼
CLAUDE.md · .cursorrules · copilot-instructions.md · AGENTS.md
│
▼
┌─────────────────────────────────┐
│ Derived files (render/derived) │
│ service-registry, HISTORY, │
│ dashboard, SCOPE, CONTRACTS │
└─────────────────────────────────┘
| CLAUDE.md alone | Cursor Rules | Copilot custom instr. | dotagent | |
|---|---|---|---|---|
| One file per tool | yes | yes | yes | one source, every tool, identical body |
| Schema-driven manifest | no | no | no | yes — coverage-gated by CI |
| Tier-aware (project-root / service / standalone) | no | no | no | yes; service-repo inherits |
| Embeds top-N from bug-registry / anti-patterns | manual | manual | manual | automatic (v1) or pointers only (v3 default) |
| Per-developer personalization | no | no | no | per-actor profile; never leaks |
| Attribution surviving in git log | no | no | no | Co-authored-by trailer |
| Stack-trace → past failures | no | no | no | dotagent tool debug |
| Auto-learn from team (mandatory rationale) | no | no | no | Auto-Dream |
| Track modules through dev↔QA cycle | no | no | no | dotagent project with mandatory QA rationale + S1–S11 scoring |
| Conflict detection on active edits | no | no | no | yes |
| Rule expiration + re-rationale | no | no | no | dream review-stale / rerationale / expire-stale |
| Required-doc coverage for changed files | no | no | no | dotagent doc-coverage |
| Doc | What |
|---|---|
USING_WITH_CLAUDE_CODE.md |
Practical session guide |
CHANGELOG.md |
Release notes |
CONTRIBUTING.md |
How to contribute |
docs/CLAUDE_MD_DESIGN.md |
Four-layer manifest design |
docs/SERVICE_REPO_CLAUDE_MD.md |
Service-repo tier (child of project-root) |
docs/DERIVED_FILES_DESIGN.md |
What dotagent generates |
docs/HAND_MAINTAINED_DOCS_CONVENTION.md |
What dotagent indexes but never writes |
docs/DOC_COVERAGE_CLI.md |
dotagent doc-coverage reference |
CODA_PROMPT.md |
Coda orchestrator integration spec |
examples/ |
Sample docs/*.md formats |
| Wiki | Getting Started · Architecture · Memory Model · Auto-Dream · Project Management · Multi-Project · Troubleshooting · FAQ |
dotagent doctor # first line of defense — covers 90% of issues
DOTAGENT_DEBUG=1 dotagent sync # surface silenced exceptions| Symptom | Fix |
|---|---|
CLAUDE.md still v1 (compendium) after v0.5 upgrade |
Check .agent/config.yaml — remove render: { use_manifest: false } or set to true |
| Pre-commit hook overwrites my docs | It doesn't — only re-renders generated adapters. Generated files aren't auto-staged. Disable via hooks.auto_regen_on_docs: false |
Tests reference KIND_GENERATED on a hand-maintained doc |
Boundary violation — file an issue. Test test_regenerate_derived_files_never_writes_hand_maintained should catch this. |
v0.5.3 — schema-driven navigation manifest is the default renderer. Layered project architecture, durable business-intent capture, end-to-end traceability, per-repo contracts dashboards, plan-negotiation primitives, cross-repo rollups, git-layout enforcement, derived-files orchestrator (service-registry · HISTORY · dashboard), hand-maintained docs convention, doc-coverage CLI.
dotagent now detects dotgraph at render time and refreshes graph-derived docs during sync; doctor reports the graph's freshness; the contract scaffold gained a ## Surfaces section that downstream gates can pipe into dotgraph reconcile.
792 tests passing. See CHANGELOG.md for what changed when.
MIT. See LICENSE.