@p_tipso/agentive 1.1.0 → 1.1.2

package/README.md

@@ -99,17 +99,12 @@ We love contributions! Whether it's adding new built-in skills, fixing bugs, or
 
 Please read our [Contributing Guide](CONTRIBUTING.md) to get started with setting up your local environment and submitting a Pull Request.
 
+
 ---
 
 ## ⭐ Star History
 
-<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>
+[![Star History Chart](https://raw.githubusercontent.com/TiPS0/agentive/star-tracker/star-tracker.svg)](https://star-history.com/#TiPS0/agentive&Date)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p_tipso/agentive",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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",

package/src/commands/init.js

@@ -39,7 +39,7 @@ async function runInit() {
     message: 'What type of project are you building?',
     choices: [
       { title: 'General / Universal', value: 'general' },
-      { title: 'Web Development', value: 'web', disabled: true },
+      { title: 'Web Development', value: 'web' },
       { title: 'Mobile Development', value: 'mobile' },
     ],
     initial: 0,
@@ -51,18 +51,35 @@ async function runInit() {
   }
 
   let framework = null;
-  if (typeResponse.projectType === 'mobile') {
+  if (typeResponse.projectType === 'web') {
+    const fwResponse = await prompts({
+      type: 'select',
+      name: 'framework',
+      message: 'Which framework are you using?',
+      choices: [
+        { title: 'Next.js', value: 'nextjs' },
+        { title: 'Nuxt', value: 'nuxt' },
+      ],
+      initial: 0,
+    });
+
+    if (!fwResponse.framework) {
+      console.log(chalk.red('  ✖ ') + 'Setup cancelled.');
+      process.exit(1);
+    }
+    framework = fwResponse.framework;
+  } else 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' },
+        { title: 'React Native', value: 'react-native', disabled: true },
       ],
       initial: 0,
     });
-    
+
     if (!fwResponse.framework) {
       console.log(chalk.red('  ✖ ') + 'Setup cancelled.');
       process.exit(1);

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

@@ -4,26 +4,51 @@ This folder contains **skill definitions** — instructions that teach AI agents
 
 ## 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.
+Each skill lives in its **own subfolder**, named after the skill. The folder must contain a `SKILL.md` file as its entry point.
 
-## Structure
+```
+.agents/skills/
+├── route-groups-setup/
+│   └── SKILL.md
+├── create-expo-app/
+│   └── SKILL.md
+└── my-custom-skill/
+    └── SKILL.md
+```
 
-Each skill file should include:
+IDE and CLI tools that support slash-commands will autocomplete the folder name, then load the `SKILL.md` inside it (e.g., typing `/route-groups-setup` activates that skill).
 
-- **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
+## SKILL.md Structure
 
-## Examples of skills you could add
+Each `SKILL.md` file must include a YAML frontmatter block at the top:
 
-| File | Purpose |
+```markdown
+---
+name: my-skill-name
+description: A short description of what this skill does.
+version: 1.0.0
+---
+
+# Skill instructions go here...
+```
+
+- **`name`** and **`description`** are required — they are used for skill discovery and autocomplete matching.
+- The body (below the frontmatter) contains the actual instructions the agent follows when the skill is activated.
+
+## Skill Folder Layout
+
+A skill folder can include optional subdirectories for more complex skills:
+
+| Path | 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 |
+| `SKILL.md` | *(Required)* Main instructions with YAML frontmatter |
+| `scripts/` | Helper scripts the agent can run |
+| `examples/` | Reference implementations or usage patterns |
+| `resources/` | Templates, assets, or additional files |
+| `references/` | Extra documentation the agent can read on demand |
 
 ## Adding new skills
 
-Create a new `.md` file in this folder. Name it after the role (e.g., `api-designer.md`, `database-manager.md`).
+1. Create a new folder under `.agents/skills/` named after your skill (e.g., `api-designer/`)
+2. Add a `SKILL.md` file inside it with the required frontmatter
+3. Describe the agent's role, responsibilities, and constraints in the body

package/src/templates/base/skills/route-groups-setup/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: route-groups-setup
+description: Guidelines for enforcing the Route Groups pattern across modern file-based routing frameworks (Next.js, Expo Router, Nuxt).
+version: 1.1.0
+updated_at: 2026-07-10
+---
+
+# Modern File-Based Routing Guidelines
+
+**CRITICAL INSTRUCTION FOR AI AGENTS**: When working with modern meta-frameworks (e.g., **Next.js**, **Expo Router**, or **Nuxt**) in this workspace, you must enforce a clean routing structure using **Route Groups**. This applies regardless of the specific framework or version.
+
+## Route Groups Context
+
+Route Groups (directories named with parentheses, like `(tabs)`, `(auth)`, or `(marketing)`) allow you to organize files and share layouts without adding a segment to the URL path.
+
+As projects grow, a flat file-based routing structure can quickly become messy and hard to maintain. To prevent this, the modern standard is to use Route Groups to keep the routing directory organized, modular, and clean.
+
+## The Standard Routing Pattern
+
+You must strictly enforce the following rules for routing:
+
+### 1. Structural Requirements
+
+- **Root Directory**: The routing root is `app/` or `src/app/` (Next.js App Router, Expo Router). _Note: These rules do not apply to the legacy Next.js `pages/` router._
+- **Global Layouts**: Base files like `index.tsx`, `page.tsx`, `_layout.tsx`, `layout.tsx`, and `+not-found.tsx` MUST remain at the root of the routing directory.
+- **Top-Level Feature Modules**: ALL distinct top-level feature modules or screen sections MUST be wrapped in parentheses `()` to form a Route Group.
+  - **DO NOT** create flat static directories at the root level (e.g., `app/profile/index.tsx`).
+  - **DO** create Route Group directories for top-level features (e.g., `app/(profile)/index.tsx`).
+  - _Note: Normal static folders are completely fine INSIDE a Route Group when you specifically need to add a URL segment._
+- **Consistency**: Ensure that layouts and screens for a specific feature are contained entirely within their respective Route Group directory.
+
+#### ⚠️ Critical Rule — Route Groups Are Invisible in the URL
+
+Route Groups `(name)` are **completely ignored** in the final URL path. They exist purely for layout organization. This has a critical implication for dynamic routes:
+
+- **DO NOT** place two dynamic segments at the same URL depth using nested Route Groups.
+  - ❌ `app/(shop)/[storeId].tsx` + `app/(shop)/(product)/[productId].tsx` → **Both resolve to `/:id` — URL collision!**
+- **DO** chain dynamic segments directly by nesting them, or use static folders to separate them.
+  - ✅ `app/(shop)/[storeId]/[productId]/page.tsx` → URLs: `/:storeId` and `/:storeId/:productId`
+
+### 2. Folder Naming Conventions (Quick Matrix)
+
+You must understand the exact differences between folder types to construct valid routes:
+
+| Folder Pattern | URL Impact           | Type              | Best Used For                                                            |
+| -------------- | -------------------- | ----------------- | ------------------------------------------------------------------------ |
+| `(groupName)/` | **None (Hidden)**    | **Route Group**   | Organizing code by feature or sharing layouts (e.g., `(auth)`)           |
+| `folderName/`  | Exact Match          | **Static Route**  | Fixed pages with hardcoded URLs (e.g., `dashboard`, `shop`)              |
+| `[paramName]/` | Variable Placeholder | **Dynamic Route** | Dynamic data pages matching IDs or slugs (e.g., `[userId]`, `[storeId]`) |
+
+### 3. The Purpose of Layout Files (`_layout.tsx` / `layout.tsx`)
+
+Layout files are crucial in Route Groups. Even though the Route Group folder `(groupName)` is invisible in the URL, the routing framework relies on the `_layout.tsx` file inside it to know _how_ to render the screens it contains.
+
+**Why it is needed:**
+Without a layout file (`_layout.tsx` in Expo returning a `<Stack />`, or `layout.tsx` in Next.js returning `{children}`), the framework won't know how to render the screens or provide navigation between them (e.g., it won't know how to slide screens in or provide a back button).
+
+**Advanced Use Cases:**
+
+1. **Shared Context Providers**: If you build a state manager that only applies to specific screens (e.g., `<ShopStateProvider>`), wrap it inside `(shop)/layout.tsx` so it doesn't degrade performance for the rest of the app.
+2. **Auth Guards**: You can enforce security at the folder level. Checking `if (!isAuthenticated)` inside `(dashboard)/layout.tsx` instantly protects every screen inside the dashboard folder (like the profile page).
+3. **Shared UI**: Use the layout file to inject a custom header, footer, or navigation bar that applies to every screen in that specific Route Group.
+
+### 4. Example Valid Directory Tree
+
+```text
+app/ (or src/app/)
+├── _layout.tsx (or layout.tsx)
+├── index.tsx (or page.tsx)
+│
+├── (auth)/                          ← Route Group: shared auth layout
+│   ├── _layout.tsx (or layout.tsx)
+│   └── login.tsx                    → URL: /login
+│
+├── (tabs)/                          ← Route Group: tab bar layout
+│   ├── _layout.tsx (or layout.tsx)
+│   ├── dashboard.tsx                → URL: /dashboard
+│   └── shop.tsx                     → URL: /shop  (tab entry point)
+│
+├── (dashboard)/                     ← Route Group: dashboard layout
+│   ├── _layout.tsx (or layout.tsx)
+│   └── profile.tsx                  → URL: /profile
+│
+└── (shop)/                          ← Route Group: shared shop layout (URL-invisible)
+    ├── _layout.tsx (or layout.tsx)
+    └── [storeId]/                   ← Dynamic folder → URL: /:storeId
+        ├── index.tsx (or page.tsx)  → URL: /123
+        └── [productId]/             ← Nested dynamic folder → URL: /:storeId/:productId
+            └── index.tsx (or page.tsx) → URL: /123/456
+```
+
+**How the shop flow works:**
+
+1. `(tabs)/shop.tsx` → the tab that shows the store list (`/shop`)
+2. User selects a store → navigates to `(shop)/[storeId]/index.tsx` → URL: `/123`
+3. User selects a product → navigates to `(shop)/[storeId]/[productId]/index.tsx` → URL: `/123/456`
+
+The `(shop)` Route Group provides a **shared layout** (e.g., a back-button header) for both the store and product screens, without polluting the URL.
+
+**Important File Naming Note:**
+When using dynamic folders like `[storeId]`, always name the main entry file `index.tsx` (Expo Router) or `page.tsx` (Next.js). Do NOT name the file `storeId.tsx` inside the `[storeId]` folder, as that would result in an awkward URL like `/123/storeId`.
+
+## Required Agent Workflow for Routing Tasks
+
+Whenever you are asked to create, modify, or debug routes/screens, you must execute these steps:
+
+1. **Identify the Framework**: Check `package.json` to determine if the project uses Next.js, Expo, Remix, or Nuxt, and note the correct file naming conventions (`page.tsx`, `index.tsx`, `index.vue`).
+2. **Verify the Structure**: Check the `app/` or `src/app/` directory to understand the existing root.
+3. **Enforce Route Groups**: Ensure that top-level feature modules are created exclusively inside parentheses `(group_name)`. You are FORBIDDEN from creating new standard flat folder routes directly at the root of `app/` (e.g., `app/home/`).
+4. **Refactor if Necessary**: If you encounter an existing flat routing structure at the root (e.g., `app/home/`), you MUST transition it to the standard Route Group pattern (e.g., `app/(home)/`) before adding new features.

package/src/utils/fileSystem.js

@@ -42,8 +42,6 @@ async function createAgentDirectory(cwd, overwrite = false) {
 
   if (overwrite) {
     await fs.rm(agentsDir, { recursive: true, force: true });
-    // Also remove old AGENTS.md if overwriting
-    try { await fs.rm(path.join(cwd, 'AGENTS.md'), { force: true }); } catch { /* noop */ }
   }
 
   await fs.mkdir(agentsDir, { recursive: true });
@@ -130,10 +128,21 @@ async function copyTemplates(templatesDir, agentsDir, projectName, projectType =
 
   // 1. Copy AGENTS.md from base to project root
   const agentMdSrc = path.join(templatesDir, 'base', 'AGENTS.md');
+  const targetAgentMdPath = path.join(cwd, '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');
+    
+    let finalContent = content;
+    try {
+      const existingContent = await fs.readFile(targetAgentMdPath, 'utf-8');
+      if (existingContent.trim()) {
+        // Prepend the new template content to the existing content
+        finalContent = content + '\n\n' + existingContent;
+      }
+    } catch { /* target may not exist, that's fine */ }
+
+    await fs.writeFile(targetAgentMdPath, finalContent, 'utf-8');
   } catch { /* template may not exist */ }
 
   // 1.5 Copy aiignore from base to project root as .aiignore