🌐 English | 한국어 | 日本語 | 中文 | Español | Français | Deutsch | Русский | हिन्दी | العربية
One command to give any AI agent instant project understanding.
Scans your project → generates AGENTS.md + knowledge/skill/role context
→ any AI tool starts working immediately, every session.
Run this inside your project directory:
cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/itdar/agents-initializer/main/install.sh | bash
Wait for the script to finish.
That's it. Select your AI tool, pick a language, and everything is generated automatically.
After setup, launch agent sessions:
./ai-agency.sh
Other install methods
# Download only (don't run setup automatically)
curl -fsSL https://raw.githubusercontent.com/itdar/agents-initializer/main/install.sh | bash -s -- --no-run
# Or clone and copy manually
git clone https://github.com/itdar/agents-initializer.git
cp agents-initializer/setup.sh agents-initializer/HOW_TO_AGENTS.md /path/to/your-project/
cd /path/to/your-project
./setup.shToken notice: Initial setup analyzes the full project and may consume tens of thousands of tokens. This is a one-time cost — subsequent sessions load pre-built context instantly.
The directory where you run setup.sh becomes the Root PM. The hierarchy depth is determined automatically by your project structure.
my-product/ <-- run setup.sh here
├── apps/
│ ├── api/ --> Backend agent
│ ├── web/ --> Frontend agent
│ └── worker/ --> Backend agent
└── infra/ --> Infra agent
Result: 2 layers (PM --> workers)
apps/ = simple passthrough, no own context
my-product/ <-- run setup.sh here
├── apps/
│ ├── api/ --> Backend agent
│ └── web/ --> Frontend agent
├── business/ --> Business Analyst agent
├── planning/ --> Planner agent
└── infra/ --> Infra agent
Result: 2 layers (PM --> workers)
Dev and business agents are peers under the same PM.
platform/ <-- run setup.sh here
├── commerce/ --> Domain Coordinator (auto-detected)
│ ├── order-api/ --> Backend agent
│ ├── catalog-api/ --> Backend agent
│ └── storefront/ --> Frontend agent
├── social/ --> Domain Coordinator (auto-detected)
│ ├── feed-api/ --> Backend agent
│ └── chat-api/ --> Backend agent
└── infra/ --> Infra agent
Result: 3 layers (PM --> Domain Coordinators --> workers)
commerce/, social/ get their own .ai-agents/context/
Child services reference domain context (no duplication).
Auto-detection rule: A directory with only subdirectories, where 2+ subdirectories have their own build files (
package.json,go.mod, etc.), is classified as a domain boundary with its own context and coordination role.
AI agents forget everything when a session ends. Every time, they spend time understanding the project structure, analyzing APIs, and learning conventions.
| Problem | Consequence |
|---|---|
| Doesn't know team conventions | Code style inconsistencies |
| Doesn't know the full API map | Explores entire codebase each time (cost +20%) |
| Doesn't know prohibited actions | Risky operations like direct production DB access |
| Doesn't know service dependencies | Missed side effects |
| Doesn't know business rules/KPIs | Proposals misaligned with business goals |
| Doesn't know approval flows | Skips required stakeholder sign-offs |
| Doesn't know operational procedures | Incorrect incident response or deployment steps |
Session Start
┌──────────────────────────────────────────────────┐
│ │
│ Reads AGENTS.md (automatic) │
│ │ │
│ ▼ │
│ "I am the backend expert for this service" │
│ — or — │
│ "I am the business analyst for this product" │
│ "Conventions, rules, prohibited actions loaded" │
│ │ │
│ ▼ │
│ Loads .ai-agents/context/ files (5 seconds) │
│ "APIs, entities, KPIs, stakeholders understood" │
│ │ │
│ ▼ │
│ Starts working immediately! │
│ │
└──────────────────────────────────────────────────┘
ai-initializer solves this — generate once, and any AI tool understands your project instantly.
Your Project
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ AGENTS.md│ │.ai-agents│ │.ai-agents│
│ │ │ /context/│ │ /skills/ │
│ Identity │ │ Knowledge│ │ Behavior │
│ "Who │ │ "What │ │ "How │
│ am I?" │ │ do I │ │ do I │
│ │ │ know?" │ │ work?" │
│ + Rules │ │ │ │ │
│ + Perms │ │ + Domain │ │ + Deploy │
│ + Paths │ │ + Models │ │ + Review │
└──────────┘ └──────────┘ └──────────┘
Entry Point Memory Store Workflow Standards
The identity file for the agent deployed in each directory.
project/
├── AGENTS.md ← PM: The leader who coordinates everything
├── apps/
│ └── api/
│ └── AGENTS.md ← API Expert: Responsible for this service only
├── infra/
│ ├── AGENTS.md ← SRE: Manages all infrastructure
│ └── monitoring/
│ └── AGENTS.md ← Monitoring specialist
├── business/
│ └── AGENTS.md ← Business Analyst: KPIs, requirements, specs
├── planning/
│ └── AGENTS.md ← Planner: Roadmaps, milestones, specs
└── cs/
└── AGENTS.md ← CS Specialist: Runbooks, escalation, FAQ
It works just like a team org chart — not just for developers:
- The PM oversees everything and distributes tasks
- Developers, business analysts, planners, and CS specialists each have their own agent
- Each agent deeply understands only their area
- They don't directly handle other teams' work — they request it
A folder where essential knowledge is pre-organized so the AI doesn't have to read the code every time.
.ai-agents/context/
├── domain-overview.md ← "This service handles order management..."
├── data-model.md ← "There are Order, Payment, Delivery entities..."
├── api-spec.json ← "POST /orders, GET /orders/{id}, ..."
├── event-spec.json ← "Publishes the order-created event..."
├── business-metrics.md ← "GMV target: $10M/quarter, conversion rate: 3.5%..."
├── stakeholder-map.md ← "Feature approval: Product Lead → CTO..."
├── ops-runbook.md ← "P1 incident: page on-call → escalate in 15min..."
└── planning-roadmap.md ← "v2.1: domain-grouping (done), v2.2: dashboards..."
Analogy: Onboarding documentation for a new employee — developers, planners, and business analysts alike. Document it once, and no one has to explain it again.
Standardized workflow manuals for repetitive tasks.
.ai-agents/skills/
├── develop/SKILL.md ← "Feature dev: Analyze → Design → Implement → Test → PR"
├── deploy/SKILL.md ← "Deploy: Tag → Request → Verify"
└── review/SKILL.md ← "Review: Security, Performance, Test checklist"
Analogy: The team's operations manual — makes the AI follow rules like "check this checklist before submitting a PR."
ETH Zurich (2026.03): Including inferable content reduces success rates and increases cost by +20%
Write This Don't Write This
┌─────────────────────────┐ ┌─────────────────────────┐
│ │ │ │
│ "Use feat: format for │ │ "Source code is in │
│ commits" │ │ the src/ folder" │
│ AI cannot infer this │ │ AI can see this with ls│
│ │ │ │
│ "No direct push to │ │ "React is component- │
│ main" │ │ based" │
│ Team rule, not in code │ │ Already in official │
│ │ │ docs │
│ "QA team approval │ │ "This file is 100 │
│ required before │ │ lines long" │
│ deploy" │ │ AI can read it │
│ Process, not inferable │ │ directly │
│ │ │ │
└─────────────────────────┘ └─────────────────────────┘
Write in AGENTS.md Do NOT write!
Exception: "Things that can be inferred but are too expensive to do every time"
e.g.: Full API list (need to read 20 files to figure out)
e.g.: Data model relationships (scattered across 10 files)
e.g.: Inter-service call relationships (need to check both code + infra)
→ Pre-organize these in .ai-agents/context/!
→ In AGENTS.md, only write the path: "go here to find it"
Include (non-inferable) .ai-agents/context/ (costly inference) Exclude (cheap inference)
─────────────────────── ──────────────────────────────────── ────────────────────────
Team conventions Full API map Directory structure
Prohibited actions Data model relationships Single file contents
PR/commit formats Event pub/sub specs Official framework docs
Hidden dependencies Infrastructure topology Import relationships
KPI targets & business metrics
Stakeholder map & approval flows
Ops runbooks & escalation paths
Roadmap & milestone tracking
Explores directories up to depth 3 and auto-classifies by file patterns.
deployment.yaml + service.yaml → k8s-workload
values.yaml (Helm) → infra-component
package.json + *.tsx → frontend
go.mod → backend-go
Dockerfile + CI config → cicd
...19 types auto-detected
Generates .ai-agents/context/ knowledge files by actually analyzing the code based on detected types.
Backend service detected
→ Scan routes/controllers → Generate api-spec.json
→ Scan entities/schemas → Generate data-model.md
→ Scan Kafka config → Generate event-spec.json
Generates AGENTS.md for each directory using appropriate templates.
Root AGENTS.md (Global Conventions)
→ Commits: Conventional Commits
→ PR: Template required, 1+ approvals
→ Branches: feature/{ticket}-{desc}
│
▼ Auto-inherited (not repeated in children)
apps/api/AGENTS.md
→ Overrides only: "This service uses Python"
Global rules use an inheritance pattern — write in one place, and it automatically applies downstream.
Root AGENTS.md ──────────────────────────────────────────
│ Global Conventions:
│ - Commits: Conventional Commits (feat:, fix:, chore:)
│ - PR: Template required, at least 1 reviewer
│ - Branch: feature/{ticket}-{desc}
│
│ Auto-inherited Auto-inherited
│ ┌──────────────────┐ ┌──────────────────┐
│ ▼ │ ▼ │
│ apps/api/AGENTS.md │ infra/AGENTS.md │
│ (Only additional │ (Only additional │
│ rules specified) │ rules specified) │
│ "This service uses │ "When changing Helm │
│ Python" │ values, Ask First" │
└────────────────────────┴───────────────────────────
Benefits:
- Want to change commit rules? → Modify only the root
- Adding a new service? → Global rules apply automatically
- Need different rules for a specific service? → Override in that service's AGENTS.md
Adds bridges to vendor-specific configs so all AI tools read the generated AGENTS.md.
┌──────────────┐ ┌─────────────┐ ┌─────────────┐
│ Claude Code │ │ Cursor │ │ Codex │
│ CLAUDE.md │ │ .mdc rules │ │ AGENTS.md │
│ ↓ │ │ ↓ │ │ (native) │
│ "read │ │ "read │ │ ✓ │
│ AGENTS.md" │ │ AGENTS.md" │ │ │
└──────┬───────┘ └──────┬──────┘ └─────────────┘
└──────────┬─────────┘
▼
AGENTS.md (single source of truth)
│
┌─────────┼─────────┐
▼ ▼ ▼
.ai-agents/ .ai-agents/ .ai-agents/
context/ skills/ roles/
Principle: Bootstrap files are only generated for vendors already in use. Config files for unused tools are never created.
| Tool | Auto-reads AGENTS.md | Bootstrap |
|---|---|---|
| OpenAI Codex | Yes (native) | Not needed |
| Claude Code | Partial (fallback) | Adds directive to CLAUDE.md |
| Cursor | No | Adds .mdc to .cursor/rules/ |
| GitHub Copilot | No | Generates .github/copilot-instructions.md |
| Windsurf | No | Adds directive to .windsurfrules |
| Aider | Yes | Adds read to .aider.conf.yml |
Auto-generate bootstraps:
bash scripts/sync-ai-rules.shproject-root/
├── AGENTS.md # PM Agent (overall orchestration)
├── .ai-agents/
│ ├── context/ # Knowledge files (loaded at session start)
│ │ ├── domain-overview.md # Business domain, policies, constraints
│ │ ├── data-model.md # Entity definitions, relationships, state transitions
│ │ ├── api-spec.json # API map (JSON DSL, 3x token savings)
│ │ ├── event-spec.json # Kafka/MQ event specs
│ │ ├── infra-spec.md # Helm charts, networking, deployment order
│ │ ├── external-integration.md # External APIs, auth, rate limits
│ │ ├── business-metrics.md # KPIs, OKRs, revenue model, success criteria
│ │ ├── stakeholder-map.md # Decision makers, approval flows, RACI
│ │ ├── ops-runbook.md # Operational procedures, escalation, SLA
│ │ └── planning-roadmap.md # Milestones, dependencies, timeline
│ ├── skills/ # Behavioral workflows (loaded on demand)
│ │ ├── develop/SKILL.md # Dev: analyze → design → implement → test → PR
│ │ ├── deploy/SKILL.md # Deploy: tag → deploy request → verify
│ │ ├── review/SKILL.md # Review: checklist-based
│ │ ├── hotfix/SKILL.md # Emergency fix workflow
│ │ └── context-update/SKILL.md # Context file update procedure
│ └── roles/ # Role definitions (role-specific context depth)
│ ├── pm.md # Project Manager
│ ├── domain-coordinator.md # Domain Coordinator (multi-domain projects)
│ ├── backend.md # Backend Developer
│ ├── frontend.md # Frontend Developer
│ ├── sre.md # SRE / Infrastructure
│ └── reviewer.md # Code Reviewer
│
├── apps/
│ ├── api/AGENTS.md # Per-service agents
│ └── web/AGENTS.md
└── infra/
└── helm/AGENTS.md
./ai-agency.sh # Interactive: select agent + tool
./ai-agency.sh --tool claude # Direct launch with Claude
./ai-agency.sh --agent api # Select agent by keyword
./ai-agency.sh --multi # Parallel agents in tmux
./ai-agency.sh --list # List all available agentsSee the Sample Output in Quick Start for a full walkthrough.
| Format | Token Count | Notes |
|---|---|---|
| Natural language API description | ~200 tokens | |
| JSON DSL | ~70 tokens | 3x savings |
api-spec.json example:
{
"service": "order-api",
"apis": [{
"method": "POST",
"path": "/api/v1/orders",
"domains": ["Order", "Payment"],
"sideEffects": ["kafka:order-created", "db:orders.insert"]
}]
}AGENTS.md target: Under 300 tokens after substitution
Session start:
1. Read AGENTS.md (most AI tools do this automatically)
2. Follow context file paths to load .ai-agents/context/
3. Check .ai-agents/context/current-work.md (in-progress work)
4. git log --oneline -10 (understand recent changes)
Session end:
1. In-progress work → Record in current-work.md
2. Newly learned domain knowledge → Update context files
3. Incomplete TODOs → Record explicitly
When the project changes, .ai-agents/context/ files must be updated accordingly.
Who updates?
- During AI sessions: Each AGENTS.md includes maintenance triggers — the AI agent updates context files automatically as part of its normal workflow (e.g., after adding an API, it updates
api-spec.json). - After major changes: Run
./setup.shand select Incremental update mode. This re-scans the project and generates context for new directories without overwriting existing files. - Manual override: You can always instruct the AI directly: "Update
.ai-agents/context/domain-overview.mdwith the new business rules."
API added/changed/removed → Update api-spec.json
DB schema changed → Update data-model.md
Event spec changed → Update event-spec.json
Business policy changed → Update domain-overview.md
External integration changed → Update external-integration.md
Infrastructure config changed → Update infra-spec.md
KPI/OKR targets changed → Update business-metrics.md
Team structure changed → Update stakeholder-map.md
Operational procedure changed → Update ops-runbook.md
Milestone/roadmap changed → Update planning-roadmap.md
Failing to update means the next session will work with stale context.
Traditional Dev Team AI Agent Team
──────────────────── ──────────────────
Leader PM (human) Root AGENTS.md (PM agent)
Members N developers AGENTS.md in each directory
Onboarding Confluence/Notion .ai-agents/context/
Manuals Team wiki .ai-agents/skills/
Role Defs Job titles/R&R docs .ai-agents/roles/
Team Rules Team convention docs Global Conventions (inherited)
Clock In Arrive at office Session starts → AGENTS.md loaded
Clock Out Leave (memory retained) Session ends (memory lost!)
Next Day Memory intact .ai-agents/context/ loaded (memory restored)
Key difference: Humans retain their memory after leaving work, but AI forgets everything each time.
That's why .ai-agents/context/ exists — it serves as the AI's long-term memory.
Phase 1 (Basics) Phase 2 (Context) Phase 3 (Operations)
──────────────── ───────────────── ────────────────────
☐ Generate AGENTS.md ☐ Create .ai-agents/context/ ☐ Define .ai-agents/roles/
☐ Record build/test commands ☐ domain-overview.md ☐ Run multi-agent sessions
☐ Record conventions & rules ☐ api-spec.json (DSL) ☐ .ai-agents/skills/ workflows
☐ Global Conventions ☐ data-model.md ☐ Iterative feedback loop
☐ Vendor bootstraps ☐ Set up maintenance rules
| File | Audience | Purpose |
|---|---|---|
setup.sh |
Human | One-command interactive setup (tool + language → auto-generate) |
HOW_TO_AGENTS.md |
AI | Meta-instruction manual that agents read and execute |
README.md |
Human | This document — a guide for human understanding |
ai-agency.sh |
Human | Agent selection → AI session launcher |
AGENTS.md (each directory) |
AI | Per-directory agent identity + rules |
.ai-agents/context/*.md/json |
AI | Pre-organized domain knowledge |
.ai-agents/skills/*/SKILL.md |
AI | Standardized work workflows |
.ai-agents/roles/*.md |
AI/Human | Per-role context loading strategies |
- Kurly OMS Team AI Workflow — Inspiration for the context design of this system
- AGENTS.md Standard — Vendor-neutral agent instruction standard
- ETH Zurich Research — "Only document what cannot be inferred"
MIT
Reduce the time it takes for AI agents to understand your project to zero.