AI Assistant Instructions

Teaching AI assistants how to help you better. Yes, it's AI instructions written with AI assistance. We've come full circle.

Scope: Commands, skills, agents, and hooks have been migrated to JacobPEvans/claude-code-plugins and are delivered as portable plugins. This repository now maintains the generic pieces that aren't plugin-delivered: the canonical AGENTS.md / CLAUDE.md / GEMINI.md configuration, the auto-loaded rules in agentsmd/rules/, the default development workflow in agentsmd/workflows/, and the CI / validation tooling that keeps all of the above honest. (Tool permissions now live in dryvist/nix-claude-code.)

What Is This?

A centralized collection of instructions, workflows, and configurations for AI coding assistants. Drop these into your projects and get consistent, high-quality AI assistance across Claude, Copilot, and Gemini.

Think of it as a style guide, but for your AI pair programmer.

Repo boundaries

The AI configuration layer is split across three repositories. This repo owns the rules. claude-code-plugins owns commands, skills, agents, and hooks. docs owns the public-facing reference site at docs.jacobpevans.com.

graph LR
    Rules["**ai-assistant-instructions**<br/>rules · workflows · CI tooling"]
    Plugins["**claude-code-plugins**<br/>commands · skills · agents · hooks"]
    Docs["**docs**<br/>public-facing reference"]
    Session(("Developer session"))

    Rules -->|"auto-loaded"| Session
    Plugins -->|"marketplace install"| Session
    Docs -.->|"read by humans and AI"| Session

    style Rules fill:#d4e6ff,stroke:#4a90d9,color:#000
    style Plugins fill:#fff3d4,stroke:#d4a017,color:#000
    style Docs fill:#e8d4ff,stroke:#8a4ad9,color:#000

Loading

Full rule, decision table, and update workflow: docs.jacobpevans.com/ai-development/repo-boundaries.

For the broader Nix ecosystem context and session lifecycle diagrams, see docs/diagrams.md.

Prerequisites

• Git 2.30+ (for worktree support)
• GitHub CLI (gh) 2.0+ (for PR/issue management)
• (Optional) Python 3.8+ for validation hooks
• (Optional) Node.js 18+ for markdown linting

Installation

# 1. Clone the repo
git clone https://github.com/JacobPEvans/ai-assistant-instructions.git

# 2. Copy AGENTS.md into your project
cp ai-assistant-instructions/AGENTS.md your-project/

#    Optional: copy the auto-loaded rules too
mkdir -p your-project/agentsmd
cp -r ai-assistant-instructions/agentsmd/rules your-project/agentsmd/

# 3. Create vendor symlinks so each AI tool reads the same source
cd your-project
ln -sf AGENTS.md CLAUDE.md
ln -sf AGENTS.md GEMINI.md

# 4. Install the plugins from JacobPEvans/claude-code-plugins
#    (commands, skills, agents, and hooks live there, not here)
claude marketplace add JacobPEvans/claude-code-plugins
claude plugin install git-workflows github-workflows git-standards

# 5. Verify setup
claude doctor

Or just browse the documentation and cherry-pick what you need.

Usage

Once installed, the AI assistants read CLAUDE.md / AGENTS.md / GEMINI.md automatically at session start, and the auto-loaded rules in agentsmd/rules/ are pulled in for every session. Plugin-delivered commands and skills from JacobPEvans/claude-code-plugins are invoked via slash commands (/refresh-repo, /finalize-pr, /ship, etc.) or directly by name.

See the default workflow below for the expected development loop, and AGENTS.md for the full set of rules, routing decisions, and on-demand standards.

Directory Structure

