agentsge-1

# 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 ```bash 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 ```bash agents init # Initialize .agents/, detect stack, install hooks agents init --force # Overwrite existing .agents/ agents sync # Re-sync entrypoints (with knowledge digest) and MCP configs agents status # Show project info, knowledge stats, ref warnings agents capture list # Show pending knowledge items agents capture accept <name> # Accept pending item into knowledge agents capture accept --all # Accept all pending items agents capture reject <name> # Delete a pending item agents capture context # Output knowledge digest (for debugging) agents capture context --compact # Short digest (10-15 lines) agents hooks install # Install capture hooks for detected platforms agents hooks install --agent claude # Install for specific platform 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: ```bash 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) ## Automatic Knowledge Capture When hooks are installed, agentsge captures knowledge automatically: 1. **Session start** — saves git HEAD marker, injects knowledge digest into agent context 2. **File edits** — logs changed files (fast, no LLM, <10ms per event) 3. **Session end** — collects diff since marker, extracts knowledge via LLM, saves to `pending/` Pending items require review before entering the knowledge base: ```bash agents capture list # See what was captured agents capture accept --all # Accept into .agents/knowledge/ agents capture reject bad-one # Discard ``` Accepted items are moved to `.agents/knowledge/<type>/`, added to `_index.md`, and included in future context digests. ### Context Injection Three levels of recall guarantee: | Level | Mechanism | Guarantee | Works with | |-------|-----------|-----------|------------| | **Entrypoint** | Inline digest in CLAUDE.md / .cursorrules | ~95% — always in context | All agents | | **SessionStart hook** | Full digest injected as systemMessage | ~99% — agent sees it | Claude, Cursor, OpenCode | | **beforeSubmitPrompt** | Compact digest on every prompt | 100% — cannot be skipped | Claude Code | `agents sync` regenerates entrypoints with the latest knowledge digest. Hooks inject context at runtime. ### Supported Platforms | Platform | Hooks support | Config location | |----------|--------------|-----------------| | Claude Code | sessionStart, postToolUse, stop | `.claude/settings.local.json` | | Cursor | sessionStart, postToolUse, stop | `.cursor/hooks/hooks.json` | | Git (fallback) | post-commit | `.git/hooks/post-commit` | | Copilot | planned | — | | OpenCode | planned | — | | Gemini CLI | planned | — | | Codex CLI | planned | — | ## Requirements Node.js >= 22 ## License MIT <!-- daliagents-attribution --> --- **Created by [Dali Agents](https://daliagents.com)** · Production AI agents for support, sales, and ops.