agents.dev 1.0.5 → 1.0.6

package/README.md

@@ -1,132 +1,44 @@
-# 🤖 Agents.dev
-
-**The "Package Manager" for AI Agents.**
-Agents.dev is a CLI tool that defines a standard Squad of AI Developers and installs them directly into your favorite AI Coding Assistant contexts (Gemini, Roo Code, Kilo Code, OpenCode).
-
-Stop prompting from scratch. Install a proven workflow.
-
-## 🚀 Quick Start
-
-### Prerequisites
-- Node.js 18+
-- An AI Coding Assistant (e.g., Google IDX with Gemini, VSCode with Roo Code)
-
-### Installation & Usage
-
-**Option 1: Direct Install (Recommended)**
-Install globally or in your project:
-```bash
-npx agents.dev
-# OR
-npm install agents.dev
-agents-install
-```
-
-**Option 2: From Source**
-1. Clone the repo:
-   ```bash
-   git clone https://github.com/your-username/agents.dev.git
-   cd agents.dev
-   ```
-2. Install & Run:
-   ```bash
-   npm install
-   npm start
-   ```
-
-### First Run
-Run the **init** command to start the configuration Wizard:
-```bash
-agents.dev init
-# OR with npx
-npx agents.dev init
-```
-
-The Wizard will guide you through:
-1.  **Select OS**: Windows or Unix.
-2.  **Select Targets**: Choose formats to build (Gemini, Roo, etc.).
-3.  **Docs Auto-Gen**: It automatically creates `docs/` and a workflow guide.
-
----
-
-## 👥 The Squad (Agent Functions)
-
-The system works best when you follow this pipeline. Each agent saves their "Brain" in the `docs/` folder, which serves as context for the next agent.
-
-### 🏗️ 1. Project Architect
-**"The Visionary"**  
-Transforms your raw idea into a professional specification. It acts as an interviewer to discover hidden requirements.
-- **Trigger:** `/dev.project "I want a Uber clone for dog walking"`
-- **Action:** Asks clarifying questions about features, target audience, and constraints.
-- **Output:** `docs/project.md` (Scope, User Stories, Core Principles).
-
-### 🧱 2. Requirements Engineer
-**"The Tech Lead"**  
-Decides *how* to build it. Defines the stack, database schema, and technical boundaries based on the Spec.
-- **Trigger:** `/dev.requirements`
-- **Action:** Selects libraries (e.g., "Prisma vs TypeORM"), defines API contracts, and security rules.
-- **Output:** `docs/requirements.md` (The "Technical Contract" that the Coder must obey).
-
-### 🗺️ 3. Milestone Manager
-**"The Strategist"**  
-Prevents you from trying to build everything at once. Slices the project into logical "MVPs" (Phases).
-- **Trigger:** `/dev.milestone`
-- **Output:** `docs/milestones.md` (e.g., Phase 1: Auth, Phase 2: Payment, Phase 3: GPS).
-
-### 📋 4. Task Planner
-**"The Project Manager"**  
-Takes **ONE Milestone** and breaks it down into atomic, bite-sized tasks for the AI Coder.
-- **Reasoning:** AI Coders hallucinate less when the context is small.
-- **Trigger:** `/dev.tasks 1` (Plan Milestone 1)
-- **Output:** `docs/task.md` (A checklist of 5-10 specific file operations).
-
-### 🕵️ 5. Auditor
-**"The Gatekeeper"**  
-A safety check before you start coding. It reads the **Requirements** and the **Task Plan** to ensure nothing was lost in translation.
-- **Trigger:** `/dev.auditor`
-- **Action:** "Hey, you planned the Login UI but forgot the 'Forgot Password' flow mentioned in Requirements."
-- **Output:** `audit_report.md` (Pass/Fail).
-
-### 💻 6. Coder
-**"The Senior Developer"**  
-The workhorse. It executes ONE task from the checklist at a time.
-- **Features:**
-    - **Context Aware:** Reads `project.md` to know "Project Principles" (e.g., "Use Functional Components").
-    - **Safety:** Checks `.gitignore` before creating files.
-    - **TDD:** Can write tests before code if requested.
-- **Trigger:** `/dev.coder 1.1` (Implement Task 1.1)
-- **Output:** Writes code to `src/` and logs to `work_log.md`.
-
-### ⚖️ 7. QA Engineer
-**"The Reviewer"**  
-Simulates a Pull Request review. It checks if the code matches the Requirements contracts.
-- **Trigger:** `/dev.review 1.1`
-- **Action:** Reads the code and the `requirements.md`. If variables are named poorly or logic is insecure, it REJECTS the task.
-
-### 📦 8. Release Manager
-**"The Historian"**  
-Consolidates the messy daily `work_log.md` into a clean `CHANGELOG`.
-- **Trigger:** `/dev.log`
-
----
-
-## 🛠️ On-Demand Toolkit
-
-### 🏗️ DevOps Engineer (`/dev.ops`)
-**"The Config Specialist"**  
-Don't waste token context on config files during feature dev. Call this agent specifically for:
-- "Create a Dockerfile for this Node structure"
-- "Setup Github Actions for tests"
-- "Configure ESLint and Prettier"
-
----
-
-## 🎯 Supported Targets
-
-- **Gemini CLI** (`.gemini/commands/*.toml`)
-- **Roo Code** (`.roo/commands/*.md`)
-- **Kilo Code** (`.kilocode/workflows/*.md`)
-- **OpenCode** (`.opencode/command/*.md`)
-
-## 📄 Documentation
-During installation, the CLI automatically generates a `docs/README.md` guide inside your project, explaining exactly how to chain these commands for the perfect workflow.
+# agents-dev (Universal Spec CLI)
+
+Ferramenta CLI para configurar automaticamente o ambiente de desenvolvimento e instalar agentes de IA (Auditor, Coder, etc.) para diversas ferramentas como Gemini CLI, Roo Code, Cline e Kilo Code.
+
+## Funcionalidades
+
+### 1. Instalação de Agentes de IA
+Lê definições agnósticas (YAML) e converte para formatos específicos:
+*   **Gemini CLI:** Gera arquivos de configuração `.toml`.
+*   **Roo Code / Cline:** Gera modos customizados (`_custom_modes.json`).
+*   **Kilo Code:** Gera prompts em Markdown (`.kilo/prompts/*.md`).
+
+### 2. Configuração
+Automatiza a criação de arquivos de configuração necessários para integrar agentes de IA ao seu fluxo de trabalho.
+
+## Instalação e Uso
+
+Você pode executar a ferramenta diretamente via `npx` sem instalação prévia:
+
+```bash
+npx agents-dev
+```
+
+Ou instalar globalmente:
+
+```bash
+npm install -g agents-dev
+agents-dev
+```
+
+## Como funciona
+
+1.  Execute `npx agents-dev` na raiz do seu projeto.
+2.  A interface interativa perguntará quais configurações você deseja aplicar.
+3.  Os arquivos de configuração dos agentes serão gerados na pasta do seu projeto.
+
+## Estrutura do Projeto
+
+*   `src/`: Código fonte da CLI.
+*   `definitions/`: Definições YAML dos agentes (agnósticas).
+
+## Licença
+
+MIT

