agents.dev 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# Agents.dev
+
+**Agents.dev** is a CLI tool that acts as a "Source of Truth" for your AI Development Agents.
+Inspired by tools like *Specify*, it allows you to define your agent personas in a single, agnostic YAML format and "compile" them into configuration files for various AI coding assistants.
+
+## 🚀 Supported Targets
+
+The CLI currently installs agents directly into the configuration paths for:
+
+- **Gemini CLI**: `.gemini/commands/dev/`
+- **Roo Code**: `.roo/commands/`
+- **Kilo Code**: `.kilocode/workflows/`
+- **OpenCode**: `.opencode/command/`
+
+## 📦 Installation
+
+This project is designed to be run as a dev dependency or a local tool within your repository.
+
+```bash
+npm install
+```
+
+## 🛠️ Usage
+
+### 1. Define your Agents
+Create YAML files in the `definitions/` directory.
+
+**Example:** `definitions/backend-architect.yaml`
+```yaml
+name: Backend Architect
+role: Senior Backend Engineer
+emoji: 🏗️
+systemPrompt: |
+  You are a Senior Backend Engineer.
+  You specialize in Scalable Node.js APIs.
+rules:
+  - Always write unit tests.
+  - Use snake_case for database columns.
+```
+
+### 2. Build/Install
+Run the start command to convert your YAMLs into target configurations.
+
+**Interactive Mode:**
+```bash
+npm start
+```
+*Select which targets you want to update using the interactive menu.*
+
+**CLI Mode (CI/CD friendly):**
+```bash
+npm start -- --target gemini,roo
+```
+
+## ✅ Validation
+The CLI includes Zod validation to ensure your definitions are complete.
+Required fields:
+- `name`
+- `role`
+- `systemPrompt` (min 10 characters)
+
+## 📂 Project Structure
+```text
+.
+├── definitions/       # Your Source of Truth (YAML)
+├── src/               # CLI Source Code
+├── .gemini/           # Generated Gemini Commands
+├── .roo/              # Generated Roo Contexts
+├── .kilocode/         # Generated Kilo Workflows
+└── .opencode/         # Generated OpenCode Commands
+```

package/definitions/backend-architect.yaml

