Skip to main content
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, the Antigravity (agy) 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 the git-flow branching/merge model and git-flow-next tool usage — agentsmd/rules/git-flow.md; the human-readable version lives in Branch conventions and PR conventions
  • Owns AI-runtime concerns: skill execution semantics, subagent typing, LiteLLM-routing details
  • Owns the autonomy-resilience rules hardened after the 2026-07 overnight runs — agentsmd/rules/subagent-resilience.md (probe before fan-out, bounded concurrency, mandatory solo fallback), agentsmd/rules/loop-cadence.md (every recurring loop gates itself on a durable min-interval marker), and agentsmd/rules/delegation-trust.md (a denial binds to the action, not the requester — no permission laundering across agent hops)
  • Owns the shared behavioral base (soul) for every agent surface — agentsmd/rules/soul.md (ground truth before claims, verify before done, reversibility gates autonomy) and its copy-paste rendering for non-Claude agents, agentsmd/prompts/autonomous-base.md
  • 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 for the full set. Situational agent guidance — pre-commit architecture, the Nix tool policy, shared-workflow org references — ships as on-demand skills in claude-code-plugins instead of always-loaded rules, keeping the per-session footprint focused on voice, tool use, skill-execution integrity, and repository-local routing. The default development loop 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.
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

​
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:
  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

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