guild-agents 0.0.1 → 0.2.0

package/src/utils/files.js

@@ -0,0 +1,103 @@
+/**
+ * files.js — Utilidades de sistema de archivos para Guild v1
+ */
+
+import { mkdirSync, copyFileSync, existsSync, readdirSync, readFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+const AGENTS_DIR = join('.claude', 'agents');
+const SKILLS_DIR = join('.claude', 'skills');
+
+/**
+ * Lista los nombres de los 9 agentes v1.
+ */
+export function getAgentNames() {
+  return [
+    'advisor',
+    'product-owner',
+    'tech-lead',
+    'developer',
+    'code-reviewer',
+    'qa',
+    'bugfix',
+    'db-migration',
+    'platform-expert',
+  ];
+}
+
+/**
+ * Copia los templates de agentes y skills al proyecto del usuario.
+ */
+export async function copyTemplates() {
+  mkdirSync(AGENTS_DIR, { recursive: true });
+  mkdirSync(SKILLS_DIR, { recursive: true });
+
+  // Copy flat agent .md files
+  for (const name of getAgentNames()) {
+    const src = join(TEMPLATES_DIR, 'agents', `${name}.md`);
+    const dest = join(AGENTS_DIR, `${name}.md`);
+    if (existsSync(src)) {
+      copyFileSync(src, dest);
+    }
+  }
+
+  // Copy skill directories with SKILL.md
+  const skillsTemplate = join(TEMPLATES_DIR, 'skills');
+  if (existsSync(skillsTemplate)) {
+    const skills = readdirSync(skillsTemplate, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+
+    for (const skill of skills) {
+      const skillDir = join(SKILLS_DIR, skill);
+      mkdirSync(skillDir, { recursive: true });
+
+      const src = join(skillsTemplate, skill, 'SKILL.md');
+      const dest = join(skillDir, 'SKILL.md');
+      if (existsSync(src)) {
+        copyFileSync(src, dest);
+      }
+    }
+  }
+}
+
+/**
+ * Lee el contenido de PROJECT.md si existe.
+ */
+export function readProjectMd() {
+  const path = 'PROJECT.md';
+  if (!existsSync(path)) return null;
+  return readFileSync(path, 'utf8');
+}
+
+/**
+ * Lee el contenido de SESSION.md si existe.
+ */
+export function readSessionMd() {
+  const path = 'SESSION.md';
+  if (!existsSync(path)) return null;
+  return readFileSync(path, 'utf8');
+}
+
+/**
+ * Resuelve la raiz del proyecto Guild caminando hacia arriba desde startDir.
+ * Busca .claude/ o PROJECT.md como marcadores de un proyecto Guild.
+ * Retorna la ruta absoluta del proyecto o null si no se encuentra.
+ */
+export function resolveProjectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(join(dir, '.claude')) || existsSync(join(dir, 'PROJECT.md'))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      // Reached filesystem root without finding a project
+      return null;
+    }
+    dir = parent;
+  }
+}

package/src/utils/generators.js

@@ -0,0 +1,111 @@
+/**
+ * generators.js — Genera los archivos de estado del proyecto (v1)
+ */
+
+import { writeFileSync } from 'fs';
+
+/**
+ * Genera PROJECT.md con los datos del onboarding.
+ * V1: solo metadata cruda — CLAUDE.md tiene el contexto enriquecido.
+ */
+export async function generateProjectMd(data) {
+  const date = new Date().toISOString().split('T')[0];
+
+  let content = `# PROJECT.md
+> Generado por Guild v1 el ${date}
+
+## Proyecto
+- **Nombre:** ${data.name}
+- **Tipo:** ${data.type}
+- **Stack:** ${data.stack}
+- **Codigo existente:** ${data.hasExistingCode ? 'Si' : 'No'}
+`;
+
+  if (data.github?.repoUrl) {
+    content += `
+## GitHub
+- **Repositorio:** ${data.github.repoUrl}
+`;
+  }
+
+  writeFileSync('PROJECT.md', content, 'utf8');
+}
+
+/**
+ * Genera CLAUDE.md — documento central con placeholders para guild-specialize.
+ */
+export async function generateClaudeMd(data) {
+  const content = `# ${data.name}
+
+## Framework
+Este proyecto usa Guild. Leer SESSION.md al inicio de cada sesion.
+
+## Stack
+${data.stack}
+
+## Estructura del proyecto
+[PENDIENTE: guild-specialize]
+
+## Convenciones de codigo
+[PENDIENTE: guild-specialize]
+
+## Patrones de arquitectura
+[PENDIENTE: guild-specialize]
+
+## Variables de entorno
+[PENDIENTE: guild-specialize]
+
+## Reglas globales
+- No implementar sin plan aprobado
+- Actualizar SESSION.md al cerrar cada sesion
+- ESModules en todo el codigo
+- path.join() siempre para construir paths
+
+## Subagent rules
+- Guild agent roles (advisor, developer, tech-lead, etc.) are NOT Claude Code subagent_types
+- Always use \`subagent_type: "general-purpose"\` when spawning agents via Task tool
+- CLAUDE.md and SESSION.md changes must be committed separately from feature code
+- No \`git stash\` in automated pipelines — use \`wip:\` commits instead
+- Parallel agents must use git worktrees for isolation
+
+## Skills disponibles
+- /guild-specialize  — enriquecer CLAUDE.md explorando el proyecto real
+- /build-feature     — pipeline completo de desarrollo
+- /new-feature       — crear branch y scaffold para feature
+- /council           — debatir decisiones con multiples agentes
+- /review            — code review sobre el diff actual
+- /qa-cycle          — ciclo QA + bugfix
+- /status            — ver estado del proyecto
+- /dev-flow          — ver fase actual del pipeline
+- /session-start     — cargar contexto y retomar trabajo
+- /session-end       — guardar estado en SESSION.md
+`;
+
+  writeFileSync('CLAUDE.md', content, 'utf8');
+}
+
+/**
+ * Genera SESSION.md inicial.
+ */
+export async function generateSessionMd() {
+  const date = new Date().toISOString().split('T')[0];
+
+  const content = `# SESSION.md
+
+## Sesion activa
+- **Fecha:** ${date}
+- **Tarea en curso:** —
+- **Agente activo:** —
+- **Estado:** Proyecto recien inicializado con Guild v1
+
+## Contexto relevante
+- Onboarding completado. Ver PROJECT.md para datos del proyecto.
+- CLAUDE.md tiene placeholders — ejecutar /guild-specialize para enriquecer.
+
+## Proximos pasos
+1. Abrir Claude Code y ejecutar /guild-specialize
+2. Definir la primera feature con /build-feature
+`;
+
+  writeFileSync('SESSION.md', content, 'utf8');
+}

