awesome-ai-setup: Instructions file for Codex

AGENTS.md — awesome-ai-setup

Context for AI agents working on this repository.

---

What This Repo Is

awesome-ai-setup is an npm CLI tool + a collection of executable AI agents that help developers set up AI-native development context for any codebase.

Published as npx awesome-ai-setup. Current version: 0.6.0.

The core philosophy: instead of shipping static template files for humans to adapt, this repo ships agents — markdown instruction files that tell an AI assistant to inspect a real codebase and generate accurate, project-specific documentation from what it finds. Static templates rot; agents can be re-run.

---

Repository Structure

awesome-ai-setup/
├── bin/
│   └── cli.js              # Entry point — interactive CLI (ESM)
├── src/
│   ├── detect.js           # Detects project state (agents exist?, maturity level)
│   ├── install.js          # Copies agent files and scaffolds ignore/MCP config files
│   └── output.js           # Prints post-install summary to the terminal
├── agents/                 # The 7 executable AI agents (core product)
│   ├── README.md           # Invocation reference for all agents across tools
│   ├── diagnose-and-setup.md
│   ├── generate-architecture.md
│   ├── generate-context.md
│   ├── generate-mcp-config.md
│   ├── generate-scoped-instructions.md
│   ├── generate-agent-workflows.md
│   └── update-memory.md
├── examples/               # Reference output for target project types
│   ├── flutter/            # Flutter + Riverpod + Clean Architecture
│   └── nodejs/             # Node.js + Express + TypeScript + Prisma
├── docs/
│   ├── MATURITY_MODEL.md
│   ├── CONTEXT_ENGINEERING.md
│   └── MCP_GUIDE.md
├── package.json            # name: awesome-ai-setup, main: bin/cli.js
├── README.md
├── CONTRIBUTING.md
└── CHANGELOG.md

---

Tech Stack

• Runtime: Node.js ≥ 16, ESM ("type": "module")
• Dependencies: fs-extra (file operations), prompts (interactive CLI prompts)
• No build step. Source is plain JS, runs directly with Node.
• Test suite: node --test test/lint-agents.js (run via npm test). Checks agent frontmatter and file structure.