AGENTS.md

Single source of truth for every coding agent — Claude Code, VS Code Copilot, Cursor, Windsurf, Zed, JetBrains Junie, Codex, Gemini and ~20 other tools read this file natively. Tool-specific files (CLAUDE.md, .cursor/rules) stay thin and point here. Open standard: https://agents.md

This repository is the Universal Agent Seed — a minimal, stack-agnostic base you copy to start any new project. It ships the portable cross-IDE config, a curated MCP toolset, and a self-improving knowledge loop, and it grows into a concrete language stack on demand instead of pinning one up front.

Project overview

• Type: stack-agnostic seed (no language runtime pinned until you pick one).
• Pick a stack: run /bootstrap-stack python or /bootstrap-stack typescript in Claude Code, or uncomment the relevant block in mise.toml.
• Keystone tool: mise manages tool versions, env vars, and tasks. There is one definition (mise.toml); humans, agents, git hooks, and CI all call the same tasks.

Commands (authoritative — agents should run these)

If mise is not on the host PATH, call the underlying tool directly (e.g. dprint fmt). Inside the dev container mise is always available.

Project structure

.               root config (AGENTS.md, CLAUDE.md, mise.toml, lefthook.yml, dprint.json, .mcp.json)
.github/        CI workflow (mise run doctor + check on Linux/macOS/Windows; pinned actions)
.claude-plugin/ plugin + marketplace manifests (install the machinery as a Claude Code plugin)
.devcontainer/  reproducible container env (base image + mise feature only)
.vscode/        VS Code + Cursor shared settings, recommended extensions, MCP (key "servers")
.cursor/        Cursor MCP (key "mcpServers") + thin rules that defer here
.claude/        Claude Code: settings, hooks, rules, knowledge store, skills, agents, commands
scripts/        cross-platform helper scripts behind mise tasks (setup.py, doctor.py)
skillopt/       opt-in OFFLINE skill optimizer slot (Microsoft SkillOpt / DSPy GEPA)
docs/           deep-dive docs (self-improvement loop, architecture)
src/            your code (created when you bootstrap a stack)

Code style

• Formatting is owned by tools, not humans: dprint (Markdown/JSON/TOML) and, per stack, Ruff (Python) / Biome (JS/TS). .editorconfig is the universal IDE baseline. Never hand-format — run mise run fmt.
• Make minimal, focused changes that match the surrounding code.

Per-project rules promoted by /reflect are mirrored here from .claude/rules/core-rules.md so every IDE/agent (not just Claude) sees them:

(none yet — promoted rules will be mirrored here from core-rules.md.)

Testing

• Add tests beside the code they cover.
• When you bootstrap a stack, wire mise run test to the real runner (pytest, vitest, …).
• Verify behavior, not just types: run the actual command and read the output.

Git workflow

• Conventional Commits (feat:, fix:, docs:, chore:, refactor: …).
• pre-commit formats + lints; pre-push runs tests (lefthook → mise).
• Git is intentionally not initialized in the seed — run git init when you start a real project (the .gitignore / .gitattributes are already in place).

Boundaries — Always / Ask first / Never

Always

• Run mise run fmt before finishing a change.
• Keep AGENTS.md the source of truth; mirror into tool files, never duplicate logic.
• Record durable learnings through the knowledge loop (below), not in throwaway comments.

Ask first

• Adding a dependency, an MCP server, or a new language stack.
• Editing .claude/settings.json, hooks, or permissions.
• Any publish, deploy, or destructive data migration.

Never

• Commit secrets or .env* (only .env.example is allowed).
• Force-push shared branches, rm -rf outside the repo, or disable the safety hooks.
• Auto-rewrite a skill or rule without the review + version-control gate.

Self-improvement loop (how this project learns about you)

This seed accumulates project knowledge automatically and safely (staged, reversible, model-judged — never blind self-editing):

1. Capture (automatic). A SessionEnd hook scans the session for corrections and decisions and appends candidates to .claude/knowledge/pending.md — staging only, never live context.
2. Inject (automatic). A SessionStart hook loads .claude/rules/core-rules.md plus .claude/knowledge/* into context and nudges you when pending.md has unreviewed items.
3. Reflect (model-mediated). /reflect (or the reflect skill) reviews the pending candidates, promotes high-confidence corrections into core-rules.md or the relevant SKILL.md, dedupes, and archives them. Every promotion is backed up and (when git is on) committed with a rationale.
4. Distill. /distill <name> crystallizes a finished multi-step task into a new, reusable skill under .claude/skills/.
5. Optimize (opt-in, offline). For a verifiable skill with a held-out eval set, skillopt/ wires Microsoft SkillOpt / DSPy GEPA to tune its SKILL.md against a metric. See skillopt/README.md.

Where knowledge lives: .claude/knowledge/ (project facts) · .claude/rules/ (behavior rules) · .claude/skills/ (procedures). Keep each small and rely on progressive disclosure — bigger is not better.

MCP tools available (curated "full core")

• Context7 — live, version-specific library docs. Use it before coding against any library so you never guess an API or version.
• Serena — semantic, symbol-level code navigation/editing via LSP. Prefer it over dumping whole files on large codebases (far cheaper on tokens).
• Playwright — drive a real browser to verify UI and end-to-end behavior.
• GitHub — repos, PRs, issues, code search. Until GITHUB_MCP_PAT is set it returns 401 on its own calls; this does not affect the other three servers.

Prerequisites: Serena needs uv/uvx (mise use -g uv), Playwright needs Node/npx (mise use -g node). Context7 needs neither (remote HTTP, keyless). Without these, the respective server just fails to start — the others still work.

Config lives in .mcp.json (Claude Code), .vscode/mcp.json (VS Code, key servers) and .cursor/mcp.json (Cursor, key mcpServers). The server definitions are the same in all three — only the wrapper key and the secret-substitution syntax differ (${VAR} for Claude, ${env:VAR} for Cursor, ${input:…} for VS Code). See docs/ARCHITECTURE.md for the full picture. mise run doctor checks the three mirrors stay in sync.