guild-agents 0.1.0 → 0.2.1

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

@@ -20,20 +20,32 @@ Ejecuta un code review independiente sobre los cambios actuales del proyecto. In
 
 ## Proceso
 
-### Paso 1 — Obtener diff
+### Paso 1 — Obtener diff y estado de verificacion
 
 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
 
+Ejecuta verificacion automatizada para dar contexto al reviewer:
+
+4. Ejecuta tests del proyecto (ej: `npm test`) — captura resultado
+5. Ejecuta lint del proyecto (ej: `npm run lint`) — captura resultado
+6. Incluye ambos resultados como contexto para el Code Reviewer
+
+Nota: El Code Reviewer no tiene acceso a Bash (solo Read, Glob, Grep), por eso los tests y lint se ejecutan aqui antes de invocar al reviewer.
+
 ### 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:
+3. Recibe el diff completo + resultados de tests y lint del Paso 1
+4. Si tests o lint fallaron, esto es automaticamente un hallazgo Blocker
+5. Revisa el diff completo
+6. Clasifica cada hallazgo por severidad:
    - **Blocker**: Debe corregirse antes de merge
    - **Warning**: Deberia corregirse, introduce deuda tecnica
    - **Suggestion**: Mejora opcional
@@ -41,8 +53,24 @@ Invoca al agente Code Reviewer usando Task tool:
 ### 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.
+
+## Example Session
+
+```text
+User: /review
+
+Reviewing diff: 4 files changed, +127 -34
+
+Findings:
+- [Warning] src/api/users.js:45 — No input validation on email parameter
+- [Suggestion] src/utils/format.js:12 — Consider using Intl.DateTimeFormat
+- [Blocker] src/db/queries.js:78 — SQL injection vulnerability in raw query
+
+1 blocker, 1 warning, 1 suggestion.
+```

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

@@ -22,6 +22,7 @@ Guarda el estado actual del trabajo en SESSION.md para poder retomarlo en la sig
 ### 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`)
@@ -38,17 +39,46 @@ Actualiza SESSION.md con la siguiente informacion:
 - **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
+### Paso 3 — Commit WIP if uncommitted work exists
+
+If there are uncommitted changes, create a checkpoint commit:
+
+```bash
+git add -A
+git commit -m "wip: session paused — [brief description of current state]"
+```
+
+This ensures no work is lost between sessions. Never leave uncommitted changes across session boundaries.
+
+## Example Session
+
+```text
+User: /session-end
+
+Saving session state...
+Task: user-preferences
+Phase: 4 — Implementation (in progress)
+Files modified: 3 files
+WIP committed: wip: session paused — user-preferences phase 4
+
+SESSION.md updated. Safe to close.
+```
+
+### Paso 4 — Confirmar
 
 Confirma al usuario:
+
 - SESSION.md actualizado con el estado actual
+- WIP committed (if applicable)
 - Proximos pasos registrados
 - Puedes cerrar la sesion con seguridad

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

@@ -22,32 +22,62 @@ Carga el contexto del proyecto y retoma el trabajo desde donde se dejo en la ses
 ### 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
+### Paso 2 — Detect resumable work
+
+Check for `wip:` checkpoint commits on active branches:
+
+```bash
+git branch --list "feature/*" --list "fix/*" | while read branch; do
+  git log --oneline "$branch" -1 | grep "^wip:" && echo "Resumable: $branch"
+done
+```
+
+If `wip:` commits are found, present them to the user with the phase they were in when interrupted.
+
+### Paso 3 — 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
+- **Resumable pipelines** (if wip: commits detected)
 
-### Paso 3 — Sugerir como continuar
+### Paso 4 — 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
+### Paso 5 — Actualizar sesion
 
 Actualiza SESSION.md con la fecha actual para registrar que la sesion inicio.
+
+## Example Session
+
+```text
+User: /session-start
+
+Loading context...
+Last session: 2026-02-22
+Task in progress: user-preferences (Phase 4 — Implementation)
+Resumable: feature/user-preferences (wip: phase 3 complete)
+
+Suggested: Continue with /build-feature to resume implementation.
+```

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

@@ -23,6 +23,7 @@ Muestra un resumen completo del estado actual del proyecto, la sesion activa y l
 ### 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
@@ -31,7 +32,7 @@ Lee los archivos de configuracion de Guild:
 
 Muestra el resumen con el siguiente formato:
 
