grimoire-framework 1.0.18 → 1.0.20

package/.grimoire/install-manifest.yaml

@@ -7,8 +7,8 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.0.18
-generated_at: "2026-02-22T14:00:42.557Z"
+version: 1.0.20
+generated_at: "2026-02-22T14:39:48.383Z"
 generator: scripts/generate-install-manifest.js
 file_count: 1011
 files:

package/bin/commands/agent.js

@@ -0,0 +1,216 @@
+/**
+ * grimoire agent — Agent Management CLI
+ *
+ * Commands:
+ *   grimoire agent create    — interative wizard to create a custom agent
+ *   grimoire agent list      — alias for grimoire agents list
+ *   grimoire agent edit <n>  — open agent in $EDITOR
+ *   grimoire agent remove <n>— delete a custom agent
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+// ── Personas catalogue for the wizard ─────────────────────────────────────────
+const BASE_AGENTS = [
+    { id: 'dev', icon: '🎨', name: 'Da Vinci', specialty: 'Full-Stack Development' },
+    { id: 'qa', icon: '🖌️', name: 'Dürer', specialty: 'Quality Assurance' },
+    { id: 'architect', icon: '🏛️', name: 'Gaudí', specialty: 'System Architecture' },
+    { id: 'analyst', icon: '🔍', name: 'Vermeer', specialty: 'Research & Analysis' },
+    { id: 'grimoire-master', icon: '👑', name: 'Michelangelo', specialty: 'Orchestration' },
+];
+
+const ICON_OPTIONS = ['🎭', '🎪', '🌟', '⚡', '🔮', '🦊', '🐉', '🌊', '🔥', '🌙', '🎯', '🗡️', '🧙', '🎸', '🦅'];
+
+// ── Template generator ─────────────────────────────────────────────────────────
+function generateAgentTemplate({ id, name, icon, specialty, baseAgent, description }) {
+    const base = BASE_AGENTS.find(a => a.id === baseAgent);
+    const baseRef = base ? `Based on ${base.name} (${base.id})` : 'Custom Agent';
+
+    return `# ${id}
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
+
+CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
+
+## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
+
+\`\`\`yaml
+activation-instructions:
+  - STEP 1: Read THIS ENTIRE FILE to understand your persona
+  - STEP 2: Adopt the ${name} persona completely
+  - STEP 3: Present your greeting to the user
+  - STEP 4: HALT and await user input
+  - STAY IN CHARACTER until user types *exit
+
+agent:
+  name: ${name}
+  id: ${id}
+  title: ${specialty}
+  icon: ${icon}
+  base: ${baseRef}
+  whenToUse: ${description}
+
+persona:
+  role: ${specialty} Specialist
+  style: Collaborative and focused on ${specialty.toLowerCase()}
+  identity: ${name} — ${description}
+
+greeting_levels:
+  default: |
+    ${icon} **${name}** (${id}) pronto!
+    Especialidade: **${specialty}**
+
+    Como posso ajudar?
+
+commands:
+  - "*help  — Show available commands"
+  - "*exit  — Exit agent mode"
+
+signature_closing: '— ${name} ${icon}'
+\`\`\`
+`;
+}
+
+// ── Prompt helpers (without @clack/prompts dependency) ─────────────────────────
+const readline = require('readline');
+
+function prompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        rl.question(question, answer => { rl.close(); resolve(answer.trim()); });
+    });
+}
+
+async function select(question, options) {
+    console.log(`\n${question}`);
+    options.forEach((opt, i) => console.log(`  ${i + 1}. ${opt.label || opt}`));
+    const answer = await prompt('  Escolha (número): ');
+    const idx = parseInt(answer) - 1;
+    if (idx >= 0 && idx < options.length) return options[idx].value || options[idx];
+    return options[0].value || options[0];
+}
+
+// ── Commands ───────────────────────────────────────────────────────────────────
+async function run(args) {
+    const sub = args[0];
+    switch (sub) {
+        case 'create': await createWizard(); break;
+        case 'edit': await editAgent(args[1]); break;
+        case 'remove':
+        case 'delete': await removeAgent(args[1]); break;
+        case 'list':
+        default: listAgents(); break;
+    }
+}
+
+function listAgents() {
+    const cwd = process.cwd();
+    const agentsDir = path.join(cwd, '.codex', 'agents');
+    if (!fs.existsSync(agentsDir)) {
+        console.log('❌ Agents directory not found. Run: npx grimoire-framework install');
+        return;
+    }
+    const agents = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+    console.log(`\n🤖 Grimoire Agents (${agents.length}):\n`);
+    agents.forEach(f => {
+        const name = f.replace('.md', '');
+        const base = BASE_AGENTS.find(a => a.id === name);
+        const icon = base ? base.icon : '🎭';
+        const persona = base ? ` — ${base.name} (${base.specialty})` : ' — Custom Agent';
+        console.log(`  ${icon} @${name}${persona}`);
+    });
+    console.log('\n💡 Para criar um agente customizado: grimoire agent create');
+}
+
+async function createWizard() {
+    console.log('\n🧙 Grimoire Agent Creator\n');
+
+    // Step 1: Name/ID
+    const id = await prompt('Nome do agente (ex: caravaggio): ');
+    if (!id || !/^[a-z0-9-]+$/.test(id)) {
+        console.log('❌ Nome inválido. Use apenas letras minúsculas, números e hífens.');
+        return;
+    }
+
+    const cwd = process.cwd();
+    const agentsDir = path.join(cwd, '.codex', 'agents');
+    const agentFile = path.join(agentsDir, `${id}.md`);
+
+    if (fs.existsSync(agentFile)) {
+        console.log(`❌ Agente "${id}" já existe em ${agentFile}`);
+        return;
+    }
+
+    // Step 2: Display name
+    const name = await prompt(`Nome de exibição (ex: Caravaggio): `);
+
+    // Step 3: Specialty
+    const specialty = await prompt('Especialidade (ex: Arte Generativa e Criatividade): ');
+
+    // Step 4: Icon
+    const iconChoice = await select(
+        'Ícone do agente:',
+        ICON_OPTIONS.map((i, idx) => ({ label: `${i} (${idx + 1})`, value: i }))
+    );
+
+    // Step 5: Base agent (inherit style from)
+    const baseChoice = await select(
+        'Baseado em (herda o estilo de):',
+        [...BASE_AGENTS.map(a => ({ label: `${a.icon} ${a.name} — ${a.specialty}`, value: a.id })),
+        { label: '🆕 Custom (do zero)', value: 'custom' }]
+    );
+
+    // Step 6: Short description
+    const description = await prompt('Descrição curta (ex: Especialista em arte e criatividade visual): ');
+
+    // Generate & write
+    if (!fs.existsSync(agentsDir)) fs.mkdirSync(agentsDir, { recursive: true });
+
+    const content = generateAgentTemplate({
+        id, name: name || id, icon: iconChoice, specialty: specialty || 'Custom Specialist',
+        baseAgent: baseChoice !== 'custom' ? baseChoice : null,
+        description: description || `Custom agent: ${id}`
+    });
+
+    fs.writeFileSync(agentFile, content, 'utf8');
+
+    console.log(`
+✅ Agente criado: .codex/agents/${id}.md
+
+🎭 ${iconChoice} ${name || id} — ${specialty}
+
+Para ativar no Gemini CLI:
+  @${id}
+
+Para sincronizar com outras IDEs:
+  npx grimoire-framework update
+`);
+}
+
+async function editAgent(id) {
+    if (!id) { console.log('Usage: grimoire agent edit <name>'); return; }
+    const file = path.join(process.cwd(), '.codex', 'agents', `${id}.md`);
+    if (!fs.existsSync(file)) { console.log(`❌ Agent "${id}" not found.`); return; }
+    const editor = process.env.EDITOR || process.env.VISUAL || 'notepad';
+    try { execSync(`${editor} "${file}"`, { stdio: 'inherit' }); }
+    catch (e) { console.log(`❌ Could not open editor. Edit manually: ${file}`); }
+}
+
+async function removeAgent(id) {
+    if (!id) { console.log('Usage: grimoire agent remove <name>'); return; }
+    const file = path.join(process.cwd(), '.codex', 'agents', `${id}.md`);
+    if (!fs.existsSync(file)) { console.log(`❌ Agent "${id}" not found.`); return; }
+    const confirmed = await prompt(`Remove @${id}? (y/N): `);
+    if (confirmed.toLowerCase() === 'y') {
+        fs.unlinkSync(file);
+        console.log(`✅ Agent "${id}" removed.`);
+    } else {
+        console.log('Cancelled.');
+    }
+}
+
+module.exports = { run };

package/bin/commands/memory.js

@@ -16,13 +16,13 @@ const lockfile = require('proper-lockfile');
  */
 async function run(args) {
   const subCommand = args[0];
-  
+
   // Look for .grimoire directory in cwd or in grimoire/ subdirectory
   let baseDir = process.cwd();
   if (!existsSync(path.join(baseDir, '.grimoire')) && existsSync(path.join(baseDir, 'grimoire', '.grimoire'))) {
     baseDir = path.join(baseDir, 'grimoire');
   }
-  
+
   const memoryDir = path.join(baseDir, '.grimoire', 'memory');
 
   if (!existsSync(memoryDir)) {
@@ -41,6 +41,15 @@ async function run(args) {
       case 'show':
         await showSession(args.slice(1), memoryDir);
         break;
+      case 'search':
+        await searchMemory(args.slice(1), memoryDir);
+        break;
+      case 'export':
+        await exportMemory(args.slice(1), memoryDir);
+        break;
+      case 'clear':
+        await clearMemory(args.slice(1), memoryDir);
+        break;
       case 'digest':
         await digestMemory(args.slice(1), memoryDir);
         break;
@@ -80,7 +89,7 @@ async function saveMemory(args, memoryDir) {
   let release;
   try {
     // Acquire lock with retry logic
-    release = await lockfile.lock(sessionFile, { 
+    release = await lockfile.lock(sessionFile, {
       retries: {
         retries: 5,
         factor: 3,
@@ -115,8 +124,14 @@ async function listSessions(memoryDir) {
  * Shows session parsing JSONL or legacy JSON
  */
 async function showSession(args, memoryDir) {
-  const date = args[0] || new Date().toISOString().split('T')[0];
-  
+  // Support: grimoire memory show --last 5
+  let date, lastN;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--last' && args[i + 1]) lastN = parseInt(args[i + 1]);
+    else if (!args[i].startsWith('-')) date = args[i];
+  }
+  date = date || new Date().toISOString().split('T')[0];
+
   let sessionFile = path.join(memoryDir, 'sessions', `${date}.jsonl`);
   let isJsonl = true;
 
@@ -131,20 +146,101 @@ async function showSession(args, memoryDir) {
   }
 
   const rawContent = await fs.readFile(sessionFile, 'utf8');
-  console.log(`\n📖 Session: ${date}`);
-
+  let entries;
   if (isJsonl) {
-    const lines = rawContent.split('\n').filter(l => l.trim());
-    lines.forEach(line => {
-      const e = JSON.parse(line);
-      console.log(`  [${e.timestamp.split('T')[1].split('.')[0]}] ${e.content}`);
-    });
+    entries = rawContent.split('\n').filter(l => l.trim()).map(l => JSON.parse(l));
   } else {
-    const data = JSON.parse(rawContent);
-    data.entries.forEach(e => {
-      console.log(`  [${e.timestamp.split('T')[1].split('.')[0]}] ${e.content}`);
+    entries = JSON.parse(rawContent).entries;
+  }
+
+  if (lastN) entries = entries.slice(-lastN);
+
+  console.log(`\n📖 Session: ${date} (${entries.length} entr${entries.length === 1 ? 'y' : 'ies'})`);
+  entries.forEach(e => {
+    console.log(`  [${e.timestamp.split('T')[1].split('.')[0]}] ${e.content}`);
+  });
+}
+
+/**
+ * Search entries across all sessions
+ */
+async function searchMemory(args, memoryDir) {
+  const keyword = args.join(' ');
+  if (!keyword) { console.error('❌ Provide a search term.'); return; }
+
+  const sessionsDir = path.join(memoryDir, 'sessions');
+  const files = (await fs.readdir(sessionsDir)).filter(f => f.endsWith('.jsonl') || f.endsWith('.json'));
+
+  let matches = [];
+  for (const file of files) {
+    const raw = await fs.readFile(path.join(sessionsDir, file), 'utf8');
+    const entries = file.endsWith('.jsonl')
+      ? raw.split('\n').filter(l => l.trim()).map(l => JSON.parse(l))
+      : JSON.parse(raw).entries || [];
+    const date = file.replace(/\.(jsonl|json)$/, '');
+    for (const e of entries) {
+      if (e.content.toLowerCase().includes(keyword.toLowerCase())) {
+        matches.push({ date, time: e.timestamp.split('T')[1].split('.')[0], content: e.content });
+      }
+    }
+  }
+
+  console.log(`\n🔍 Search: "${keyword}" — ${matches.length} result${matches.length === 1 ? '' : 's'}`);
+  if (matches.length === 0) { console.log('  (No entries found)'); return; }
+  matches.forEach(m => console.log(`  [${m.date} ${m.time}] ${m.content}`));
+}
+
+/**
+ * Export all sessions to a Markdown file
+ */
+async function exportMemory(args, memoryDir) {
+  const format = args.includes('--format') ? args[args.indexOf('--format') + 1] : 'markdown';
+  const sessionsDir = path.join(memoryDir, 'sessions');
+  const files = (await fs.readdir(sessionsDir)).filter(f => f.endsWith('.jsonl') || f.endsWith('.json')).sort();
+
+  let output = '# Grimoire Memory Export\n\n';
+  output += `> Exported: ${new Date().toISOString()}\n\n`;
+
+  for (const file of files) {
+    const date = file.replace(/\.(jsonl|json)$/, '');
+    const raw = await fs.readFile(path.join(sessionsDir, file), 'utf8');
+    const entries = file.endsWith('.jsonl')
+      ? raw.split('\n').filter(l => l.trim()).map(l => JSON.parse(l))
+      : JSON.parse(raw).entries || [];
+
+    output += `## ${date}\n\n`;
+    entries.forEach(e => {
+      output += `- \`${e.timestamp.split('T')[1].split('.')[0]}\` ${e.content}\n`;
     });
+    output += '\n';
   }
+
+  const outFile = path.join(process.cwd(), `grimoire-memory-export-${Date.now()}.md`);
+  await fs.writeFile(outFile, output, 'utf8');
+  console.log(`✅ Memory exported to: ${outFile}`);
+}
+
+/**
+ * Clear sessions older than N days
+ */
+async function clearMemory(args, memoryDir) {
+  const olderThan = args.find(a => a.startsWith('--older-than'));
+  const days = olderThan ? parseInt(olderThan.replace('--older-than=', '').replace('--older-than', '') || args[args.indexOf(olderThan) + 1] || '30') : 30;
+
+  const sessionsDir = path.join(memoryDir, 'sessions');
+  const files = (await fs.readdir(sessionsDir)).filter(f => f.match(/^\d{4}-\d{2}-\d{2}/));
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+
+  let removed = 0;
+  for (const file of files) {
+    const datePart = file.replace(/\.(jsonl|json)$/, '');
+    if (new Date(datePart) < cutoff) {
+      await fs.unlink(path.join(sessionsDir, file));
+      removed++;
+    }
+  }
+  console.log(`✅ Cleared ${removed} session${removed === 1 ? '' : 's'} older than ${days} days.`);
 }
 
 /**
@@ -175,7 +271,7 @@ async function digestMemory(args, memoryDir) {
   categories.misc = entries.filter(e => !categorizedIds.has(e));
 
   console.log(`📊 Analysis complete: ${entries.length} entries processed.`);
-  
+
   if (categories.decisions.length > 0) {
     console.log('\n🏛️  PROPOSED DECISIONS (Update entities/decisions.md):');
     categories.decisions.forEach(e => console.log(`  - ${e.content}`));
@@ -194,21 +290,31 @@ async function digestMemory(args, memoryDir) {
   console.log('\n--- SESSION ARCHIVING ---');
   const archiveDir = path.join(memoryDir, 'sessions', 'archived');
   if (!existsSync(archiveDir)) await fs.mkdir(archiveDir);
-  
+
   await fs.rename(sessionFile, path.join(archiveDir, `${date}.jsonl`));
   console.log(`✅ Session ${date} digested and archived.`);
 }
 
 function showHelp() {
   console.log(`
-📊 Grimoire Memory Management (Turbo I/O)
-
-USAGE:
-  grimoire memory save "<text>"   # Save a new entry (Fast Append)
-  grimoire memory list            # List all recorded sessions
-  grimoire memory show <date>     # Show entries for a specific date
-  grimoire memory digest <date>   # Consolidate daily logs into permanent docs
-  grimoire memory help            # Show this help
+💾 Grimoire Memory — Gestão de Contexto
+
+USO:
+  grimoire memory save "<texto>"        Salva uma entrada na sessão de hoje
+  grimoire memory list                  Lista todas as sessões
+  grimoire memory show [data]           Mostra entradas de uma data (padrão: hoje)
+  grimoire memory show --last 5         Mostra as últimas 5 entradas de hoje
+  grimoire memory search "<termo>"      Busca em todas as sessões
+  grimoire memory export                Exporta tudo para Markdown
+  grimoire memory digest [data]         Categoriza e arquiva uma sessão
+  grimoire memory clear --older-than 30d   Remove sessões antigas
+
+EXEMPLOS:
+  grimoire memory save "Decidimos usar PostgreSQL por performance"
+  grimoire memory show --last 10
+  grimoire memory search "PostgreSQL"
+  grimoire memory export --format markdown
+  grimoire memory clear --older-than 30
 `);
 }
 

package/bin/commands/update.js

@@ -24,6 +24,7 @@ const FRAMEWORK_SYNC_DIRS = [
     { src: '.gemini/rules/grimoire', dest: '.gemini/rules/grimoire' },
     { src: '.cursor/rules/agents', dest: '.cursor/rules/agents' },
     { src: '.claude/commands/grimoire', dest: '.claude/commands/grimoire' },
+    { src: 'squads', dest: '.grimoire/squads' },
 ];
 
 // Single files to sync (framework root → project root)

package/bin/grimoire-cli.js

@@ -12,8 +12,93 @@ const { execSync } = require('child_process');
 const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 const args = process.argv.slice(2);
 const command = args[0];
+const currentVersion = packageJson.version;
+
+// ── Update Banner (async, non-blocking, 24h cooldown) ─────────────────────────
+const UPDATE_CACHE_FILE = path.join(
+  process.env.HOME || process.env.USERPROFILE || require('os').homedir(),
+  '.grimoire-update-cache.json'
+);
+
+function shouldCheckForUpdates() {
+  if (process.env.GRIMOIRE_NO_UPDATE_CHECK) return false;
+  if (['update', '--version', '-v', 'doctor'].includes(command)) return false;
+  try {
+    if (fs.existsSync(UPDATE_CACHE_FILE)) {
+      const cache = JSON.parse(fs.readFileSync(UPDATE_CACHE_FILE, 'utf8'));
+      const hoursSince = (Date.now() - cache.lastCheck) / (1000 * 60 * 60);
+      if (hoursSince < 24) return false;
+    }
+  } catch (e) { /* ignore */ }
+  return true;
+}
+
+async function checkForUpdates() {
+  if (!shouldCheckForUpdates()) return;
+  try {
+    const https = require('https');
+    const data = await new Promise((resolve, reject) => {
+      const req = https.get(
+        'https://registry.npmjs.org/grimoire-framework/latest',
+        { timeout: 3000 },
+        (res) => {
+          let body = '';
+          res.on('data', d => body += d);
+          res.on('end', () => { try { resolve(JSON.parse(body)); } catch (e) { reject(e); } });
+        }
+      );
+      req.on('error', reject);
+      req.on('timeout', () => req.destroy());
+    });
+    const latest = data.version;
+    // Save to cache
+    fs.writeFileSync(UPDATE_CACHE_FILE, JSON.stringify({ lastCheck: Date.now(), latest }));
+    // Compare versions
+    const [maj, min, pat] = currentVersion.split('.').map(Number);
+    const [lmaj, lmin, lpat] = latest.split('.').map(Number);
+    const isNewer = lmaj > maj || (lmaj === maj && lmin > min) || (lmaj === maj && lmin === min && lpat > pat);
+    if (isNewer) {
+      console.log(`\n💡 Nova versão disponível: v${latest} (você tem v${currentVersion})`);
+      console.log(`   Atualize com: npx grimoire-framework update\n`);
+    }
+  } catch (e) { /* offline ou erro — ignorar silenciosamente */ }
+}
+
+// ── First-Run Experience ───────────────────────────────────────────────────────
+function showNextSteps(projectDir) {
+  const cwd = projectDir || process.cwd();
+  // Detect installed IDE
+  const hasGemini = fs.existsSync(path.join(cwd, 'GEMINI.md'));
+  const hasCursor = fs.existsSync(path.join(cwd, '.cursor'));
+  const hasClaude = fs.existsSync(path.join(cwd, '.claude'));
+
+  let ideStep = '   2. Abra o Gemini CLI:  gemini';
+  if (hasClaude) ideStep = '   2. Abra o Claude Code — agentes prontos com /dev, /qa, /architect';
+  else if (hasCursor) ideStep = '   2. Abra o Cursor — @dev, @qa, @architect disponíveis no chat';
+  else if (hasGemini) ideStep = '   2. Abra o Gemini CLI:  gemini  →  Michelangelo te recebe';
+
+  const agentsDir = path.join(cwd, '.codex', 'agents');
+  const agentCount = fs.existsSync(agentsDir)
+    ? fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length : 0;
+
+  console.log(`
+🎯 Próximos passos:
+   1. Verifique a instalação:  grimoire status
+${ideStep}
+   3. Para ver todos os agentes: grimoire agents list
+   4. Para diagnóstico:           grimoire doctor
+
+💡 Dica rápida: Diga \"@dev implementa o login\" no chat da sua IDE
+   Você tem ${agentCount} agentes prontos: @dev, @qa, @architect, @grimoire-master...
+
+📚 Docs: https://github.com/gabrielrlima/grimoire#readme
+`);
+}
 
 async function main() {
+  // Non-blocking update check (runs in background)
+  const updatePromise = checkForUpdates().catch(() => { });
+
   switch (command) {
     case 'memory':
       await require('./commands/memory').run(args.slice(1));
@@ -27,6 +112,9 @@ async function main() {
     case 'agents':
       handleAgents(args.slice(1));
       break;
+    case 'agent':
+      await require('./commands/agent').run(args.slice(1));
+      break;
     case 'status':
       handleStatus();
       break;
@@ -47,7 +135,7 @@ async function main() {
       break;
     case '--version':
     case '-v':
-      console.log(`Grimoire Pro v${packageJson.version}`);
+      console.log(`Grimoire v${packageJson.version}`);
       break;
     case '--help':
     case '-h':
@@ -55,6 +143,9 @@ async function main() {
       showHelp();
       break;
   }
+
+  // Wait for update check to finish (prints banner after main command if needed)
+  await updatePromise;
 }
 
 function handleSquads(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grimoire-framework",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Grimoire: AI-Orchestrated System for Full Stack Development - Core Framework",
   "publishConfig": {
     "access": "public"
@@ -36,6 +36,7 @@
     ".claude/hooks/",
     "GEMINI.md",
     "pro/license/",
+    "squads/",
     "README.md",
     "LICENSE"
   ],

package/packages/installer/src/utils/grimoire-colors.js

@@ -19,73 +19,73 @@ const colors = {
   // ============================================
   // CORE BRAND COLORS
   // ============================================
-  
+
   /**
    * Primary brand color - ClickUp-inspired purple
    * Usage: Main questions, headers, CTAs, primary actions
    */
   primary: chalk.hex('#8B5CF6'),
-  
+
   /**
    * Secondary brand color - Magenta accent from logo gradient
    * Usage: Important highlights, special emphasis, key information
    */
   secondary: chalk.hex('#EC4899'),
-  
+
   /**
    * Tertiary brand color - Blue accent from logo gradient
    * Usage: Secondary actions, links, complementary elements
    */
   tertiary: chalk.hex('#3B82F6'),
-  
+
   // ============================================
   // FUNCTIONAL COLORS
   // ============================================
-  
+
   /**
    * Success state color
    * Usage: Checkmarks, completed steps, success messages
    */
   success: chalk.hex('#10B981'),
-  
+
   /**
    * Warning state color - Orange from logo gradient
    * Usage: Warnings, confirmations, caution states
    */
   warning: chalk.hex('#F59E0B'),
-  
+
   /**
    * Error state color
    * Usage: Errors, critical alerts, validation failures
    */
   error: chalk.hex('#EF4444'),
-  
+
   /**
    * Info state color - Cyan-blue from logo gradient
    * Usage: Info messages, tips, helper text, additional context
    */
   info: chalk.hex('#06B6D4'),
-  
+
   // ============================================
   // NEUTRAL COLORS
   // ============================================
-  
+
   /**
    * Muted text color
    * Usage: Subtle text, disabled states, secondary content
    */
   muted: chalk.hex('#94A3B8'),
-  
+
   /**
    * Dim text color
    * Usage: Secondary text, muted content, less important info
    */
   dim: chalk.hex('#64748B'),
-  
+
   // ============================================
   // GRADIENT SYSTEM
   // ============================================
-  
+
   /**
    * Brand gradient colors for animations and special effects
    * Matches grimoire logo gradient: magenta → purple → blue
@@ -93,28 +93,28 @@ const colors = {
   gradient: {
     /** Gradient start - Magenta (logo top) */
     start: chalk.hex('#EC4899'),
-    
+
     /** Gradient middle - Purple (brand) */
     middle: chalk.hex('#8B5CF6'),
-    
+
     /** Gradient end - Blue (logo bottom) */
     end: chalk.hex('#3B82F6'),
   },
-  
+
   // ============================================
   // SEMANTIC SHORTCUTS
   // ============================================
-  
+
   /**
    * Highlighted text - Bold magenta for key information
    */
   highlight: chalk.hex('#EC4899').bold,
-  
+
   /**
    * Primary branding - Bold purple for grimoire brand moments
    */
   brandPrimary: chalk.hex('#8B5CF6').bold,
-  
+
   /**
    * Secondary branding - Cyan for supporting brand elements
    */
@@ -127,25 +127,25 @@ const colors = {
 const status = {
   /** Success indicator: ✓ (green) */
   success: (text) => `${colors.success('✓')} ${text}`,
-  
+
   /** Error indicator: ✗ (red) */
   error: (text) => `${colors.error('✗')} ${text}`,
-  
+
   /** Warning indicator: ⚠️ (orange) */
   warning: (text) => `${colors.warning('⚠️')} ${text}`,
-  
+
   /** Info indicator: ℹ (cyan) */
   info: (text) => `${colors.info('ℹ')} ${text}`,
-  
+
   /** Loading indicator: ⏳ (cyan) */
   loading: (text) => `${colors.info('⏳')} ${text}`,
-  
+
   /** Skipped indicator: ⊘ (muted) */
   skipped: (text) => `${colors.muted('⊘')} ${text}`,
-  
+
   /** Tip indicator: 💡 (info) */
   tip: (text) => `${colors.info('💡')} ${text}`,
-  
+
   /** Party indicator: 🎉 (brand primary) */
   celebrate: (text) => `${colors.brandPrimary('🎉')} ${text}`,
 };
@@ -156,13 +156,13 @@ const status = {
 const headings = {
   /** H1 - Brand primary, bold, large spacing */
   h1: (text) => `\n${colors.brandPrimary(text)}\n`,
-  
+
   /** H2 - Primary color, bold */
   h2: (text) => `\n${colors.primary.bold(text)}\n`,
-  
+
   /** H3 - Primary color */
   h3: (text) => colors.primary(text),
-  
+
   /** Section divider */
   divider: () => colors.dim('─'.repeat(50)),
 };
@@ -173,10 +173,10 @@ const headings = {
 const lists = {
   /** Bullet point (primary) */
   bullet: (text) => `${colors.primary('•')} ${text}`,
-  
+
   /** Numbered item (primary) */
   numbered: (num, text) => `${colors.primary(`${num}.`)} ${text}`,
-  
+
   /** Checkbox unchecked */
   checkbox: (text, checked = false) => {
     const icon = checked ? colors.success('☑') : colors.muted('☐');
@@ -192,31 +192,60 @@ const examples = {
     console.log(headings.h1('🎉 Welcome to grimoire v4 Installer!'));
     console.log(colors.info('Let\'s configure your project in just a few steps...\n'));
   },
-  
+
   question: () => {
     console.log(colors.primary('? Select your project type:'));
     console.log(lists.bullet('Greenfield (new project)'));
     console.log(lists.bullet('Brownfield (existing project)'));
   },
-  
+
   progress: () => {
     console.log(status.loading('Installing dependencies...'));
     console.log(status.success('Dependencies installed'));
     console.log(status.loading('Configuring environment...'));
   },
-  
+
   feedback: () => {
     console.log(status.success('Configuration complete!'));
     console.log(status.warning('Existing .env found. Overwrite?'));
     console.log(status.error('Invalid path provided'));
     console.log(status.tip('You can change this later in settings'));
   },
-  
-  complete: () => {
+
+  complete: (projectDir) => {
     console.log('\n' + headings.divider());
     console.log(status.celebrate('Installation Complete!'));
     console.log(colors.info('Your grimoire project is ready to use.'));
     console.log(headings.divider() + '\n');
+
+    // First-Run Next Steps
+    const path = require('path');
+    const fs = require('fs');
+    const cwd = projectDir || process.cwd();
+    const hasGemini = fs.existsSync(path.join(cwd, 'GEMINI.md'));
+    const hasClaude = fs.existsSync(path.join(cwd, '.claude'));
+    const hasCursor = fs.existsSync(path.join(cwd, '.cursor'));
+
+    let ideStep = '  2. Abra o Gemini CLI: gemini  →  Michelangelo te recebe';
+    if (hasClaude) ideStep = '  2. Abra o Claude Code — use /dev, /qa, /architect';
+    else if (hasCursor) ideStep = '  2. Abra o Cursor — @dev, @qa, @architect no chat';
+    else if (hasGemini) ideStep = '  2. Abra o Gemini CLI: gemini  →  Michelangelo te recebe';
+
+    const agentsDir = path.join(cwd, '.codex', 'agents');
+    const agentCount = fs.existsSync(agentsDir)
+      ? fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length : 0;
+
+    console.log(`🎯 Próximos passos:
+  1. Verifique a instalação:   grimoire status
+${ideStep}
+  3. Liste os agentes:         grimoire agents list
+  4. Diagnóstico completo:     grimoire doctor
+
+💡 Dica: Diga "@dev implementa o login" no chat da sua IDE.
+   Você tem ${agentCount} agentes prontos: @dev @qa @architect @grimoire-master...
+
+📚 Docs: https://github.com/gabrielrlima/grimoire#readme
+`);
   },
 };
 

package/squads/.gitkeep

@@ -0,0 +1,2 @@
+# This file ensures the squads directory is tracked by Git
+# Add your squads (squads) here

package/squads/README.md

@@ -0,0 +1,25 @@
+# Grimoire Squads
+
+Este diretório contém os squads pré-configurados para organizar o fluxo de trabalho dos agentes.
+
+## Squads Disponíveis
+
+### 1. Full Stack Development
+**Agentes:** @dev, @qa, @architect  
+**Foco:** Planejamento técnico, codificação e testes.
+
+### 2. Planning & Strategy
+**Agentes:** @analyst, @pm, @architect, @ux-design-expert  
+**Foco:** Transformar ideias em PRDs e arquitetura.
+
+### 3. DevOps & Management
+**Agentes:** @devops, @sm, @po  
+**Foco:** Backlog, sprints e pipelines de deploy.
+
+## Como Usar
+Para carregar um squad durante a instalação ou re-setup, selecione as opções correspondentes no CLI do Grimoire.
+
+## Como Criar Squads Customizados
+1. Crie uma nova pasta dentro de `squads/`.
+2. Adicione um arquivo `squad.yaml` com nome, descrição e a lista de agentes (referenciando arquivos em `.codex/agents/`).
+3. Adicione fluxos de trabalho em uma pasta `workflows/` opcional.

package/squads/devops/squad.yaml

@@ -0,0 +1,9 @@
+name: "DevOps & Management Squad"
+description: "Squad responsável pelo ciclo de entrega, automação e gerenciamento de backlog."
+agents:
+  - devops
+  - sm
+  - po
+workflows:
+  - id: deploy-pipeline
+    file: workflows/deploy-pipeline.md

package/squads/devops/workflows/deploy-pipeline.md

@@ -0,0 +1,22 @@
+# Workflow: Pipeline de Deploy (Deploy Pipeline)
+
+**Objetivo:** Garantir a entrega segura e automatizada do software.
+
+## Etapas do Fluxo
+
+### 1. Quality Gate
+- **Agente:** @devops
+- **Ação:** Rodar lint, testes e build no CI antes do push.
+
+### 2. Versionamento
+- **Agente:** @devops
+- **Ação:** Realizar o bump de versão e criar tags de release.
+
+### 3. Promoção de Ambiente
+- **Agente:** @devops
+- **Ação:** Orquestrar o deploy para staging ou produção.
+
+## Ferramentas
+- GitHub Actions
+- Semantic Release
+- Quality Gate Hooks

package/squads/fullstack/squad.yaml

@@ -0,0 +1,11 @@
+name: "Full Stack Development Squad"
+description: "Squad completo para planejamento, implementação e teste de features de software."
+agents:
+  - dev
+  - qa
+  - architect
+workflows:
+  - id: new-feature
+    file: workflows/new-feature.md
+  - id: code-review
+    file: workflows/code-review.md

package/squads/fullstack/workflows/code-review.md

@@ -0,0 +1,22 @@
+# Workflow: Revisão de Código (Code Review)
+
+**Objetivo:** Garantir a qualidade e consistência do código antes do merge.
+
+## Etapas do Fluxo
+
+### 1. Análise Estática
+- **Agente:** @qa (em conjunto com CodeRabbit)
+- **Ação:** Identificar bugs latentes, vulnerabilidades e dívida técnica.
+
+### 2. Revisão de Padrões
+- **Agente:** @architect
+- **Ação:** Validar se o código segue os padrões arquiteturais do projeto.
+
+### 3. Validação de Lógica
+- **Agente:** @dev (Peer Review)
+- **Ação:** Revisar a lógica de negócio implementada.
+
+## Critérios de Aprovação
+- Zero problemas críticos de segurança.
+- Lint e testes passando 100%.
+- Conformidade com ADRs existentes.

package/squads/fullstack/workflows/new-feature.md

@@ -0,0 +1,24 @@
+# Workflow: Nova Funcionalidade (New Feature)
+
+**Objetivo:** Levar uma ideia de funcionalidade até a produção através de um fluxo estruturado.
+
+## Etapas do Fluxo
+
+### 1. Planejamento Arquitetural
+- **Agente:** @architect
+- **Ação:** Criar ou atualizar o design do sistema para a nova feature.
+- **Saída:** Documento de arquitetura técnica.
+
+### 2. Implementação
+- **Agente:** @dev
+- **Ação:** Codificar a funcionalidade seguindo o design aprovado.
+- **Saída:** Código-fonte implementado e commitado localmente.
+
+### 3. Garantia de Qualidade (QA)
+- **Agente:** @qa
+- **Ação:** Validar a implementação contra os critérios de aceitação.
+- **Saída:** Aprovação de QA e sugestões de melhoria.
+
+## Gatilhos (Triggers)
+- Solicitação de nova feature pelo @pm
+- Backlog de sprints atualizado pelo @sm

package/squads/planning/squad.yaml

@@ -0,0 +1,10 @@
+name: "Planning & Strategy Squad"
+description: "Squad focado em requisitos, design de sistema e experiência do usuário (UX)."
+agents:
+  - analyst
+  - pm
+  - architect
+  - ux-design-expert
+workflows:
+  - id: prd-to-stories
+    file: workflows/prd-to-stories.md

package/squads/planning/workflows/prd-to-stories.md

@@ -0,0 +1,20 @@
+# Workflow: PRD para Histórias (PRD to Stories)
+
+**Objetivo:** Fragmentar requisitos de alto nível em unidades de desenvolvimento acionáveis.
+
+## Etapas do Fluxo
+
+### 1. Refinamento de Requisitos
+- **Agente:** @analyst + @pm
+- **Ação:** Validar o briefing e transformar em um PRD completo.
+
+### 2. Design Visual (UX)
+- **Agente:** @ux-design-expert
+- **Ação:** Criar fluxos de usuário e wireframes para os requisitos.
+
+### 3. Fragmentação (Sharding)
+- **Agente:** @sm
+- **Ação:** Criar as histórias (stories) em `docs/stories/` com base no PRD.
+
+## Saída Esperada
+- Backlog de stories priorizado e pronto para implementação.