package/definitions/dev.coder.yaml

@@ -1,60 +1,60 @@
-name: Coder
-role: Senior Software Engineer (Implementation)
-emoji: 💻
-systemPrompt: |
-  # SYSTEM ROLE & IDENTITY
-  You are the **Senior Software Engineer**.
-  You do not just "write code". You **architect solutions** at the file level.
-  You follow **SOLID** principles and **Clean Code** standards.
-  Your goal is to implement the task from `task.md` with **Zero Regression**.
-
-  # INPUT CONTEXT
-  1. **Mandatory:** Read `docs/task.md` (The Task).
-  2. **Mandatory:** Read `docs/requirements.md` (The Stack & Rules).
-  3. **Mandatory:** Read `docs/project.md` (The Principles).
-
-  # EXECUTION WORKFLOW
-
-  ## PHASE 1: ANALYSIS & SAFETY
-  1.  **Scope Verification:** asking yourself "What files do I need to touch?".
-      -   *Constraint:* Do NOT touch unrelated files.
-  2.  **Environment Check:**
-      -   Check if `.gitignore` exists. If not, create it.
-      -   Check if tests exists.
-
-  ## PHASE 2: IMPLEMENTATION
-  1.  **Code:** Implement the feature following the "Project Principles" from `project.md`.
-  2.  **Test (Conditional):** 
-      -   **IF** `requirements.md` mandates tests: Create/Update tests to verify your changes.
-      -   **IF** strict TDD is requested in principles: Write tests *before* code.
-
-  ## PHASE 3: SELF-CORRECTION
-  1.  **Build/Lint:** Run the compiler/linter.
-      -   *If Error:* Fix it immediately. Do not ask user.
-  2.  **Test:** Run the tests.
-      -   *If Fail:* Fix the code.
-
-  ## PHASE 4: REPORTING
-  1.  **Update task.md:** Mark the task as `[x]`.
-  2.  **Log Work:** Append to `work_log.md`.
-
-  # OUTPUT STRUCTURE (work_log.md - Append)
-  ---
-  **[DATE] Task:** [ID] | **Status:** [Completed]
-  **Changes:**
-  - Created `src/components/Button.tsx`
-  - Updated `src/utils/helpers.ts`
-  **Self-Check:**
-  - [x] Linter Passed
-  - [x] Tests Passed (if applicable)
-  ---
-
-  # INSTRUCTION
-  Read the context. Execute the task using the Workflow. Report in `work_log.md`.
-rules:
-  - "**SINGLE FILE:** Never create files like `report_task_1.md`. Everything goes to `work_log.md`."
-  - "**CLEANUP:** Keep `work_log.md` concise."
-  - "**ENV SAFETY:** Before writing code in a new folder, check if `.gitignore` exists."
-  - "**NO BROKEN WINDOWS:** Leave the code better than you found it. Fix linter errors you caused."
-  - "**STRICT SCOPE:** Only edit files related to the specific Task ID."
-  - "Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language."
+name: Coder
+role: Senior Software Engineer (Implementation)
+emoji: 💻
+systemPrompt: |
+  # SYSTEM ROLE & IDENTITY
+  You are the **Senior Software Engineer**.
+  You do not just "write code". You **architect solutions** at the file level.
+  You follow **SOLID** principles and **Clean Code** standards.
+  Your goal is to implement the task from `task.md` with **Zero Regression**.
+
+  # INPUT CONTEXT
+  1. **Mandatory:** Read `docs/task.md` (The Task).
+  2. **Mandatory:** Read `docs/requirements.md` (The Stack & Rules).
+  3. **Mandatory:** Read `docs/project.md` (The Principles).
+
+  # EXECUTION WORKFLOW
+
+  ## PHASE 1: ANALYSIS & SAFETY
+  1.  **Scope Verification:** asking yourself "What files do I need to touch?".
+      -   *Constraint:* Do NOT touch unrelated files.
+  2.  **Environment Check:**
+      -   Check if `.gitignore` exists. If not, create it.
+      -   Check if tests exists.
+
+  ## PHASE 2: IMPLEMENTATION
+  1.  **Code:** Implement the feature following the "Project Principles" from `project.md`.
+  2.  **Test (Conditional):** 
+      -   **IF** `requirements.md` mandates tests: Create/Update tests to verify your changes.
+      -   **IF** strict TDD is requested in principles: Write tests *before* code.
+
+  ## PHASE 3: SELF-CORRECTION
+  1.  **Build/Lint:** Run the compiler/linter.
+      -   *If Error:* Fix it immediately. Do not ask user.
+  2.  **Test:** Run the tests.
+      -   *If Fail:* Fix the code.
+
+  ## PHASE 4: REPORTING
+  1.  **Update task.md:** Mark the task as `[x]`.
+  2.  **Log Work:** Append to `work_log.md`.
+
+  # OUTPUT STRUCTURE (work_log.md - Append)
+  ---
+  **[DATE] Task:** [ID] | **Status:** [Completed]
+  **Changes:**
+  - Created `src/components/Button.tsx`
+  - Updated `src/utils/helpers.ts`
+  **Self-Check:**
+  - [x] Linter Passed
+  - [x] Tests Passed (if applicable)
+  ---
+
+  # INSTRUCTION
+  Read the context. Execute the task using the Workflow. Report in `work_log.md`.
+rules:
+  - "**SINGLE FILE:** Never create files like `report_task_1.md`. Everything goes to `work_log.md`."
+  - "**CLEANUP:** Keep `work_log.md` concise."
+  - "**ENV SAFETY:** Before writing code in a new folder, check if `.gitignore` exists."
+  - "**NO BROKEN WINDOWS:** Leave the code better than you found it. Fix linter errors you caused."
+  - "**STRICT SCOPE:** Only edit files related to the specific Task ID."
+  - "Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language."

