guild-agents 0.1.0 → 0.2.1

package/src/templates/agents/platform-expert.md

@@ -0,0 +1,89 @@
+---
+name: platform-expert
+description: "Diagnostica y resuelve problemas de integracion con Claude Code — permisos, subagentes, hooks, settings"
+---
+
+# Platform Expert
+
+Eres el Platform Expert de [PROYECTO]. Tu trabajo es diagnosticar y resolver problemas de integracion entre Guild y Claude Code, incluyendo permisos de herramientas, configuracion de subagentes, hooks, y settings.
+
+## Responsabilidades
+
+- Diagnosticar problemas de permisos en subagentes (Bash denied, tool access, etc.)
+- Configurar frontmatter de agentes para acceso correcto a herramientas
+- Implementar PreToolUse hooks para workarounds de permisos
+- Mantener compatibilidad con versiones de Claude Code
+- Documentar limitaciones de la plataforma y workarounds conocidos
+
+## Conocimiento especializado
+
+### Subagent Permission Model
+
+Claude Code subagents corren en modo `dontAsk` por defecto. No heredan permisos de `settings.json`. Para otorgar acceso a Bash:
+
+1. **Frontmatter `tools` field:** Declara herramientas disponibles explicitamente
+2. **Frontmatter `permissionMode`:** Controla nivel de permisos
+3. **PreToolUse hooks:** Workaround para auto-aprobar herramientas
+
+### Configuracion de agentes con Bash
+
+```yaml
+---
+name: agent-name
+description: "Description for delegation"
+tools: Read, Write, Edit, Bash, Glob, Grep
+permissionMode: bypassPermissions
+---
+```
+
+### Configuracion de agentes sin Bash (analisis)
+
+```yaml
+---
+name: agent-name
+description: "Description for delegation"
+tools: Read, Glob, Grep
+permissionMode: plan
+---
+```
+
+### PreToolUse Hook workaround
+
+Si `permissionMode` no funciona, usar hooks:
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\"}}'"
+```
+
+### Bugs conocidos de Claude Code
+
+- Issue #18950: Subagentes no heredan permisos de settings.json (OPEN)
+- Issue #14714: Subagentes no heredan tools del parent
+- Issue #21585: subagent_type "Bash" fabrica output en vez de ejecutar
+
+## Lo que NO haces
+
+- No implementas features de negocio — eso es del Developer
+- No defines arquitectura de aplicacion — eso es del Tech Lead
+- No evaluas estrategia — eso es del Advisor
+
+## Proceso
+
+1. Lee CLAUDE.md para entender la configuracion actual
+2. Identifica el problema de permisos/integracion
+3. Investiga la documentacion de Claude Code y issues conocidos
+4. Propone solucion con frontmatter, hooks, o settings
+5. Prueba la solucion con un subagente de test
+6. Documenta la solucion y workaround
+
+## Reglas de comportamiento
+
+- Siempre verifica la version de Claude Code antes de diagnosticar
+- Prioriza soluciones oficiales sobre workarounds
+- Documenta TODOS los workarounds con referencia al issue de GitHub
+- No asumas que un fix de platform funciona — siempre prueba

package/src/templates/agents/product-owner.md

@@ -1,6 +1,8 @@
 ---
 name: product-owner
 description: "Convierte ideas aprobadas en tareas concretas e implementables"
+tools: Read, Glob, Grep
+permissionMode: plan
 ---
 
 # Product Owner

package/src/templates/agents/qa.md

@@ -1,6 +1,8 @@
 ---
 name: qa
 description: "Testing, edge cases, regression"
+tools: Read, Write, Edit, Bash, Glob, Grep
+permissionMode: bypassPermissions
 ---
 
 # QA

package/src/templates/agents/tech-lead.md

@@ -1,6 +1,8 @@
 ---
 name: tech-lead
 description: "Define approach tecnico y arquitectura"
+tools: Read, Glob, Grep
+permissionMode: plan
 ---
 
 # Tech Lead

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

@@ -17,6 +17,22 @@ Pipeline completo para construir una feature de punta a punta con todos los agen
 
 `/build-feature [descripcion de la feature]`
 
+## Parallel Execution: Worktree Isolation
+
+When multiple build-feature pipelines run in parallel, each MUST use its own git worktree to avoid branch conflicts:
+
+```bash
+git worktree add .claude/worktrees/[branch-name] -b [branch-name] develop
+```
+
+All file operations within the pipeline must use the worktree directory as the working directory. After the PR is merged, clean up with:
+
+```bash
+git worktree remove .claude/worktrees/[branch-name]
+```
+
+When running a single build-feature, a simple `git checkout -b` is sufficient.
+
 ## Pipeline de 6 fases
 
 ### Fase 1 — Evaluacion (Advisor)
@@ -24,6 +40,7 @@ Pipeline completo para construir una feature de punta a punta con todos los agen
 **Agente:** Lee `.claude/agents/advisor.md` via Task tool
 **Input:** La descripcion de la feature proporcionada por el usuario
 **Proceso:**
+
 1. El Advisor evalua la feature contra la vision del proyecto
 2. Identifica riesgos, dependencias y conflictos con funcionalidad existente
 3. Emite evaluacion: Aprobado / Rechazado / Requiere ajustes
@@ -36,6 +53,7 @@ Pipeline completo para construir una feature de punta a punta con todos los agen
 **Agente:** Lee `.claude/agents/product-owner.md` via Task tool
 **Input:** La feature aprobada por el Advisor + sus observaciones
 **Proceso:**
+
 1. El Product Owner descompone la feature en tareas concretas
 2. Define criterios de aceptacion verificables para cada tarea
 3. Estima esfuerzo y sugiere orden de implementacion
@@ -47,6 +65,7 @@ Pipeline completo para construir una feature de punta a punta con todos los agen
 **Agente:** Lee `.claude/agents/tech-lead.md` via Task tool
 **Input:** Tareas del Product Owner + criterios de aceptacion
 **Proceso:**
+
 1. El Tech Lead define el approach de implementacion
 2. Identifica archivos a modificar, patrones a seguir, interfaces
 3. Anticipa riesgos tecnicos y propone mitigaciones
@@ -58,6 +77,7 @@ Pipeline completo para construir una feature de punta a punta con todos los agen
 **Agente:** Lee `.claude/agents/developer.md` via Task tool
 **Input:** Plan tecnico del Tech Lead + criterios de aceptacion del PO
 **Proceso:**
+
 1. El Developer implementa siguiendo el plan tecnico
 2. Escribe tests unitarios como parte de la implementacion
 3. Hace commits atomicos con mensajes descriptivos
@@ -65,35 +85,76 @@ Pipeline completo para construir una feature de punta a punta con todos los agen
 
 **Output:** Codigo implementado + tests + commits realizados
 
+### Gate pre-Review (obligatorio)
+
+Antes de avanzar a Fase 5, ejecutar verificacion automatizada:
+
+1. Ejecuta los comandos de test del proyecto (ej: `npm test`) — si falla, el Developer debe corregir antes de avanzar
+2. Ejecuta los comandos de lint del proyecto (ej: `npm run lint`) — si falla, el Developer debe corregir antes de avanzar
+3. Solo hacer checkpoint commit **despues** de que ambos pasen
+
+Este gate NO se puede saltar, incluso si el usuario solicito skip de fases. Los comandos concretos estan en la seccion "Comandos CLI" de CLAUDE.md.
+
 ### Fase 5 — Review (Code Reviewer)
 
 **Agente:** Lee `.claude/agents/code-reviewer.md` via Task tool
 **Input:** Los cambios implementados (git diff)
 **Proceso:**
+
 1. El Code Reviewer revisa calidad, patrones, seguridad y tests
 2. Clasifica hallazgos como Blocker, Warning o Suggestion
 
 **Output:** Reporte de review con hallazgos clasificados
 **Condicion de loop:** Si hay hallazgos de tipo Blocker, vuelve a **Fase 4** para que el Developer los corrija. Maximo 2 iteraciones de review-fix.
 
-### Fase 6 — QA
+### Fase 6 — QA (delega a /qa-cycle)
 
-**Agente:** Lee `.claude/agents/qa.md` via Task tool
-**Input:** Criterios de aceptacion del PO + codigo implementado
-**Proceso:**
-1. QA ejecuta los tests y valida criterios de aceptacion
-2. Prueba edge cases y escenarios de error
-3. Si encuentra bugs, reporta con pasos de reproduccion
+Ejecuta el skill `/qa-cycle` pasandole los criterios de aceptacion del PO como contexto. El qa-cycle se encarga de:
+
+1. Ejecutar tests y lint del proyecto
+2. Validar criterios de aceptacion
+3. Probar edge cases y escenarios de error
+4. Ciclo bugfix si hay problemas (maximo 3 ciclos)
+
+**Condicion de loop adicional:** Si el bugfix del qa-cycle introduce cambios significativos, vuelve a **Fase 5** (Review) para verificar. Maximo 2 ciclos de review-QA.
+
+## Checkpoint Commits
+
+After each phase completes, create a checkpoint commit to preserve progress. This ensures work survives session interruptions.
 
-**Output:** Reporte QA con resultado por cada criterio de aceptacion
-**Condicion de loop:** Si hay bugs:
-1. Invoca agente Bugfix (lee `.claude/agents/bugfix.md` via Task tool) para corregir
-2. Vuelve a **Fase 5** (Review) para verificar el fix
-3. Maximo 2 ciclos de bugfix-review-QA
+```bash
+git add -A
+git commit -m "wip: [feature-name] phase N complete — [phase-name]"
+```
+
+Pattern for each phase:
+
+- After Phase 1: `wip: [feature] phase 1 — advisor approved`
+- After Phase 2: `wip: [feature] phase 2 — PO spec ready`
+- After Phase 3: `wip: [feature] phase 3 — tech approach defined`
+- After Phase 4: `wip: [feature] phase 4 — implementation done`
+- After Phase 5: `wip: [feature] phase 5 — review passed`
+- After Phase 6: `wip: [feature] phase 6 — QA passed`
+
+Also update SESSION.md at each phase transition:
+
+```text
+- [timestamp] | build-feature | Phase N ([phase-name]) complete for [feature]
+```
+
+## Gate final (obligatorio antes de Finalizacion)
+
+Antes de declarar el pipeline como completado, ejecutar verificacion final:
+
+1. Ejecuta tests del proyecto — si falla, volver a Fase 6 (QA/Bugfix)
+2. Ejecuta lint del proyecto — si falla, volver a Fase 4 (Developer)
+3. Ambos deben pasar con exit code 0
+
+Este gate es la ultima red de seguridad. NO se puede saltar bajo ninguna circunstancia.
 
 ## Finalizacion
 
-Al completar todas las fases exitosamente:
+Al completar todas las fases y el gate final exitosamente:
 
 1. Presenta resumen del pipeline:
    - Feature implementada
@@ -107,8 +168,47 @@ Al completar todas las fases exitosamente:
    - Decisiones tomadas durante el pipeline
    - Proximos pasos si los hay
 
+3. Close the GitHub Issue (if applicable):
+   - Do NOT use `Closes #N` in PR description (only works when merging to default branch)
+   - After the PR is merged, run: `gh issue close N --comment "Resolved in PR #X"`
+
+## Subagent Configuration
+
+When spawning agents via the Task tool, use these `subagent_type` values:
+
+| Guild Agent Role | subagent_type to use |
+| --- | --- |
+| advisor, product-owner, tech-lead | `"general-purpose"` |
+| developer, bugfix | `"general-purpose"` |
+| code-reviewer, qa | `"general-purpose"` |
+
+**IMPORTANT:** Guild agent role names (advisor, developer, etc.) are NOT valid Claude Code subagent_types. Always use `"general-purpose"` for agents that need full tool access (Read, Write, Edit, Bash, Grep, Glob, etc.). Never use `"Bash"` alone — it lacks file editing tools.
+
+Example Task invocation:
+
+```text
+Task tool with:
+  subagent_type: "general-purpose"
+  prompt: "Read .claude/agents/developer.md and assume that role. Then: [task description]"
+```
+
+## Example Session
+
+```text
+User: /build-feature add dark mode toggle to settings page
+
+Phase 1 — Advisor: Approved. Low risk, aligns with UX roadmap.
+Phase 2 — PO: 3 tasks defined with acceptance criteria.
+Phase 3 — Tech Lead: Use CSS variables + context provider pattern.
+Phase 4 — Developer: Implemented ThemeContext, toggle component, CSS vars.
+Phase 5 — Review: Passed. 1 suggestion (memoize context value).
+Phase 6 — QA: All 3 acceptance criteria verified. 0 bugs.
+
+Feature complete. PR ready for merge.
+```
+
 ## Notas
 
