docgarden

Repository knowledge tooling for agentic engineering repositories: route agents to the right context with minimum tokens, and enforce the doc hygiene that makes routing reliable.

Why

Agent-first repositories keep their working knowledge in Markdown: design docs, product specs, skills, and agent instructions. docgarden applies progressive disclosure to that knowledge base, so agents load the right context instead of the whole repo. Every document carries a description frontmatter field, and docgarden match uses BM25F to rank the right paths. Instead of maintaining a central routing table, the docs route themselves.

docgarden lint checks the rules that keep routing accurate: description frontmatter on every doc, plus size budgets on high-traffic entry points like AGENTS.md so agents do not burn tokens just getting oriented. To paraphrase Ryan Lopopolo: give agents a map, not a 1,000-page instruction manual.

Philosophy

docgarden is meant to work with agents as a context engineering tool for repository knowledge. It handles the parts that can be done deterministically, so agents can spend their context on work that actually requires judgment. If something depends on summarization, interpretation, or natural-language reasoning, it belongs to the agent, not the tool.

Using

match: route an agent to the right document

docgarden match <QUERY>

Ranks repository Markdown documents by how well their frontmatter fields match the query. Returns path | name | description by default.

# route a review task to the active-plan workflow
docgarden match review against the active plan

# path-only for piping the top few candidates into agent context
docgarden match -p -n 3 implement from the active plan

# show scoring diagnostics
docgarden match --explain docgarden match scoring

Options: -n <LIMIT> to cap results, -p / --path-only for plain paths, --explain for BM25F score breakdown.

Example AGENTS.md instruction for non-code context discovery:

## Step 0 (required before discovering documentation, repository context, or skills)
Run `docgarden match <query>` to route the task.
Do not spawn agents or run any search commands (`rg`, `grep`, `find`) to locate docs, plans, guidance, context, or skills until this is done.
This step is not required for code-first tasks.
Use it when you need non-code context; otherwise inspect and search code directly.

lint: enforce repository knowledge hygiene

docgarden lint [TARGETS]

Lints without modifying files. Targets can be the repository root, specific directories, or individual Markdown files (defaults to .).

# lint the whole repo
docgarden lint

# lint a specific subtree
docgarden lint docs/

Checks include: unresolved local references, missing description frontmatter, AGENTS.md line/token budget violations, and path style policy (backtick vs Markdown link).

Configuration

docgarden looks for docgarden.toml at the repository root. If you do not create one, it uses this built-in default configuration:

[[rules]]
path = "*.md"

[rules.frontmatter.fields.description]
max_chars = 1024

[[rules]]
path = "*.md"
exclude = ["AGENTS.md", "CLAUDE.md", "GEMINI.md", "README.md"]

[rules.frontmatter]
required = ["description"]

[[rules]]
path = "AGENTS.md"
max_lines = 100
max_tokens = 1000

[[rules]]
path = "SKILL.md"
max_lines = 500
max_tokens = 5000

[rules.frontmatter]
required = ["name", "description"]

That is a good starting point to copy into docgarden.toml and tweak for your repository.

Top-level exclude removes files from the lint run entirely. For example:

exclude = ["docs/generated/**"]

Contributing

Contributions are welcome. If you want to add a new repository-knowledge check, keep it aligned with the project's philosophy: rules should be deterministic, repository-local, and enforceable without model inference.

License

Apache 2.0. See LICENSE for details.