package/package.json

@@ -1,46 +1,40 @@
 {
-  "name": "agents.dev",
-  "version": "1.0.5",
-  "description": "",
-  "main": "dist/index.js",
-  "bin": {
-    "agents.dev": "./dist/index.js",
-    "agents-install": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "definitions"
-  ],
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "start": "npx ts-node src/index.ts",
-    "build": "tsc",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "agents",
-    "ai",
-    "cli",
-    "workflow"
-  ],
-  "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"
-  }
+    "name": "agents.dev",
+    "version": "1.0.6",
+    "description": "Instalador automático dos agentes de desenvolvimento",
+    "main": "src/index.js",
+    "bin": {
+        "agents.dev": "./src/index.js"
+    },
+    "scripts": {
+        "start": "node src/index.js",
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "dependencies": {
+        "@clack/prompts": "^0.7.0",
+        "js-yaml": "^4.1.0",
+        "picocolors": "^1.0.0",
+        "zod": "^4.2.1"
+    },
+    "author": "",
+    "license": "MIT",
+    "files": [
+        "src",
+        "definitions",
+        "README.md"
+    ],
+    "keywords": [
+        "ai",
+        "agents",
+        "cli",
+        "dev-tools",
+        "llm",
+        "gemini",
+        "roo-code",
+        "cline"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/filipeoliveira93/agents.dev"
+    }
 }

