@ngocbaongo/ai-agent-init 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngocbaongo/ai-agent-init",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Bootstrap any project with AI-agent-ready documentation and conventions. Run once, let the AI do the rest.",
   "keywords": [
     "ai-agent",
@@ -21,7 +21,9 @@
   "bugs": {
     "url": "https://github.com/ngocbaomobile/ai-agent-init/issues"
   },
-  "bin": "./bin/cli.js",
+  "bin": {
+    "ai-agent-init": "bin/cli.js"
+  },
   "files": [
     "bin/",
     "templates/"

package/templates/ai_bootstrap.md

@@ -16,15 +16,19 @@ Scan the project root directory and determine:
 - 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 |
+| File/Folder Found | Tech Stack | Template |
+|---|---|---|
+| `pubspec.yaml` | Flutter / Dart | `rules_flutter.md` |
+| `requirements.txt` / `pyproject.toml` / `setup.py` | Python | `rules_python.md` |
+| `package.json` + `react-native` dependency | React Native | `rules_react_native.md` |
+| `package.json` (no react-native) | Node.js / TypeScript | `rules_nodejs.md` |
+| `go.mod` | Go | `rules_go.md` |
+| `Cargo.toml` | Rust | `rules_rust.md` |
+| `build.gradle` / `settings.gradle` + Kotlin | Android / Kotlin | `rules_android.md` |
+| `*.xcodeproj` / `*.xcworkspace` / `Package.swift` | iOS / Swift | `rules_swift.md` |
+| `pom.xml` / `build.gradle` + Spring Boot | Java / Spring Boot | `rules_java_spring.md` |
+| `composer.json` + Laravel | PHP / Laravel | `rules_php_laravel.md` |
+| `*.csproj` / `*.sln` | .NET / C# | `rules_dotnet.md` |
 
 ---
 

package/templates/rules_android.md

@@ -0,0 +1,51 @@
+# Android / Kotlin — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for an Android/Kotlin project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: Kotlin
+- UI Framework: [Jetpack Compose / XML Views — detect from build.gradle and source files]
+- Architecture: MVVM with Android Architecture Components
+- DI: [Hilt / Koin — detect from build.gradle]
+- Async: Kotlin Coroutines + Flow
+- Networking: [Retrofit + OkHttp — detect from build.gradle]
+- Local DB: [Room — detect from build.gradle]
+
+## Folder Structure (Feature-based)
+```
+app/src/main/
+├── java/<package>/
+│   ├── core/           # Shared base classes, utils, DI setup
+│   ├── data/           # Repositories (impl), DTOs, data sources, Room DAOs
+│   ├── domain/         # Use cases, repository interfaces, domain models
+│   ├── presentation/   # ViewModels, Composables/Fragments, UI state
+│   │   └── <feature>/
+│   │       ├── <Feature>ViewModel.kt
+│   │       ├── <Feature>Screen.kt   (Compose) or <Feature>Fragment.kt
+│   │       └── <Feature>UiState.kt
+│   └── di/             # Hilt modules
+└── res/                # Layouts (XML), drawables, strings
+```
+
+## Naming Conventions
+- Files/Classes: `PascalCase`
+- Functions/variables/properties: `camelCase`
+- Constants: `UPPER_SNAKE_CASE` (companion object) or `camelCase` (top-level val)
+- Composable functions: `PascalCase` (treated as components)
+- ViewModels: `FeatureNameViewModel`
+- UI State: `FeatureNameUiState` (sealed class or data class)
+
+## Code Conventions
+- Use `StateFlow` / `SharedFlow` for ViewModel → UI communication
+- Use `sealed class` for UiState (Loading, Success, Error)
+- Inject dependencies via constructor (with Hilt `@Inject`)
+- Use `viewModelScope` for coroutines in ViewModels
+- Never access Android context inside ViewModels — pass data only
+- Use `data class` for all model/DTO types
+
+## What NOT To Do
+- Do NOT do network calls or DB access on the main thread
+- Do NOT put business logic in Activities/Fragments/Composables
+- Do NOT use `GlobalScope` for coroutines
+- Do NOT use `LiveData` for new code — prefer `StateFlow`

package/templates/rules_dotnet.md

@@ -0,0 +1,47 @@
+# .NET / C# — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a .NET/C# project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: C# 12 / .NET 8+
+- Framework: [ASP.NET Core Web API / Blazor / MAUI — detect from .csproj]
+- ORM: [Entity Framework Core / Dapper — detect from .csproj]
+- Architecture: [Clean Architecture / Minimal API / MVC — detect from folder structure]
+- DI: Built-in Microsoft.Extensions.DependencyInjection
+
+## Folder Structure (Clean Architecture)
+```
+src/
+├── <AppName>.API/          # ASP.NET Core project (controllers, middleware, DI setup)
+├── <AppName>.Application/  # Use cases, commands/queries (MediatR), DTOs, interfaces
+├── <AppName>.Domain/       # Entities, value objects, domain events, interfaces
+└── <AppName>.Infrastructure/ # EF Core, repositories (impl), external services
+tests/
+├── <AppName>.UnitTests/
+└── <AppName>.IntegrationTests/
+```
+
+## Naming Conventions
+- Classes/Interfaces/Records: `PascalCase`
+- Interfaces: `IPascalCase` (e.g., `IUserRepository`)
+- Methods/Properties: `PascalCase`
+- Private fields: `_camelCase` (underscore prefix)
+- Local variables/parameters: `camelCase`
+- Constants: `PascalCase` (C# convention, not UPPER_SNAKE_CASE)
+- Async methods: suffix with `Async` (e.g., `GetUserByIdAsync`)
+
+## Code Conventions
+- Use `record` for immutable DTOs and value objects
+- Use MediatR pattern (Commands/Queries/Handlers) for application layer
+- Use `ILogger<T>` for logging — never `Console.WriteLine`
+- Use `async/await` throughout — never `.Result` or `.Wait()` on tasks
+- Use `CancellationToken` as last parameter in all async methods
+- Use primary constructors (C# 12) for cleaner dependency injection
+- Use `FluentValidation` for command/query validation
+
+## What NOT To Do
+- Do NOT use `.Result` or `.Wait()` on Tasks — causes deadlocks in ASP.NET Core
+- Do NOT use `static` mutable state — use DI with appropriate lifetimes
+- Do NOT expose EF Core entities directly in API responses — use DTOs/records
+- Do NOT catch `Exception` broadly — catch specific exception types

package/templates/rules_java_spring.md

@@ -0,0 +1,50 @@
+# Java / Spring Boot — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a Java/Spring Boot project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: Java 17+ / Kotlin
+- Framework: Spring Boot 3.x
+- Build Tool: [Maven (pom.xml) / Gradle (build.gradle) — detect from root files]
+- ORM: [Spring Data JPA + Hibernate — detect from pom.xml/build.gradle]
+- Database: [PostgreSQL / MySQL / H2 — detect from application.properties]
+- Security: [Spring Security — detect from dependencies]
+
+## Architecture
+Layered architecture (standard Spring Boot):
+```
+src/main/java/<package>/
+├── controller/     # REST controllers (@RestController)
+├── service/        # Business logic (@Service)
+├── repository/     # Data access (@Repository, JPA interfaces)
+├── entity/         # JPA entities (@Entity)
+├── dto/            # Data Transfer Objects (request/response bodies)
+├── config/         # Spring configuration classes (@Configuration)
+├── exception/      # Custom exceptions + global exception handler
+└── util/           # Utility/helper classes
+```
+
+## Naming Conventions
+- Classes: `PascalCase`
+- Methods/variables: `camelCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Packages: `lowercase.dot.separated`
+- Controllers: `FeatureNameController`
+- Services: `FeatureNameService` + `FeatureNameServiceImpl`
+- Repositories: `FeatureNameRepository`
+- DTOs: `FeatureNameRequest`, `FeatureNameResponse`
+
+## Code Conventions
+- Use constructor injection (never field injection with `@Autowired`)
+- Use `@Slf4j` (Lombok) for logging — never `System.out.println`
+- Use `@Valid` + Bean Validation annotations on DTOs
+- Use `ResponseEntity<T>` for REST controller return types
+- Handle exceptions globally with `@ControllerAdvice`
+- Use Lombok (`@Data`, `@Builder`, `@RequiredArgsConstructor`) to reduce boilerplate
+
+## What NOT To Do
+- Do NOT use field injection (`@Autowired` on fields)
+- Do NOT put business logic in controllers
+- Do NOT expose JPA entities directly as API response — use DTOs
+- Do NOT use `Optional.get()` without checking `isPresent()` — use `orElseThrow()`

package/templates/rules_php_laravel.md

@@ -0,0 +1,55 @@
+# PHP / Laravel — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a Laravel project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: PHP 8.2+
+- Framework: Laravel 11.x
+- ORM: Eloquent
+- Frontend: [Blade / Inertia.js (Vue/React) / Livewire — detect from composer.json and resources/]
+- Queue: [Laravel Queues with Redis/Database — detect from .env or config/queue.php]
+- Auth: [Laravel Sanctum / Passport / Breeze / Jetstream — detect from composer.json]
+
+## Folder Structure (Laravel convention)
+```
+app/
+├── Http/
+│   ├── Controllers/    # Request handling
+│   ├── Requests/       # Form Request validation classes
+│   ├── Resources/      # API Resources (JSON transformers)
+│   └── Middleware/
+├── Models/             # Eloquent models
+├── Services/           # Business logic (custom, not Laravel default)
+├── Repositories/       # Data access abstraction (if used)
+├── Jobs/               # Queue jobs
+├── Events/ & Listeners/
+└── Providers/
+database/
+├── migrations/
+├── seeders/
+└── factories/
+```
+
+## Naming Conventions
+- Controllers: `PascalCase` + `Controller` suffix (e.g., `UserController`)
+- Models: Singular `PascalCase` (e.g., `User`, `OrderItem`)
+- Migrations: `snake_case` with timestamp prefix
+- Form Requests: `StoreFeatureNameRequest`, `UpdateFeatureNameRequest`
+- Jobs: `PascalCase` + verb (e.g., `SendWelcomeEmail`, `ProcessOrder`)
+- Variables/methods: `camelCase`
+- DB columns/table names: `snake_case`
+
+## Code Conventions
+- Use Form Request classes for all validation — never validate in controllers directly
+- Use API Resources for all JSON responses — never return raw Eloquent models
+- Use Services for business logic that spans multiple models
+- Use Eloquent relationships instead of manual joins where possible
+- Use Laravel's built-in helpers (`cache()`, `queue()`, `event()`) over manual instantiation
+- Always use database migrations — never modify the DB schema directly
+
+## What NOT To Do
+- Do NOT put business logic in controllers — use Services
+- Do NOT use `DB::raw()` without parameterized bindings (SQL injection risk)
+- Do NOT use `env()` outside of config files — use `config()` helper instead
+- Do NOT disable CSRF protection on routes that modify data

package/templates/rules_react_native.md

@@ -0,0 +1,52 @@
+# React Native — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a React Native project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: TypeScript (strict mode)
+- Framework: React Native [with Expo / bare workflow — detect from app.json or package.json]
+- Navigation: [React Navigation v6 / Expo Router — detect from package.json]
+- State Management: [Zustand / Redux Toolkit / Jotai / Context API — detect from package.json]
+- Styling: [StyleSheet / NativeWind / Tamagui — detect from package.json]
+- Networking: [Axios / React Query / SWR — detect from package.json]
+
+## Folder Structure
+```
+src/
+├── app/              # Screens / Expo Router routes
+├── components/       # Reusable UI components
+│   ├── common/       # Generic (Button, Text, Input, etc.)
+│   └── <feature>/    # Feature-specific components
+├── hooks/            # Custom React hooks
+├── stores/           # State management (Zustand/Redux)
+├── services/         # API calls, external services
+├── utils/            # Pure utility functions
+├── types/            # Shared TypeScript types/interfaces
+├── constants/        # App-wide constants, theme tokens
+└── assets/           # Images, fonts, icons
+```
+
+## Naming Conventions
+- Files: `PascalCase.tsx` for components, `camelCase.ts` for hooks/utils
+- Components: `PascalCase` (e.g., `UserProfileCard`)
+- Hooks: `useFeatureName` (e.g., `useAuthState`)
+- Screens: `FeatureNameScreen.tsx`
+- Types/Interfaces: `PascalCase` (e.g., `UserProfile`, `ApiResponse<T>`)
+- Constants: `UPPER_SNAKE_CASE`
+
+## Code Conventions
+- Enable `strict: true` in `tsconfig.json`
+- Components must be functional — no class components
+- Extract business logic into custom hooks or services, not inside components
+- Use `React.memo()` for components that receive stable props but render frequently
+- Always type component props with an explicit interface (`interface Props {}`)
+- Use `const` arrow functions for components: `const MyComponent = () => {}`
+- Use `StyleSheet.create()` for styles — avoid inline style objects in render
+
+## What NOT To Do
+- Do NOT use `any` type — use `unknown` with type guards
+- Do NOT mix navigation logic inside UI components — use navigation hooks
+- Do NOT use `useEffect` for data fetching — use React Query / SWR instead
+- Do NOT hardcode colors/spacing — use theme tokens from constants/
+- Do NOT use platform-specific code without `Platform.OS` checks

package/templates/rules_rust.md

@@ -0,0 +1,49 @@
+# Rust — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a Rust project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: Rust (stable toolchain)
+- Build Tool: Cargo
+- Async Runtime: [Tokio / async-std / None — detect from Cargo.toml]
+- Web Framework: [Axum / Actix-web / Warp — detect from Cargo.toml]
+- ORM/DB: [SQLx / Diesel / SeaORM — detect from Cargo.toml]
+- Error Handling: [thiserror / anyhow — detect from Cargo.toml]
+
+## Workspace Structure
+```
+src/
+├── main.rs         # Binary entry point
+├── lib.rs          # Library entry point (if dual crate)
+├── domain/         # Business logic, domain models
+├── infrastructure/ # DB, external services, adapters
+├── api/            # HTTP handlers, routes
+└── config.rs       # Configuration structs
+tests/              # Integration tests
+benches/            # Benchmarks (if any)
+```
+
+## Naming Conventions
+- Files/modules: `snake_case.rs`
+- Types/Structs/Enums/Traits: `PascalCase`
+- Functions/variables/fields: `snake_case`
+- Constants: `UPPER_SNAKE_CASE`
+- Lifetimes: short, lowercase (`'a`, `'buf`)
+- Macros: `snake_case!`
+
+## Code Conventions
+- Use `thiserror` for library errors, `anyhow` for application errors
+- Prefer `?` operator for error propagation over `.unwrap()`
+- Use `clippy` and `rustfmt` — run `cargo clippy` and `cargo fmt` before committing
+- Prefer owned types in public APIs; use references internally where possible
+- Use `#[derive(Debug, Clone, PartialEq)]` on all domain structs/enums
+- Write doc comments (`///`) for all public items
+- Use `mod.rs` sparingly — prefer inline `mod` declarations in parent files
+
+## What NOT To Do
+- Do NOT use `.unwrap()` or `.expect()` in production code paths (only in tests/examples)
+- Do NOT use `unsafe` without a detailed safety comment explaining why it's sound
+- Do NOT use `std::sync::Mutex` in async code — use `tokio::sync::Mutex`
+- Do NOT clone excessively to avoid borrow checker issues — redesign the ownership instead
+- Do NOT use global mutable state (`static mut`)

package/templates/rules_swift.md

@@ -0,0 +1,60 @@
+# Swift / iOS — Rules & Conventions Template
+
+> AI Agent: Use this file as reference to fill in `docs/ai/rules.md` for a Swift/iOS project.
+> Adapt every section to match what you actually observe in the codebase.
+
+## Tech Stack
+- Language: Swift 5.9+
+- Platform: iOS 16+ / macOS 13+
+- UI Framework: [SwiftUI / UIKit / Both — detect from source files]
+- Architecture: [MVVM / MVC / TCA (The Composable Architecture) / VIPER — detect from folder structure]
+- Package Manager: [Swift Package Manager (SPM) / CocoaPods — detect from Package.swift or Podfile]
+- Networking: [URLSession / Alamofire / Moya — detect from Package.swift or Podfile]
+- Async: [async/await / Combine / Completion handlers — detect from code style]
+
+## Architecture
+[Detect and describe. Common patterns:]
+- **MVVM + SwiftUI**: Views observe ViewModels via @StateObject / @ObservedObject / @Observable
+- **TCA**: Store, Reducer, Action, State pattern from pointfreeco/swift-composable-architecture
+- **VIPER**: View, Interactor, Presenter, Entity, Router — common in older UIKit projects
+
+## Folder Structure (SwiftUI MVVM example)
+```
+<AppName>/
+├── App/              # App entry point, main scene
+├── Features/         # One folder per feature
+│   └── <Feature>/
+│       ├── Views/
+│       ├── ViewModels/
+│       └── Models/
+├── Core/             # Shared utilities, extensions, services
+│   ├── Network/
+│   ├── Storage/
+│   └── Extensions/
+└── Resources/        # Assets, fonts, localization strings
+```
+
+## Naming Conventions
+- Files: `PascalCase.swift`
+- Types/Classes/Structs/Enums: `PascalCase`
+- Functions/variables/properties: `camelCase`
+- Constants: `camelCase` (Swift style, not UPPER_SNAKE_CASE)
+- Protocols: `PascalCase`, often suffixed with `-able`, `-ing`, or `-Delegate`
+- View files: `FeatureNameView.swift`
+- ViewModel files: `FeatureNameViewModel.swift`
+
+## Code Conventions
+- Prefer `struct` over `class` for value semantics (models, view models where possible)
+- Use `@Observable` macro (iOS 17+) or `ObservableObject` for view models
+- Use Swift Concurrency (`async/await`, `Task`, `Actor`) over Combine for new code
+- Keep Views "dumb" — no business logic inside View body
+- Use `private` access control by default; only expose what's necessary
+- Prefer `let` over `var` wherever possible
+- Handle errors explicitly — never use `try!` or `as!` in production code
+- Use `#Preview` macro for SwiftUI previews
+
+## What NOT To Do
+- Do NOT use force unwrap (`!`) or force cast (`as!`) — use `guard let` or `if let`
+- Do NOT put network calls or business logic directly in Views
+- Do NOT use global singletons unless absolutely necessary (prefer dependency injection)
+- Do NOT ignore `@MainActor` requirements for UI updates