Awesome Ai Setup

Awesome AI Setup

> Turn AI coding tools into a real engineering system.

Claude Code • GitHub Copilot • Cursor • MCP • Memory • Context Engineering • Agent Workflows • Architecture Awareness

Quick Start • What's in This Repo • The Agents • AI Maturity Model • Config Reference • Docs

 

---

Practical agents and patterns for AI-native repository workflows.

This is not a prompt collection. It's a structured approach to context engineering - using AI itself to analyze your repository and generate accurate, project-specific documentation that makes AI coding assistants significantly more effective.

---

The Core Idea

Most AI setup guides give you static files to copy. The problem: static files describe a hypothetical project, not yours.

This repository takes a different approach.

The AI assistant is the execution engine. Instead of shipping a static ARCHITECTURE.md for you to adapt, this repo ships an agent that instructs your AI assistant to analyze your actual codebase and generate an accurate ARCHITECTURE.md from what it finds.

# Instead of this:
copy examples/flutter/ARCHITECTURE.md → your-project/ARCHITECTURE.md
# and manually adapt 300 lines of template...

# You do this:
"Read agents/generate-architecture.md and execute it on this repository."

# AI inspects your actual folder structure, detects your patterns,
# infers your conventions, and generates an accurate file.

The result is documentation that reflects your real project - not a generic ideal.

---

Why This Matters

Static templates rot. A copied ARCHITECTURE.md is accurate on day one, stale by month three. Agents can be re-run whenever your architecture evolves.

Works across tools. Plain markdown files, compatible with Claude Code, Cursor, Copilot, Codex, Aider, and anything else that can read a file. No vendor lock-in, no tool-specific syntax.

Infer, don't invent. Every agent has a "Do NOT" section. Hallucination constraints are as important as generation instructions. Output is derived from your actual code, not a template.

Composable. Run one agent or all seven. The files work independently.

---

What's in This Repo

awesome-ai-setup/

agents/               # 7 executable AI agents (the core product)
  README.md           # invocation reference for all agents and tools
  *.md                # one file per agent

docs/
  MATURITY_MODEL.md
  CONTEXT_ENGINEERING.md
  MCP_GUIDE.md

examples/
  flutter/            # Flutter + Riverpod + Clean Architecture reference output
  nodejs/             # Node.js + Express + TypeScript reference output

---

Quick Start

Step 1 - Install the agents into your project

Run this from your project root. It copies the agents/ folder and asks which tools you use.

npx awesome-ai-setup

Step 2 - Run the diagnostic

Start here regardless of where you are: fresh project, existing project with no AI setup, or existing project with a partial setup.

Claude Code

Read agents/diagnose-and-setup.md and execute it on this repository.

Cursor

Type /diagnose-and-setup in Agent chat.

GitHub Copilot (VS Code)

Open Copilot Chat, click the agent picker (mode dropdown), select diagnose-and-setup, then send:

execute the diagnostic on this codebase

The diagnostic produces a short, prioritized action plan tailored to your current state: fresh project, no AI setup, or partial setup.

Step 3 - Follow the generated action plan

Run the recommended agents in the same tool. For Claude Code, swap the filename. For Cursor, type /agent-name in Agent chat. For Copilot, select the agent from the picker. Review each output before committing - agents mark uncertain sections with `` for human review.

Using an example as reference

On existing projects (where src/, lib/, or app/ exists), the CLI will offer to copy an example during setup. You can also browse examples/ directly at any time to see what high-quality agent output looks like for a specific stack.

Current examples:

| Example | Stack | |---------|-------| | flutter | Flutter, Riverpod 2.x, Clean Architecture, GoRouter, Freezed | | nodejs | Node.js 22, Express 5, TypeScript (strict), Prisma, Zod, Vitest |

---

The Agents

| Agent | What It Generates | When to Use | |--------------------------------|-----------------------------------------------------|----------------------------------------------| | diagnose-and-setup | Prioritized action plan | Start here - any project, any stage | | generate-architecture | ARCHITECTURE.md | Active codebase setup, after major refactors | | generate-context | CONTEXT.md | Active codebase setup, when domain evolves | | update-memory | MEMORY.md | After architectural decisions, migrations | | generate-scoped-instructions | Per-file-type scoped rules + optional tool overlays | Any stage - works with minimal code | | generate-mcp-config | MCP config per detected tool | When adding tool connections (Level 3) | | generate-agent-workflows | AGENTS.md, workflows/ | After Levels 1–4 are in place |

→ [Agents documentation](agents/README.md)

---

AI Maturity Model

Use this as a diagnostic, not a checklist.

