@ngocbaongo/ai-agent-init 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# 🤖 ai-agent-init
+
+> Bootstrap any project with AI-agent-ready documentation in seconds.
+
+Stop wasting time explaining your project structure to every new AI Agent. Run one command, point your agent to one file, and get a fully documented, standardized project.
+
+## The Problem
+
+Every time you start a new AI coding session, you waste tokens and time re-explaining:
+- What tech stack you're using
+- What architecture patterns to follow
+- What naming conventions to use
+- Where files should go
+
+## The Solution
+
+`ai-agent-init` drops a smart bootstrap file into your project. You point your AI Agent to it, and the agent does the rest — generating tailored documentation for your specific codebase, then cleaning up after itself.
+
+## Usage
+
+```bash
+# 1. cd into any project (new or existing)
+cd my-project
+
+# 2. Run the initializer
+npx ai-agent-init init
+
+# 3. Tell your AI Agent (Cursor, Copilot, Cline, Gemini, etc.):
+# "Read docs/ai/ai_bootstrap.md and set up this project."
+```
+
+**That's it.** The agent will:
+- 🔍 Analyze your codebase and detect the tech stack
+- 📝 Generate `docs/ai/rules.md` — conventions tailored to your project
+- 🗺️ Generate `docs/ai/project_map.md` — a map of your folder structure
+- 📄 Create or update `README.md` with real project info
+- ⚙️ Create `.cursorrules` and `.clinerules` at the root
+- 🧹 Delete all template files automatically
+
+## Supported Tech Stacks
+
+The bootstrap templates cover conventions for:
+
+| Stack | Detected By |
+|---|---|
+| Flutter / Dart | `pubspec.yaml` |
+| Python | `requirements.txt`, `pyproject.toml` |
+| Node.js / TypeScript | `package.json` |
+| Go | `go.mod` |
+| Generic | Fallback for any other project |
+
+## What Gets Generated
+
+```
+your-project/
+├── docs/
+│   └── ai/
+│       ├── rules.md          ← Code conventions & architecture for this project
+│       └── project_map.md    ← Folder structure map with descriptions
+├── README.md                 ← Updated with real project info
+├── .cursorrules              ← For Cursor IDE
+└── .clinerules               ← For Cline / Roo-Code
+```
+
+## Why This Works
+
+The key insight is: **AI Agents are great at reading context and adapting**. Instead of writing complex detection logic in the CLI, we give the agent a clear instruction file (`ai_bootstrap.md`) and let it figure out the specifics. This makes the tool:
+
+- ✅ **Adaptive** — works with any language or framework
+- ✅ **Accurate** — agent reads actual code, not just file names
+- ✅ **Lightweight** — CLI has zero dependencies
+- ✅ **Self-cleaning** — no template clutter after setup
+
+## Contributing
+
+Contributions welcome! To add a new tech stack template:
+1. Add a `templates/rules_<tech>.md` file
+2. Reference it in `templates/ai_bootstrap.md`'s detection table
+
+## License
+
+MIT © [ngocbaomobile](https://github.com/ngocbaomobile)

package/bin/cli.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+
+function log(msg) { console.log(`${CYAN}[ai-agent-init]${RESET} ${msg}`); }
+function success(msg) { console.log(`${GREEN}✔${RESET} ${msg}`); }
+function warn(msg) { console.log(`${YELLOW}⚠${RESET} ${msg}`); }
+
+function printHelp() {
+  console.log(`
+${BOLD}ai-agent-init${RESET} — Bootstrap any project with AI-agent-ready documentation.
+
+${BOLD}Usage:${RESET}
+  npx ai-agent-init init     Copy AI bootstrap templates to current directory
+  npx ai-agent-init help     Show this help message
+
+${BOLD}Workflow:${RESET}
+  1. cd into your project directory
+  2. Run: npx ai-agent-init init
+  3. Tell your AI agent: "Read docs/ai/ai_bootstrap.md and set up the project"
+  4. The AI agent will generate all docs and clean up the template files
+
+${BOLD}Supports:${RESET}
+  Flutter • Python • Node.js / TypeScript • Go • Generic
+`);
+}
+
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      if (fs.existsSync(destPath)) {
+        warn(`Skipped (already exists): ${destPath}`);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+        success(`Created: ${path.relative(process.cwd(), destPath)}`);
+      }
+    }
+  }
+}
+
+function init() {
+  const cwd = process.cwd();
+  const templatesDir = path.join(__dirname, '..', 'templates');
+  const destDir = path.join(cwd, 'docs', 'ai');
+
+  console.log(`\n${BOLD}🚀 ai-agent-init${RESET}\n`);
+  log(`Copying AI bootstrap templates to: ${destDir}\n`);
+
+  if (!fs.existsSync(templatesDir)) {
+    console.error('Error: templates directory not found. Please reinstall ai-agent-init.');
+    process.exit(1);
+  }
+
+  copyDirRecursive(templatesDir, destDir);
+
+  console.log(`
+${GREEN}${BOLD}✅ Done!${RESET}
+
+${BOLD}Next step — tell your AI Agent:${RESET}
+${CYAN}"Read the file docs/ai/ai_bootstrap.md and follow the instructions to set up this project."${RESET}
+
+The agent will:
+  • Analyze the codebase and detect the tech stack
+  • Generate docs/ai/rules.md, docs/ai/project_map.md, README.md
+  • Create .cursorrules / .clinerules at the root
+  • Clean up all template files automatically
+`);
+}
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  printHelp();
+} else if (command === 'init') {
+  init();
+} else {
+  console.error(`Unknown command: "${command}". Run "npx ai-agent-init help" for usage.`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ngocbaongo/ai-agent-init",
+  "version": "1.0.0",
+  "description": "Bootstrap any project with AI-agent-ready documentation and conventions. Run once, let the AI do the rest.",
+  "keywords": [
+    "ai-agent",
+    "cursor",
+    "copilot",
+    "project-template",
+    "conventions",
+    "bootstrap",
+    "developer-tools"
+  ],
+  "author": "ngocbaongo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/ngocbaomobile/ai-agent-init.git"
+  },
+  "homepage": "https://github.com/ngocbaomobile/ai-agent-init#readme",
+  "bugs": {
+    "url": "https://github.com/ngocbaomobile/ai-agent-init/issues"
+  },
+  "bin": {
+    "aia": "./bin/cli.js",
+    "ai-agent-init": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "templates/"
+  ],
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/templates/ai_bootstrap.md

@@ -0,0 +1,133 @@
+# 🤖 AI BOOTSTRAP INSTRUCTIONS
+
+> **This is a temporary file for AI Agent setup. You must delete it after completing all steps.**
+
+Hello AI Agent! You have been invoked to standardize this codebase and make it AI-agent-friendly.
+Follow the steps below carefully and in order.
+
+---
+
+## Step 1: Analyze the Codebase
+
+Scan the project root directory and determine:
+- The **primary programming language(s)** used
+- The **framework(s)** in use (e.g. Flutter, FastAPI, Next.js, Express, Go standard lib)
+- The **architecture pattern** if identifiable (e.g. Clean Architecture, MVC, Feature-first)
+- The **existing folder structure** (top-level directories and their apparent purpose)
+
+**Detection signals to look for:**
+| File/Folder Found | Tech Stack |
+|---|---|
+| `pubspec.yaml` | Flutter / Dart |
+| `requirements.txt` / `pyproject.toml` / `setup.py` | Python |
+| `package.json` | Node.js / TypeScript / JavaScript |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `build.gradle` / `settings.gradle` | Android / Kotlin |
+| `*.xcodeproj` / `*.xcworkspace` | iOS / Swift |
+
+---
+
+## Step 2: Generate `docs/ai/rules.md`
+
+Create the file `docs/ai/rules.md` with the following sections, filling in details specific to **this project's actual tech stack and patterns**:
+
+```markdown
+# Project Rules & Conventions
+
+## Tech Stack
+- Language: [e.g. Dart 3.x]
+- Framework: [e.g. Flutter 3.x]
+- State Management: [e.g. BLoC]
+- Key Libraries: [list the most important ones from pubspec/package.json/requirements]
+
+## Architecture
+[Describe the architecture. E.g. "This project uses Clean Architecture with 3 layers: Data, Domain, Presentation."]
+
+## Folder Structure Conventions
+[Describe what goes where. E.g. "Features are organized under lib/features/<feature_name>/ with bloc/, data/, domain/, presentation/ sub-folders."]
+
+## Naming Conventions
+- Files: [e.g. snake_case.dart]
+- Classes: [e.g. PascalCase]
+- Variables: [e.g. camelCase]
+- Constants: [e.g. kConstantName or UPPER_SNAKE_CASE]
+
+## Code Conventions
+- [Key rules, e.g. "Always use dependency injection via GetIt"]
+- [e.g. "Never put business logic in Widgets"]
+- [e.g. "All API calls must go through a Repository interface"]
+
+## Approved Libraries
+Only use the libraries already listed in the dependency file. Do NOT add new packages without explicit user approval.
+
+## What NOT To Do
+- [e.g. "Do not use setState in pages that have a BLoC"]
+- [e.g. "Do not hardcode strings — use the l10n/localization system"]
+```
+
+---
+
+## Step 3: Generate `docs/ai/project_map.md`
+
+Scan the active directories (exclude: `.git`, build artifacts, `node_modules`, `.venv`, `.dart_tool`, `.gradle`, `Pods`, etc.) and create `docs/ai/project_map.md`:
+
+```markdown
+# Project Map
+
+> Auto-generated by ai-agent-init. Update this file when the structure changes significantly.
+
+## Overview
+[1-2 sentence description of what this project does]
+
+## Root Structure
+[List top-level directories/files with a short description of their purpose]
+
+## Key Entry Points
+- Main file: [e.g. lib/main.dart or main.py or src/index.ts]
+- Config: [e.g. pubspec.yaml or package.json]
+- Tests: [e.g. test/ or __tests__/]
+```
+
+---
+
+## Step 4: Create or Update `README.md`
+
+If `README.md` does not exist, create it. If it exists but is a placeholder, update it. Use the template from `docs/ai/templates/readme_template.md` as a guide, replacing all placeholders with actual project information you have discovered.
+
+---
+
+## Step 5: Create AI Config Files at Root
+
+Create the following files at the **project root** by copying the content of `docs/ai/rules.md` into them:
+
+- `.cursorrules` — for Cursor IDE
+- `.clinerules` — for Cline / Roo-Code (VS Code extension)
+
+---
+
+## Step 6: Cleanup (CRITICAL — Do Not Skip)
+
+After successfully creating and verifying all files above:
+
+1. **Delete** the `docs/ai/templates/` directory and all its contents.
+2. **Delete this file** (`docs/ai/ai_bootstrap.md`).
+3. Report back to the user with:
+   - Detected tech stack summary
+   - List of files generated
+   - Any assumptions made that the user should review
+
+---
+
+## ✅ Definition of Done
+
+The setup is complete when these files exist and have real content (not placeholders):
+- [ ] `docs/ai/rules.md`
+- [ ] `docs/ai/project_map.md`
+- [ ] `README.md`
+- [ ] `.cursorrules`
+- [ ] `.clinerules`
+
+And these have been deleted:
+- [ ] `docs/ai/ai_bootstrap.md` (this file)
+- [ ] `docs/ai/templates/` (entire directory)

package/templates/readme_template.md

@@ -0,0 +1,71 @@
+# [Project Name]
+
+> [One-sentence description of what this project does and who it's for]
+
+---
+
+## Overview
+
+[2-3 paragraphs describing the project: what problem it solves, how it works at a high level, and what makes it unique or important]
+
+## Architecture
+
+```
+[Insert a simple ASCII or Mermaid diagram of the architecture here]
+```
+
+**Key concepts:**
+- [Architecture layer 1]: [Description]
+- [Architecture layer 2]: [Description]
+
+## Tech Stack
+
+| Category | Technology |
+|---|---|
+| Language | [e.g. Dart 3.x] |
+| Framework | [e.g. Flutter 3.x] |
+| State Management | [e.g. BLoC] |
+| Backend / API | [e.g. REST / GraphQL / Firebase] |
+| Database | [e.g. PostgreSQL / Hive / SQLite] |
+
+## Getting Started
+
+### Prerequisites
+- [e.g. Flutter SDK >= 3.0]
+- [e.g. Node.js >= 18]
+
+### Installation
+
+```bash
+# Clone the repository
+git clone [repo-url]
+cd [project-name]
+
+# Install dependencies
+[e.g. flutter pub get / npm install / pip install -r requirements.txt]
+```
+
+### Running the Project
+
+```bash
+# Development
+[e.g. flutter run / npm run dev / python main.py]
+
+# Tests
+[e.g. flutter test / npm test / pytest]
+
+# Build
+[e.g. flutter build apk / npm run build]
+```
+
+## Project Structure
+
+See [`docs/ai/project_map.md`](docs/ai/project_map.md) for a full directory map.
+
+## Contributing
+
+See [`docs/ai/rules.md`](docs/ai/rules.md) for code conventions and architecture guidelines used in this project.
+
+## License
+
+[MIT / Apache 2.0 / etc.]

package/templates/rules_flutter.md

@@ -0,0 +1,59 @@
+# Flutter / Dart — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a Flutter project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: Dart 3.x
+- Framework: Flutter 3.x
+- State Management: [BLoC / Riverpod / GetX / Provider — detect from pubspec.yaml]
+- Navigation: [GoRouter / AutoRoute / Navigator 2.0 — detect from pubspec.yaml]
+- DI: [GetIt / Injectable — detect from pubspec.yaml]
+- Networking: [Dio / http]
+- Local DB: [Hive / Isar / sqflite — if present]
+
+## Architecture
+This project uses **Clean Architecture** with the following layers:
+- **Data**: API clients, repositories (implementation), DTOs, local data sources
+- **Domain**: Entities, repository interfaces, use cases
+- **Presentation**: BLoC/Cubit, Pages, Widgets
+
+## Folder Structure
+```
+lib/
+├── core/           # Shared utilities, base classes, theme, router
+├── features/       # One folder per feature
+│   └── <feature>/
+│       ├── data/
+│       ├── domain/
+│       └── presentation/
+│           ├── bloc/
+│           ├── pages/
+│           └── widgets/
+└── main.dart
+```
+
+## Naming Conventions
+- Files: `snake_case.dart`
+- Classes: `PascalCase`
+- BLoC classes: `FeatureNameBloc`, `FeatureNameState`, `FeatureNameEvent`
+- Variables/methods: `camelCase`
+- Constants: `kConstantName`
+- Widgets: `FeatureNameWidget` or `FeatureNamePage`
+
+## Code Conventions
+- Never put business logic inside Widget build() methods
+- Use dependency injection (GetIt) for all use cases and repositories
+- All Widgets that depend on BLoC must use BlocBuilder / BlocListener / BlocConsumer
+- Use `freezed` for immutable state and data classes if available
+- Prefer `const` constructors wherever possible
+- Each feature must be self-contained; cross-feature access only through core/
+
+## Approved Libraries
+Only use libraries already declared in `pubspec.yaml`. Do NOT add new packages without user approval.
+
+## What NOT To Do
+- Do NOT use setState in pages that have a BLoC
+- Do NOT hardcode strings — use the localization/l10n system
+- Do NOT import across features directly; use core abstractions
+- Do NOT put API calls inside Widgets or Pages

package/templates/rules_go.md

@@ -0,0 +1,43 @@
+# Go — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a Go project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: Go 1.21+
+- Framework: [Gin / Echo / Fiber / Chi / None — detect from go.mod]
+- ORM: [GORM / sqlx / raw sql — detect from go.mod]
+- Testing: go test (standard)
+
+## Architecture
+Standard Go Project Layout (https://github.com/golang-standards/project-layout):
+```
+cmd/          # Main applications (entry points)
+internal/     # Private application and library code
+pkg/          # Library code usable by external apps
+api/          # API definitions (OpenAPI, proto)
+configs/      # Config files
+scripts/      # Build/install scripts
+```
+
+## Naming Conventions
+- Files: `snake_case.go`
+- Packages: `lowercase`, single word preferred
+- Types/Functions (exported): `PascalCase`
+- Types/Functions (unexported): `camelCase`
+- Interfaces: `Verb`-er pattern (e.g. `Reader`, `Writer`, `Handler`)
+- Constants: `PascalCase` (exported) or `camelCase` (unexported)
+
+## Code Conventions
+- Always handle errors explicitly — never ignore with `_`
+- Use `context.Context` as first parameter in functions that do I/O
+- Prefer interfaces for dependency injection
+- Keep functions small and focused (single responsibility)
+- Use `gofmt` and `golangci-lint` for formatting/linting
+- Wrap errors with `fmt.Errorf("context: %w", err)`
+
+## What NOT To Do
+- Do NOT use `panic` for normal error handling
+- Do NOT use global variables for state
+- Do NOT return naked errors without context
+- Do NOT ignore the `context.Context` parameter

package/templates/rules_nodejs.md

@@ -0,0 +1,39 @@
+# Node.js / TypeScript — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a Node.js/TypeScript project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: TypeScript (strict mode preferred)
+- Runtime: Node.js 18+
+- Framework: [Next.js / Express / NestJS / Fastify — detect from package.json]
+- Package Manager: [npm / yarn / pnpm — detect from lockfile]
+- Testing: [Jest / Vitest — detect from package.json]
+
+## Architecture
+[Detect and describe. Common patterns:]
+- **Next.js App Router**: app/, components/, lib/, hooks/
+- **NestJS**: modules/, controllers/, services/, entities/
+- **Express Layered**: routes/, controllers/, services/, repositories/
+
+## Naming Conventions
+- Files: `kebab-case.ts` (Next.js) or `camelCase.ts` (libraries)
+- Classes: `PascalCase`
+- Interfaces: `IPascalCase` or `PascalCase` (without I prefix — depends on project)
+- Functions/variables: `camelCase`
+- Constants: `UPPER_SNAKE_CASE` or `camelCase`
+- React components: `PascalCase.tsx`
+
+## Code Conventions
+- Enable `strict: true` in tsconfig.json
+- Use `interface` for object shapes, `type` for unions/intersections
+- Prefer named exports over default exports (except for Next.js pages)
+- All async functions must have proper error handling (try/catch or Result pattern)
+- Use index.ts barrel files for clean imports within modules
+- Never use `any` — use `unknown` and type guards instead
+
+## What NOT To Do
+- Do NOT use `var` — always use `const` or `let`
+- Do NOT use `any` type
+- Do NOT mutate function arguments
+- Do NOT mix CommonJS and ESM imports in the same project

package/templates/rules_python.md

@@ -0,0 +1,48 @@
+# Python — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a Python project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: Python 3.11+
+- Framework: [FastAPI / Django / Flask / None — detect from requirements.txt or pyproject.toml]
+- Package Manager: [pip / Poetry / PDM — detect from pyproject.toml or requirements.txt]
+- Testing: [pytest — standard]
+- Linter/Formatter: [ruff / black / flake8 — detect from config files]
+
+## Architecture
+[Detect and describe. Common patterns:]
+- **Layered**: routes → services → repositories → models
+- **Domain-Driven**: domain/, application/, infrastructure/, interfaces/
+
+## Folder Structure (FastAPI example)
+```
+app/
+├── api/          # Route handlers (controllers)
+├── core/         # Config, dependencies, security
+├── models/       # SQLAlchemy / Pydantic models
+├── schemas/      # Pydantic request/response schemas
+├── services/     # Business logic
+└── repositories/ # DB access layer
+tests/
+main.py
+```
+
+## Naming Conventions
+- Files/modules: `snake_case.py`
+- Classes: `PascalCase`
+- Functions/variables: `snake_case`
+- Constants: `UPPER_SNAKE_CASE`
+- Private: `_prefixed_with_underscore`
+
+## Code Conventions
+- Use type hints on all function signatures
+- Use Pydantic for data validation and serialization
+- All business logic lives in services/, not in route handlers
+- Use dependency injection via FastAPI's `Depends()` system
+- Follow PEP 8 style guide
+
+## What NOT To Do
+- Do NOT put DB queries directly in route handlers
+- Do NOT use mutable default arguments
+- Do NOT ignore exceptions silently — always log or re-raise