guild-agents 0.0.1 → 0.2.0

package/src/commands/init.js

@@ -0,0 +1,140 @@
+/**
+ * guild init — Onboarding interactivo v1
+ *
+ * Flujo:
+ * 1. Verificar que no existe ya una instalacion de Guild
+ * 2. Recopilar: nombre, tipo, stack, GitHub, codigo existente
+ * 3. Generar PROJECT.md, CLAUDE.md, SESSION.md
+ * 4. Copiar agentes y skills
+ * 5. Instrucciones para /guild-specialize
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { existsSync } from 'fs';
+import { generateProjectMd, generateSessionMd, generateClaudeMd } from '../utils/generators.js';
+import { copyTemplates } from '../utils/files.js';
+
+export async function runInit() {
+  console.log('');
+  p.intro(chalk.bold.cyan('Guild v1 — Nuevo proyecto'));
+
+  // Verificar instalacion existente
+  if (existsSync('.claude/agents')) {
+    const overwrite = await p.confirm({
+      message: 'Guild ya esta instalado en este proyecto. Reinicializar?',
+      initialValue: false,
+    });
+
+    if (p.isCancel(overwrite) || !overwrite) {
+      p.cancel('Cancelado.');
+      return;
+    }
+  }
+
+  // ─── Nombre ─────────────────────────────────────────────────────────────────
+  const name = await p.text({
+    message: 'Nombre del proyecto:',
+    placeholder: 'mi-proyecto',
+    validate: (val) => {
+      if (!val) return 'El nombre es requerido';
+    },
+  });
+  if (p.isCancel(name)) { p.cancel('Cancelado.'); return; }
+
+  // ─── Tipo ───────────────────────────────────────────────────────────────────
+  const type = await p.select({
+    message: 'Tipo de proyecto:',
+    options: [
+      { value: 'webapp', label: 'Web app (React/Vue/Angular)' },
+      { value: 'api', label: 'API / Backend service' },
+      { value: 'cli', label: 'CLI tool' },
+      { value: 'mobile', label: 'Mobile (React Native)' },
+      { value: 'fullstack', label: 'Otro / Fullstack' },
+    ],
+  });
+  if (p.isCancel(type)) { p.cancel('Cancelado.'); return; }
+
+  // ─── Stack ──────────────────────────────────────────────────────────────────
+  const stack = await p.text({
+    message: 'Stack principal:',
+    placeholder: 'ej: Next.js, Supabase, Vercel',
+    validate: (val) => {
+      if (!val) return 'El stack es requerido';
+    },
+  });
+  if (p.isCancel(stack)) { p.cancel('Cancelado.'); return; }
+
+  // ─── GitHub ─────────────────────────────────────────────────────────────────
+  let github = null;
+  const hasRepo = await p.confirm({
+    message: 'Tiene repositorio GitHub?',
+    initialValue: true,
+  });
+
+  if (!p.isCancel(hasRepo) && hasRepo) {
+    const repoUrl = await p.text({
+      message: 'URL del repositorio:',
+      placeholder: 'https://github.com/org/repo',
+      validate: (val) => {
+        if (!val) return 'La URL es requerida';
+        if (!val.includes('github.com')) return 'Debe ser una URL de GitHub';
+      },
+    });
+    if (!p.isCancel(repoUrl)) {
+      github = { repoUrl };
+    }
+  }
+
+  // ─── Codigo existente ───────────────────────────────────────────────────────
+  const hasExistingCode = await p.confirm({
+    message: 'Tiene codigo existente?',
+    initialValue: true,
+  });
+
+  // ─── Generacion ─────────────────────────────────────────────────────────────
+  const spinner = p.spinner();
+  spinner.start('Generando estructura Guild v1...');
+
+  const projectData = {
+    name,
+    type,
+    stack,
+    github,
+    hasExistingCode: !p.isCancel(hasExistingCode) && hasExistingCode,
+  };
+
+  try {
+    await copyTemplates();
+    spinner.message('Generando CLAUDE.md...');
+    await generateClaudeMd(projectData);
+
+    spinner.message('Generando PROJECT.md...');
+    await generateProjectMd(projectData);
+
+    spinner.message('Generando SESSION.md...');
+    await generateSessionMd();
+
+    spinner.stop('Estructura creada.');
+  } catch (error) {
+    spinner.stop('Error durante la inicializacion.');
+    throw error;
+  }
+
+  // ─── Resumen ────────────────────────────────────────────────────────────────
+  p.log.success('CLAUDE.md');
+  p.log.success('PROJECT.md');
+  p.log.success('SESSION.md');
+  p.log.success('.claude/agents/    (8 agentes base)');
+  p.log.success('.claude/skills/    (10 skills)');
+
+  p.note(
+    'Abre Claude Code en este directorio y ejecuta:\n\n' +
+    '  /guild-specialize\n\n' +
+    'Este skill explorara tu codigo y enriquecera CLAUDE.md\n' +
+    'con la informacion real del proyecto.',
+    'Siguiente paso'
+  );
+
+  p.outro(chalk.bold.cyan('Guild v1 listo.'));
+}

package/src/commands/list.js

@@ -0,0 +1,82 @@
+/**
+ * list.js — Lists installed agents and skills with descriptions
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Parses YAML frontmatter from a markdown file content.
+ * Returns an object with key-value pairs from the frontmatter.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const fm = {};
+  for (const line of match[1].split('\n')) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim().replace(/^["']|["']$/g, '');
+    if (key && value) fm[key] = value;
+  }
+  return fm;
+}
+
+export async function runList() {
+  p.intro(chalk.bold.cyan('Guild — Agents & Skills'));
+
+  // List agents
+  const agentsDir = join('.claude', 'agents');
+  p.log.step('Agents');
+
+  if (existsSync(agentsDir)) {
+    const agentFiles = readdirSync(agentsDir).filter(f => f.endsWith('.md')).sort();
+    if (agentFiles.length > 0) {
+      for (const file of agentFiles) {
+        const content = readFileSync(join(agentsDir, file), 'utf8');
+        const fm = parseFrontmatter(content);
+        const name = fm.name || file.replace('.md', '');
+        const desc = fm.description || chalk.gray('(no description)');
+        p.log.info(`  ${chalk.bold(name)} — ${desc}`);
+      }
+    } else {
+      p.log.info(chalk.gray('  No agents found'));
+    }
+  } else {
+    p.log.info(chalk.gray('  No agents directory (.claude/agents/)'));
+  }
+
+  // List skills
+  const skillsDir = join('.claude', 'skills');
+  p.log.step('Skills');
+
+  if (existsSync(skillsDir)) {
+    const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name)
+      .sort();
+    if (skillDirs.length > 0) {
+      for (const dir of skillDirs) {
+        const skillFile = join(skillsDir, dir, 'SKILL.md');
+        if (existsSync(skillFile)) {
+          const content = readFileSync(skillFile, 'utf8');
+          const fm = parseFrontmatter(content);
+          const name = fm.name || dir;
+          const desc = fm.description || chalk.gray('(no description)');
+          p.log.info(`  ${chalk.bold(name)} — ${desc}`);
+        } else {
+          p.log.info(`  ${chalk.bold(dir)} — ${chalk.gray('(missing SKILL.md)')}`);
+        }
+      }
+    } else {
+      p.log.info(chalk.gray('  No skills found'));
+    }
+  } else {
+    p.log.info(chalk.gray('  No skills directory (.claude/skills/)'));
+  }
+
+  p.outro('');
+}

package/src/commands/new-agent.js

@@ -0,0 +1,92 @@
+/**
+ * new-agent.js — Crea un nuevo agente v1 (archivo plano)
+ *
+ * Flujo:
+ * 1. Validar nombre (lowercase, guiones, sin espacios)
+ * 2. Verificar que Guild esta instalado
+ * 3. Verificar que el agente NO existe
+ * 4. Pedir descripcion del agente
+ * 5. Crear .claude/agents/[nombre].md con placeholder
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const AGENTS_DIR = join('.claude', 'agents');
+
+export async function runNewAgent(agentName) {
+  p.intro(chalk.bold.cyan('Guild — Nuevo agente'));
+
+  // Validar nombre
+  if (!isValidAgentName(agentName)) {
+    throw new Error(`Nombre invalido: "${agentName}". Solo lowercase, numeros y guiones. Ejemplo: guild new-agent security-auditor`);
+  }
+
+  // Verificar Guild instalado
+  if (!existsSync(AGENTS_DIR)) {
+    throw new Error('Guild no esta instalado. Ejecuta: guild init');
+  }
+
+  // Verificar que el agente NO existe
+  const agentPath = join(AGENTS_DIR, `${agentName}.md`);
+  if (existsSync(agentPath)) {
+    throw new Error(`El agente "${agentName}" ya existe.`);
+  }
+
+  // Pedir descripcion
+  const description = await p.text({
+    message: `Que hace "${agentName}"? (descripcion corta):`,
+    placeholder: 'ej: Evalua oportunidades de trading basado en analisis tecnico',
+    validate: (val) => !val ? 'La descripcion es requerida' : undefined,
+  });
+  if (p.isCancel(description)) { p.cancel('Cancelado.'); return; }
+
+  // Crear agente
+  const spinner = p.spinner();
+  spinner.start(`Creando agente "${agentName}"...`);
+
+  try {
+    const content = `---
+name: ${agentName}
+description: "${description}"
+---
+
+# ${agentName}
+
+Eres ${agentName} de [PROYECTO].
+
+## Responsabilidades
+[Definir con /guild-specialize]
+
+## Lo que NO haces
+[Definir con /guild-specialize]
+
+## Proceso
+[Definir con /guild-specialize]
+
+## Reglas de comportamiento
+- Siempre lee CLAUDE.md y SESSION.md al inicio de la sesion
+`;
+
+    writeFileSync(agentPath, content, 'utf8');
+
+    spinner.stop(`Agente "${agentName}" creado.`);
+
+    p.log.success(`Archivo: ${agentPath}`);
+    p.note(
+      `Ejecuta /guild-specialize para que Claude\n` +
+      `genere las instrucciones completas de "${agentName}".`,
+      'Especializacion pendiente'
+    );
+    p.outro(chalk.bold.cyan(`Agente ${agentName} listo.`));
+  } catch (error) {
+    spinner.stop('Error al crear agente.');
+    throw error;
+  }
+}
+
+function isValidAgentName(name) {
+  return /^[a-z][a-z0-9-]*$/.test(name);
+}

package/src/commands/status.js

@@ -0,0 +1,57 @@
+/**
+ * status.js — Muestra el estado actual del proyecto v1
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export async function runStatus() {
+  if (!existsSync('PROJECT.md')) {
+    throw new Error('Guild no esta instalado. Ejecuta: guild init');
+  }
+
+  const projectMd = readFileSync('PROJECT.md', 'utf8');
+  const nameMatch = projectMd.match(/\*\*Nombre:\*\*\s*(.+)/);
+  const stackMatch = projectMd.match(/\*\*Stack:\*\*\s*(.+)/);
+  const projectName = nameMatch ? nameMatch[1].trim() : 'Proyecto';
+
+  p.intro(chalk.bold.cyan(`Guild — ${projectName}`));
+
+  if (stackMatch) {
+    p.log.info(chalk.gray(`Stack: ${stackMatch[1].trim()}`));
+  }
+
+  // Sesion activa
+  if (existsSync('SESSION.md')) {
+    p.log.step('Sesion activa');
+    const sessionMd = readFileSync('SESSION.md', 'utf8');
+    const taskMatch = sessionMd.match(/\*\*Tarea en curso:\*\*\s*(.+)/);
+    const stateMatch = sessionMd.match(/\*\*Estado:\*\*\s*(.+)/);
+    if (taskMatch && taskMatch[1].trim() !== '—') p.log.info(`  Tarea: ${taskMatch[1].trim()}`);
+    if (stateMatch) p.log.info(chalk.gray(`  ${stateMatch[1].trim()}`));
+  }
+
+  // Agentes
+  const agentsDir = join('.claude', 'agents');
+  if (existsSync(agentsDir)) {
+    p.log.step('Agentes');
+    const agents = readdirSync(agentsDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.replace('.md', ''));
+    p.log.info(chalk.gray(`  ${agents.join(', ')}`));
+  }
+
+  // Skills
+  const skillsDir = join('.claude', 'skills');
+  if (existsSync(skillsDir)) {
+    p.log.step('Skills');
+    const skills = readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+    p.log.info(chalk.gray(`  ${skills.join(', ')}`));
+  }
+
+  p.outro('');
+}

package/src/templates/agents/advisor.md

@@ -0,0 +1,47 @@
+---
+name: advisor
+description: "Evalua ideas y da direccion estrategica antes de comprometer trabajo"
+tools: Read, Glob, Grep
+permissionMode: plan
+---
+
+# Advisor
+
+Eres el guardian de dominio de [PROYECTO]. Tu trabajo es evaluar ideas y propuestas antes de que el equipo comprometa esfuerzo, asegurando coherencia con la vision y viabilidad del producto.
+
+## Responsabilidades
+
+- Evaluar propuestas de features y cambios contra la vision del proyecto
+- Identificar riesgos de negocio, dependencias ocultas y conflictos con funcionalidad existente
+- Aprobar, rechazar o ajustar ideas antes de que pasen a planificacion
+- Detectar scope creep y mantener el foco del proyecto
+- Validar que las prioridades propuestas tienen sentido estrategico
+
+## Lo que NO haces
+
+- No defines arquitectura ni approach tecnico — eso es del Tech Lead
+- No priorizas backlog ni escribes criterios de aceptacion — eso es del Product Owner
+- No revisas codigo — eso es del Code Reviewer
+- No implementas nada — eso es del Developer
+
+## Proceso
+
+1. Lee CLAUDE.md y SESSION.md para entender el estado actual del proyecto
+2. Analiza la propuesta en contexto del dominio y la vision de [PROYECTO]
+3. Identifica riesgos, dependencias y conflictos
+4. Emite tu evaluacion con el formato de salida
+
+## Formato de salida
+
+- **Evaluacion**: Aprobado / Rechazado / Requiere ajustes
+- **Razonamiento**: Por que esta decision (2-3 oraciones)
+- **Ajustes sugeridos**: Cambios concretos si aplica
+- **Riesgos identificados**: Lista priorizada de riesgos
+
+## Reglas de comportamiento
+
+- Siempre lee CLAUDE.md y SESSION.md antes de evaluar
+- Se conciso — el equipo necesita decisiones, no ensayos
+- Fundamenta cada evaluacion con razones concretas, no opiniones vagas
+- Si no tienes suficiente contexto, pide clarificacion antes de evaluar
+- Distingue entre riesgos reales y preferencias personales

package/src/templates/agents/bugfix.md

@@ -0,0 +1,50 @@
+---
+name: bugfix
+description: "Diagnostico y resolucion de bugs"
+tools: Read, Write, Edit, Bash, Glob, Grep
+permissionMode: bypassPermissions
+---
+
+# Bugfix
+
+Eres el especialista en diagnostico y resolucion de bugs de [PROYECTO]. Llegas a cada bug sin el sesgo cognitivo del Developer original, lo que te da perspectiva fresca para encontrar la causa raiz.
+
+## Responsabilidades
+
+- Reproducir el bug de forma consistente antes de investigar
+- Identificar la causa raiz, no solo el sintoma
+- Proponer el fix minimo que resuelve el problema sin efectos secundarios
+- Implementar la correccion y verificar que no introduce regresiones
+- Documentar la causa raiz para prevenir bugs similares
+
+## Lo que NO haces
+
+- No implementas features nuevas — eso es del Developer
+- No validas comportamiento general — eso es de QA
+- No investigas errores triviales de compilacion o sintaxis
+- No defines approach tecnico — eso es del Tech Lead
+
+## Proceso
+
+1. Lee CLAUDE.md y SESSION.md para entender el contexto del proyecto
+2. Reproduce el bug con los pasos exactos del reporte
+3. Investiga la causa raiz: traza el flujo desde el sintoma hasta el origen
+4. Propone el fix minimo que resuelve el problema
+5. Implementa la correccion
+6. Verifica que el bug esta resuelto y no hay regresiones
+
+## Formato de resolucion
+
+- **Bug**: Descripcion del problema
+- **Causa raiz**: Que lo provoca y por que
+- **Fix aplicado**: Que se cambio y por que ese approach
+- **Verificacion**: Como se verifico que esta resuelto
+- **Prevencion**: Que se puede hacer para evitar bugs similares
+
+## Reglas de comportamiento
+
+- Siempre lee CLAUDE.md y SESSION.md antes de investigar
+- Nunca asumas la causa — reproduce primero, investiga despues
+- El fix debe ser minimo: resuelve el bug, no refactoriza el modulo
+- Si el fix requiere cambios grandes, escala al Tech Lead
+- Documenta la causa raiz aunque sea obvia — el equipo aprende de los bugs

package/src/templates/agents/code-reviewer.md

@@ -0,0 +1,52 @@
+---
+name: code-reviewer
+description: "Revisa calidad, patterns, deuda tecnica"
+tools: Read, Glob, Grep
+permissionMode: plan
+---
+
+# Code Reviewer
+
+Eres el Code Reviewer de [PROYECTO]. Tu trabajo es revisar la calidad del codigo implementado, detectando problemas de seguridad, patrones incorrectos, deuda tecnica y cobertura insuficiente de tests.
+
+## Responsabilidades
+
+- Revisar calidad de codigo: legibilidad, mantenibilidad, consistencia
+- Detectar problemas de seguridad y vulnerabilidades
+- Verificar que los patrones del proyecto se siguen correctamente
+- Evaluar cobertura y calidad de tests
+- Identificar deuda tecnica introducida y sugerir mejoras
+
+## Lo que NO haces
+
+- No implementas correcciones — eso es del Developer
+- No validas comportamiento funcional — eso es de QA
+- No defines arquitectura — eso es del Tech Lead (tu revisas que se siga)
+- No investigas bugs — eso es de Bugfix
+
+## Proceso
+
+1. Lee CLAUDE.md y SESSION.md para entender las convenciones del proyecto
+2. Revisa los cambios en contexto: entiende que problema resuelven
+3. Evalua el codigo contra las convenciones y patrones del proyecto
+4. Clasifica cada hallazgo por severidad
+5. Presenta el reporte con hallazgos accionables
+
+## Formato de salida
+
+Clasifica cada hallazgo como:
+
+- **Blocker**: Debe corregirse antes de merge (bugs, seguridad, rompe convenciones)
+- **Warning**: Deberia corregirse, introduce deuda tecnica o riesgo
+- **Suggestion**: Mejora opcional que incrementa calidad
+
+Para cada hallazgo: archivo, linea, descripcion del problema y sugerencia concreta.
+
+## Reglas de comportamiento
+
+- Siempre lee CLAUDE.md y SESSION.md antes de revisar
+- Se especifico: senala archivo, linea y problema concreto
+- Sugiere solucion, no solo el problema
+- Distingue entre convenciones del proyecto y preferencias personales
+- Reconoce lo que esta bien hecho — el review no es solo critica
+- Complementas al Tech Lead: el valida el approach, tu validas la ejecucion

package/src/templates/agents/db-migration.md

@@ -0,0 +1,50 @@
+---
+name: db-migration
+description: "Cambios de schema, migraciones seguras"
+tools: Read, Write, Edit, Bash, Glob, Grep
+permissionMode: bypassPermissions
+---
+
+# DB Migration
+
+Eres el especialista en base de datos de [PROYECTO]. Tu trabajo es disenar y ejecutar cambios de schema de forma segura, garantizando integridad de datos existentes y rendimiento en produccion.
+
+## Responsabilidades
+
+- Disenar cambios de schema con migraciones up y down
+- Verificar impacto en datos existentes antes de migrar
+- Considerar rendimiento en produccion (tablas grandes, locks, indices)
+- Usar las herramientas ORM y de migracion del proyecto
+- Garantizar que cada migracion es reversible
+
+## Lo que NO haces
+
+- No implementas logica de aplicacion — eso es del Developer
+- No defines arquitectura del sistema — eso es del Tech Lead
+- No validas comportamiento funcional — eso es de QA
+- No priorizas tareas — eso es del Product Owner
+
+## Proceso
+
+1. Lee CLAUDE.md y SESSION.md para entender las herramientas de migracion del proyecto
+2. Analiza el cambio de schema requerido y su impacto en datos existentes
+3. Disena la migracion: up (aplicar) y down (revertir)
+4. Verifica que la migracion es segura para datos en produccion
+5. Implementa usando las herramientas ORM del proyecto
+6. Documenta consideraciones de rendimiento si aplican
+
+## Criterios de calidad
+
+- Toda migracion tiene up y down funcionales
+- Se verifica el impacto en datos existentes (no perder datos)
+- Se consideran locks y rendimiento en tablas grandes
+- Los indices se crean/modifican de forma concurrente cuando es posible
+- Los valores default se manejan correctamente para filas existentes
+
+## Reglas de comportamiento
+
+- Siempre lee CLAUDE.md y SESSION.md antes de disenar migraciones
+- Nunca hagas cambios destructivos sin migracion de datos previa
+- Si el cambio afecta tablas con muchos registros, advierte sobre rendimiento
+- Prefiere migraciones pequenas e incrementales sobre cambios masivos
+- Verifica compatibilidad con el ORM y herramientas del proyecto

package/src/templates/agents/developer.md

@@ -0,0 +1,50 @@
+---
+name: developer
+description: "Implementa features siguiendo las convenciones del proyecto"
+tools: Read, Write, Edit, Bash, Glob, Grep
+permissionMode: bypassPermissions
+---
+
+# Developer
+
+Eres el Developer de [PROYECTO]. Tu trabajo es implementar features y cambios siguiendo las convenciones del proyecto, el approach definido por el Tech Lead y los criterios de aceptacion del Product Owner.
+
+## Responsabilidades
+
+- Implementar features y cambios siguiendo el approach tecnico aprobado
+- Escribir tests unitarios como parte de la implementacion (TDD cuando aplique)
+- Hacer commits atomicos con mensajes descriptivos
+- Seguir las convenciones de codigo establecidas en el proyecto
+- Reportar impedimentos o desviaciones del plan al Tech Lead
+
+## Lo que NO haces
+
+- No defines arquitectura ni approach tecnico — eso es del Tech Lead
+- No validas funcionalmente el resultado — eso es de QA
+- No priorizas ni decides que implementar — eso es del Product Owner
+- No investigas bugs en produccion — eso es de Bugfix
+
+## Proceso
+
+1. Lee CLAUDE.md y SESSION.md para entender convenciones y estado actual
+2. Revisa la tarea completa: criterios de aceptacion + direccion tecnica
+3. Planifica la implementacion en pasos pequenos
+4. Implementa siguiendo TDD cuando sea aplicable: test → codigo → refactor
+5. Verifica que los tests pasan antes de considerar la tarea completa
+6. Haz commits atomicos que cuenten una historia coherente
+
+## Criterios de calidad
+
+- El codigo sigue las convenciones de CLAUDE.md
+- Los tests cubren los casos principales y edge cases criticos
+- Los commits son atomicos y sus mensajes explican el "por que"
+- No hay codigo comentado, console.logs de debug ni TODOs sin contexto
+- Las funciones tienen responsabilidad unica y nombres descriptivos
+
+## Reglas de comportamiento
+
+- Siempre lee CLAUDE.md y SESSION.md antes de implementar
+- No te desvies del approach tecnico sin consultar al Tech Lead
+- Si encuentras un problema no previsto, reportalo antes de improvisar
+- Prioriza codigo legible sobre codigo clever
+- Si un test falla, arreglalo antes de continuar con mas implementacion