agentsge

Make any project agent-ready with .agents/ directory.

Project intelligence belongs to the project, not the agent. One source of truth — every AI tool reads it.

Quick Start

npx agentsge init

Then open your AI agent (Claude Code, Cursor, Codex, Gemini — any) in the project. It reads AGENTS.md, scans the codebase, asks a few sharp questions, and fills .agents/ with project knowledge.

What happens

1. agentsge init scans the project, detects stack, creates .agents/ with config and capture rules, generates AGENTS.md with onboarding prompt
2. Your AI agent reads AGENTS.md and follows the onboarding steps:
   • Quick scan → updates config.yaml, writes architecture overview
   • Asks 0-3 questions about things it can't find in code
   • Saves answers as knowledge files
   • Replaces AGENTS.md with a clean session-start pointer
3. From now on, _capture.md rule handles ongoing knowledge capture

Commands

agents init              # Initialize .agents/ in your project
agents init --force      # Overwrite existing .agents/

agents sync              # Re-sync AGENTS.md and MCP configs from .agents/

agents status            # Show project info, knowledge stats, ref warnings

agents add rule <name>   # Add a new rule
agents add skill <name>  # Add a new skill
agents add mcp <name>    # Add an MCP server (auto-syncs configs)

agents validate          # Validate .agents/ structure and schemas

.agents/ Structure

.agents/
  config.yaml              # Project name, description, stack
  rules/                   # Rules for agents (all mandatory)
    _capture.md            # Built-in: ongoing knowledge capture
  skills/                  # Reusable multi-step workflows
  mcp/                     # MCP server definitions
    config.yaml            # -> synced to .claude/, .cursor/, .codex/
  knowledge/               # Accumulated project knowledge
    _index.md              # Index — always loaded into agent context
    architecture/          # Decisions and trade-offs (WHY)
    patterns/              # Repeating codebase patterns
    lessons/               # Bug investigations, edge cases
    conventions/           # "We do it this way" — not in config files
    dependencies/          # Why X was chosen, known issues

How It Works

AGENTS.md          -> points to .agents/
.agents/           -> single source of truth
  config.yaml      -> project metadata
  rules/*.md       -> mandatory agent rules
  knowledge/       -> accumulated context
  skills/          -> reusable workflows

Every AI agent can read markdown files. No format translation needed — only MCP configs require agent-specific JSON output.

Knowledge System

The _capture.md rule instructs agents to save knowledge when they discover something valuable that a future agent wouldn't find by reading the codebase:

• architecture — decisions, rejected alternatives, trade-offs
• pattern — repeating patterns not obvious from single files
• lesson — bugs where the symptom misled the cause
• convention — team rules that contradict common practice
• dependency — non-obvious choices, known issues, workarounds

Knowledge lives in git. _index.md gives agents instant overview. agents status shows staleness warnings and broken refs.

MCP Sync

Define MCP servers once in .agents/mcp/config.yaml, sync to all agent formats:

agents add mcp postgres
agents sync

Generates: .claude/settings.json, .cursor/mcp.json, .codex/mcp.json, .github/copilot-mcp.json

Stack Detection

The scanner auto-detects:

• Language (TypeScript, Python, Rust, Go, Java)
• Framework (Next, Expo, React, FastAPI, etc.)
• Testing (Vitest, Jest, pytest, etc.)
• Package manager (npm, pnpm, yarn, bun, pip, cargo)
• Monorepo structure (workspaces, multiple frameworks)

Requirements

Node.js >= 22

License

MIT