@p_tipso/agentive 1.0.2 → 1.1.0

package/README.md

@@ -20,16 +20,16 @@
 
 ---
 
-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.
+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                                                          |
 | :---------------------------- | :------------------------------------------------------------------- |
-| 🚀 **Zero Config**            | Run one command and get a fully structured workspace instantly.      |
+| 🚀 **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.   |
-| ⚡ **No Prompts**             | Just run it. No annoying interactive setup wizards to slow you down. |
+| ⚡ **Dynamic Layering**     | Scaffolds base rules and safely merges framework-specific guardrails. |
 
 ---
 
@@ -52,7 +52,9 @@ agentive
 
 | Command                           | Description                                                  |
 | :-------------------------------- | :----------------------------------------------------------- |
-| `npx @p_tipso/agentive`           | Scaffold `.agents/` workspace instantly in current directory |
+| `npx @p_tipso/agentive init`      | Scaffold `.agents/` workspace instantly in current directory |
+| `npx @p_tipso/agentive install <pkg>`| Install an agent skill or rule from the registry (alias: `add`) |
+| `npx @p_tipso/agentive remove <pkg>` | Remove an installed skill or rule (alias: `rm`)              |
 | `npx @p_tipso/agentive --version` | Print the current CLI version                                |
 | `npx @p_tipso/agentive --help`    | Show available commands and options                          |
 
@@ -60,11 +62,12 @@ agentive
 
 ## 🏗 What Happens Under the Hood?
 
-When you run `agentive`, it detects your current directory and instantly scaffolds this structure:
+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
+├── .aiignore                      ← Hides irrelevant files from AI to save tokens
 ├── .agents/
 │   ├── settings.json              ← Project config
 │   ├── settings.local.json        ← Local machine overrides (auto-gitignored)
@@ -78,12 +81,16 @@ your-project/
 │       └── README.md              ← Guide: how to add rules
 ```
 
-### 📂 Folder Guide
+### 📂 File & Folder Guide
 
+- **`.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.
 
+### 🌟 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.
+
 ---
 
 ## 🤝 Contributing

package/bin/index.js

@@ -20,4 +20,22 @@ program
     await runInit();
   });
 
+program
+  .command('install <package>')
+  .alias('add')
+  .description('Install a skill or rule from the registry')
+  .action(async (packageName) => {
+    const { runInstall } = require('../src/commands/install');
+    await runInstall(packageName);
+  });
+
+program
+  .command('remove <package>')
+  .alias('rm')
+  .description('Remove an installed skill or rule')
+  .action(async (packageName) => {
+    const { runRemove } = require('../src/commands/remove');
+    await runRemove(packageName);
+  });
+
 program.parse(process.argv);

package/package.json

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

@@ -57,7 +57,7 @@ async function runInit() {
       name: 'framework',
       message: 'Which framework are you using?',
       choices: [
-        { title: 'Expo', value: 'expo' },
+        { title: 'Expo (Recommended)', value: 'expo' },
         { title: 'React Native', value: 'react-native' },
       ],
       initial: 0,
@@ -88,6 +88,7 @@ async function runInit() {
   });
 
   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 ---
