guild-agents 0.0.1 → 0.1.0

package/src/templates/skills/guild-specialize/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: guild-specialize
+description: "Enriquece CLAUDE.md explorando el proyecto y especializa los agentes al stack real"
+user-invocable: true
+---
+
+# Guild Specialize
+
+Explora el proyecto real del usuario y enriquece toda la configuracion de Guild con informacion concreta del stack, arquitectura y convenciones detectadas.
+
+Este skill se ejecuta una vez despues de `guild init`. Transforma los placeholders genericos en informacion real del proyecto.
+
+## Cuando usarlo
+
+- Inmediatamente despues de ejecutar `guild init`
+- Cuando se agrega un stack nuevo al proyecto (nueva base de datos, nuevo framework)
+- Cuando la estructura del proyecto cambio significativamente
+
+## Proceso
+
+### Paso 1 — Leer contexto base
+
+Lee los archivos de configuracion de Guild:
+
+- `CLAUDE.md` — instrucciones actuales (contiene placeholders `[PENDIENTE: guild-specialize]`)
+- `PROJECT.md` — identidad y stack declarado durante init
+- `SESSION.md` — estado de sesion actual
+
+### Paso 2 — Explorar el proyecto real
+
+Investiga la estructura real del proyecto buscando:
+
+**Dependencias y versiones:**
+- `package.json` (Node.js/frontend)
+- `pom.xml` o `build.gradle` (Java)
+- `requirements.txt` o `pyproject.toml` (Python)
+- `Gemfile` (Ruby)
+- `go.mod` (Go)
+- `Cargo.toml` (Rust)
+
+**Arquitectura y estructura:**
+- Carpetas `src/`, `app/`, `lib/`, `pkg/`, `internal/`
+- Patron de organizacion: por capas, por features, por dominio
+- Entry points del proyecto
+
+**Configuracion y convenciones:**
+- `tsconfig.json`, `eslint.config.*`, `.prettierrc`
+- `.env.example`, `.env.local` (variables de entorno — NO leer `.env` real)
+- `Dockerfile`, `docker-compose.yml`
+- CI/CD: `.github/workflows/`, `.gitlab-ci.yml`
+
+**Base de datos y migraciones:**
+- Carpeta `migrations/`, `db/`, `prisma/`, `drizzle/`
+- ORM o query builder configurado
+- Schema existente
+
+**Documentacion existente:**
+- `README.md` — vision general del proyecto
+- Documentacion interna en `docs/`
+
+### Paso 3 — Enriquecer CLAUDE.md
+
+Reemplaza todos los placeholders `[PENDIENTE: guild-specialize]` en CLAUDE.md con informacion real:
+
+- **Stack con versiones exactas**: extraidas de los archivos de dependencias
+- **Estructura de carpetas explicada**: que hace cada carpeta principal
+- **Convenciones de codigo detectadas**: linter, formatter, estilo de imports
+- **Patrones de arquitectura identificados**: MVC, hexagonal, modular, etc.
+- **Variables de entorno conocidas**: listadas desde `.env.example`
+- **Limitaciones y deuda tecnica visible**: dependencias desactualizadas, TODOs encontrados
+- **Comandos utiles del proyecto**: scripts de npm/make/cargo detectados
+
+### Paso 4 — Especializar agentes
+
+Para cada agente en `.claude/agents/*.md`, agrega contexto especifico del proyecto:
+
+- **advisor.md**: dominio real del proyecto, usuarios objetivo
+- **tech-lead.md**: stack especifico, patrones detectados, decisiones de arquitectura
+- **product-owner.md**: funcionalidades existentes, backlog visible
+- **developer.md**: convenciones de codigo, framework principal, estructura de archivos
+- **code-reviewer.md**: reglas de lint, patrones del proyecto, anti-patrones a vigilar
+- **qa.md**: framework de testing, comandos para ejecutar tests, cobertura actual
+- **bugfix.md**: stack de debugging, logs, herramientas disponibles
+- **db-migration.md**: ORM, herramienta de migraciones, schema actual (si aplica)
+
+Usa el tool `Task` para invocar cada agente leyendo su `.claude/agents/[nombre].md` si necesitas perspectiva especializada para enriquecer su configuracion.
+
+### Paso 5 — Confirmar
+
+Presenta un resumen de lo detectado:
+
+```
+Guild v1 especializado para [nombre-proyecto]
+
+Stack detectado:
+- [lista de tecnologias con versiones]
+
+Arquitectura:
+- [patron identificado]
+- [estructura principal]
+
+Agentes actualizados:
+- [lista de agentes con su especializacion aplicada]
+
+Ejecuta /status para ver el estado completo.
+```
+
+## Notas importantes
+
+- NUNCA leas archivos `.env` reales — solo `.env.example` o `.env.local`
+- Si no puedes detectar algo con certeza, pregunta al usuario en vez de asumir
+- Prioriza precision sobre completitud — es mejor decir "no detectado" que inventar
+- Los agentes deben quedar especializados al stack real, no generico

