An agent-first repository template and guide for agent-led development.
The repo IS the guide. It demonstrates every pattern it teaches.
Context_Map is a repository template that structures projects for AI agent productivity. It captures the patterns that make agent-led development work:
- Progressive disclosure — agents find the right info in ≤3 hops
- Docs as system of record — documentation drives development, not the reverse
- Execution plans as artifacts — structured plans with lifecycle states
- Quality scoring — automated enforcement of standards
- Multi-agent support — one truth, five entry points (Claude Code, Codex, Cursor, Copilot, universal)
- Teams adopting agent-led development — use as a template for new projects
- Developers working with AI agents — learn the patterns that reduce friction
- Anyone scaling agent workflows — proven structure for multi-session, multi-agent work
Start with your dedicated entry file — it has your orientation, constraints,
and routing into docs/:
| Agent | Entry Point |
|---|---|
| Any / Universal | AGENTS.md |
| Claude Code | CLAUDE.md |
| OpenAI Codex | CODEX.md |
| Cursor | .cursorrules → .cursor/rules/global.mdc |
| GitHub Copilot | .github/copilot-instructions.md |
gh repo create my-project --template context-map/context-map
cd my-project
# Or scaffold into an existing project with Claude Code:
# /context-map scaffoldStart with guide/README.md, or browse individual chapters:
- Why Agent Legibility
- Progressive Disclosure
- Multi-Agent Setup
- Execution Plans
- Quality & Enforcement
- Doc Gardening
- Session Handoffs
- Building Skills
Context_Map/
├── AGENTS.md # Universal agent entry point (routing table)
├── CLAUDE.md # Claude Code entry point (routing table)
├── CODEX.md # OpenAI Codex entry point (routing table)
├── ARCHITECTURE.md # Architecture summary → docs/architecture/
├── docs/ # THE SYSTEM OF RECORD (operational, mutable)
│ ├── _INDEX.md # Master navigation with freshness dates
│ ├── architecture/ # System design and ADRs
│ ├── golden-rules/ # Principles and coding standards
│ ├── quality/ # Scorecard and tech debt
│ ├── workflows/ # Development, PR, testing, doc processes
│ ├── agent-guide/ # Onboarding and common tasks
│ └── session/ # Session handoff state
├── plans/ # Execution plans (temporal, lifecycle)
│ ├── active/ # Currently executing plans
│ └── completed/ # Finished plans (archive)
├── guide/ # Educational content (read-only, immutable)
├── scripts/ # Validation and enforcement
├── .claude/ # Claude Code config and skills
├── .codex/ # OpenAI Codex config
├── .cursor/ # Cursor rules
└── .github/ # GitHub Copilot instructions
- Single source of truth — all agent entry files route to
docs/, never duplicate - Progressive disclosure — entry (~100 lines) → index → detailed doc → code
- Three content zones —
docs/(operational),guide/(educational),plans/(temporal) - Enforce what matters — if a rule is worth stating, it's worth checking automatically
- Freshness is measurable — every doc has a review date, staleness is detected
See docs/golden-rules/PRINCIPLES.md for the full set.
Run these from the repository root before committing changes:
scripts/check-structure.sh # All required files and directories exist
scripts/check-doc-freshness.sh # Every doc has a current review date
scripts/check-agent-files.sh # Agent entry points route correctly
scripts/check-doc-links.sh # Local markdown links resolveCI runs the same suite on every pull request via .github/workflows/validate.yml.
See docs/workflows/DEVELOPMENT.md for the full development workflow.
/context-map scaffold— scaffold the Context_Map structure in a new project/context-map audit— audit an existing project against the standard/session-handoff— generate a session handoff document
This is a template repository. To contribute:
- Fork the repo
- Create a feature branch
- Follow the development workflow in
docs/workflows/DEVELOPMENT.md - Submit a PR following
docs/workflows/PR_REVIEW.md
MIT — see LICENSE