---
name: nuevo-proyecto
description: Flujo para inicializar un proyecto de software nuevo. Recopila visión, restricciones técnicas y de negocio, stack tecnológico y contexto del equipo. Genera la carpeta .planning/ con PROYECTO.md, REQUISITOS.md y HOJA-RUTA.md como artefactos de arranque.
version: "1.0.0"
herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
exclusiones:
  - "No cargar para incorporar un proyecto existente al sistema SWL; usar el comando `/swl:adoptar-proyecto`."
  - "No cargar si `.planning/PROYECTO.md` ya existe y el objetivo es actualizar requisitos; editar ese archivo directamente."
  - "No cargar para generar solo el PLAN.md de una fase puntual sin visión de proyecto; usar `discutir-fase` + `planear-fase`."
  - "No cargar para instalar componentes SWL en el proyecto recién creado; usar `instalar-sistema` como paso siguiente."
evolvable: true  # default para skill estandar
---
# Habilidad: Inicializar Proyecto Nuevo

## Propósito

Establecer una base sólida de documentación y contexto antes de escribir la primera
línea de código. Un proyecto sin contexto escrito acumula deuda de decisiones desde
el día uno. Esta habilidad evita ese antipatrón.

## Cuándo activar

- El usuario dice "quiero crear un proyecto", "empecemos un sistema", "nuevo proyecto"
- No existe carpeta `.planning/` en el directorio de trabajo
- Se recibe un brief o documento de requisitos sin estructura técnica

## Cuándo NO cargar

- El proyecto ya tiene `.planning/PROYECTO.md` — se está inicializando un proyecto ya iniciado. En ese caso actualizar el archivo existente.
- El usuario quiere incorporar un codebase existente al sistema SWL; usar `/swl:adoptar-proyecto` que hace análisis automático del código.
- El usuario solo quiere planear una fase de trabajo dentro de un proyecto ya definido; usar `discutir-fase` + `planear-fase`.
- El objetivo es instalar componentes SWL (agentes, skills, hooks) en el directorio; eso lo hace `instalar-sistema` después de la inicialización.

---

## Fase 1 — Recopilación de contexto (cuestionario)

Antes de generar cualquier archivo, haz las siguientes preguntas. Agrupa las que
puedas en un solo mensaje para no saturar al usuario.

### Bloque A — Visión y alcance

1. ¿Cuál es el problema de negocio que resuelve este sistema? (1-3 oraciones)
2. ¿Quiénes son los usuarios finales? ¿Cuántos usuarios concurrentes se esperan?
3. ¿Hay una fecha límite o MVP en mente?
4. ¿Existe algún sistema legado que este proyecto reemplaza o integra?

### Bloque B — Stack y restricciones técnicas

5. ¿Hay lenguajes, frameworks o plataformas mandatorias (por política o equipo)?
6. ¿La solución es on-premise, cloud (cuál proveedor) o híbrida?
7. ¿Existe una base de datos preferida o mandatoria?
8. ¿Hay restricciones de licencia (OSS only, sin GPL, etc.)?

### Bloque C — Equipo y proceso

9. ¿Cuántas personas trabajarán en el proyecto y cuáles son sus roles?
10. ¿Se usa algún proceso formal (Scrum, Kanban, waterfall)?
11. ¿Hay un repositorio de código ya creado? ¿Rama principal?
12. ¿Hay pipelines CI/CD existentes o se crean desde cero?

### Bloque D — Calidad y seguridad

13. ¿Existen políticas de cobertura de tests mínima?
14. ¿El sistema maneja datos sensibles (PII, financieros, médicos)?
15. ¿Hay requerimientos regulatorios (GDPR, HIPAA, SOC 2, etc.)?

---

## Fase 2 — Generación de artefactos

Una vez obtenidas las respuestas, crea la carpeta `.planning/` y los tres documentos.

### Plantilla: `.planning/PROYECTO.md`