package/src/templates/skills/new-feature/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: new-feature
+description: "Crea branch y scaffold para una nueva feature"
+user-invocable: true
+---
+
+# New Feature
+
+Prepara el entorno para trabajar en una nueva feature: crea branch, actualiza SESSION.md y opcionalmente crea un GitHub Issue.
+
+## Cuando usarlo
+
+- Al iniciar una feature nueva antes de escribir codigo
+- Cuando quieres dejar registrado el contexto de la feature en SESSION.md
+
+## Uso
+
+`/new-feature [nombre-de-la-feature]`
+
+## Proceso
+
+### Paso 1 — Obtener nombre
+
+Si el usuario no proporciono nombre, preguntale:
+- Nombre corto para la feature (se usara en el nombre del branch)
+- Descripcion breve (1-2 oraciones)
+
+### Paso 2 — Crear branch
+
+Crea un branch git para la feature:
+
+```bash
+git checkout -b feature/[nombre-de-la-feature]
+```
+
+Si el branch ya existe, pregunta si quiere cambiarse a el o crear uno nuevo.
+
+### Paso 3 — Actualizar SESSION.md
+
+Actualiza SESSION.md con el contexto de la nueva feature:
+
+- **Fecha:** fecha actual
+- **Tarea en curso:** nombre de la feature
+- **Estado:** Feature iniciada — pendiente de implementacion
+
+### Paso 4 — GitHub Issue (opcional)
+
+Si el proyecto tiene integracion GitHub configurada en PROJECT.md:
+1. Pregunta si quiere crear un GitHub Issue para la feature
+2. Si acepta, crea el issue con `gh issue create`
+3. Registra la URL del issue en SESSION.md
+
+### Paso 5 — Confirmar
+
+Confirma al usuario:
+- Branch creado: `feature/[nombre]`
+- SESSION.md actualizado
+- GitHub Issue creado (si aplica)
+- Sugiere: "Ejecuta /build-feature para implementar la feature completa"

package/src/templates/skills/qa-cycle/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: qa-cycle
+description: "Ciclo QA + bugfix hasta que pase"
+user-invocable: true
+---
+
+# QA Cycle
+
+Ejecuta un ciclo de validacion QA seguido de bugfix hasta que todos los criterios pasen limpio. Util para validar implementaciones sin el pipeline completo de build-feature.
+
+## Cuando usarlo
+
+- Despues de implementar cambios que necesitan validacion
+- Para verificar que una correccion de bug no introdujo regresiones
+- Como ciclo final antes de crear un PR
+
+## Uso
+
+`/qa-cycle`
+
+## Proceso
+
+### Paso 1 — Validacion QA
+
+Invoca el agente QA usando Task tool:
+1. Lee `.claude/agents/qa.md` para asumir el rol de QA
+2. Lee CLAUDE.md y SESSION.md para contexto
+3. Revisa los criterios de aceptacion de la tarea en curso (si existen en SESSION.md)
+4. Ejecuta los tests del proyecto
+5. Valida edge cases y escenarios de error
+6. Reporta resultados
+
+### Paso 2 — Bugfix (si hay bugs)
+
+Si QA reporta bugs, invoca el agente Bugfix usando Task tool:
+1. Lee `.claude/agents/bugfix.md` para asumir el rol de Bugfix
+2. Recibe el reporte de bugs de QA como input
+3. Diagnostica la causa raiz de cada bug
+4. Implementa la correccion minima
+5. Verifica que el fix resuelve el problema
+
+### Paso 3 — Re-validacion
+
+Vuelve al Paso 1 para re-validar despues del bugfix.
+Maximo 3 ciclos de QA-bugfix para evitar loops infinitos.
+
+### Paso 4 — Resultado final
+
+Presenta el resultado:
+- **Aprobado**: Todos los criterios pasan, no hay bugs pendientes
+- **Con advertencias**: Pasa pero hay warnings menores
+- **Rechazado**: Hay bugs criticos que no se pudieron resolver — escalar al Tech Lead
+
+Actualiza SESSION.md con el resultado del ciclo QA.