package/src/index.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { intro, outro, multiselect, select, spinner, note } = require('@clack/prompts');
+const pc = require('picocolors');
+
+// Módulos Internos
+const { AgentSchema } = require('./lib/schema');
+const { toGeminiTOML, toRooConfig, toKiloMarkdown } = require('./lib/transformers');
+const { generateWorkflowGuide } = require('./lib/docs');
+
+async function main() {
+    console.clear();
+    intro(pc.bgMagenta(pc.white(' UNIVERSAL SPEC CLI ')));
+
+    // 1. Seleção de Componentes
+    const components = await multiselect({
+        message: 'O que você deseja configurar?',
+        options: [
+            { value: 'docs', label: 'Gerar Documentação de Workflow (docs/README.md)', hint: 'Essencial' },
+            { value: 'agents', label: 'Instalar Agentes de IA', hint: 'Recomendado' },
+            { value: 'vscode', label: 'Configurar VS Code', hint: '(Simulado)' },
+        ],
+        required: true,
+    });
+
+    if (!components) {
+        outro('Operação cancelada.');
+        process.exit(0);
+    }
+
+    // 2. Instalação de Documentação
+    if (components.includes('docs')) {
+        const created = generateWorkflowGuide(process.cwd());
+        if (created) {
+            note('Documentação criada em docs/README.md', 'Docs');
+        } else {
+            console.log(pc.gray('ℹ️  Pasta docs/ já existe. Ignorando criação.'));
+        }
+    }
+
+    // 3. Instalação de Agentes
+    if (components.includes('agents')) {
+        const tool = await select({
+            message: 'Onde você deseja instalar os Agentes?',
+            options: [
+                { value: 'gemini', label: 'Gemini CLI', hint: '.gemini/commands/dev' },
+                { value: 'roo', label: 'Roo Code', hint: 'Gera roo_custom_modes.json' },
+                { value: 'cline', label: 'Cline', hint: 'Gera cline_custom_modes.json' },
+                { value: 'kilo', label: 'Kilo Code', hint: '.kilo/prompts/*.md' },
+            ],
+        });
+
+        if (!tool) process.exit(0);
+
+        await processAgentsInstallation(tool);
+    }
+
+    outro(pc.green('Configuração concluída com sucesso! 🚀'));
+}
+
+async function processAgentsInstallation(tool) {
+    const s = spinner();
+    s.start('Carregando definições...');
+
+    const definitionsDir = path.join(__dirname, '..', 'definitions');
+    if (!fs.existsSync(definitionsDir)) {
+        s.stop('Falha');
+        note(`Pasta de definições não encontrada: ${definitionsDir}`, 'Erro Fatal');
+        return;
+    }
+
+    const files = fs.readdirSync(definitionsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+    const validAgents = [];
+
+    // Validação e Carregamento
+    for (const file of files) {
+        try {
+            const content = fs.readFileSync(path.join(definitionsDir, file), 'utf8');
+            const raw = yaml.load(content);
+            
+            // Validação com Zod
+            const parsed = AgentSchema.safeParse(raw);
+            if (!parsed.success) {
+                console.warn(pc.yellow(`⚠️  Ignorando ${file}: Inválido`));
+                continue;
+            }
+
+            const agent = parsed.data;
+            agent.slug = file.replace(/\.ya?ml$/, '').replace(/\./g, '-'); // dev.coder -> dev-coder
+            validAgents.push(agent);
+
+        } catch (e) {
+            console.error(pc.red(`Erro ao ler ${file}: ${e.message}`));
+        }
+    }
+
+    s.message(`Instalando ${validAgents.length} agentes para ${tool}...`);
+
+    // Instalação Específica por Ferramenta
+    try {
+        if (tool === 'gemini') {
+            const targetDir = path.join(process.cwd(), '.gemini', 'commands', 'dev');
+            if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+
+            for (const agent of validAgents) {
+                const toml = toGeminiTOML(agent);
+                // Nome original com pontos (dev.coder.toml) é preferível para Gemini CLI
+                const fileName = `${agent.slug.replace(/-/g, '.')}.toml`; 
+                fs.writeFileSync(path.join(targetDir, fileName), toml);
+            }
+        } 
+        else if (tool === 'roo' || tool === 'cline') {
+            const modes = validAgents.map(agent => toRooConfig(agent, agent.slug));
+            const jsonContent = JSON.stringify({ customModes: modes }, null, 2);
+            const fileName = `${tool}_custom_modes.json`;
+            fs.writeFileSync(path.join(process.cwd(), fileName), jsonContent);
+            note(`Copie o conteúdo de '${fileName}' para as configurações da extensão.`, 'Ação Manual');
+        } 
+        else if (tool === 'kilo') {
+            const targetDir = path.join(process.cwd(), '.kilo', 'prompts');
+            if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+
+            for (const agent of validAgents) {
+                const md = toKiloMarkdown(agent);
+                fs.writeFileSync(path.join(targetDir, `${agent.slug}.md`), md);
+            }
+        }
+        s.stop('Instalação finalizada!');
+
+    } catch (e) {
+        s.stop('Falha');
+        console.error(pc.red(e.message));
+    }
+}
+
+main().catch(console.error);

package/src/lib/docs.js

@@ -0,0 +1,97 @@
+const fs = require('fs');
+const path = require('path');
+const pc = require('picocolors');
+
+/**
+ * Gera o guia de workflow do projeto
+ */
+function generateWorkflowGuide(baseDir) {
+    const docsDir = path.join(baseDir, 'docs');
+    
+    // Conteúdo baseado no exemplo provided
+    const content = `# 🤖 Agent Workflow Guide
+
+Este documento descreve o fluxo de desenvolvimento padrão usando os Agentes instalados.
+O sistema segue um processo **Waterfall** para planejamento (precisão) e **Iterativo** para execução.
+
+---
+
+## 1. 🏗️ Project Spec (@Project Architect)
+**Role:** O Visionário.
+**Goal:** Traduzir sua ideia vaga em uma Especificação concreta com "Project Principles" definidos.
+- **Comando:** \
+/dev:project "Eu quero um App de Todo que..."
+- **Saída:** 
+`docs/project.md`
+
+## 2. 🧱 Requirements Engineering (@Requirements Engineer)
+**Role:** O Tech Lead.
+**Goal:** Fechar decisões técnicas (Stack, Banco de Dados, Libs).
+- **Why?** Evita que o Coder "invente" arquitetura. Cria o "Contrato".
+- **Comando:** 
+/dev:requirements
+- **Saída:** 
+`docs/requirements.md`
+
+## 3. 🗺️ Roadmap Strategy (@Milestone Manager)
+**Role:** O Estrategista.
+**Goal:** Fatiar o projeto em fases de entrega (MVPs).
+- **Comando:** 
+/dev:milestone
+- **Saída:** 
+`docs/milestones.md`
+
+## 4. 📋 Task Planning (@Task Planner)
+**Role:** O Gerente.
+**Goal:** Quebrar um Milestone específico em tarefas atômicas para desenvolvedores.
+- **Why?** IAs falham com contextos gigantes. Tarefas pequenas = Código perfeito.
+- **Comando:** 
+/dev:tasks <Milestone_ID>
+- **Saída:** 
+`docs/task.md`
+
+## 5. 🕵️ Blueprint Audit (@Auditor)
+**Role:** O Guardião.
+**Goal:** Validar consistência entre **Requirements** e **Tasks**.
+- **Comando:** 
+/dev:auditor
+- **Saída:** 
+`audit_report.md`
+
+## 6. 💻 Implementation (@Coder)
+**Role:** O Construtor.
+**Goal:** Executar *uma tarefa por vez* do arquivo 
+`task.md`.
+- **Comando:** 
+/dev:coder <Task_ID>
+- **Buffer:** 
+`work_log.md`
+
+## 7. ⚖️ Quality Assurance (@QA Engineer)
+**Role:** O Inspetor.
+**Goal:** Verificar se a implementação bate com os Requisitos.
+- **Comando:** 
+/dev:review <Task_ID>
+- **Saída:** 
+`docs/logs/review_log.md`
+
+## 8. 📦 Release Management (@Release Manager)
+**Role:** O Historiador.
+**Goal:** Consolidar o 
+`work_log.md` em um 
+`changelog.md` permanente.
+- **Comando:** 
+/dev:log
+- **Saída:** 
+`changelog.md`
+`;
+
+    if (!fs.existsSync(docsDir)) {
+        fs.mkdirSync(docsDir, { recursive: true });
+        fs.writeFileSync(path.join(docsDir, 'README.md'), content);
+        return true;
+    }
+    return false;
+}
+
+module.exports = { generateWorkflowGuide };

package/src/lib/schema.js

@@ -0,0 +1,13 @@
+const { z } = require('zod');
+
+const AgentSchema = z.object({
+  name: z.string().min(1, "Nome é obrigatório"),
+  role: z.string().min(1, "Papel (Role) é obrigatório"),
+  emoji: z.string().optional().default('🤖'),
+  systemPrompt: z.string().min(10, "System Prompt deve ter pelo menos 10 caracteres"),
+  rules: z.array(z.string()).optional().default([]),
+  tools: z.array(z.string()).optional().default([]),
+  description: z.string().optional()
+});
+
+module.exports = { AgentSchema };