```markdown
# PROYECTO.md — [Nombre del Proyecto]

## Visión
[1 párrafo describiendo el problema y la solución]

## Objetivos del MVP
- [ ] Objetivo 1
- [ ] Objetivo 2

## Usuarios y contexto de uso
| Actor | Descripción | Volumen estimado |
|-------|-------------|-----------------|
|       |             |                 |

## Stack tecnológico
| Capa        | Tecnología | Justificación |
|-------------|-----------|---------------|
| Backend     |           |               |
| Frontend    |           |               |
| Base de datos |         |               |
| Infraestructura |       |               |

## Restricciones no negociables
1.
2.

## Equipo
| Rol | Responsabilidad |
|-----|----------------|
|     |                |

## Fechas clave
- Kick-off:
- MVP:
- Producción:

## Criterios de éxito
- [ ] Criterio medible 1
- [ ] Criterio medible 2
```

### Plantilla: `.planning/REQUISITOS.md`

```markdown
# REQUISITOS.md — [Nombre del Proyecto]

## Requerimientos Funcionales

### RF-001: [Nombre]
- **Descripción**:
- **Actores**:
- **Prioridad**: Alta / Media / Baja
- **Criterios de aceptación**:
  - [ ] CA-1
  - [ ] CA-2

[Repetir para cada RF]

## Requerimientos No Funcionales

| ID     | Categoría     | Descripción | Métrica de aceptación |
|--------|--------------|-------------|----------------------|
| RNF-001 | Rendimiento  |             | p95 < 200ms          |
| RNF-002 | Disponibilidad|            | 99.5% uptime         |
| RNF-003 | Seguridad    |             |                      |

## Requerimientos de Integración
- Sistema externo 1: [protocolo, frecuencia, volumen]
- Sistema externo 2:

## Fuera de alcance (explícito)
- X no está incluido en este proyecto.
- Y se abordará en una fase posterior.
```

### Plantilla: `.planning/HOJA-RUTA.md`

```markdown
# HOJA-RUTA.md — [Nombre del Proyecto]

## Fase 0 — Infraestructura base
- [ ] Repositorio y branching strategy
- [ ] CI/CD pipeline básico
- [ ] Entorno local de desarrollo documentado
- **Duración estimada**:

## Fase 1 — [Nombre del primer bloque funcional]
- [ ] Tarea 1
- [ ] Tarea 2
- **Objetivo**:
- **Duración estimada**:

## Fase N — ...

## Hitos de revisión
| Hito | Criterio de salida | Fecha estimada |
|------|-------------------|---------------|
|      |                   |               |
```

---

## Fase 3 — Generar CLAUDE.md raíz del proyecto

Antes de cerrar la sesión de inicialización, **genera un `CLAUDE.md` mínimo en
la raíz del proyecto recién creado**. Es el onboarding script que Claude leerá
en cada sesión futura sobre este proyecto.

> Sigue las best practices del video oficial Anthropic
> ("The CLAUDE.md file"): empieza compacto, deja que el archivo crezca con
> correcciones explícitas. Las cinco secciones canónicas son:
> Stack / Comandos / Code style / Conventions / @references.

### Plantilla mínima: `./CLAUDE.md` del proyecto

Usa los datos del Bloque B (stack) y del Bloque C (equipo, repo) del cuestionario.

```markdown
# CLAUDE.md — [Nombre del Proyecto]

## Stack

- **Lenguaje**: [del Bloque B5 / B6]
- **Framework principal**: [si aplica]
- **Base de datos**: [del Bloque B7]
- **Infraestructura**: [del Bloque B6]

## Comandos del proyecto

| Comando | Propósito |
|---------|-----------|
| `[npm run dev / poetry run / etc.]` | Servidor de desarrollo |
| `[npm test / pytest / cargo test]` | Tests |
| `[npm run build / ...]` | Build |
| `[npm run lint / ruff / clippy]` | Lint |

## Code style

- [Convención de indentación si difiere del default del lenguaje]
- [Preferencia de exports / módulos si aplica]
- [Naming si difiere del idiomático del lenguaje]

## Conventions

- [Convención de organización: dónde van los endpoints / componentes / utils]
- [Patrones a preferir: ej. "preferir async sobre callbacks"]
- [Restricciones del Bloque B8 si son operativas]

## @references

- `@.planning/PROYECTO.md` — visión, objetivos del MVP, criterios de éxito
- `@.planning/REQUISITOS.md` — requerimientos funcionales y no funcionales
- `@.planning/HOJA-RUTA.md` — fases planeadas

## Cómo evolucionar este archivo

1. Empieza mínimo. No adelantes reglas.
2. Cuando corrijas a Claude, pídele explícitamente: *"guarda esto en CLAUDE.md"*.
3. Para preferencias personales (no del proyecto), usa `~/.claude/CLAUDE.md`.
4. Si crece demasiado, ejecuta `/swl:claudemd refactor` para extraer secciones.
```

