A structured documentation repository that AI coding agents use as context when working in a codebase.

An agentic knowledge store is a set of documentation files designed to be read by AI coding agents (Claude Code, Codex, Copilot, etc.) before they write code. It gives agents the architectural context, coding standards, gotchas, and product understanding they need to produce high-quality work — without you repeating yourself every session.

Think of it as onboarding docs, but optimized for machines.

AI agents are powerful but context-poor. Without guidance, they:

• Reinvent patterns that already exist in your codebase
• Miss critical gotchas and footguns
• Write code that doesn't match your conventions
• Make architectural decisions without understanding the system

This knowledge store fixes that by giving agents a structured, discoverable source of truth.

├── AGENTS.md                    # START HERE — dev setup, commands, gotchas, PR format
├── ARCHITECTURE.md              # System design, domain model, data flow, infrastructure
├── README.md                    # This file (meta-doc)
└── docs/
    ├── DESIGN.md                # Design philosophy, visual language, component patterns
    ├── FRONTEND.md              # Frontend stack, tooling, patterns, gotchas
    ├── PLANS.md                 # How to write and structure execution plans
    ├── PRODUCT_SENSE.md         # Product thinking — what we build and why
    ├── QUALITY_SCORE.md         # Quality rubric for code review and self-assessment
    ├── RELIABILITY.md           # Error handling, observability, resilience patterns
    ├── SECURITY.md              # Security policies, auth patterns, secret management
    ├── design-docs/
    │   ├── index.md             # Index of architectural decisions
    │   └── core-beliefs.md      # Non-negotiable engineering principles
    ├── exec-plans/
    │   ├── active/              # In-progress execution plans
    │   ├── completed/           # Shipped execution plans (for reference)
    │   └── tech-debt-tracker.md # Known tech debt with priority and context
    ├── generated/
    │   └── db-schema.md         # Auto-generated schema documentation
    ├── product-specs/
    │   ├── index.md             # Index of product specs
    │   └── example-spec.md      # Template for writing product specs
    └── references/
        └── README.md            # External references, vendor docs, API docs

1. AGENTS.md is the entry point. Agents read this first for setup, commands, and standards.
2. ARCHITECTURE.md is the map. Agents read this to understand the system before making changes.
3. docs/ files are deep dives. Agents read relevant docs based on the task at hand.
4. exec-plans/ track work. Agents create plans in active/ before complex work and move them to completed/ when done.

1. Copy this directory structure into your repo root (or a docs/ subdirectory)
2. Start with AGENTS.md — fill in every placeholder. This is the highest-ROI file.
3. Fill in ARCHITECTURE.md next — domain model, directories, integrations
4. Add docs as you go — don't try to write everything upfront

• Update docs when you build, not after
• Add gotchas to AGENTS.md the moment you discover them
• Move completed exec plans to completed/ — they're valuable context for future work
• Run a periodic review (monthly) to prune stale content

• Placeholders use <angle_brackets> — search for < to find unfilled sections
• Every code block should be copy-paste runnable — agents will try to execute them
• Link between docs — use relative paths (e.g. See docs/FRONTEND.md)
• Keep AGENTS.md under 200 lines — it's read every session; link to deeper docs