.
├── AGENTS.md                  # Canonical configuration (GEMINI.md is a symlink)
├── CLAUDE.md                  # Stub — Nix wiring auto-loads AGENTS.md globally; no re-import
├── agentsmd/
│   ├── rules/                 # Auto-loaded universal and path-scoped rules
│   ├── workflows/             # Default workflow plus full-discipline guidance
│   └── docs/                  # Workflow and integration support docs
├── .copilot/instructions.md   # Symlink → AGENTS.md
├── .gemini/config.yaml        # Gemini-specific config
├── scripts/                   # Validation helpers (token limits, links)
└── .github/workflows/         # CI gates (markdown, spellcheck, link check, CodeQL, release-please)

Claude-Code plugins (commands, skills, agents, hooks) live in JacobPEvans/claude-code-plugins and are consumed via the git-workflows, github-workflows, git-standards, code-standards, infra-standards, project-standards, ai-delegation, config-management, content-guards, git-guards, script-guards, codeql-resolver, and session-analytics plugins (among others).

Supported AI Assistants

Assistant	Integration	Notes
Claude	.claude/ directory	Full command support via Claude Code
GitHub Copilot	.github/copilot-instructions.md + prompts	Works in VS Code, GitHub.com, Visual Studio
Gemini	.gemini/ directory	Style guide and config support

The Default Workflow

This repo centers on a lightweight autonomous loop:

1. Research & Explore - Gather enough context to act correctly
2. Plan - Pick the simplest verifiable path
3. Define Success - Choose the narrowest useful evidence
4. Implement & Verify - Make the smallest correct change and prove it
5. Finalize - Report changed files and verification results

Full PRD/test-first discipline remains available on demand for high-risk, multi-session, compliance-sensitive, cross-owner, or explicitly gated work. Details live in agentsmd/workflows/.

Plugin-delivered commands, skills, agents, and hooks

All slash commands, skills, agents, and hooks previously listed in this README now ship as plugins in JacobPEvans/claude-code-plugins. Install the marketplace and enable the plugins you need:

Plugin	Provides
git-workflows	/refresh-repo, /sync-main, /rebase-pr, /troubleshoot-*
github-workflows	/finalize-pr, /squash-merge-pr, /ship, /resolve-pr-threads, /shape-issues, /trigger-ai-reviews
git-standards	/git-workflow-standards, /pr-standards
code-standards	/code-quality-standards, /review-standards
infra-standards	/infrastructure-standards
project-standards	/agentsmd-authoring, /workspace-standards, /skills-registry
ai-delegation	/delegate-to-ai, /auto-maintain
config-management	/sync-permissions, /quick-add-permission
codeql-resolver	/resolve-codeql + specialist agents
session-analytics	/token-breakdown
content-guards, git-guards, script-guards, pr-lifecycle, pal-health, process-cleanup	PreToolUse / PostToolUse / Stop hooks — invoked automatically

See AGENTS.md for the full on-demand standards table and the auto-loaded rules reference.

Core Concepts

The documentation covers:

• Code Standards - Consistency across languages
• Documentation Standards - AI-friendly markdown
• Infrastructure Standards - Terraform/Terragrunt patterns
• Permission System - Where AI tool permissions now live (nix-claude-code)
• DRY Principle - Why everything symlinks to one place
• Memory Bank - Maintaining AI context across sessions
• Remote Commit Workflow - Making commits via GitHub API without local clone

Browse agentsmd/rules/ and agentsmd/docs/.

Advanced: Tool permissions are no longer defined in this repo. They live in dryvist/nix-claude-code, which nix-ai renders into Claude / Codex / Gemini / Copilot settings. See agentsmd/docs/permission-system.md for the pointer.

Need Help?

• Codex Quick Start - repo analysis, prompt patterns, and Codex parity backlog
• 📖 Documentation Home - Getting started guides and references
• 🐛 Issues - Report bugs or request features

Contributing

Contributions welcome. See CONTRIBUTING.md for the details, though the short version is: open a PR, don't be a jerk, and I'll probably merge it.

Security

Found a vulnerability? Please report it responsibly. See SECURITY.md for details.

License

Apache 2.0 - Use it, modify it, just keep the attribution.

---

Built by a human, refined by AI, used by both.