### Reglas de generación

- **Llenar TODOS los placeholders `[...]` con los datos reales del cuestionario**.
  Si falta un dato (ej. el usuario no especificó comandos), dejar el bullet con
  un comentario `<!-- pendiente: confirmar con el equipo -->` en lugar de
  eliminar el bullet o dejarlo vacío.
- **Mantener el archivo bajo 80 líneas inicialmente**. El video oficial
  recomienda explícitamente "empezar sin uno y construir desde ahí" — la
  primera versión debe ser un esqueleto, no una enciclopedia.
- **NO incluir reglas que aún no han sido violadas**. Por ejemplo, no
  agregar "no usar `eval()`" si Claude nunca lo usó en este proyecto. Esa
  regla puede vivir como global del usuario o agregarse cuando aparezca el
  primer caso.
- **NO duplicar información que ya está en `.planning/PROYECTO.md`**. Usar
  `@.planning/PROYECTO.md` como referencia.

---

## Fase 4 — Checklist de arranque

Antes de cerrar la sesión de inicialización, verifica:

- [ ] PROYECTO.md tiene todos los campos poblados (no hay `[TBD]` en restricciones)
- [ ] Cada RF tiene al menos un criterio de aceptación medible
- [ ] El HOJA-RUTA.md tiene fases con duración estimada
- [ ] Las restricciones "no negociables" están identificadas y documentadas
- [ ] Se registró quién tomó cada decisión de stack (para futura referencia)
- [ ] CLAUDE.md raíz generado con secciones canónicas pobladas (Stack, Comandos, @references)
- [ ] CLAUDE.md raíz validado con `/swl:claudemd audit` (sin warnings)

## Gotchas / Errores comunes no obvios

- **PROYECTO.md generado con `[TBD]` en restricciones no negociables**: el agente deja campos sin resolver para no bloquear al usuario, pero las restricciones vacías generan retrabajos costosos cuando se descubren tardíamente. Causa: el checklist de cierre de la Fase 4 no se aplicó rigurosamente. Solución: no cerrar la sesión de inicialización hasta que no quede ningún `[TBD]` en el bloque de restricciones — si el usuario no puede responder, registrar la restricción como "pendiente" en la sección `## Decisiones pendientes` con ticket asignado.
- **Fase 1 de HOJA-RUTA.md sin duración estimada**: el usuario acepta el documento sin notar que las fases no tienen estimaciones. Causa: el agente genera el template sin poblar las duraciones. Solución: antes de entregar HOJA-RUTA.md, pedir al usuario una estimación rough (días, semanas) para cada fase — sin eso el roadmap es decorativo.
- **Stack seleccionado sin verificar restricciones del Bloque B**: el agente sugiere un stack "moderno" que viola una restricción de licencia OSS o de plataforma mandatoria del equipo. Causa: el Bloque B se procesó en orden pero las respuestas no se cruzaron con las sugerencias del Bloque A. Solución: al proponer stack, citar explícitamente cada restricción del Bloque B y confirmar que ninguna es violada.
- **No preguntar por sistemas legados cuando el usuario menciona "reemplazar"**: el agente omite la pregunta 4 del Bloque A asumiendo que el proyecto es greenfield. Causa: mala clasificación del proyecto como nuevo cuando el usuario usó la palabra "reemplazar". Solución: si el usuario menciona "reemplazar", "migrar" o "integrar con" en la descripción, la pregunta 4 es obligatoria, no opcional.

## Señales de alerta

Detente y escala si el usuario no puede responder:
- Qué problema resuelve el sistema (visión indefinida)
- Quiénes son los usuarios finales (alcance sin ancla)
- Si hay sistemas legados involucrados (riesgo de integración oculto)

Estos huecos de información generan retrabajos costosos. Registra las preguntas
sin respuesta en PROYECTO.md bajo la sección `## Decisiones pendientes`.