package/src/templates/skills/review/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: review
+description: "Code review standalone sobre el diff actual"
+user-invocable: true
+---
+
+# Review
+
+Ejecuta un code review independiente sobre los cambios actuales del proyecto. Invoca al agente Code Reviewer para analizar calidad, patrones, seguridad y deuda tecnica.
+
+## Cuando usarlo
+
+- Antes de crear un PR
+- Para revisar cambios propios antes de pedir review a otros
+- Cuando quieres una segunda opinion sobre el codigo que escribiste
+
+## Uso
+
+`/review`
+
+## Proceso
+
+### Paso 1 — Obtener diff
+
+Obtiene los cambios actuales:
+1. Primero intenta `git diff --staged` (cambios en staging)
+2. Si no hay cambios en staging, usa `git diff` (cambios sin stage)
+3. Si no hay ningun cambio, informa que no hay nada que revisar
+
+### Paso 2 — Invocar Code Reviewer
+
+Invoca al agente Code Reviewer usando Task tool:
+1. Lee `.claude/agents/code-reviewer.md` para asumir el rol
+2. Lee CLAUDE.md para entender las convenciones del proyecto
+3. Revisa el diff completo
+4. Clasifica cada hallazgo por severidad:
+   - **Blocker**: Debe corregirse antes de merge
+   - **Warning**: Deberia corregirse, introduce deuda tecnica
+   - **Suggestion**: Mejora opcional
+
+### Paso 3 — Presentar hallazgos
+
+Presenta el reporte organizado por severidad:
+- Cantidad total de hallazgos por tipo
+- Detalle de cada hallazgo: archivo, descripcion, sugerencia de correccion
+- Veredicto final: Aprobado / Aprobado con warnings / Bloqueado
+
+Si hay blockers, sugiere corregirlos y ejecutar `/review` de nuevo.

package/src/templates/skills/session-end/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: session-end
+description: "Guarda estado actual en SESSION.md"
+user-invocable: true
+---
+
+# Session End
+
+Guarda el estado actual del trabajo en SESSION.md para poder retomarlo en la siguiente sesion. Ejecuta este skill antes de cerrar la sesion de trabajo.
+
+## Cuando usarlo
+
+- Antes de cerrar la sesion de trabajo
+- Cuando necesitas pausar y quieres guardar el contexto
+
+## Uso
+
+`/session-end`
+
+## Proceso
+
+### Paso 1 — Recopilar estado actual
+
+Analiza el estado actual del trabajo:
+- Que tarea estaba en curso
+- En que fase del pipeline se encuentra (si aplica)
+- Que archivos se modificaron (via `git status`)
+- Que commits se hicieron en esta sesion
+
+### Paso 2 — Actualizar SESSION.md
+
+Actualiza SESSION.md con la siguiente informacion:
+
+- **Fecha:** fecha actual
+- **Tarea en curso:** nombre de la tarea o "ninguna"
+- **GitHub Issue:** URL del issue asociado (si existe)
+- **Agente activo:** ultimo agente utilizado o "ninguno"
+- **Estado:** descripcion concreta de donde quedo el trabajo
+
+**Contexto relevante:**
+- Decisiones tomadas en esta sesion
+- Problemas encontrados y como se resolvieron
+- Informacion importante para retomar
+
+**Proximos pasos:**
+- Las 2-3 acciones concretas mas importantes al retomar
+- Skill sugerido para continuar (ej: "ejecutar /build-feature para continuar desde Fase 4")
+
+### Paso 3 — Confirmar
+
+Confirma al usuario:
+- SESSION.md actualizado con el estado actual
+- Proximos pasos registrados
+- Puedes cerrar la sesion con seguridad