@@ -0,0 +1,12 @@
+name: Backend Architect
+role: Senior Backend Engineer specializes in scalable APIs
+emoji: 🏗️
+systemPrompt: |
+  You are a Senior Backend Engineer. Your goal is to design and implement scalable, robust, and secure backend systems.
+  You prefer Node.js with TypeScript or Python with FastAPI.
+  You always consider performance implications.
+rules:
+  - Follow RESTful API design principles.
+  - Use environment variables for secrets.
+  - Write unit tests for all business logic.
+  - Document API endpoints.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agents.dev",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "npx ts-node src/index.ts build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "@types/inquirer": "^9.0.9",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "fs-extra": "^11.3.2",
+    "inquirer": "^8.2.7",
+    "user": "^0.0.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.0.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,140 @@
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'path';
+import YAML from 'yaml';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { AgentDefinition, AgentSchema } from './types';
+import { toGeminiSystemPrompt } from './transformers/gemini';
+import { toRooRules } from './transformers/roo';
+import { toKiloConfig } from './transformers/kilo';
+import { toOpenCodeCommand } from './transformers/opencode';
+
+const program = new Command();
+
+program
+  .name('agents')
+  .description('Agent Installer CLI')
+  .version('1.0.0');
+
+program
+  .command('build')
+  .description('Build agent definitions into target formats')
+  .option('-o, --out <dir>', 'Output directory', '.')
+  .option('-t, --target <targets>', 'Comma-separated target formats (gemini, roo, kilo, opencode)')
+  .action(async (options) => {
+    const definitionsDir = path.join(process.cwd(), 'definitions');
+    const outDir = path.resolve(options.out);
+
+    // Determine targets
+    let selectedTargets: string[] = [];
+    if (options.target) {
+      selectedTargets = options.target.split(',').map((t: string) => t.trim().toLowerCase());
+    } else {
+      const answers = await inquirer.prompt([
+        {
+          type: 'checkbox',
+          name: 'targets',
+          message: 'Select target formats to build:',
+          choices: [
+            { name: 'Gemini CLI', value: 'gemini', checked: true },
+            { name: 'Roo Code', value: 'roo', checked: false },
+            { name: 'Kilo Code', value: 'kilo', checked: false },
+            { name: 'OpenCode', value: 'opencode', checked: false }
+          ],
+          validate: (answer) => {
+            if (answer.length < 1) {
+              return 'You must choose at least one target.';
+            }
+            return true;
+          }
+        }
+      ]);
+      selectedTargets = answers.targets;
+    }
+
+    if (selectedTargets.length === 0) {
+      console.log(chalk.yellow('No targets selected. Exiting.'));
+      return;
+    }
+
+    console.log(chalk.blue(`Building agents from ${definitionsDir} to ${outDir}...`));
+    console.log(chalk.blue(`Targets: ${selectedTargets.join(', ')}`));
+
+    try {
+      if (outDir !== process.cwd()) {
+          await fs.ensureDir(outDir);
+      }
+      
+      const files = await fs.readdir(definitionsDir);
+      
+      for (const file of files) {
+        if (!file.endsWith('.yaml') && !file.endsWith('.yml')) continue;
+
+        const content = await fs.readFile(path.join(definitionsDir, file), 'utf-8');
+        const rawAgent = YAML.parse(content);
+        const parseResult = AgentSchema.safeParse(rawAgent);
+
+        if (!parseResult.success) {
+           console.error(chalk.red(`Validation failed for ${file}:`));
+           parseResult.error.issues.forEach((err) => {
+             console.error(chalk.red(`  - ${err.path.join('.')}: ${err.message}`));
+           });
+           continue; // Skip this agent
+        }
+
+        const agent = parseResult.data;
+        const slug = file.replace(/\.(yaml|yml)$/, '');
+
+        console.log(chalk.green(`Processing agent: ${agent.name} (${slug})`));
+
+        // specific outputs
+        const allTargets = [
+          {
+            id: 'gemini',
+            subDir: '.gemini/commands/dev',
+            ext: 'md',
+            content: toGeminiSystemPrompt(agent),
+            name: `${slug}.md`
+          },
+          {
+            id: 'roo',
+            subDir: '.roo/commands',
+            ext: 'md',
+            content: toRooRules(agent),
+            name: `${slug}.md`
+          },
+          {
+            id: 'kilo',
+            subDir: '.kilocode/workflows',
+            ext: 'md',
+            content: toKiloConfig(agent),
+            name: `${slug}.md`
+          },
+          {
+            id: 'opencode',
+            subDir: '.opencode/command',
+            ext: 'md',
+            content: toOpenCodeCommand(agent),
+            name: `${slug}.md`
+          }
+        ];
+
+        const targetsToBuild = allTargets.filter(t => selectedTargets.includes(t.id));
+
+        for (const target of targetsToBuild) {
+          const targetDir = path.join(outDir, target.subDir);
+          await fs.ensureDir(targetDir);
+          await fs.writeFile(path.join(targetDir, target.name), target.content);
+          console.log(chalk.gray(`  -> ${target.subDir}/${target.name}`));
+        }
+      }
+      console.log(chalk.bold.green('Build complete!'));
+      
+    } catch (err) {
+      console.error(chalk.red('Build failed:'), err);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/src/transformers/gemini.ts

@@ -0,0 +1,31 @@
+import { AgentDefinition } from '../types';
+
+export function toGeminiSystemPrompt(agent: AgentDefinition): string {
+  const parts = [];
+
+  // Identity
+  parts.push(`# Identity\n`);
+  parts.push(`You are **${agent.name}** ${agent.emoji || ''}`);
+  parts.push(`Role: ${agent.role}\n`);
+
+  // System Prompt
+  parts.push(`# Core Instructions\n`);
+  parts.push(agent.systemPrompt.trim());
+  parts.push('\n');
+
+  // Rules
+  if (agent.rules && agent.rules.length > 0) {
+    parts.push(`# Rules & Guidelines\n`);
+    agent.rules.forEach(rule => parts.push(`- ${rule}`));
+    parts.push('\n');
+  }
+
+  // Tools (if any)
+  if (agent.tools && agent.tools.length > 0) {
+    parts.push(`# Preferred Tools\n`);
+    agent.tools.forEach(tool => parts.push(`- ${tool}`));
+    parts.push('\n');
+  }
+
+  return parts.join('\n');
+}

package/src/transformers/kilo.ts

@@ -0,0 +1,21 @@
+import { AgentDefinition } from '../types';
+
+export function toKiloConfig(agent: AgentDefinition): string {
+  // Kilo Code generic config/prompt
+  const parts = [];
+
+  parts.push(`<!--- Kilo Code Agent Config --->`);
+  parts.push(`# ${agent.name} ${agent.emoji || ''}`);
+  parts.push(`**Role**: ${agent.role}\n`);
+
+  parts.push(`## Instructions`);
+  parts.push(agent.systemPrompt.trim());
+  parts.push('\n');
+
+  if (agent.rules && agent.rules.length > 0) {
+    parts.push(`## Constraints`);
+    agent.rules.forEach(rule => parts.push(`- ${rule}`));
+  }
+
+  return parts.join('\n');
+}

package/src/transformers/opencode.ts

@@ -0,0 +1,21 @@
+import { AgentDefinition } from '../types';
+
+export function toOpenCodeCommand(agent: AgentDefinition): string {
+  // OpenCode generic config/prompt
+  const parts = [];
+
+  parts.push(`<!--- OpenCode Agent Config --->`);
+  parts.push(`# ${agent.name} ${agent.emoji || ''}`);
+  parts.push(`**Role**: ${agent.role}\n`);
+
+  parts.push(`## Instructions`);
+  parts.push(agent.systemPrompt.trim());
+  parts.push('\n');
+
+  if (agent.rules && agent.rules.length > 0) {
+    parts.push(`## Constraints`);
+    agent.rules.forEach(rule => parts.push(`- ${rule}`));
+  }
+
+  return parts.join('\n');
+}

package/src/transformers/roo.ts

@@ -0,0 +1,23 @@
+import { AgentDefinition } from '../types';
+
+export function toRooRules(agent: AgentDefinition): string {
+  // Roo Code / Cline usually expects a clear set of rules and role definition.
+  const parts = [];
+
+  parts.push(`# ${agent.name} (${agent.role})`);
+  parts.push(`\n${agent.systemPrompt.trim()}\n`);
+
+  if (agent.rules && agent.rules.length > 0) {
+    parts.push(`## Analytical Rules & Guidelines`);
+    agent.rules.forEach(rule => parts.push(`- ${rule}`));
+    parts.push('\n');
+  }
+
+  // Tools might be handled differently in Roo, but listing them as preferences is safe
+  if (agent.tools && agent.tools.length > 0) {
+    parts.push(`## Tool Usage Preferences`);
+    agent.tools.forEach(tool => parts.push(`- Prefer using ${tool} when applicable.`));
+  }
+
+  return parts.join('\n');
+}

package/src/types.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const AgentSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  role: z.string().min(1, "Role is required"),
+  emoji: z.string().optional(),
+  systemPrompt: z.string().min(10, "System prompt must be at least 10 characters"),
+  rules: z.array(z.string()).optional(),
+  tools: z.array(z.string()).optional()
+});
+
+export type AgentDefinition = z.infer<typeof AgentSchema>;

package/test-inquirer.ts

@@ -0,0 +1,19 @@
+import inquirer from 'inquirer';
+
+(async () => {
+  console.log('Testing inquirer checkbox...');
+  const answers = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'targets',
+      message: 'Select target formats:',
+      choices: [
+        { name: 'Gemini CLI', value: 'gemini', checked: true },
+        { name: 'Roo Code', value: 'roo', checked: true },
+        { name: 'Kilo Code', value: 'kilo', checked: true },
+        { name: 'OpenCode', value: 'opencode', checked: true }
+      ]
+    }
+  ]);
+  console.log('Selected:', answers.targets);
+})();

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}