{"id":47900489,"url":"https://github.com/itdar/ai-agency","last_synced_at":"2026-04-13T04:29:05.349Z","repository":{"id":347090662,"uuid":"1192816230","full_name":"itdar/ai-agency","owner":"itdar","description":"One command to give any AI agent instant project understanding. Auto-generates AGENTS.md + context for Claude Code, Codex, Cursor, Copilot, and more.","archived":false,"fork":false,"pushed_at":"2026-04-04T02:16:49.000Z","size":1137,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T04:27:21.323Z","etag":null,"topics":["agents-md","ai-agents","ai-coding","ai-context","aider","automation","claude-code","cli","codex","copilot","cursor","developer-tools","multi-agent","project-setup","windsurf"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itdar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"itdar"}},"created_at":"2026-03-26T15:34:36.000Z","updated_at":"2026-04-04T02:16:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/itdar/ai-agency","commit_stats":null,"previous_names":["itdar/agents-initializer","itdar/ai-agency"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/itdar/ai-agency","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdar%2Fai-agency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdar%2Fai-agency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdar%2Fai-agency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdar%2Fai-agency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itdar","download_url":"https://codeload.github.com/itdar/ai-agency/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdar%2Fai-agency/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31501903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai-agents","ai-coding","ai-context","aider","automation","claude-code","cli","codex","copilot","cursor","developer-tools","multi-agent","project-setup","windsurf"],"created_at":"2026-04-04T04:01:37.195Z","updated_at":"2026-04-13T04:29:05.337Z","avatar_url":"https://github.com/itdar.png","language":"Shell","funding_links":["https://github.com/sponsors/itdar"],"categories":[],"sub_categories":[],"readme":"🌐 [English](README.md) | [한국어](docs/README_ko.md) | [中文](docs/README_zh.md) | [日本語](docs/README_ja.md) | [Español](docs/README_es.md) | [Português](docs/README_pt.md)\n\n\u003cdiv align=\"center\"\u003e\n\n# ai-agency\n\n**Your own AI agency, built around your goals.**\n\nBuild your context once — never explain it again.\nDev, planning, business, design — specialist agents share the same knowledge and collaborate.\nNo more wasted tokens. Just orchestrated teamwork toward your objectives.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-red?logo=github)](https://github.com/sponsors/itdar)\n\n\u003c/div\u003e\n\n---\n\n## What is ai-agency?\n\nEvery AI session starts from scratch. Your agent doesn't know your APIs, your team rules, or your business goals. You explain the same things over and over — burning time and money.\n\n**ai-agency** builds persistent context for your organization and orchestrates AI specialists on top of it:\n\n1. **Context once, forever** — Build your project's knowledge layer once. Every agent starts fully briefed — codebase, conventions, business rules, team structure. No repeated token costs, no wasted warm-up time.\n\n2. **Orchestrated specialists** — Not just one agent on one repo. Dev, planning, business, design, QA, operations — each specialist shares the same context and collaborates. A PM agent coordinates them to tackle tasks, solve problems, and deliver results across your organization.\n\nWhether it's a single service or an entire company's workflow — ai-agency orchestrates the right experts with the right context.\n\nWorks with any AI tool: Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf, Aider.\n\n\u003c!-- TODO: 30-second demo GIF showing ai-agency init → ai-agency session launch → agent working with full context --\u003e\n\n---\n\n## Install\n\n### Homebrew (recommended)\n\n```bash\nbrew install itdar/tap/ai-agency\n```\n\n### Without Homebrew\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/itdar/ai-agency/main/src/install.sh | bash -s -- --global\n```\n\n### Per-project only\n\n```bash\ncd /path/to/your-project\ncurl -fsSL https://raw.githubusercontent.com/itdar/ai-agency/main/src/install.sh | bash\n```\n\n---\n\n## Getting Started\n\n### 1. Initialize your project\n\n```bash\ncd ~/my-project\nai-agency init\n```\n\nOr from anywhere: `ai-agency init ~/my-project`\n\nThis does three things automatically:\n1. **Scans** your directory structure and classifies each directory (backend, frontend, infra, business, etc.)\n2. **Generates** `AGENTS.md` files and `.ai-agents/` context for each area\n3. **Validates** the generated files for completeness\n\n\u003c!-- TODO: Screenshot of ai-agency init running — showing the interactive tool/language selection CUI --\u003e\n\nYou pick your AI tool (Claude Code, Codex, or Gemini) and language. The AI then analyzes your project and builds the context. This is a one-time setup — it takes a few minutes but saves hours later.\n\n### 2. Launch an agent session\n\n```bash\nai-agency\n```\n\nThat's it. Pick an agent from the interactive menu and start working. The agent already knows your project.\n\n\u003c!-- TODO: Screenshot of ai-agency interactive CUI — showing the agent list with arrow-key navigation, colored agents --\u003e\n\n### 3. Daily use\n\nYour daily workflow doesn't change. Just run `ai-agency` instead of launching your AI tool directly.\n\n```bash\nai-agency                     # Pick agent interactively\nai-agency --agent api         # Jump straight to the API agent\n```\n\nWhen you select a top-level agent (PM, Domain Coordinator), it automatically spawns and coordinates sub-agents as needed — you don't have to manage them yourself.\n\nFor running multiple independent agents side-by-side in tmux split panes:\n\n```bash\nai-agency --multi             # Select which agents to run in parallel\n```\n\n\u003c!-- TODO: Screenshot of tmux multi-agent split panes — 2-3 agents running simultaneously with colored pane borders --\u003e\n\n---\n\n## Why You Need This\n\n### Without ai-agency\n\nEvery session starts from zero. The AI spends time (and your tokens) figuring out your project:\n\n- \"What framework is this?\" — reads 20 files to figure out\n- \"What are the API endpoints?\" — scans every controller\n- \"What are the team conventions?\" — has no idea, guesses wrong\n- \"Who approves deploys?\" — doesn't know, skips the step\n\n\u003e Research (ETH Zurich, 2026): AI agents that re-analyze a known project waste **20% more tokens** and produce **worse results** than agents with pre-built context.\n\n### With ai-agency\n\nThe AI loads everything in seconds and starts working immediately:\n\n```\nSession Start\n  → Reads AGENTS.md            \"I'm the backend expert for order-api\"\n  → Loads .ai-agents/context/  \"I know the APIs, data models, team rules\"\n  → Starts working             No exploration phase needed\n```\n\n\u003c!-- TODO: Before/after comparison image — left side: AI exploring files aimlessly, right side: AI immediately productive with context loaded --\u003e\n\n---\n\n## What Gets Generated\n\nWhen you run `ai-agency init`, three layers of context are created:\n\n```\nyour-project/\n├── AGENTS.md                    # Who am I? (role, rules, permissions)\n├── .ai-agents/\n│   ├── context/                 # What do I know? (domain knowledge)\n│   │   ├── domain-overview.md   #   Business purpose, policies, constraints\n│   │   ├── api-spec.json        #   API endpoints map\n│   │   ├── data-model.md        #   Entities and relationships\n│   │   └── ...                  #   (generated based on your project type)\n│   ├── skills/                  # How do I work? (workflow standards)\n│   │   ├── develop/SKILL.md     #   Dev: analyze → implement → test → PR\n│   │   └── review/SKILL.md      #   Review: security, performance checklist\n│   └── roles/                   # Role-specific loading strategies\n│       ├── pm.md\n│       └── backend.md\n├── apps/\n│   ├── api/AGENTS.md            # Per-service agent\n│   └── web/AGENTS.md\n└── infra/AGENTS.md\n```\n\n**Only non-obvious information is stored.** Things the AI can figure out by reading code (like \"this is a React app\") are excluded. Things it can't infer (like \"we use squash merge\" or \"QA approval is required before deploy\") are included.\n\n---\n\n## Project Structure Examples\n\nai-agency adapts to your project's shape. The directory where you run `ai-agency init` becomes the PM (coordinator).\n\n### Simple product\n\n```\nmy-app/               ← PM agent\n├── api/              ← Backend agent\n├── web/              ← Frontend agent\n└── infra/            ← Infra agent\n```\n\n### Product + business teams\n\n```\nmy-product/            ← PM agent\n├── api/              ← Backend agent\n├── web/              ← Frontend agent\n├── business/         ← Business Analyst agent\n├── planning/         ← Planner agent\n└── infra/            ← Infra agent\n```\n\nNot just code — business, planning, QA, operations, and more. Each area gets its own specialized agent.\n\n### Multi-domain platform\n\n```\nplatform/              ← PM agent\n├── commerce/         ← Domain Coordinator (auto-detected)\n│   ├── order-api/    ← Backend agent\n│   └── storefront/   ← Frontend agent\n├── social/           ← Domain Coordinator (auto-detected)\n│   ├── feed-api/     ← Backend agent\n│   └── chat-api/     ← Backend agent\n└── infra/            ← Infra agent\n```\n\nDomains are detected automatically when a directory contains 2+ subdirectories with their own build files.\n\n---\n\n## Team Mode\n\nRun a PM agent that coordinates sub-agents, or launch multiple agents in parallel.\n\n### Coordinated team (Claude Code)\n\nThe PM agent delegates tasks to specialists via Claude Code's native agent teams:\n\n```bash\nai-agency                     # Select \"team\" mode from the menu\n```\n\n\u003c!-- TODO: Screenshot of team mode selection in the CUI — showing single/team/multi options --\u003e\n\n### Parallel agents (any AI tool)\n\nLaunch multiple agents in tmux split panes. Each agent works independently with file-based coordination:\n\n```bash\nai-agency --multi             # Select agents, they run in split panes\n```\n\nAgents coordinate through `.ai-agents/coordination/` — a shared task board and message log that works across any AI tool.\n\n\u003c!-- TODO: Screenshot of tmux multi-agent session with task-board.md visible in one pane --\u003e\n\n---\n\n## Keeping Context Fresh\n\nContext files are updated automatically during AI sessions — each AGENTS.md includes maintenance triggers that tell the agent when to update what.\n\nAfter a session, ai-agency checks if code changed but context wasn't updated, and warns you:\n\n```\n[ai-agency] Code changes detected but no context files updated.\n  Run: ai-agency verify --staleness\n```\n\nYou can also check manually:\n\n```bash\nai-agency verify              # Validate structure and completeness\nai-agency verify --staleness  # Check if context is up-to-date with code\n```\n\nFor major changes, re-run init in incremental mode — it only generates context for new directories:\n\n```bash\nai-agency init                # Select \"incremental\" when prompted\n```\n\n---\n\n## Supported AI Tools\n\nai-agency is vendor-neutral. AGENTS.md works with any tool, and bootstrap files are auto-generated for tools that need them.\n\n| Tool | Works out of the box | Auto-bootstrap |\n|---|---|---|\n| **OpenAI Codex** | Yes | Not needed |\n| **Claude Code** | Yes | `CLAUDE.md` generated |\n| **Cursor** | Via rules | `.cursor/rules/` generated |\n| **GitHub Copilot** | Via instructions | `.github/copilot-instructions.md` generated |\n| **Windsurf** | Via rules | `.windsurfrules` generated |\n| **Aider** | Via config | `.aider.conf.yml` updated |\n| **Gemini CLI** | Yes | Not needed |\n\nBootstrap files are only generated for tools you actually use. Nothing is created for tools you don't have.\n\n---\n\n## CLI Reference\n\n```bash\n# Setup\nai-agency init [path]           # Initialize a project (scan, generate, validate)\nai-agency classify [path]       # Preview directory classification without generating\n\n# Daily use\nai-agency                       # Interactive agent launcher\nai-agency --agent \u003ckeyword\u003e     # Launch specific agent\nai-agency --multi               # Parallel agents in tmux split panes\nai-agency --tool \u003cclaude|codex\u003e # Specify AI tool\nai-agency --lang \u003ccode\u003e         # Set UI language (en ko ja zh es fr de ru hi ar)\n\n# Project management\nai-agency register [path]       # Register a project\nai-agency scan [dir]            # Auto-discover projects with AGENTS.md\nai-agency list                  # List registered projects\nai-agency unregister [path]     # Remove from registry\n\n# Maintenance\nai-agency verify [path]         # Validate generated files\nai-agency verify --staleness    # Check context freshness\nai-agency clear [path]          # Remove all generated files\n```\n\n---\n\n## How It Works (Under the Hood)\n\nFor those curious about the internals:\n\n1. **classify-dirs.sh** scans your project and applies 19 priority rules to classify each directory (k8s-workload, frontend, backend-go, business, etc.)\n2. **scaffold.sh** creates the `.ai-agents/` directory structure with placeholder files\n3. **setup.sh** launches your chosen AI tool with `HOW_TO_AGENTS.md` — a meta-instruction that guides the AI through a 7-step analysis and generation process\n4. **validate.sh** checks the generated files for structural integrity (required sections, token limits, reference completeness)\n5. **sync-ai-rules.sh** creates vendor-specific bootstrap files pointing to AGENTS.md\n6. **ai-agency.sh** manages the interactive agent selection CUI and session lifecycle, including context checksum tracking and multi-agent coordination\n\n\u003e **Token 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.\n\n---\n\n## References\n\n- [AGENTS.md Standard](https://agents.md/) — The vendor-neutral agent instruction standard this project builds on\n- [ETH Zurich Research](https://www.infoq.com/news/2026/03/agents-context-file-value-review/) — \"Only document what cannot be inferred\"\n- [Kurly OMS Team AI Workflow](https://helloworld.kurly.com/blog/oms-claude-ai-workflow/) — Inspiration for the context design\n\n---\n\n## License\n\nMIT\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eStop re-explaining your project to AI. Set up once, work forever.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitdar%2Fai-agency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitdar%2Fai-agency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitdar%2Fai-agency/lists"}