package/src/utils/github.js

@@ -0,0 +1,144 @@
+/**
+ * github.js — Integración con GitHub CLI (gh)
+ *
+ * Requiere que el usuario tenga gh instalado y autenticado.
+ * Todas las operaciones son no-bloqueantes — si gh no está disponible,
+ * Guild funciona normalmente sin integración GitHub.
+ *
+ * Uses execFileSync with array-based arguments to prevent shell injection
+ * through user-controlled strings (issue titles, bodies, labels).
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const LABELS = [
+  { name: 'backlog',      color: '8E8E8E', description: 'Tarea documentada, pendiente de iniciar' },
+  { name: 'in-progress',  color: '0075CA', description: 'En implementación' },
+  { name: 'in-review',    color: 'E4A800', description: 'En validación QA' },
+  { name: 'done',         color: '2EA44F', description: 'Completada y mergeada' },
+  { name: 'bug',          color: 'D73A4A', description: 'Bug reportado por QA' },
+  { name: 'blocked',      color: 'E99695', description: 'Bloqueada por dependencia' },
+];
+
+/**
+ * Verifica si gh CLI está instalado y autenticado.
+ */
+export function isGhAvailable() {
+  try {
+    execFileSync('gh', ['auth', 'status'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Configura los labels de estado en el repositorio GitHub.
+ */
+export async function setupGithubLabels(repoUrl) {
+  if (!isGhAvailable()) {
+    console.warn('gh CLI no disponible — saltando configuración de labels.');
+    return;
+  }
+
+  const repo = extractRepoFromUrl(repoUrl);
+  if (!repo) return;
+
+  for (const label of LABELS) {
+    try {
+      execFileSync('gh', [
+        'label', 'create', label.name,
+        '--color', label.color,
+        '--description', label.description,
+        '--repo', repo,
+        '--force',
+      ], { stdio: 'ignore' });
+    } catch {
+      // Label ya existe o error no crítico
+    }
+  }
+}
+
+/**
+ * Asigna un issue a @me y cambia su label de estado.
+ */
+export function assignIssue(issueNumber, fromLabel, toLabel) {
+  if (!isGhAvailable()) return;
+
+  try {
+    execFileSync('gh', [
+      'issue', 'assign', String(issueNumber), '--assignee', '@me',
+    ], { stdio: 'ignore' });
+    execFileSync('gh', [
+      'issue', 'edit', String(issueNumber),
+      '--add-label', toLabel,
+      '--remove-label', fromLabel,
+    ], { stdio: 'ignore' });
+  } catch {
+    // Non-critical
+  }
+}
+
+/**
+ * Agrega un comentario a un issue.
+ */
+export function commentIssue(issueNumber, body) {
+  if (!isGhAvailable()) return;
+
+  try {
+    execFileSync('gh', [
+      'issue', 'comment', String(issueNumber), '--body', body,
+    ], { stdio: 'ignore' });
+  } catch {
+    // Non-critical
+  }
+}
+
+/**
+ * Cierra un issue con un comentario.
+ */
+export function closeIssue(issueNumber, comment) {
+  if (!isGhAvailable()) return;
+
+  try {
+    execFileSync('gh', [
+      'issue', 'close', String(issueNumber), '--comment', comment,
+    ], { stdio: 'ignore' });
+  } catch {
+    // Non-critical
+  }
+}
+
+/**
+ * Crea un issue de bug referenciando una tarea padre.
+ */
+export function createBugIssue(title, body, parentIssueNumber) {
+  if (!isGhAvailable()) return null;
+
+  try {
+    const result = execFileSync('gh', [
+      'issue', 'create',
+      '--title', title,
+      '--body', body,
+      '--label', 'bug',
+    ], { encoding: 'utf8' });
+    const issueUrl = result.trim();
+    const issueNumber = issueUrl.split('/').pop();
+
+    if (parentIssueNumber) {
+      commentIssue(parentIssueNumber, `Bug encontrado: ${issueUrl}`);
+    }
+
+    return { number: issueNumber, url: issueUrl };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extrae "owner/repo" de una URL de GitHub.
+ */
+function extractRepoFromUrl(url) {
+  const match = url.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/);
+  return match ? match[1] : null;
+}

package/index.js

@@ -1 +0,0 @@
-// Guild Agents - coming soon