@@ -97,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/commands/install.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+const fs = require('fs/promises');
+const { agentDirectoryExists, addDependency, linkAgentFile } = require('../utils/fileSystem');
+
+// A simple regex to parse YAML frontmatter block at the start of a string
+const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+
+function parseFrontmatter(content) {
+  const match = content.match(frontmatterRegex);
+  const metadata = {};
+  if (match && match[1]) {
+    const lines = match[1].split('\n');
+    lines.forEach(line => {
+      const parts = line.split(':');
+      if (parts.length >= 2) {
+        const key = parts[0].trim();
+        const value = parts.slice(1).join(':').trim().replace(/^['"](.*)['"]$/, '$1');
+        metadata[key] = value;
+      }
+    });
+  }
+  return { metadata, rawMatch: match ? match[0] : '' };
+}
+
+async function runInstall(packageName) {
+  const cwd = process.cwd();
+
+  console.log('');
+  console.log(chalk.bold.cyan('  🤖 agentive') + chalk.gray(' — Installing Package'));
+  console.log(chalk.gray('  ─────────────────────────────────────────────'));
+  console.log('');
+
+  const exists = await agentDirectoryExists(cwd);
+  if (!exists) {
+    console.log(chalk.red('  ✖ ') + 'No .agents/ directory found. Run `npx agentive init` first.');
+    process.exit(1);
+  }
+
+  if (!packageName) {
+    console.log(chalk.red('  ✖ ') + 'Please specify a package to install.');
+    process.exit(1);
+  }
+
+  console.log(chalk.gray(`  Fetching ${packageName}...`));
+
+  let fileContent = '';
+  try {
+    let url = packageName;
+    if (!url.startsWith('http')) {
+      // Mock registry URL for demonstration
+      url = `https://raw.githubusercontent.com/TiPS0/agentive-registry/main/packages/${packageName}.md`;
+    }
+    
+    // Attempt fetch
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch from registry (Status: ${response.status})`);
+    }
+    fileContent = await response.text();
+  } catch (err) {
+    console.log(chalk.yellow('  ⚠ ') + `Fetch failed: ${err.message}`);
+    console.log(chalk.gray('  Creating a mock package for demonstration...'));
+    fileContent = `---
+name: ${packageName}
+type: skill
+version: 1.0.0
+description: A mock skill for ${packageName}
+---
+# ${packageName}
+This is a generated placeholder skill because the registry could not be reached.
+`;
+  }
+
+  const { metadata } = parseFrontmatter(fileContent);
+  const type = metadata.type || 'skill';
+  const name = metadata.name || packageName;
+  const version = metadata.version || '1.0.0';
+  
+  // Pluralize type for folder name (skill -> skills, rule -> rules)
+  const folderName = type.endsWith('s') ? type : `${type}s`;
+  const agentsDir = path.join(cwd, '.agents');
+  const targetFolder = path.join(agentsDir, folderName);
+  const targetFile = path.join(targetFolder, `${packageName}.md`);
+  
+  try {
+    await fs.mkdir(targetFolder, { recursive: true });
+    await fs.writeFile(targetFile, fileContent, 'utf-8');
+    
+    await addDependency(agentsDir, packageName, version, type);
+    await linkAgentFile(cwd, `.agents/${folderName}/${packageName}.md`, `[${type.toUpperCase()}] ${name}`);
+    
+    console.log(chalk.green('  ✔ ') + `Successfully installed ${chalk.cyan(name)} v${version}`);
+    console.log(chalk.gray(`      Location: .agents/${folderName}/${packageName}.md`));
+  } catch (err) {
+    console.log(chalk.red('  ✖ ') + `Failed to write file: ${err.message}`);
+    process.exit(1);
+  }
+  console.log('');
+}
+
+module.exports = { runInstall };

package/src/commands/remove.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+const fs = require('fs/promises');
+const { agentDirectoryExists, removeDependency, readSettings, unlinkAgentFile } = require('../utils/fileSystem');
+
+async function runRemove(packageName) {
+  const cwd = process.cwd();
+
+  console.log('');
+  console.log(chalk.bold.cyan('  🤖 agentive') + chalk.gray(' — Removing Package'));
+  console.log(chalk.gray('  ─────────────────────────────────────────────'));
+  console.log('');
+
+  const exists = await agentDirectoryExists(cwd);
+  if (!exists) {
+    console.log(chalk.red('  ✖ ') + 'No .agents/ directory found.');
+    process.exit(1);
+  }
+
+  if (!packageName) {
+    console.log(chalk.red('  ✖ ') + 'Please specify a package to remove.');
+    process.exit(1);
+  }
+
+  const agentsDir = path.join(cwd, '.agents');
+  const settings = await readSettings(agentsDir);
+  
+  if (!settings || !settings.dependencies || !settings.dependencies[packageName]) {
+    console.log(chalk.yellow('  ⚠ ') + `Package '${packageName}' is not installed in settings.json.`);
+  }
+
+  let type = 'skill';
+  let name = packageName;
+  if (settings && settings.dependencies && settings.dependencies[packageName]) {
+    type = settings.dependencies[packageName].type || 'skill';
+    name = settings.dependencies[packageName].name || packageName;
+  }
+
+  const folderName = type.endsWith('s') ? type : `${type}s`;
+  const targetFile = path.join(agentsDir, folderName, `${packageName}.md`);
+
+  try {
+    await fs.rm(targetFile, { force: true });
+    const removedFromSettings = await removeDependency(agentsDir, packageName);
+    await unlinkAgentFile(cwd, `.agents/${folderName}/${packageName}.md`, `[${type.toUpperCase()}] ${name}`);
+    
+    if (removedFromSettings) {
+      console.log(chalk.green('  ✔ ') + `Successfully removed ${chalk.cyan(packageName)}`);
+    } else {
+      console.log(chalk.green('  ✔ ') + `Deleted file for ${chalk.cyan(packageName)}`);
+    }
+  } catch (err) {
+    console.log(chalk.red('  ✖ ') + `Failed to remove: ${err.message}`);
+  }
+  console.log('');
+}
+
+module.exports = { runRemove };

package/src/templates/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/utils/fileSystem.js

@@ -136,6 +136,13 @@ async function copyTemplates(templatesDir, agentsDir, projectName, projectType =
     await fs.writeFile(path.join(cwd, 'AGENTS.md'), content, 'utf-8');
   } catch { /* template may not exist */ }
 
+  // 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'];
 
   // Helper to copy a specific template layer
@@ -196,10 +203,104 @@ async function copyDirectoryRecursive(src, dest, projectName) {
     }
   }
 }
+// ─── Package Manager Utilities ────────────────────────────────────────────────
+
+/**
+ * Read the settings.json file.
+ */
+async function readSettings(agentsDir) {
+  try {
+    const content = await fs.readFile(path.join(agentsDir, 'settings.json'), 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update the settings.json file.
+ */
+async function updateSettings(agentsDir, newSettings) {
+  await fs.writeFile(
+    path.join(agentsDir, 'settings.json'),
+    JSON.stringify(newSettings, null, 2) + '\n',
+    'utf-8'
+  );
+}
+
+/**
+ * Add a dependency to settings.json
+ */
+async function addDependency(agentsDir, packageName, version, type = 'skill') {
+  const settings = await readSettings(agentsDir);
+  if (!settings) return false;
+  if (!settings.dependencies) settings.dependencies = {};
+  settings.dependencies[packageName] = { version, type };
+  await updateSettings(agentsDir, settings);
+  return true;
+}
+
+/**
+ * Remove a dependency from settings.json
+ */
+async function removeDependency(agentsDir, packageName) {
+  const settings = await readSettings(agentsDir);
+  if (!settings) return false;
+  if (settings.dependencies && settings.dependencies[packageName]) {
+    delete settings.dependencies[packageName];
+    await updateSettings(agentsDir, settings);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Link a downloaded agent file into AGENTS.md
+ */
+async function linkAgentFile(cwd, relativePath, title) {
+  const agentMdPath = path.join(cwd, 'AGENTS.md');
+  try {
+    let content = await fs.readFile(agentMdPath, 'utf-8');
+    const linkStr = `- [${title}](${relativePath})`;
+    if (!content.includes(linkStr)) {
+      content += `\n${linkStr}\n`;
+      await fs.writeFile(agentMdPath, content, 'utf-8');
+    }
+  } catch (err) {
+    // AGENTS.md might not exist
+  }
+}
+
+/**
+ * Unlink a removed agent file from AGENTS.md
+ */
+async function unlinkAgentFile(cwd, relativePath, title) {
+  const agentMdPath = path.join(cwd, 'AGENTS.md');
+  try {
+    let content = await fs.readFile(agentMdPath, 'utf-8');
+    const linkStr = `- [${title}](${relativePath})`;
+    if (content.includes(linkStr)) {
+      content = content.replace(new RegExp(`\\n?${escapeRegex(linkStr)}\\n?`, 'g'), '\n');
+      await fs.writeFile(agentMdPath, content, 'utf-8');
+    }
+  } catch (err) {
+    // AGENTS.md might not exist
+  }
+}
+
+function escapeRegex(string) {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 
 module.exports = {
   agentDirectoryExists,
   createAgentDirectory,
   writeSettings,
   copyTemplates,
+  readSettings,
+  updateSettings,
+  addDependency,
+  removeDependency,
+  linkAgentFile,
+  unlinkAgentFile,
 };