-- Si el usuario quiere saltar fases (ej: "ya la evaluo, implementa directo"), permite saltar a Fase 4 pero advierte que se pierde validacion
+- Si el usuario quiere saltar fases (ej: "ya la evaluo, implementa directo"), permite saltar a Fase 4 pero advierte que se pierde validacion. Los gates de verificacion (pre-Review y final) NUNCA se saltan
 - El pipeline es secuencial: cada fase depende del output de la anterior
 - Los loops de review/QA tienen limite para evitar ciclos infinitos

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

@@ -31,6 +31,7 @@ Opcionalmente puedes especificar el tipo: `/council architecture [pregunta]`
 **Cuando aplica:** Decisiones sobre arquitectura, patrones, refactors grandes, tecnologias nuevas
 
 Invoca los 3 agentes EN PARALELO usando Task tool:
+
 - Task 1: Lee `.claude/agents/tech-lead.md` — perspectiva de arquitectura y coherencia tecnica
 - Task 2: Lee `.claude/agents/advisor.md` — perspectiva de viabilidad y riesgos de negocio
 - Task 3: Lee `.claude/agents/developer.md` — perspectiva de implementabilidad y pragmatismo
@@ -41,6 +42,7 @@ Invoca los 3 agentes EN PARALELO usando Task tool:
 **Cuando aplica:** Definir alcance de features, priorizar funcionalidades, evaluar propuestas de producto
 
 Invoca los 3 agentes EN PARALELO usando Task tool:
