~/.agents

Private home for shared AI coding-assistant instructions, skills, and preferences. The same behavioral contract is duplicated in AGENTS.md and CLAUDE.md so different tools (Codex, Claude Code, others) can load the same text.

What agents are expected to do

High level:

• Plan and research first on non-trivial work: use plan mode (/plan where supported), subagents, and web research—assume documentation and APIs may have changed.
• Honor hard boundaries: do not read or edit paths listed in .agentignore (if present); do not push with git or gh; if a URL cannot be fetched, use browser or MCP and fall back to Chromium where needed.
• Maintain persistent memory: ensure ./.notes/ exists, read ./.notes/MEMORY.md every run, and keep that index updated whenever you add files under .notes/. Use notes for future-you and other agents—not for dumping implementation details (the codebase is the source of truth).
• After making edits, follow the post-edit checklist in order: update notes → reflect → style → changelog (when user-facing) → offer tests → then commit (gitmoji in AGENT_AUTONOMY_MODE=yolo, otherwise suggest a message and ask).

Autonomy: when AGENT_AUTONOMY_MODE is yolo (case-insensitive), skip confirmations and apply best guesses; skills that define YOLO behavior should honor that.

Code philosophy (from the instruction files): code optimized for human readers; generous comments for intent; spacing and structure that read cleanly—“Ruby-like elegance meets modern JS.”

Repository layout

Path	Role
AGENTS.md	Canonical agent instructions (tool-agnostic).
CLAUDE.md	Same content as AGENTS.md; kept for Claude-oriented tooling.
skills/	Invoked workflows: changelog, reflect, style, test, translate (each is a SKILL.md).
preferences/	Optional context loaded when relevant: js-style.md, tooling-preferences.md, design-preferences.md.
symlink.sh	Wires this tree into ~/.claude/ (see below).
.notes/	Local memory store; create if missing. Index is MEMORY.md.

Hooking up Claude Code (symlink.sh)

The script links AGENTS.md → ~/.claude/CLAUDE.md and skills → ~/.claude/skills. It warns if CODEX_HOME is unset (expected ~/.agents when using this layout with Codex-style paths).

Review the script before running; create ~/.claude if your setup expects it.

# After auditing symlink.sh:
bash ~/.agents/symlink.sh

Skills (quick map)

• reflect — Recent work: intent alignment, elegance, bugs; optional plan output; merges PR comment review when a pr-comments skill exists.
• style — Style-only pass against AGENTS.md / CLAUDE.md and preferences/js-style.md.
• changelog — Changelog + version surfaces + README when behavior changes; respects YOLO for confirmations.
• test — Discover and run tests; fix flow differs for autonomous/YOLO vs interactive.
• translate — i18n sync with English as canonical source.

Invocation syntax differs by product (/skill vs $skill, etc.); each SKILL.md frontmatter describes when to trigger it.

Preferences

When ~/.agents/preferences exists, agents should pull in:

• JavaScript → js-style.md (mentie logging, snake_case, functional style, JSDoc on exports, React conventions, etc.).
• Tooling / stack → tooling-preferences.md (Node, Vite, React, mentie, airier scaffold, etc.).
• UI/UX → design-preferences.md (sensory/accessibility-oriented constraints, typography, motion, ethics).

These apply in addition to project-local instructions when you work in a codebase that uses this home directory as the agent config source.

Git and .gitignore

This tree uses a restrictive .gitignore (* with specific patterns). Only paths listed with ! exceptions are easy to track without git add -f. By default, README.md and the core .notes/*.md index files (MEMORY.md, GOTCHAS.md, RESEARCH.md, TIMELINE.md) are un-ignored; everything else under .notes/ stays local unless you add more exceptions.

Security

• Do not commit secrets, tokens, or real environment files.
• Treat .notes/ as local/personal unless you deliberately share it.