> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jacobpevans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assistant rules

> Vendor-agnostic framework for AI coding workflows. One set of rules, every AI tool reads them: Claude, Gemini, Copilot, Codex.

export const RepoFit = ({children}) => <Tip>{children}</Tip>;

export const RepoMeta = ({language, status, lastActive, repoUrl}) => <Info>
    Language: <b>{language}</b>  ·  Status: <b>{status}</b>  ·  Last active: <b>{lastActive}</b>  ·  <a href={repoUrl}>Source on GitHub</a>
  </Info>;

> Configure once, every model behaves the same way.

<RepoMeta language="Shell" status="active" lastActive="this week" repoUrl="https://github.com/JacobPEvans/ai-assistant-instructions" />

`ai-assistant-instructions` is the rules and conventions layer for every AI coding tool in the portfolio. The same files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.) are sourced from this repo so Claude Code, Gemini CLI, GitHub Copilot, and Codex all behave consistently.

## What it does

* Defines the canonical `CLAUDE.md` and `AGENTS.md` files used by every project
* Sets the **autonomous orchestration defaults** — proceed on low-risk ambiguity, delegate context-heavy work, verify the
  result, and keep user output compact
* Owns the **model-routing policy** — when to reach for Claude vs Gemini vs Copilot vs local MLX
* Owns the **tool-use rules** — Read over `cat`, Edit over `sed`, Bash for shell-only
* Owns AI-runtime concerns: skill execution semantics, subagent typing, Bifrost-routing details
* Symlinks the canonical files into every consuming repo via Nix or a `direnv` hook

Cross-repo writing standards that humans also need to read — commit conventions, no-scripts, diagramming, CI/CD policy, OpenTofu check placement, Nix package placement, scrubbed values — live on this docs site. See [Conventions](/conventions/overview) for the full set.

Situational agent guidance that once lived here as always-loaded rules — pre-commit architecture, the Nix tool policy,
shared-workflow org references — now ships as on-demand skills in
[claude-code-plugins](/ai-development/claude-code-plugins), keeping the per-session footprint focused on voice, tool
use, skill-execution integrity, and repository-local routing.

The [default development loop](/architecture/ai-pipeline) is intentionally lightweight: gather enough context, choose the
simplest verifiable path, implement the smallest correct change, and report only the result plus verification. PRD-heavy,
test-first gating remains available for high-risk or explicitly gated work, but it is no longer the default for routine
tasks.

## The `CLAUDE.md` → `@AGENTS.md` convention

**Every repo's `CLAUDE.md` is a thin import of `AGENTS.md` in the same folder. Always. No exceptions.**

```markdown theme={null}
# AI Agents Configuration

@AGENTS.md
```

That's the entire file. Two lines of content (plus a heading). All actual project guidance lives in `AGENTS.md`. Claude Code resolves `@AGENTS.md` as an inline file import ([official docs](https://code.claude.com/docs/en/memory)) — the contents are loaded into context exactly as if they had been written into `CLAUDE.md` directly.

### Why

