Skip to main content

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.

Configure once, every model behaves the same way.
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
  • 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, Nix tool policy, 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, Terraform check placement, Nix package placement, scrubbed values — live on this docs site. See Conventions for the full set.

​
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. 
# 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) — the contents are loaded into context exactly as if they had been written into CLAUDE.md directly.

​
Why

Problem the convention solvesHow
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 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.

​
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: 
    # .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 check from JacobPEvans/.github. No per-repo workflow edit needed.

​
How it fits

Read byConsumed by
Claude Code, Gemini CLI, GitHub Copilot, CodexClaude Code plugins

​
Getting started

1

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

Pick a profile

Profiles cover personal, work, and learning contexts. The README enumerates which rules each one activates.
3

Update from upstream regularly

The rules evolve. Pull weekly or set up a routine in claude-code-routines.

Repo boundaries

How rules, plugins, and docs are split across three repos.

claude-code-plugins

Extends Claude Code with custom skills, hooks, and commands that respect these rules.

nix-ai

Packages the AI tools that read these rules.

AI pipeline

How rules + tools + automation become an actual development loop.

Source on GitHub

Rules, profiles, full README.