context-document

context

When to use

Use this skill when:

• Documenting a module, service, or integration for future reference
• Exploring an unfamiliar area of the codebase
• Preparing for a feature that touches multiple areas
• Onboarding to a new part of the codebase

Do NOT use when:

• Writing code or features
• Creating roadmaps (use roadmap-management skill)

Procedure: Manage contexts

1. Identify scope — Which area of the codebase needs a context document?
2. Research — Use codebase-retrieval to understand the area (files, patterns, dependencies).
3. Write or update — Create/update the context doc following the template below.
4. Verify — Confirm all referenced files exist and descriptions match current code.

A context document is a structured snapshot of a codebase area:

• What it does, why it exists
• Key files, classes, and patterns
• Database tables and API endpoints
• Dependencies and known issues

Unlike feature plans (future-focused) or roadmaps (task-focused), contexts are present-focused — they describe the current state of the code.

File structure

.augment/contexts/                       # Shared contexts (about the agent system itself)
├── augment-infrastructure.md
├── skills-and-commands.md
└── documentation-hierarchy.md

agents/settings/contexts/                                # Project-wide contexts
├── {context-name}.md

{module_root}/{Module}/{agent_folder}/settings/contexts/ # Module-scoped contexts
├── {context-name}.md                                    # Laravel: app/Modules/…
                                                         # Symfony: src/Bundle/…
                                                         # Monorepo: packages/…

.augment/templates/
└── contexts.md                          # Context template

Context types

Where to store contexts

Knowledge cards — a specialized, evidence-disciplined context type

A knowledge card extends this mechanism for the evidence-first discipline; it is not a second system. Unlike a normal context (a present-state snapshot a human curates), a card is governed: it is a cache of expensive remote evidence, never a source of truth and never a build input. Its trusted core is its negative facts + pointers (trust: durable); its positive structure is a per-line, last-verified hypothesis that loads as "Assumed (from card)" and must be re-confirmed against the live source before use. Cards pass the check_knowledge_cards.ts pointer-CI (size ≤ 150, mandatory authoritative pointer, trust tagging, multi-evidence consistency). See source-discovery for when a structure is card-worthy and evidence-discipline for the full model.

Knowledge pages — the typed sibling directories

Alongside knowledge cards, agents/knowledge/{sessions,concepts,procedures,decisions}/ holds team-shared knowledge that grows while working the project — coding standards observed, module structure, API endpoint shapes, recurring mistakes, small decisions not big enough for an ADR. Fill new pages from the knowledge-pages template.

Retrieval protocol — index-first, then grep, then read. Read agents/knowledge/INDEX.md first (one line per page, regenerated by src/scripts/generate_knowledge_index.ts); grep for keywords second; read the specific file third. Never enumerate every knowledge file directly — there is no search infrastructure by design.

Standards cards — Class A configured convention (Evidence v2)

A standards card is a present-state context whose claims are derived from the project's real tooling config (.editorconfig, eslint.config.js, pint.json, pyproject.toml/ruff.toml, commit-lint, CI lint steps). It is trust: high (config-derived) — high because the config is the truth, not because the agent believes it. Each standard is a pointer + digest (value + source: file:key + scope), never a flattened claim; conflicting configs are surfaced as two pointers, never merged. The digest is regenerated when a source config's mtime/hash changes (auto-refresh, no human gate — Class A is deterministic) and is read for heuristics only, never to bypass a fresh structural read. Build it with the standards-from-config skill; store under agents/settings/contexts/.

Shared vs. project-specific contexts

.augment/contexts/ — Part of the shared package. Describes the agent infrastructure: how overrides work, what skills/commands exist, the documentation hierarchy. These are read-only at project level (like all .augment/ content).

agents/settings/contexts/ — Project-specific. Describes the project's business domain: modules, services, integrations, database architecture. These are created and maintained per project.

Integration with other systems

Sessions

When working in an area that has a context document, load it at session start. The session's Context section can reference it.

Features

Before planning a feature, check if a context document exists for the affected area. It provides the baseline understanding needed for planning.

Module exploration

/module-explore gathers the data needed to create a module context. /context-create turns that exploration into a persistent document.

Overrides

When customizing a shared skill or command, read .augment/contexts/override-system.md for the naming conventions and format.

Shared contexts

When working on the agent infrastructure itself (skills, commands, rules), check .augment/contexts/ for existing documentation about the system.

Behavior rules

Creating contexts

1. Always analyze the code first — use codebase-retrieval, view, and file listing.
2. Be factual — describe what IS, not what SHOULD be.
3. Be specific — link to files, name classes, reference tables.
4. Ask the user about anything unclear.

Maintaining contexts

• Update Last Updated when modifying.
• When code changes affect a context, update it.
• /context-refactor is the dedicated command for this.

Commands

Output format

1. Context document in the correct location with structured sections
2. Cross-references to related contexts updated

Auto-trigger keywords

• context document
• codebase context
• orientation doc
• context creation

Gotcha

• Context docs become stale — always check the actual code before trusting a context document.
• Don't create context docs for areas that change weekly — they'll be outdated immediately.
• Keep context docs factual, not aspirational — document what IS, not what should be.

Do NOT

• Do NOT create contexts without analyzing the code first.
• Do NOT guess about architecture — verify by reading the code.
• Do NOT duplicate information from AGENTS.md — reference it instead.
• Do NOT commit or push without permission.
• Do NOT create contexts for trivial areas — only when the knowledge is worth persisting.