+
 - Task 1: Lee `.claude/agents/advisor.md` — perspectiva de dominio y vision estrategica
 - Task 2: Lee `.claude/agents/product-owner.md` — perspectiva de valor para el usuario y scope
 - Task 3: Lee `.claude/agents/tech-lead.md` — perspectiva de viabilidad tecnica y esfuerzo
@@ -51,6 +53,7 @@ Invoca los 3 agentes EN PARALELO usando Task tool:
 **Cuando aplica:** Decidir si abordar deuda tecnica, planificar refactors, evaluar calidad del codebase
 
 Invoca los 3 agentes EN PARALELO usando Task tool:
+
 - Task 1: Lee `.claude/agents/tech-lead.md` — perspectiva de impacto arquitectonico
 - Task 2: Lee `.claude/agents/developer.md` — perspectiva de costo de implementacion
 - Task 3: Lee `.claude/agents/code-reviewer.md` — perspectiva de calidad y riesgos
@@ -60,6 +63,7 @@ Invoca los 3 agentes EN PARALELO usando Task tool:
 ### Paso 1 — Identificar tipo de consejo
 
 Analiza la pregunta del usuario y determina que tipo de consejo aplica:
+
 - Si menciona arquitectura, patrones, tecnologias → **architecture**
 - Si menciona features, prioridades, scope, usuarios → **feature-scope**
 - Si menciona deuda tecnica, refactor, calidad, mantenibilidad → **tech-debt**
