@p_tipso/agentive 1.0.1 → 1.0.3

package/README.md

@@ -1,158 +1,116 @@
 <div align="center">
 
-# 🤖 agentive
+# Agentive
 
 **A universal, framework-agnostic AI agent workspace CLI.**
 
-[![npm version](https://img.shields.io/npm/v/@p_tipso/agentive.svg?style=flat-square)](https://www.npmjs.com/package/@p_tipso/agentive)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@p_tipso/agentive"><img src="https://img.shields.io/npm/v/@p_tipso/agentive?style=for-the-badge&color=blue" alt="npm version"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=for-the-badge&logo=nodedotjs" alt="Node.js"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@p_tipso/agentive"><img src="https://img.shields.io/npm/dm/@p_tipso/agentive?style=flat-square&label=downloads" alt="npm downloads"></a>
+  <a href="https://github.com/TiPS0/agentive/stargazers"><img src="https://img.shields.io/github/stars/TiPS0/agentive?style=flat-square&logo=github" alt="GitHub stars"></a>
+  <a href="https://github.com/TiPS0/agentive/issues"><img src="https://img.shields.io/github/issues/TiPS0/agentive?style=flat-square" alt="GitHub issues"></a>
+</p>
 
 </div>
 
 ---
 
-Stop maintaining separate rule files for every AI tool. **agentive** scaffolds a universal `.agents/` directory and an `AGENTS.md` file in your project — your single source of truth for agent commands, skills, and rules.
+Stop maintaining separate rule files for every AI tool. **agentive** scaffolds a universal `.agents/` directory, an `AGENTS.md` file, and an `.aiignore` file in your project — providing a **single source of truth** for all your agent commands, skills, and rules, while significantly saving token usage.
+
+## ✨ Why Agentive?
+
+| Feature                       | Description                                                          |
+| :---------------------------- | :------------------------------------------------------------------- |
+| 🚀 **Interactive Setup**    | Select your environment (General, Expo, React Native) to get tailored rules. |
+| 🌍 **Universal**              | Framework-agnostic setup. Works with React, Python, Go, you name it. |
+| 🧠 **Single Source of Truth** | Centralize skills and rules for _all_ your AI agents in one place.   |
+| ⚡ **Dynamic Layering**     | Scaffolds base rules and safely merges framework-specific guardrails. |
+
+---
 
-## ✨ What it does
+## 📦 Installation & Usage
 
-Run one command, get a fully structured AI agent workspace:
+Run one command, get a fully structured AI agent workspace instantly:
 
 ```bash
 npx @p_tipso/agentive
 ```
 
-No prompts. No config. Just run it and it scaffolds everything instantly into the folder your terminal is currently in.
+If you prefer to install it globally for frequent usage:
+
+```bash
+npm install -g @p_tipso/agentive
+agentive
+```
 
-### What happens when you run it
+### CLI Commands
 
-1. Detects your current directory and project name
-2. Creates an `AGENTS.md` file at your project root (top-level agent instructions)
-3. Creates a `.agents/` folder with the full workspace structure:
-   - `settings.json` — project config (committed to git)
-   - `settings.local.json` — local machine overrides (auto-gitignored)
-   - `commands/` — reusable prompt commands (e.g. code review, fix errors)
-   - `skills/` — skill definitions for agent roles
-   - `rules/` — project-wide rules all agents must follow
-4. If `.agents/` already exists, it skips to avoid overwriting your customisations
+| Command                           | Description                                                  |
+| :-------------------------------- | :----------------------------------------------------------- |
+| `npx @p_tipso/agentive`           | Scaffold `.agents/` workspace instantly in current directory |
+| `npx @p_tipso/agentive --version` | Print the current CLI version                                |
+| `npx @p_tipso/agentive --help`    | Show available commands and options                          |
 
 ---
 
-## 📁 Output Structure
+## 🏗 What Happens Under the Hood?
 
-```
+When you run `agentive`, it launches an interactive wizard asking about your project environment (e.g., General, Mobile > Expo, React Native). It then intelligently scaffolds a tailored workspace:
+
+```text
 your-project/
-├── AGENTS.md                      ← root agent instructions
+├── AGENTS.md                      ← Root agent instructions
+├── .aiignore                      ← Hides irrelevant files from AI to save tokens
 ├── .agents/
-│   ├── settings.json              ← project config
-│   ├── settings.local.json        ← local overrides (auto-gitignored)
+│   ├── settings.json              ← Project config
+│   ├── settings.local.json        ← Local machine overrides (auto-gitignored)
 │   ├── commands/
-│   │   ├── README.md              ← guide: how to add commands
-│   │   ├── review.md              ← code review command
-│   │   └── fix-issue.md           ← zero-error fix command
+│   │   ├── README.md              ← Guide: how to add commands
+│   │   ├── review.md              ← Example code review command
+│   │   └── fix-issue.md           ← Example zero-error fix command
 │   ├── skills/
-│   │   └── README.md              ← guide: how to add skills
+│   │   └── README.md              ← Guide: how to add skills
 │   └── rules/
-│       └── README.md              ← guide: how to add rules
-```
-
-### `settings.json`
-
-```json
-{
-  "projectName": "my-app",
-  "agentiveVersion": "1.1.0",
-  "createdAt": "2026-07-05T12:00:00.000Z"
-}
+│       └── README.md              ← Guide: how to add rules
 ```
 
----
-
-## 🏗 Package Architecture
+### 📂 File & Folder Guide
 
-This is the source code structure of the `agentive` npm package itself:
+- **`.aiignore`**: Prevents context pollution and saves tokens by hiding files (like `node_modules` or build outputs) from your AI agents.
+- **`commands/`**: Reusable prompt instructions that agents can execute on demand (e.g. `review.md`).
+- **`skills/`**: Skill definitions that teach agents how to behave in specific roles.
+- **`rules/`**: Project-wide rules that all agents must follow strictly.
 
-```
-agentive/
-├── bin/
-│   └── index.js                   ← CLI entry point (shebang + commander)
-├── src/
-│   ├── commands/
-│   │   └── init.js                ← scaffolding logic (no prompts, auto-install)
-│   ├── templates/                 ← files copied into the user's project
-│   │   ├── AGENTS.md              ← → copied to project root
-│   │   ├── commands/
-│   │   │   ├── README.md
-│   │   │   ├── review.md
-│   │   │   └── fix-issue.md
-│   │   ├── skills/
-│   │   │   └── README.md
-│   │   └── rules/
-│   │       └── README.md
-│   └── utils/
-│       ├── fileSystem.js          ← async fs helpers, directory creation, settings
-│       └── compilers.js           ← sync to Cursor / Claude / Windsurf formats
-├── .github/
-│   └── workflows/
-│       └── publish.yml            ← auto-publish to npm on git tag push
-├── .gitignore
-├── LICENSE
-├── README.md
-└── package.json
-```
+### 🌟 Framework-Specific Guardrails
+By selecting a specific framework (like **Expo** or **React Native**), `agentive` overlays expertly crafted rules into your `.agents/` folder. This ensures your AI understands nuances like *Expo Router*, *Native Modules*, or *Unitless Pixels* right out of the box—preventing common hallucinations.
 
 ---
 
-## 📂 Folder Guide
-
-### Commands (`commands/`)
-
-Reusable prompt instructions that agents can execute on demand.
-
-| File | Purpose |
-|------|---------|
-| `review.md` | Structured code review for bugs, performance, and security |
-| `fix-issue.md` | Diagnose and fix errors with zero tolerance |
-
-### Skills (`skills/`)
-
-Skill definitions that teach agents how to behave in specific roles. Add `.md` files to define new capabilities.
-
-### Rules (`rules/`)
-
-Project-wide rules that all agents must follow. Add `.md` files for coding standards, architecture rules, etc.
-
----
-
-## 📦 Commands
-
-| Command | Description |
-|---|---|
-| `npx @p_tipso/agentive` | Scaffold `.agents/` workspace instantly |
-| `npx @p_tipso/agentive --version` | Print the current version |
-| `npx @p_tipso/agentive --help` | Show available commands |
+## 🤝 Contributing
 
----
+We love contributions! Whether it's adding new built-in skills, fixing bugs, or improving documentation, your help is appreciated.
 
-## 🛠 Install Globally (optional)
-
-```bash
-npm install -g @p_tipso/agentive
-agentive
-```
+Please read our [Contributing Guide](CONTRIBUTING.md) to get started with setting up your local environment and submitting a Pull Request.
 
 ---
 
-## 🤝 Contributing
+## ⭐ Star History
 
-1. Fork the repo: [github.com/TiPS0/agentive](https://github.com/TiPS0/agentive)
-2. Clone your fork
-3. `npm install`
-4. `npm link` (to use `agentive` locally while developing)
-5. Make your changes and open a pull request!
+<a href="https://star-history.com/#TiPS0/agentive&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=TiPS0/agentive&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=TiPS0/agentive&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=TiPS0/agentive&type=Date" />
+ </picture>
+</a>
 
 ---
 
 ## 📄 License
 
-MIT © [Pakawat Tipso](https://github.com/TiPS0)
+This project is licensed under the [MIT License](./LICENSE).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@p_tipso/agentive",
-  "version": "1.0.1",
-  "description": "A universal, framework-agnostic AI agent repository setup CLI. Scaffold a .agent/ workspace and sync to Cursor, Claude, and Windsurf.",
+  "version": "1.0.3",
+  "description": "A universal, framework-agnostic AI agent repository setup CLI. Scaffold a .agents/ workspace, AGENTS.md, and .aiignore to sync and optimize context for Cursor, Claude, and Windsurf.",
   "license": "MIT",
   "author": "Pakawat Tipso",
   "type": "commonjs",
@@ -27,7 +27,8 @@
     "scaffold",
     "init",
     "rules",
-    "context"
+    "context",
+    "aiignore"
   ],
   "repository": {
     "type": "git",

package/src/commands/init.js

@@ -2,6 +2,7 @@
 
 const path = require('path');
 const chalk = require('chalk');
+const prompts = require('prompts');
 const { version } = require('../../package.json');
 const {
   createAgentDirectory,
@@ -31,19 +32,63 @@ async function runInit() {
   console.log(chalk.gray('  Installing to: ') + chalk.white(cwd));
   console.log('');
 
+  // --- Prompt User for Project Type ---
+  const typeResponse = await prompts({
+    type: 'select',
+    name: 'projectType',
+    message: 'What type of project are you building?',
+    choices: [
+      { title: 'General / Universal', value: 'general' },
+      { title: 'Web Development', value: 'web', disabled: true },
+      { title: 'Mobile Development', value: 'mobile' },
+    ],
+    initial: 0,
+  });
+
+  if (!typeResponse.projectType) {
+    console.log(chalk.red('  ✖ ') + 'Setup cancelled.');
+    process.exit(1);
+  }
+
+  let framework = null;
+  if (typeResponse.projectType === 'mobile') {
+    const fwResponse = await prompts({
+      type: 'select',
+      name: 'framework',
+      message: 'Which framework are you using?',
+      choices: [
+        { title: 'Expo (Recommended)', value: 'expo' },
+        { title: 'React Native', value: 'react-native' },
+      ],
+      initial: 0,
+    });
+    
+    if (!fwResponse.framework) {
+      console.log(chalk.red('  ✖ ') + 'Setup cancelled.');
+      process.exit(1);
+    }
+    framework = fwResponse.framework;
+  }
+
+  const projectType = typeResponse.projectType;
+  console.log('');
+
   // --- Scaffold .agents/ directory ---
   const templatesDir = path.join(__dirname, '..', 'templates');
   const agentsDir = await createAgentDirectory(cwd, false);
-  await copyTemplates(templatesDir, agentsDir, projectName);
+  await copyTemplates(templatesDir, agentsDir, projectName, projectType, framework);
 
   // --- Write settings.json and settings.local.json ---
   await writeSettings(agentsDir, {
     projectName,
+    projectType,
+    framework,
     agentiveVersion: version,
     createdAt: new Date().toISOString(),
   });
 
   console.log(chalk.green('  ✔ ') + chalk.white('Created ') + chalk.cyan('AGENTS.md'));
+  console.log(chalk.green('  ✔ ') + chalk.white('Created ') + chalk.cyan('.aiignore'));
   console.log(chalk.green('  ✔ ') + chalk.white('Scaffolded ') + chalk.cyan('.agents/') + chalk.white(' workspace'));
 
   // --- Done ---
@@ -53,6 +98,7 @@ async function runInit() {
   console.log(chalk.white('  Your AI workspace is ready:'));
   console.log('');
   console.log(chalk.gray('    AGENTS.md                       ← root agent instructions'));
+  console.log(chalk.gray('    .aiignore                       ← hides files from AI to save tokens'));
   console.log(chalk.gray('    .agents/'));
   console.log(chalk.gray('    ├── settings.json               ← project config'));
   console.log(chalk.gray('    ├── settings.local.json         ← local overrides (gitignored)'));

package/src/templates/{AGENTS.md → base/AGENTS.md}

@@ -19,6 +19,11 @@ All agent configuration lives inside the `.agents/` directory:
 | `.agents/skills/` | Skill definitions that teach agents how to behave |
 | `.agents/rules/` | Project-wide rules all agents must follow |
 
+## Context Management
+
+When exploring, reading, or searching this repository, you **MUST** respect the exclusion rules defined in `.aiignore`. 
+Additionally, you must also read and respect any rules defined in `.gitignore`, `.cursorignore`, or `.aiexclude` if they exist in the repository to prevent context pollution and save token usage.
+
 ## Getting Started
 
 1. Edit the markdown files inside `.agents/` to customise agent behaviour

package/src/templates/base/aiignore

@@ -0,0 +1,48 @@
+# Standard AI Ignore file - prevents context pollution & saves tokens
+# Learn more: https://github.com/TiPS0/agentive
+
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+vendor/
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Build outputs & generated files
+dist/
+build/
+out/
+coverage/
+.next/
+.nuxt/
+.vuepress/
+.cache/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Version control & OS files
+.git/
+.DS_Store
+*.pem
+
+# Editor directories and files
+.idea/
+.vscode/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/src/templates/mobile/expo/rules/01-expo-components.md

@@ -0,0 +1,17 @@
+# Rule: Expo Components & Libraries
+
+When building UI or accessing device features in an Expo project, you MUST adhere to the following rules:
+
+1. **Strictly Prefer Expo SDK Packages**:
+   - For images, ALWAYS use `expo-image` instead of React Native's `<Image>` or `react-native-fast-image`.
+   - For icons, prefer `expo-symbols` or `@expo/vector-icons`.
+   - For fonts, use `expo-font`.
+   - For device features (camera, location, file system), ALWAYS check if an official `expo-*` package exists before reaching for a third-party React Native package.
+
+2. **No Web Primitives**:
+   - NEVER use `<div>`, `<span>`, `<button>`, `<p>`, `<a>`, or `<input>`.
+   - You MUST use `<View>`, `<Text>`, `<Pressable>`, `<TextInput>`, etc., from `react-native`.
+
+3. **Avoid Bare Native Modules**:
+   - Do NOT recommend installing libraries that require manual `pod install` or manual Android Gradle changes unless they are explicitly Expo-compatible (e.g., they provide a Config Plugin).
+   - If a library requires native code changes, remind the user that they must use a Custom Development Client (`npx expo run:ios` or `npx expo run:android`) rather than Expo Go.

package/src/templates/mobile/expo/rules/02-expo-styling.md

@@ -0,0 +1,16 @@
+# Rule: Expo Styling
+
+1. **Flexbox Defaults**:
+   - Remember that in React Native, `flexDirection` defaults to `"column"`, NOT `"row"`.
+   - `display: "flex"` is the default and only display type for Views.
+
+2. **Unitless Values**:
+   - NEVER use string values with `px` for dimensions (e.g., `width: "100px"`). ALWAYS use unitless numbers (e.g., `width: 100`).
+   - Percentages are allowed as strings (e.g., `width: "100%"`).
+
+3. **StyleSheet Priority**:
+   - Unless NativeWind (Tailwind) is explicitly set up in the project, ALWAYS use `StyleSheet.create({ ... })` from `react-native` to define styles.
+   - Avoid inline object styles except for dynamic values (e.g., `style={{ width: dynamicWidth }}`).
+
+4. **SafeAreaView**:
+   - In Expo Router, do NOT use `react-native`'s `SafeAreaView`. Use `react-native-safe-area-context` and its `useSafeAreaInsets` hook or `<SafeAreaView>` component to handle notches properly across all platforms.

package/src/templates/mobile/expo/rules/expo-router.md

@@ -0,0 +1,16 @@
+# Rule: Expo Router
+
+1. **File-Based Routing Architecture**:
+   - You MUST use Expo Router (`expo-router`) exclusively. Do NOT install or use `@react-navigation/native` directly.
+   - All screens must be placed inside the `app/` directory (or `src/app/` if a `src` folder is used).
+
+2. **Layouts and Navigation**:
+   - Use `_layout.tsx` files to define shared UI (like Stack or Tabs) across multiple screens in a directory.
+   - NEVER use `<NavigationContainer>`. Expo Router handles this automatically.
+
+3. **Links and Dynamic Routes**:
+   - ALWAYS use the `<Link>` component from `expo-router` for navigation between screens, or the `useRouter()` hook for programmatic navigation.
+   - Dynamic routes use square brackets (e.g., `app/user/[id].tsx`). Retrieve parameters using the `useLocalSearchParams()` hook from `expo-router`.
+
+4. **Not-Found Screens**:
+   - Use `+not-found.tsx` to handle 404 routes.

package/src/templates/mobile/expo/skills/create-expo-app.md

@@ -0,0 +1,19 @@
+# Skill: Create Expo App
+
+## Context
+When a user asks to start a new Expo project from scratch, follow these modern initialization standards based on the latest Expo documentation.
+
+## Execution Steps
+1. **Initialize Command**: 
+   - Propose running `npx create-expo-app@latest` in the terminal. This uses the default template which includes Expo Router and modern defaults.
+   - If a specific template is requested, use `npx create-expo-app@latest --template <template-name>`.
+
+2. **Start the Development Server**:
+   - Propose running `npx expo start` to start the Metro bundler.
+   - Explain to the user that they can press `i` to open the iOS simulator, or `a` to open the Android emulator.
+
+3. **Resetting Cache**:
+   - If the user reports weird bundling errors or missing modules, propose running `npx expo start --clear` (or `-c`) to clear the Metro cache.
+
+4. **Dependencies**:
+   - ALWAYS use `npx expo install <package>` instead of `npm install` or `yarn add` when installing native packages. This ensures the version installed is compatible with the current Expo SDK.

package/src/templates/mobile/expo/skills/expo-upgrader.md

@@ -0,0 +1,10 @@
+# Skill: Expo SDK Migration Expert
+
+## Operational Objective
+Safely upgrade the local codebase's native wrappers and library versions to the targeted modern Expo SDK layout without generating cascade system failures.
+
+## Step-by-Step Execution Protocol
+1. **Context Extraction:** Check `package.json` and `.agents/settings.json` to confirm current project dependencies and target thresholds.
+2. **Reference Audit:** Compare existing components against any files found in `.agents/reference/`. Identify breaking changes, deprecated hooks, and required config plugins before making code mutations.
+3. **Strict Live Verification:** Do not guess method arguments. If internet permissions are active, query `site:docs.expo.dev/versions/` appending the target SDK code to verify exact API shifts.
+4. **Isolated Incremental Assembly:** Modify files sequentially. Complete dependency resolution inside configuration files first, verify type parameters, and fix breaking interface adjustments step-by-step.

package/src/templates/mobile/react-native/rules/01-native-primitives.md

@@ -0,0 +1,18 @@
+# Rule: React Native Primitives
+
+1. **NO HTML Elements**:
+   - NEVER use HTML DOM elements like `<div>`, `<span>`, `<button>`, `<p>`, `<a>`, `<ul>`, `<li>`, or `<input>`.
+   - React Native does not use the browser DOM. Using web elements will crash the app instantly.
+
+2. **Core Components**:
+   - ALWAYS use React Native core components imported from `react-native`.
+   - Use `<View>` instead of `<div>`.
+   - Use `<Text>` instead of `<span>` or `<p>`. All strings MUST be wrapped in a `<Text>` component.
+   - Use `<Pressable>` or `<TouchableOpacity>` instead of `<button>`.
+   - Use `<TextInput>` instead of `<input>`.
+   - Use `<Image>` instead of `<img>` (and note that local images require `source={require('./path')}`, while remote require `source={{ uri: '...' }}`).
+   - Use `<ScrollView>` or `<FlatList>` for scrollable areas.
+
+3. **Event Handlers**:
+   - Do NOT use `onClick`. The correct prop for `<Pressable>` is `onPress`.
+   - Do NOT use `onChange` for text inputs. The correct prop for `<TextInput>` is `onChangeText`.

package/src/templates/mobile/react-native/rules/02-native-styling.md

@@ -0,0 +1,29 @@
+# Rule: Native Styling
+
+1. **No Web CSS Attributes**:
+   - Do NOT use web-specific CSS properties like `grid`, `float`, `display: block`, etc.
+   - Do NOT use string styles for dimensions like `width: "100px"`.
+
+2. **Unitless Pixels**:
+   - Layout dimensions and font sizes must use unitless values (e.g., `width: 100`, `fontSize: 16`). These represent logical pixels.
+   - Percentages are allowed as strings (e.g., `width: "100%"`).
+
+3. **Flexbox Architecture**:
+   - In React Native, `flexDirection` defaults to `"column"`. If you want items side-by-side, you MUST explicitly set `flexDirection: "row"`.
+   - `display: "flex"` is the default and only display type for Views.
+   - Use `justifyContent` and `alignItems` heavily for positioning.
+
+4. **StyleSheet**:
+   - ALWAYS use `StyleSheet.create` for defining component styles to ensure performance and avoid inline object recreation on every render.
+   - Example:
+     ```javascript
+     const styles = StyleSheet.create({
+       container: {
+         flex: 1,
+         justifyContent: 'center',
+         alignItems: 'center',
+         backgroundColor: '#fff',
+       }
+     });
+     ```
+   - Only use inline styles for values that change dynamically during render.

package/src/templates/mobile/react-native/rules/03-ios-android-builds.md

@@ -0,0 +1,14 @@
+# Rule: Native iOS & Android Builds
+
+In a bare React Native project, you must manage native dependencies meticulously.
+
+1. **iOS Dependencies (`pod install`)**:
+   - ANY time you install a new NPM package that includes native code (e.g., `react-native-device-info`, `react-native-reanimated`), you MUST remind the user to run `cd ios && pod install` (or `npx pod-install`).
+   - If an iOS build fails with a "module not found" error for a native module, the most likely solution is to run `pod install`.
+
+2. **Android Gradle Sync**:
+   - If a new native module is added, the Android project must be rebuilt.
+   - If weird caching issues occur in Android, propose running `cd android && ./gradlew clean`.
+
+3. **Avoid Manual Native Edits Unless Requested**:
+   - Do not manually edit `ios/Podfile`, `android/app/build.gradle`, `MainApplication.java`, or `AppDelegate.mm` unless the library's official documentation explicitly requires manual linking (which is rare in modern React Native due to autolinking).

package/src/templates/mobile/react-native/skills/native-linking.md

@@ -0,0 +1,27 @@
+# Skill: Native Module Linking & Troubleshooting
+
+## Context
+Use this skill when a user encounters build errors, native module crashes, or needs help installing a library with deep native hooks in a bare React Native app.
+
+## Execution Steps
+
+1. **Verify Autolinking**:
+   - React Native uses Autolinking by default for iOS and Android. 
+   - Check the `package.json` to ensure the library is installed.
+   - For iOS: Propose running `cd ios && pod install`. If the user is on an Apple Silicon Mac and encounters FFI errors, propose `arch -x86_64 pod install`.
+   - For Android: Propose running `cd android && ./gradlew clean`.
+
+2. **Manual Linking (Only if Autolinking Fails)**:
+   - Only propose manual changes to `settings.gradle` and `MainApplication.java` (Android) or `Podfile` (iOS) if the specific library documentation states that it does not support autolinking.
+
+3. **Clearing Caches**:
+   - The React Native packager (Metro) often caches aggressively. If JS changes aren't reflecting or weird module resolution errors occur, propose:
+     `npx react-native start --reset-cache`
+   - For a deeper clean, propose clearing Watchman watches:
+     `watchman watch-del-all`
+     `rm -rf node_modules && npm install`
+     `rm -rf $TMPDIR/metro-*`
+
+4. **Rebuilding**:
+   - Remind the user that after installing a native module, they CANNOT simply rely on fast refresh. They MUST recompile the app:
+     `npx react-native run-ios` OR `npx react-native run-android`

package/src/utils/fileSystem.js

@@ -72,6 +72,8 @@ async function writeSettings(agentsDir, settings) {
   // settings.json — committed to git
   const settingsJson = {
     projectName:      settings.projectName,
+    projectType:      settings.projectType || 'general',
+    framework:        settings.framework || null,
     agentiveVersion:  settings.agentiveVersion,
     createdAt:        settings.createdAt,
   };
@@ -120,31 +122,49 @@ async function writeSettings(agentsDir, settings) {
  * @param {string} templatesDir - Absolute path to src/templates/
  * @param {string} agentsDir    - Absolute path to .agents/
  * @param {string} projectName  - The user's project name
+ * @param {string} projectType  - e.g., 'general', 'web', 'mobile'
+ * @param {string} framework    - e.g., 'expo', 'react-native'
  */
-async function copyTemplates(templatesDir, agentsDir, projectName) {
+async function copyTemplates(templatesDir, agentsDir, projectName, projectType = 'general', framework = null) {
   const cwd = path.dirname(agentsDir);
 
-  // Copy AGENTS.md to project root
-  const agentMdSrc = path.join(templatesDir, 'AGENTS.md');
+  // 1. Copy AGENTS.md from base to project root
+  const agentMdSrc = path.join(templatesDir, 'base', 'AGENTS.md');
   try {
     let content = await fs.readFile(agentMdSrc, 'utf-8');
     content = replacePlaceholders(content, projectName);
     await fs.writeFile(path.join(cwd, 'AGENTS.md'), content, 'utf-8');
   } catch { /* template may not exist */ }
 
-  // Copy folder templates into .agents/
+  // 1.5 Copy aiignore from base to project root as .aiignore
+  const aiignoreSrc = path.join(templatesDir, 'base', 'aiignore');
+  try {
+    let content = await fs.readFile(aiignoreSrc, 'utf-8');
+    await fs.writeFile(path.join(cwd, '.aiignore'), content, 'utf-8');
+  } catch { /* template may not exist */ }
+
   const foldersToInclude = ['commands', 'skills', 'rules'];
-  for (const folder of foldersToInclude) {
-    const srcFolder = path.join(templatesDir, folder);
-    const destFolder = path.join(agentsDir, folder);
-
-    try {
-      await fs.access(srcFolder);
-    } catch {
-      continue;
+
+  // Helper to copy a specific template layer
+  const copyLayer = async (layerPath) => {
+    for (const folder of foldersToInclude) {
+      const srcFolder = path.join(layerPath, folder);
+      const destFolder = path.join(agentsDir, folder);
+      try {
+        await fs.access(srcFolder);
+        await copyDirectoryRecursive(srcFolder, destFolder, projectName);
+      } catch {
+        continue;
+      }
     }
+  };
+
+  // 2. Copy Base Layer
+  await copyLayer(path.join(templatesDir, 'base'));
 
-    await copyDirectoryRecursive(srcFolder, destFolder, projectName);
+  // 3. Copy Framework Layer (if applicable)
+  if (projectType !== 'general' && framework) {
+    await copyLayer(path.join(templatesDir, projectType, framework));
   }
 }