| Level | What You Have | Next Step | |-------|-------------------------------------------------|---------------------------------------------------------------------------------------| | 0 | AI autocomplete, no project context | Run diagnose-and-setup | | 1 | AGENTS.md or tool instructions file (CLAUDE.md, .cursor/rules/*.mdc) | Add ARCHITECTURE.md + CONTEXT.md via generate-architecture + generate-context | | 2 | Architecture + domain context | Add MCP config via generate-mcp-config | | 3 | Tool-connected (MCP) | Add MEMORY.md via update-memory | | 4 | Memory-aware | Add agentic workflows via generate-agent-workflows | | 5 | Agentic workflows | - |

→ [Full maturity model](docs/MATURITY_MODEL.md)

---

Config File Reference

Each AI tool has its own file format and location for each type of config. The agents generate all of them automatically for every tool you use.

┌─────────────────────────────────────────────────────────────────────────────────┐
│                          YOUR PROJECT                                           │
│                                                                                 │
│  CANONICAL PROJECT CONTEXT (each tool needs instructions to read these)         │
│  ├── ARCHITECTURE.md       folder structure, layers, conventions                │
│  ├── CONTEXT.md            domain model, business rules, terminology            │
│  ├── MEMORY.md             decisions made, anti-patterns, AI mistake log        │
│  ├── AGENTS.md             canonical agent context + agent definitions          │
│  └── workflows/            new-feature.md  bug-fix.md  refactor.md  ...         │
│                                                                                 │
│  COPILOT                   CLAUDE CODE               CURSOR                     │
│  ├── Global instructions   ├── Global instructions   ├── Global instructions    │
│  │   .github/              │   CLAUDE.md             │   .cursor/rules/         │
│  │   copilot-instructions  │                         │   global.mdc             │
│  │   .md                   ├── Scoped rules          ├── Scoped rules           │
│  ├── Scoped rules          │   .claude/rules/        │   .cursor/rules/         │
│  │   .github/instructions/ │   [name].md             │   [name].mdc             │
│  │   [name].instructions   │   (always loaded)       │   globs: **/*.dart       │
│  │   .md                   │                         │   alwaysApply: false     │
│  │   applyTo: "**/*.dart"  │                         │                          │
│  ├── MCP config            ├── MCP config            ├── MCP config             │
│  │   .vscode/mcp.json      │   .mcp.json             │   .cursor/mcp.json       │
│  │   ~/.config/copilot/  ¹ │   ~/.claude.json ¹      │   ~/.cursor/mcp.json ¹   │
│  │   intellij/mcp.json     │                         │                          │
│  ├── Ignore file           ├── Ignore file           ├── Ignore file            │
│  │   (GitHub repo settings)│   (use .gitignore)      │   .cursorignore          │
│  └── Agents                └── Agents                └── Agents                 │
│      .github/agents/           agents/                   .cursor/skills/        │
│      [name].md                 [name].md                 [name]/SKILL.md        │
│                                                                                 │
│  ¹ user-level — applies globally, not project-specifically                      │
└─────────────────────────────────────────────────────────────────────────────────┘

---

AGENTS.md Cross-Tool Support

AGENTS.md is an open convention for cross-tool agent instructions. The following tools either natively read it from the project root or support it via configuration:

| Tool | Support | How | |------|---------|-----| | Cursor | Native | Listed as a built-in rule type alongside .cursor/rules | | GitHub Copilot | Native | Nearest AGENTS.md in the directory tree is read as agent instructions | | Zed | Native | Recognized project rules filename | | Aider | Configured | Add read: AGENTS.md in .aider.conf.yml | | Gemini CLI | Configured | Add {"context": {"fileName": "AGENTS.md"}} in .gemini/settings.json | | Claude Code | Unconfirmed | Not yet explicit in first-party docs; use CLAUDE.md as the fallback |

For tools with native support, AGENTS.md can serve as the canonical shared agent context without a separate global instructions file. Tool-specific files (.github/copilot-instructions.md, .cursor/rules/*.mdc) remain useful for vendor-specific behavior, code review rules, or path-scoped conventions.

---

Docs

• [How to use the agents](agents/README.md)
• [AI Maturity Model](docs/MATURITY_MODEL.md)
• [Context Engineering Guide](docs/CONTEXT_ENGINEERING.md)
• [MCP Integration Guide](docs/MCP_GUIDE.md)

---

These patterns reflect what's working in production today. The AI tooling ecosystem is moving fast - the agent-driven approach is specifically designed to stay useful as capabilities evolve.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shuchitajain
• Source: shuchitajain/awesome-ai-setup
• License: MIT
• Homepage: https://www.npmjs.com/package/awesome-ai-setup

Install and usage instructions live in the source repository linked above.