@@ -68,6 +72,7 @@ Analiza la pregunta del usuario y determina que tipo de consejo aplica:
 ### Paso 2 — Convocar agentes
 
 Invoca los 3 agentes correspondientes EN PARALELO usando Task tool. Cada agente:
+
 1. Lee su archivo `.claude/agents/[nombre].md` para asumir su rol
 2. Lee `CLAUDE.md` y `SESSION.md` para contexto del proyecto
 3. Analiza la pregunta desde su perspectiva especializada
@@ -77,7 +82,7 @@ Invoca los 3 agentes correspondientes EN PARALELO usando Task tool. Cada agente:
 
 Presenta las perspectivas de los 3 agentes de forma estructurada:
 
-```
+```text
 ## Council: [tipo]
 Pregunta: [la pregunta del usuario]
 
@@ -99,12 +104,39 @@ Pregunta: [la pregunta del usuario]
 ### Paso 4 — Solicitar decision
 
 Presenta opciones claras al usuario basadas en el debate:
+
 - Opcion A: [resumen de una posicion]
 - Opcion B: [resumen de otra posicion]
 - Opcion C: [compromiso o alternativa]
 
 Pide al usuario que decida. Si el usuario decide, documenta la decision en SESSION.md.
 
+## Subagent Configuration
+
+When spawning council agents via the Task tool, always use `subagent_type: "general-purpose"`. Guild agent role names (advisor, developer, tech-lead, etc.) are NOT valid Claude Code subagent_types.
+
+Example:
+
+```text
+Task tool with:
+  subagent_type: "general-purpose"
+  prompt: "Read .claude/agents/tech-lead.md and assume that role. Then: [debate question]"
+```
+
+## Example Session
+
+```text
+User: /council Should we migrate from REST to GraphQL?
+
+Council: Architecture
+
+Tech Lead — Recommends GraphQL for complex queries, keep REST for simple CRUD.
+Advisor — Risk is high mid-project. Suggests incremental adoption.
+Developer — Prefers REST simplicity. GraphQL adds tooling overhead.
+
+Consensus: Incremental adoption. New endpoints in GraphQL, existing stay REST.
+```
+
 ## Notas
 
 - Los agentes deben ser invocados en paralelo para evitar que uno influencie al otro

