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, fix, and review 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 three things:

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 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.

Don't hand-edit the generated files — they're regenerated on the next Publish. 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.