@p_tipso/agentive 1.0.0 → 1.0.2

package/README.md

@@ -1,127 +1,111 @@
-<![CDATA[<div align="center">
+<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 single `.agent/` directory in your project — your source of truth for agent rules and skills — and compiles it into the specific formats each AI tool understands.
+Stop maintaining separate rule files for every AI tool. **agentive** scaffolds a universal `.agents/` directory and an `AGENTS.md` file in your project — providing a **single source of truth** for all your agent commands, skills, and rules.
 
-## ✨ What it does
+## ✨ Why Agentive?
 
-1. **Scaffolds** a universal `.agent/` workspace in your project
-2. **Syncs** your `.agent/` files into the native formats of your chosen AI tools:
-   - 🖱 **Cursor** → `.cursor/rules/`
-   - 🤖 **Claude** → `CLAUDE.md`
-   - 🌊 **Windsurf** → `.windsurfrules`
+| Feature                       | Description                                                          |
+| :---------------------------- | :------------------------------------------------------------------- |
+| 🚀 **Zero Config**            | Run one command and get a fully structured workspace instantly.      |
+| 🌍 **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.   |
+| ⚡ **No Prompts**             | Just run it. No annoying interactive setup wizards to slow you down. |
 
 ---
 
-## 🚀 Quick Start
+## 📦 Installation & Usage
+
+Run one command, get a fully structured AI agent workspace instantly:
 
 ```bash
 npx @p_tipso/agentive
 ```
 
-The interactive wizard will ask you:
-1. **Project name** (pre-filled from your directory name)
-2. **Your primary tech stack** (e.g. "Next.js, TypeScript, Postgres")
-3. **Which AI tools** you use (multi-select: Cursor, Claude, Windsurf)
-
-Then it scaffolds everything automatically.
-
----
-
-## 📁 Output Structure
-
-After running `npx @p_tipso/agentive`, your project will have:
+If you prefer to install it globally for frequent usage:
 
-```
-your-project/
-├── .agent/
-│   ├── settings.json          ← project config (commit this)
-│   ├── settings.local.json    ← local overrides (gitignored automatically)
-│   ├── rules/
-│   │   └── architecture.md    ← project-wide rules for all agents
-│   └── skills/
-│       ├── web-browser.md         ← how agents should browse the web
-│       ├── data-extractor.md      ← how agents should extract data
-│       ├── data-transformer.md    ← how agents should transform data
-│       └── output-dispatcher.md   ← how agents should deliver output
-│
-│   ── (auto-synced based on your selection) ──
-│
-├── .cursor/rules/             ← if you selected Cursor
-├── CLAUDE.md                  ← if you selected Claude
-└── .windsurfrules             ← if you selected Windsurf
+```bash
+npm install -g @p_tipso/agentive
+agentive
 ```
 
-### `settings.json` example
+### CLI Commands
 
-```json
-{
-  "projectName": "my-app",
-  "techStack": "Next.js, TypeScript, PostgreSQL",
-  "tools": ["cursor", "claude"],
-  "agentiveVersion": "1.0.0",
-  "createdAt": "2026-07-05T12:00:00.000Z"
-}
-```
+| 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                          |
 
 ---
 
-## 📦 Commands
+## 🏗 What Happens Under the Hood?
 
-| Command | Description |
-|---|---|
-| `npx @p_tipso/agentive` | Run the setup wizard and scaffold your `.agent/` workspace |
-| `npx @p_tipso/agentive init` | Same as above (explicit subcommand) |
-| `npx @p_tipso/agentive --version` | Print the current version |
-| `npx @p_tipso/agentive --help` | Show available commands |
+When you run `agentive`, it detects your current directory and instantly scaffolds this structure:
 
----
-
-## 🛠 Install Globally (optional)
+```text
+your-project/
+├── AGENTS.md                      ← Root agent instructions
+├── .agents/
+│   ├── settings.json              ← Project config
+│   ├── settings.local.json        ← Local machine overrides (auto-gitignored)
+│   ├── commands/
+│   │   ├── 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
+│   └── rules/
+│       └── README.md              ← Guide: how to add rules
+```
 
-If you use this frequently, install it globally:
+### 📂 Folder Guide
 
-```bash
-npm install -g @p_tipso/agentive
-agentive
-```
+- **`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.
 
 ---
 
-## 🔄 Re-syncing
-
-Edited your `.agent/` files and want to push changes to Cursor, Claude, etc.? Just re-run:
+## 🤝 Contributing
 
-```bash
-npx @p_tipso/agentive
-```
+We love contributions! Whether it's adding new built-in skills, fixing bugs, or improving documentation, your help is appreciated.
 
-It will detect the existing `.agent/` directory and ask before overwriting.
+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,6 +1,6 @@
 {
   "name": "@p_tipso/agentive",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A universal, framework-agnostic AI agent repository setup CLI. Scaffold a .agent/ workspace and sync to Cursor, Claude, and Windsurf.",
   "license": "MIT",
   "author": "Pakawat Tipso",
@@ -33,7 +33,7 @@
     "type": "git",
     "url": "git+https://github.com/TiPS0/agentive.git"
   },
-  "homepage": "https://github.com/TiPS0/agentive#readme",
+  "homepage": "https://github.com/TiPS0/agentive",
   "bugs": {
     "url": "https://github.com/TiPS0/agentive/issues"
   },

package/src/commands/init.js

@@ -1,8 +1,8 @@
 'use strict';
 
 const path = require('path');
-const prompts = require('prompts');
 const chalk = require('chalk');
+const prompts = require('prompts');
 const { version } = require('../../package.json');
 const {
   createAgentDirectory,
@@ -10,138 +10,103 @@ const {
   agentDirectoryExists,
   writeSettings,
 } = require('../utils/fileSystem');
-const { syncToCursor, syncToClaude, syncToWindsurf } = require('../utils/compilers');
-
-const AI_TOOLS = [
-  { title: '🖱  Cursor',   value: 'cursor',   description: 'Generates .cursor/rules/' },
-  { title: '🤖  Claude',   value: 'claude',   description: 'Generates CLAUDE.md' },
-  { title: '🌊  Windsurf', value: 'windsurf', description: 'Generates .windsurfrules' },
-];
 
 async function runInit() {
   const cwd = process.cwd();
+  const projectName = path.basename(cwd);
 
   console.log('');
   console.log(chalk.bold.cyan('  🤖 agentive') + chalk.gray(' — Universal AI Agent Workspace Setup'));
   console.log(chalk.gray('  ─────────────────────────────────────────────'));
   console.log('');
 
-  // --- Guard: check if .agent/ already exists ---
+  // --- Guard: check if .agents/ already exists ---
   const alreadyExists = await agentDirectoryExists(cwd);
   if (alreadyExists) {
-    const { overwrite } = await prompts({
-      type: 'confirm',
-      name: 'overwrite',
-      message: chalk.yellow('A .agent/ directory already exists. Overwrite it?'),
-      initial: false,
-    });
-
-    if (!overwrite) {
-      console.log('');
-      console.log(chalk.gray('  Aborted. Your existing .agent/ directory was not modified.'));
-      console.log('');
-      process.exit(0);
-    }
+    console.log(chalk.yellow('  ⚠ ') + chalk.white('.agents/ already exists — skipping (no files were modified).'));
+    console.log(chalk.gray('  Delete .agents/ first if you want to re-scaffold.'));
+    console.log('');
+    process.exit(0);
   }
 
-  // --- Wizard ---
-  const projectName = path.basename(cwd);
+  console.log(chalk.gray('  Installing to: ') + chalk.white(cwd));
+  console.log('');
 
-  const answers = await prompts(
-    [
-      {
-        type: 'text',
-        name: 'projectName',
-        message: 'Project name?',
-        initial: projectName,
-        validate: (v) => v.trim().length > 0 || 'Required.',
-      },
-      {
-        type: 'text',
-        name: 'techStack',
-        message: 'Primary tech stack?',
-        placeholder: 'e.g. Next.js, TypeScript, PostgreSQL',
-        validate: (v) => v.trim().length > 0 || 'Required.',
-      },
-      {
-        type: 'multiselect',
-        name: 'tools',
-        message: 'Which AI tools do you want to target?',
-        choices: AI_TOOLS,
-        min: 1,
-        hint: '- Space to select. Return to submit',
-        instructions: false,
-      },
+  // --- 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' },
     ],
-    {
-      onCancel: () => {
-        console.log('');
-        console.log(chalk.gray('  Setup cancelled.'));
-        process.exit(0);
-      },
-    }
-  );
+    initial: 0,
+  });
 
-  const { tools, techStack } = answers;
-  const finalProjectName = answers.projectName;
+  if (!typeResponse.projectType) {
+    console.log(chalk.red('  ✖ ') + 'Setup cancelled.');
+    process.exit(1);
+  }
 
-  console.log('');
-  console.log(chalk.gray('  Setting up your workspace...'));
+  let framework = null;
+  if (typeResponse.projectType === 'mobile') {
+    const fwResponse = await prompts({
+      type: 'select',
+      name: 'framework',
+      message: 'Which framework are you using?',
+      choices: [
+        { title: 'Expo', 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 .agent/ directory ---
+  // --- Scaffold .agents/ directory ---
   const templatesDir = path.join(__dirname, '..', 'templates');
-  const agentDir = await createAgentDirectory(cwd, alreadyExists);
-  await copyTemplates(templatesDir, agentDir, techStack);
+  const agentsDir = await createAgentDirectory(cwd, false);
+  await copyTemplates(templatesDir, agentsDir, projectName, projectType, framework);
 
   // --- Write settings.json and settings.local.json ---
-  await writeSettings(agentDir, {
-    projectName: finalProjectName,
-    techStack,
-    tools,
+  await writeSettings(agentsDir, {
+    projectName,
+    projectType,
+    framework,
     agentiveVersion: version,
     createdAt: new Date().toISOString(),
   });
 
-  console.log(chalk.green('  ✔ ') + chalk.white('Scaffolded ') + chalk.cyan('.agent/') + chalk.white(' workspace'));
-
-  // --- Sync to selected tools ---
-  const compilers = {
-    cursor: syncToCursor,
-    claude: syncToClaude,
-    windsurf: syncToWindsurf,
-  };
-
-  const toolLabels = {
-    cursor:   '.cursor/rules/',
-    claude:   'CLAUDE.md',
-    windsurf: '.windsurfrules',
-  };
-
-  for (const tool of tools) {
-    try {
-      await compilers[tool](agentDir, cwd, techStack);
-      console.log(chalk.green('  ✔ ') + chalk.white('Synced → ') + chalk.cyan(toolLabels[tool]));
-    } catch (err) {
-      console.log(chalk.red('  ✘ ') + chalk.white(`Failed to sync ${tool}: `) + chalk.gray(err.message));
-    }
-  }
+  console.log(chalk.green('  ✔ ') + chalk.white('Created ') + chalk.cyan('AGENTS.md'));
+  console.log(chalk.green('  ✔ ') + chalk.white('Scaffolded ') + chalk.cyan('.agents/') + chalk.white(' workspace'));
 
   // --- Done ---
   console.log('');
   console.log(chalk.bold.green('  ✅ All done!'));
   console.log('');
-  console.log(chalk.white('  Your AI workspace is ready at ') + chalk.cyan('.agent/'));
+  console.log(chalk.white('  Your AI workspace is ready:'));
   console.log('');
-  console.log(chalk.gray('  Structure:'));
-  console.log(chalk.gray('    .agent/'));
-  console.log(chalk.gray('    ├── settings.json       ← project config (commit this)'));
-  console.log(chalk.gray('    ├── settings.local.json ← local overrides (gitignored)'));
-  console.log(chalk.gray('    ├── rules/              ← agent rules'));
-  console.log(chalk.gray('    └── skills/             ← agent skills'));
+  console.log(chalk.gray('    AGENTS.md                       ← root agent instructions'));
+  console.log(chalk.gray('    .agents/'));
+  console.log(chalk.gray('    ├── settings.json               ← project config'));
+  console.log(chalk.gray('    ├── settings.local.json         ← local overrides (gitignored)'));
+  console.log(chalk.gray('    ├── commands/'));
+  console.log(chalk.gray('    │   ├── review.md               ← code review command'));
+  console.log(chalk.gray('    │   └── fix-issue.md            ← zero-error fix command'));
+  console.log(chalk.gray('    ├── skills/'));
+  console.log(chalk.gray('    └── rules/'));
   console.log('');
-  console.log(chalk.gray('  Edit the markdown files in .agent/ to customise agent behaviour.'));
-  console.log(chalk.gray('  Re-run ') + chalk.cyan('npx @p_tipso/agentive') + chalk.gray(' any time to re-sync to your AI tools.'));
+  console.log(chalk.gray('  Edit the markdown files to customise agent behaviour.'));
   console.log('');
 }
 

package/src/templates/base/AGENTS.md

@@ -0,0 +1,29 @@
+# Agent Instructions
+
+> This file is your project's top-level instruction file for AI agents.
+> It is generated by [agentive](https://github.com/TiPS0/agentive).
+
+## Project
+
+- **Name:** {{PROJECT_NAME}}
+
+## Agent Configuration
+
+All agent configuration lives inside the `.agents/` directory:
+
+| Path | Purpose |
+|------|---------|
+| `.agents/settings.json` | Project-wide agent configuration (commit this) |
+| `.agents/settings.local.json` | Local machine overrides (gitignored) |
+| `.agents/commands/` | Reusable prompt commands your agents can execute |
+| `.agents/skills/` | Skill definitions that teach agents how to behave |
+| `.agents/rules/` | Project-wide rules all agents must follow |
+
+## Getting Started
+
+1. Edit the markdown files inside `.agents/` to customise agent behaviour
+2. Add new commands in `.agents/commands/` for common tasks
+3. Add new skills in `.agents/skills/` to teach agents new capabilities
+4. Add new rules in `.agents/rules/` to enforce coding standards
+
+Re-run `npx @p_tipso/agentive` any time to re-sync changes to your AI tools.

package/src/templates/base/commands/README.md

@@ -0,0 +1,26 @@
+# Commands
+
+This folder contains **reusable prompt commands** — predefined instructions that AI agents can execute on demand.
+
+## How to use
+
+Each `.md` file in this directory is a command. To use a command, reference it by name when prompting your AI agent.
+
+## Structure
+
+Each command file should include:
+
+- **Goal:** What the command achieves
+- **Steps:** The ordered steps the agent should follow
+- **Output:** What the agent should produce at the end
+
+## Examples
+
+| File | Purpose |
+|------|---------|
+| `review.md` | Review code for bugs, performance, and best practices |
+| `fix-issue.md` | Diagnose and fix code errors with zero tolerance |
+
+## Adding new commands
+
+Create a new `.md` file in this folder. Name it clearly (e.g., `write-tests.md`, `refactor.md`, `deploy-check.md`).

package/src/templates/base/commands/fix-issue.md

@@ -0,0 +1,41 @@
+# Command: Fix Issue (Zero Code Error)
+
+> Use this command to diagnose and fix code errors with zero tolerance — no errors should remain after execution.
+
+## Goal
+
+Find and fix **all** code errors in the target file or project. The end result must compile, run, and pass all existing tests with zero errors.
+
+## Steps
+
+1. **Identify the error** — read the error message, stack trace, or failing test output
+2. **Locate the root cause** — trace the error to its origin (don't just fix the symptom)
+3. **Understand the context** — read surrounding code to understand the intended behaviour
+4. **Implement the fix** — make the minimal change that resolves the root cause
+5. **Check for side effects** — ensure the fix doesn't break other functionality
+6. **Verify** — confirm the error is resolved by running the relevant command or test
+
+## Rules
+
+- **Never** suppress or silence errors without fixing the underlying cause
+- **Never** add `// @ts-ignore`, `eslint-disable`, or similar without explicit approval
+- **Prefer** targeted fixes over large refactors
+- **Always** explain what caused the error and why the fix resolves it
+
+## Output
+
+```
+### Error
+[Original error message or description]
+
+### Root Cause
+[Explanation of why this error occurred]
+
+### Fix Applied
+[Description of what was changed and where]
+
+### Verification
+[How the fix was verified — command run, test passed, etc.]
+
+### Status: ✅ Resolved
+```

package/src/templates/base/commands/review.md

@@ -0,0 +1,37 @@
+# Command: Review Code
+
+> Use this command to perform a thorough code review on a file, folder, or pull request.
+
+## Goal
+
+Review the target code for correctness, performance, readability, and adherence to project conventions.
+
+## Steps
+
+1. **Read** the target code carefully from start to finish
+2. **Check for bugs** — logic errors, off-by-one errors, null/undefined handling, race conditions
+3. **Check for performance** — unnecessary re-renders, N+1 queries, missing indexes, memory leaks
+4. **Check for security** — injection vulnerabilities, exposed secrets, missing auth checks
+5. **Check for readability** — naming, function length, comment quality, dead code
+6. **Check for conventions** — does the code follow the rules defined in `.agents/rules/`?
+
+## Output
+
+Provide a structured review with:
+
+```
+### Summary
+One-sentence verdict (e.g., "Generally solid, 2 bugs found")
+
+### Issues Found
+- 🐛 **Bug:** [description] (file:line)
+- ⚡ **Performance:** [description] (file:line)
+- 🔒 **Security:** [description] (file:line)
+
+### Suggestions
+- 💡 [optional improvement]
+
+### Verdict
+- [ ] Ready to merge
+- [ ] Needs changes (see issues above)
+```

package/src/templates/base/rules/README.md

@@ -0,0 +1,29 @@
+# Rules
+
+This folder contains **project-wide rules** — constraints and standards that all AI agents must follow when working in this repository.
+
+## How to use
+
+Each `.md` file in this directory defines a set of rules. Agents will read and adhere to these rules for every task they perform.
+
+## Structure
+
+Each rule file should include:
+
+- **Purpose:** Why this rule exists
+- **Rules:** The specific constraints, listed clearly
+- **Examples:** Good vs. bad patterns (optional but recommended)
+
+## Examples of rules you could add
+
+| File | Purpose |
+|------|---------|
+| `code-style.md` | Naming conventions, formatting, and patterns |
+| `architecture.md` | How the project is structured, what goes where |
+| `testing.md` | Testing requirements, coverage expectations |
+| `security.md` | Security practices, data handling rules |
+| `git.md` | Branch naming, commit messages, PR conventions |
+
+## Adding new rules
+
+Create a new `.md` file in this folder. Name it after the topic (e.g., `error-handling.md`, `performance.md`).

package/src/templates/base/skills/README.md

@@ -0,0 +1,29 @@
+# Skills
+
+This folder contains **skill definitions** — instructions that teach AI agents how to behave in specific roles or capabilities.
+
+## How to use
+
+Each `.md` file in this directory defines a skill. The agent will adopt the role described in the skill file when activated.
+
+## Structure
+
+Each skill file should include:
+
+- **Role description:** What the agent does in this role
+- **Responsibilities:** Specific tasks the agent handles
+- **Inputs / Outputs:** What the agent expects and what it produces
+- **Constraints:** Boundaries the agent must respect
+
+## Examples of skills you could add
+
+| File | Purpose |
+|------|---------|
+| `web-browser.md` | How agents should browse the web and retrieve data |
+| `data-extractor.md` | How agents should extract structured data from raw content |
+| `code-writer.md` | How agents should write new code following project conventions |
+| `tester.md` | How agents should write and run tests |
+
+## Adding new skills
+
+Create a new `.md` file in this folder. Name it after the role (e.g., `api-designer.md`, `database-manager.md`).

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.