package/src/templates/skills/dev-flow/SKILL.md

@@ -23,6 +23,7 @@ Muestra la fase actual del pipeline de desarrollo y sugiere el siguiente paso. U
 ### Paso 1 — Leer estado
 
 Lee `SESSION.md` para determinar:
+
 - Si hay una feature en curso
 - En que fase del pipeline se encuentra
 - Que se completo y que falta
@@ -30,6 +31,7 @@ Lee `SESSION.md` para determinar:
 ### Paso 2 — Determinar fase actual
 
 Las fases del pipeline son:
+
 1. **Evaluacion** (Advisor) — go/no-go
 2. **Especificacion** (Product Owner) — criterios de aceptacion
 3. **Approach tecnico** (Tech Lead) — plan de implementacion
@@ -39,7 +41,7 @@ Las fases del pipeline son:
 
 ### Paso 3 — Presentar estado del flujo
 
-```
+```text
 Dev Flow — [nombre de la feature]
 
 [x] Fase 1 — Evaluacion (completada)
@@ -53,3 +55,15 @@ Siguiente paso: Ejecuta /build-feature para continuar desde la Fase 3.
 ```
 
 Si no hay feature en curso, informa que no hay pipeline activo y sugiere `/new-feature` o `/build-feature`.
+
+## Example Session
+
+```text
+User: /dev-flow
+
+Current pipeline: build-feature "add user preferences"
+Phase: 4 of 6 — Implementation
+Developer agent active.
+
+Next: Phase 5 — Code Review
+```

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

@@ -31,6 +31,7 @@ Lee los archivos de configuracion de Guild:
 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)
@@ -39,22 +40,26 @@ Investiga la estructura real del proyecto buscando:
 - `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/`
 
@@ -89,7 +94,7 @@ Usa el tool `Task` para invocar cada agente leyendo su `.claude/agents/[nombre].
 
 Presenta un resumen de lo detectado:
 
-```
+```text
 Guild v1 especializado para [nombre-proyecto]
 
 Stack detectado:
@@ -105,9 +110,47 @@ Agentes actualizados:
 Ejecuta /status para ver el estado completo.
 ```
 
+### Paso 6 — Commit enrichment immediately
+
+**CRITICAL:** After enriching CLAUDE.md and agent files, commit the changes immediately as their own atomic commit. Do NOT leave them as unstaged changes — they are vulnerable to `git stash` and other operations.
+
+```bash
+git add CLAUDE.md .claude/agents/*.md
+git commit -m "chore: enrich CLAUDE.md and agents via guild-specialize"
+```
+
+This ensures enrichment survives any subsequent git operations (stash, checkout, rebase).
+
+## Example Session
+
+```text
+User: /guild-specialize
+
+Guild Specialize analyzing project...
+
+Stack detected:
+- Node.js 20.11.0, TypeScript 5.3.3
+- React 18.2.0, Next.js 14.1.0
+- PostgreSQL via Prisma 5.9.0
+
+Architecture:
+- Next.js App Router (src/app/)
+- API routes in src/app/api/
+- Shared components in src/components/
+
+Agents updated:
+- developer.md: Specialized for Next.js + TypeScript
+- qa.md: Configured for Vitest + Playwright
+- db-migration.md: Configured for Prisma
+
+Run /status to see the full state.
+```
+
 ## 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
+- NEVER use `git stash` in automated pipelines — use `wip:` commits instead
+- CLAUDE.md changes must always be committed separately from feature code

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

@@ -22,12 +22,23 @@ Prepara el entorno para trabajar en una nueva feature: crea branch, actualiza SE
 ### 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
+### Paso 2 — Crear branch con worktree isolation
+
+When running in parallel with other agents, use git worktrees for isolation. When running standalone, a simple branch is sufficient.
+
+**For parallel execution (multiple build-features at once):**
+
+```bash
+git worktree add .claude/worktrees/feature-[nombre] -b feature/[nombre-de-la-feature] develop
+```
 
-Crea un branch git para la feature:
+All subsequent operations should use `.claude/worktrees/feature-[nombre]` as the working directory.
+
+**For standalone execution:**
 
 ```bash
 git checkout -b feature/[nombre-de-la-feature]
@@ -35,6 +46,8 @@ git checkout -b feature/[nombre-de-la-feature]
 
 Si el branch ya existe, pregunta si quiere cambiarse a el o crear uno nuevo.
 
+**Cleanup:** At skill exit, if using worktrees, the caller is responsible for cleanup via `git worktree remove .claude/worktrees/feature-[nombre]` after the PR is merged.
+
 ### Paso 3 — Actualizar SESSION.md
 
 Actualiza SESSION.md con el contexto de la nueva feature:
@@ -43,9 +56,22 @@ Actualiza SESSION.md con el contexto de la nueva feature:
 - **Tarea en curso:** nombre de la feature
 - **Estado:** Feature iniciada — pendiente de implementacion
 
+## Example Session
+
+```text
+User: /new-feature user-preferences
+
+Branch created: feature/user-preferences
+SESSION.md updated with feature context.
+GitHub Issue #42 created.
+
+Next: Run /build-feature to implement.
+```
+
 ### 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
@@ -53,6 +79,7 @@ Si el proyecto tiene integracion GitHub configurada en PROJECT.md:
 ### Paso 5 — Confirmar
 
 Confirma al usuario:
+
 - Branch creado: `feature/[nombre]`
 - SESSION.md actualizado
 - GitHub Issue creado (si aplica)

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

@@ -20,35 +20,64 @@ Ejecuta un ciclo de validacion QA seguido de bugfix hasta que todos los criterio
 
 ## Proceso
 
-### Paso 1 — Validacion QA
+### Paso 1 — Verificacion automatizada (obligatorio)
+
+Antes de invocar al agente QA, ejecutar los comandos de verificacion del proyecto. Los comandos concretos estan en la seccion "Comandos CLI" de CLAUDE.md:
+
+1. Ejecuta tests del proyecto (ej: `npm test`) — registra resultado y output
+2. Ejecuta lint del proyecto (ej: `npm run lint`) — registra resultado y output
+3. Si alguno falla, esto se convierte en input para el reporte QA como bug automatico de tipo Blocker
+
+### Paso 2 — 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
+3. Recibe los resultados de tests y lint del Paso 1
+4. Si tests o lint fallaron, incluirlos como bugs Blocker en el reporte
+5. Revisa los criterios de aceptacion de la tarea en curso (si existen en SESSION.md)
+6. Valida edge cases y escenarios de error
+7. Reporta resultados
+
+### Paso 3 — Bugfix (si hay bugs)
 
-### Paso 2 — Bugfix (si hay bugs)
+Si QA reporta bugs (incluyendo fallos de tests/lint), invoca el agente Bugfix usando Task tool:
 
-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
+6. Ejecuta tests y lint para confirmar que no introdujo regresiones
 
-### Paso 3 — Re-validacion
+### Paso 4 — Re-validacion
 
-Vuelve al Paso 1 para re-validar despues del bugfix.
-Maximo 3 ciclos de QA-bugfix para evitar loops infinitos.
+Vuelve al Paso 1 (verificacion automatizada) para re-validar despues del bugfix.
+Maximo 3 ciclos de verificacion-QA-bugfix para evitar loops infinitos.
 
-### Paso 4 — Resultado final
+### Paso 5 — 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.
+
+## Example Session
+
+```text
+User: /qa-cycle
+
+QA Cycle 1: 2 of 5 criteria pass. Bug: form validation missing on email field.
+Bugfix: Added email regex validation to UserForm component.
+QA Cycle 2: 5 of 5 criteria pass. 0 bugs.
+
+Result: Approved.
+```
+
+## Subagent Configuration
+
+When spawning QA or Bugfix agents via the Task tool, always use `subagent_type: "general-purpose"`. Guild agent role names are NOT valid Claude Code subagent_types.