package/src/templates/skills/session-start/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: session-start
+description: "Carga contexto y retoma trabajo desde SESSION.md"
+user-invocable: true
+---
+
+# Session Start
+
+Carga el contexto del proyecto y retoma el trabajo desde donde se dejo en la sesion anterior. Este es el primer skill que debes ejecutar al iniciar una sesion de trabajo.
+
+## Cuando usarlo
+
+- Al inicio de cada sesion de trabajo con el proyecto
+- Cuando quieres retomar el contexto despues de una pausa
+
+## Uso
+
+`/session-start`
+
+## Proceso
+
+### Paso 1 — Cargar contexto
+
+Lee los archivos de estado de Guild:
+- `CLAUDE.md` — instrucciones, convenciones y reglas del proyecto
+- `SESSION.md` — estado de la ultima sesion, tarea en curso, proximos pasos
+- `PROJECT.md` — identidad del proyecto, stack, agentes configurados
+
+### Paso 2 — Presentar estado
+
+Muestra un resumen de la sesion anterior:
+- Fecha de la ultima sesion
+- Tarea en curso (si existe)
+- Estado en que quedo el trabajo
+- Decisiones tomadas previamente
+- Proximos pasos registrados
+
+### Paso 3 — Sugerir como continuar
+
+Si hay tarea en curso:
+- Muestra el estado de la tarea
+- Sugiere continuar con el skill apropiado (ej: `/build-feature` si esta en implementacion)
+- Muestra los proximos pasos registrados en SESSION.md
+
+Si no hay tarea en curso, sugiere opciones:
+- `/build-feature [descripcion]` — para implementar una feature nueva
+- `/new-feature [nombre]` — para preparar el entorno de una feature
+- `/status` — para ver el estado general del proyecto
+- `/council [pregunta]` — para debatir una decision importante
+
+### Paso 4 — Actualizar sesion
+
+Actualiza SESSION.md con la fecha actual para registrar que la sesion inicio.

package/src/templates/skills/status/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: status
+description: "Muestra estado actual del proyecto y sesion"
+user-invocable: true
+---
+
+# Status
+
+Muestra un resumen completo del estado actual del proyecto, la sesion activa y los recursos disponibles de Guild.
+
+## Cuando usarlo
+
+- Al inicio de una sesion para orientarte
+- Para verificar que Guild esta correctamente configurado
+- Para ver que agentes y skills estan disponibles
+
+## Uso
+
+`/status`
+
+## Proceso
+
+### Paso 1 — Leer archivos de estado
+
+Lee los archivos de configuracion de Guild:
+- `CLAUDE.md` — instrucciones y convenciones del proyecto
+- `PROJECT.md` — identidad, stack y agentes configurados
+- `SESSION.md` — estado de la sesion actual
+
+### Paso 2 — Presentar estado
+
+Muestra el resumen con el siguiente formato:
+
+```
+Guild v1 — [nombre del proyecto]
+
+Sesion actual:
+- Fecha: [fecha de SESSION.md]
+- Tarea en curso: [tarea o "ninguna"]
+- Estado: [estado actual]
+
+Stack:
+- [tecnologias listadas en PROJECT.md]
+
+Agentes disponibles:
+- [lista de archivos .md en .claude/agents/]
+
+Skills disponibles:
+- [lista de directorios en .claude/skills/]
+
+Proximos pasos:
+- [extraidos de SESSION.md]
+```
+
+### Paso 3 — Sugerir acciones
+
+Si no hay tarea en curso, sugiere:
+- `/build-feature` para implementar algo nuevo
+- `/new-feature` para preparar el entorno de una feature
+- `/council` para debatir una decision
+
+Si hay tarea en curso, sugiere continuar con el skill apropiado segun el estado.

package/src/utils/files.js

@@ -0,0 +1,82 @@
+/**
+ * files.js — Utilidades de sistema de archivos para Guild v1
+ */
+
+import { mkdirSync, copyFileSync, existsSync, readdirSync, readFileSync } from 'fs';
+import { join, dirname } 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 8 agentes v1.
+ */
+export function getAgentNames() {
+  return [
+    'advisor',
+    'product-owner',
+    'tech-lead',
+    'developer',
+    'code-reviewer',
+    'qa',
+    'bugfix',
+    'db-migration',
+  ];
+}
+
+/**
+ * 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');
+}

package/src/utils/generators.js

@@ -0,0 +1,104 @@
+/**
+ * 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
+
+## 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');
+}