-```
+```text
 Guild v1 — [nombre del proyecto]
 
 Sesion actual:
@@ -55,8 +56,26 @@ Proximos pasos:
 ### 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.
+
+## Example Session
+
+```text
+User: /status
+
+Guild — MyProject
+Stack: Node.js 20, React 18, PostgreSQL
+
+Session: 2026-02-23
+Task: Implementing user preferences
+State: Phase 4 — Developer implementing
+
+Agents: advisor, product-owner, tech-lead, developer, code-reviewer, qa, bugfix, db-migration
+Skills: guild-specialize, build-feature, new-feature, council, qa-cycle, review, dev-flow,
+  status, session-start, session-end
+```

package/src/utils/files.js

@@ -3,7 +3,7 @@
  */
 
 import { mkdirSync, copyFileSync, existsSync, readdirSync, readFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -12,7 +12,7 @@ const AGENTS_DIR = join('.claude', 'agents');
 const SKILLS_DIR = join('.claude', 'skills');
 
 /**
- * Lista los nombres de los 8 agentes v1.
+ * Lista los nombres de los 9 agentes v1.
  */
 export function getAgentNames() {
   return [
@@ -24,6 +24,7 @@ export function getAgentNames() {
     'qa',
     'bugfix',
     'db-migration',
+    'platform-expert',
   ];
 }
 
@@ -80,3 +81,23 @@ export function readSessionMd() {
   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

@@ -61,6 +61,13 @@ ${data.stack}
 - 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

package/src/utils/github.js

@@ -4,9 +4,12 @@
  * 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 { execSync } from 'child_process';
+import { execFileSync } from 'node:child_process';
 
 const LABELS = [
   { name: 'backlog',      color: '8E8E8E', description: 'Tarea documentada, pendiente de iniciar' },
@@ -22,7 +25,7 @@ const LABELS = [
  */
 export function isGhAvailable() {
   try {
-    execSync('gh auth status', { stdio: 'ignore' });
+    execFileSync('gh', ['auth', 'status'], { stdio: 'ignore' });
     return true;
   } catch {
     return false;
@@ -43,10 +46,13 @@ export async function setupGithubLabels(repoUrl) {
 
   for (const label of LABELS) {
     try {
-      execSync(
-        `gh label create "${label.name}" --color "${label.color}" --description "${label.description}" --repo ${repo} --force`,
-        { stdio: 'ignore' }
-      );
+      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
     }
@@ -60,8 +66,14 @@ export function assignIssue(issueNumber, fromLabel, toLabel) {
   if (!isGhAvailable()) return;
 
   try {
-    execSync(`gh issue assign ${issueNumber} --assignee @me`, { stdio: 'ignore' });
-    execSync(`gh issue edit ${issueNumber} --add-label "${toLabel}" --remove-label "${fromLabel}"`, { stdio: 'ignore' });
+    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
   }
@@ -74,7 +86,9 @@ export function commentIssue(issueNumber, body) {
   if (!isGhAvailable()) return;
 
   try {
-    execSync(`gh issue comment ${issueNumber} --body "${body}"`, { stdio: 'ignore' });
+    execFileSync('gh', [
+      'issue', 'comment', String(issueNumber), '--body', body,
+    ], { stdio: 'ignore' });
   } catch {
     // Non-critical
   }
@@ -87,7 +101,9 @@ export function closeIssue(issueNumber, comment) {
   if (!isGhAvailable()) return;
 
   try {
-    execSync(`gh issue close ${issueNumber} --comment "${comment}"`, { stdio: 'ignore' });
+    execFileSync('gh', [
+      'issue', 'close', String(issueNumber), '--comment', comment,
+    ], { stdio: 'ignore' });
   } catch {
     // Non-critical
   }
@@ -100,10 +116,12 @@ export function createBugIssue(title, body, parentIssueNumber) {
   if (!isGhAvailable()) return null;
 
   try {
-    const result = execSync(
-      `gh issue create --title "${title}" --body "${body}" --label "bug"`,
-      { encoding: 'utf8' }
-    );
+    const result = execFileSync('gh', [
+      'issue', 'create',
+      '--title', title,
+      '--body', body,
+      '--label', 'bug',
+    ], { encoding: 'utf8' });
     const issueUrl = result.trim();
     const issueNumber = issueUrl.split('/').pop();