| Problem the convention solves                                                                                                                                                                                      | How                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Vendor lock-in.** Claude reads `CLAUDE.md`, Codex / GitHub Copilot / Cursor / OpenAI agents read `AGENTS.md`, Gemini reads `GEMINI.md`. Duplicating content across them rots fast.                               | One canonical file (`AGENTS.md`), every other tool's config file imports it.                                                            |
| **Context bloat.** A 12 KB `CLAUDE.md` burns tokens on every session.                                                                                                                                              | `CLAUDE.md` becomes \~40 bytes; `AGENTS.md` carries the load and can still be split further via nested `@path` imports.                 |
| **Size budgets.** The shared [`_file-size`](https://github.com/JacobPEvans/.github/blob/main/.github/workflows/_file-size.yml) workflow defaults to `warn=6 KB`, `error=12 KB`. A fat `CLAUDE.md` trips that gate. | A 40-byte `CLAUDE.md` never trips it; `AGENTS.md` can opt into an `extended:` limit per repo via `.file-size.yml` when actually needed. |
| **Single source of truth.** Moving project rules between files in different vendors' formats is an unforced error.                                                                                                 | All edits land in one file.                                                                                                             |

### Where it applies

**Every repo.** Public or private, monorepo or single-purpose, infra or app. If a repo has a `CLAUDE.md`, it must be the two-line import. Project-level instructions, command runbooks, conventions, and tool guidance all belong in `AGENTS.md` (or files it `@imports`).

The same convention applies symmetrically to `GEMINI.md` and any future vendor-specific files — each is a thin import of `AGENTS.md`.

**The one exception is `ai-assistant-instructions` itself.** Its `AGENTS.md` is already auto-loaded globally on Nix-managed machines (the home-level `~/CLAUDE.md` imports it), so a project-level `@AGENTS.md` import there would load the identical bytes twice in every session. That repo's `CLAUDE.md` is a stub explaining exactly this, and its auto-loaded rules likewise come from the global `~/.claude/rules` wiring rather than a per-repo `.claude/rules` symlink.

### How to migrate a repo

1. Move every section of the existing `CLAUDE.md` into `AGENTS.md` (merge with any existing content, dedupe, prefer linking to `docs/*.md` for deep dives).

2. Replace `CLAUDE.md` with the two-line import shown above.

3. If `AGENTS.md` ends up > 12 KB, either trim further (link out to `docs/`) or add a `.file-size.yml` extension:

   ```yaml theme={null}
   # .file-size.yml — extends the shared default for AGENTS.md only
   extended:
     limit: 32768
     files:
       - AGENTS
   ```

4. Mirror the same change in any other agent file (e.g. `GEMINI.md` → `@AGENTS.md`).

5. Update CI: most repos already inherit the [`_file-size`](https://github.com/JacobPEvans/.github/blob/main/.github/workflows/_file-size.yml) check from `JacobPEvans/.github`. No per-repo workflow edit needed.

## How it fits

| Read by                                        | Consumed by                                                |
| ---------------------------------------------- | ---------------------------------------------------------- |
| Claude Code, Gemini CLI, GitHub Copilot, Codex | [Claude Code plugins](/ai-development/claude-code-plugins) |

<RepoFit>
  The "rules of engagement." Every AI workflow elsewhere in the portfolio assumes this repo's content is in scope.
</RepoFit>

## Getting started

<Steps>
  <Step title="Clone or symlink">
    `git clone https://github.com/JacobPEvans/ai-assistant-instructions ~/.ai-assistant-instructions` and symlink the project files into the relevant repo, or import via the Nix module the README points to.
  </Step>

  <Step title="Pick a profile">
    Profiles cover personal, work, and learning contexts. The README enumerates which rules each one activates.
  </Step>

  <Step title="Update from upstream regularly">
    The rules evolve. Pull weekly or set up a routine in [`claude-code-routines`](https://github.com/JacobPEvans/claude-code-routines).
  </Step>
</Steps>

## Related repos

<CardGroup cols={2}>
  <Card title="Repo boundaries" icon="border-all" href="/ai-development/repo-boundaries">
    How rules, plugins, and docs are split across three repos.
  </Card>

  <Card title="claude-code-plugins" icon="plug" href="/ai-development/claude-code-plugins">
    Extends Claude Code with custom skills, hooks, and commands that respect these rules.
  </Card>

  <Card title="nix-ai" icon="bot" href="/nix/nix-ai">
    Packages the AI tools that read these rules.
  </Card>

  <Card title="AI pipeline" icon="diagram-project" href="/architecture/ai-pipeline">
    How rules + tools + automation become an actual development loop.
  </Card>

  <Card title="Source on GitHub" icon="github" href="https://github.com/JacobPEvans/ai-assistant-instructions">
    Rules, profiles, full README.
  </Card>
</CardGroup>