Discovery & AI agent context

AI coding tools guess at your conventions, invent file paths, and rediscover the same architecture every session. Discovery fixes that: Hyrax profiles your repository, then writes that knowledge into the repo so any AI agent working there starts pre-loaded with your real architecture and conventions.

Two workflows do the work. Discovery profiles the repo and stores the context in your workspace — it runs automatically the first time you connect a repo. Publish opens a pull request that writes that context into the repo itself.

What discovery produces

Discovery builds a structured profile of your repository, stored in your workspace:

• Domain summary — what the project does, in plain terms.
• Engineering principles — design rules the team follows that aren't obvious from the code.
• Conventions — naming, file layout, idioms, recurring patterns.
• Definition of done — tests, lint, the CI gates a change has to clear.
• Architecture diagram — a Mermaid diagram of how the system is laid out.
• Reusable skills — repeatable units of know-how an agent can apply to common changes.
• How-to guides — short walkthroughs for the most common tasks in the repo.

Every audit and fix gets sharper because Hyrax reads this context first — and so do your own AI tools, once it's published.

When to re-run it

Discovery reflects what was true when it ran. Re-run Discovery, then Publish again, after a significant architecture or dependency change — a new service, a restructured layout, a framework upgrade — and periodically (for example quarterly) to catch the slow drift of conventions.

What publish writes into the repo

Publish opens a pull request that commits the discovered context into your repo, where your AI tools can read it. It writes:

Location	What it is
HYRAX.md (repo root)	The bundle index — commands, rules, a how-to table, and links into the detailed context.
.hyrax/discovery/	The detailed context files, including a howto/ directory of how-to guides.
.hyrax/findings.md	A digest of the repo's open Hyrax findings, so agents working in the repo see what's already been flagged.
## Hyrax Context block in CLAUDE.md	A managed section (created if absent) pointing agents at HYRAX.md. Your edits to this block are preserved; the rest of your CLAUDE.md is never touched.
.cursorignore / .claudeignore (repo root)	Ignore files that keep AI agents out of noise like build output and vendored code. Hyrax regenerates these files on every Publish, preserving only the marked "user additions" section — add your own rules between those markers; edits anywhere else in the file are overwritten.
.hyraxignore (repo root)	A starter file for excluding paths from Hyrax audits — written only if you don't already have one. This file is yours: edit it freely, Hyrax never overwrites it.
CONTEXT.md (per module, monorepos only)	A short orientation file inside each module of a monorepo.

The generated context files — HYRAX.md, .hyrax/discovery/, .hyrax/findings.md — are regenerated on the next Publish, so don't hand-edit those — with one exception: HYRAX.md ends with a marked user notes section that's yours. Notes you add between those markers are preserved verbatim across re-publishes (the file's own header points you at them). .hyraxignore is yours and never overwritten; in the .cursorignore / .claudeignore files, your own rules survive re-publishes only when placed inside the marked "user additions" section. Because Publish writes back to your repo, it requires the Hyrax GitHub App; it can't run on repos connected in anonymous mode. See Public & private repositories.

How your AI tools use it

Once the bundle lives in the repo, every AI coding agent there picks it up: Claude Code reads CLAUDE.md, which points at HYRAX.md; Cursor, Copilot, and others read HYRAX.md and .hyrax/discovery/ as plain Markdown. An agent that knows your architecture writes code that fits the first time — fewer "we don't do it that way" rounds.

Your own guidance

Hyrax doesn't only learn about your code by reading it — you can tell it things directly. There are two places to write free-form notes:

• Workspace-wide — Settings → Agent Overrides → Freeform Notes. Context that applies to every repo: your deployment model, compliance scope, infrastructure conventions.
• Per-repo — each repository's Settings → Agent Overrides → Freeform Notes. Repo-specific nuance: known-safe patterns that shouldn't be flagged, what's deliberately out of scope, anything that should shape how Hyrax reads that repo.

Both are plain prose — no special format. Hyrax weaves them into its prompts for audits, fixes, and discovery, with repo notes layered on top of workspace notes. A line like "SOC2 only — skip GDPR/HIPAA checks" steers findings before they're produced — better than dismissing the same false positive every month. Available on every plan.

Related

• Workflows — Discovery, Publish, and every other workflow.
• Quickstart — discovery runs automatically the first time you connect a repo.