kikita-labs/kikita-create-angular-app

¿Qué hace kikita-create-angular-app?

Inicializa un nuevo proyecto Angular y genera su árbol de documentación AGENTS.md / .agents/ para que cualquier agente de IA (Claude Code, Codex, etc.) que trabaje posteriormente en el proyecto tenga una fuente de verdad completa y auto-mantenible.

0. Detección de modo (hacer siempre primero)

Tres estados posibles para el directorio de destino — verificar en este orden:

1. .agents/.kikita-scaffold.json presente → este proyecto ya fue scaffolded o adoptado por esta habilidad. Seguir update.md — no re-ejecutar el cuestionario, no re-scaffoldear, no re-ejecutar adopt.md. update.md se encarga de obtener la última plantilla, hacer diff desde el commit registrado y fusionar cambios en los archivos .agents/ (posiblemente personalizados) del proyecto.
2. Directorio vacío o casi vacío (sin package.json, sin angular.json, solo quizás un .git//README que el usuario acaba de crear) → inicialización nueva. Continuar con la sección 1 a continuación, luego plan.md.
3. Proyecto existente, sin registro de scaffold (presencia de package.json/angular.json, sin .agents/.kikita-scaffold.json) → es un proyecto Angular de otra persona (o uno más antiguo anterior a esta habilidad). No ejecutar plan.md — asume un directorio vacío e intentará hacer ng new sobre un proyecto real. Seguir adopt.md en su lugar: genera el árbol .agents/ contra lo que realmente hay, infiriendo respuestas del cuestionario a partir de la configuración existente en lugar de scaffoldear nuevas herramientas, y pregunta antes de cambiar cualquier cosa que ya exista.

0.5 Precondiciones (solo para inicialización nueva)

• Confirmar que el directorio de trabajo está vacío o que el usuario quiere explícitamente inicializar aquí.
• Si al verificar el directorio resulta no estar vacío, detenerse y redirigir al caso 3 anterior (adopt.md) en lugar de forzar la ruta de inicialización — no pedir al usuario que simplemente "confirme que está bien inicializar aquí" cuando lo que realmente se necesita es el flujo de adopción.

1. Cuestionario (preguntar siempre antes de tocar el sistema de archivos)

Seguir plan.md paso a paso desde aquí. No saltarse el cuestionario. No saltarse la instalación de MCP. Al terminar, ejecutar checklist.md antes de informar al usuario que está completo.

Preguntar al usuario, una sola ronda, todas las preguntas a la vez:

1. CSS: ¿CSS nativo (propiedades personalizadas), SCSS o Tailwind CSS?
   • Tailwind es una rama estructuralmente diferente, no una variante de las otras dos: sin esquema @layer {{PREFIJO}}.*, sin tokens :root escritos a mano, sin mixins SCSS — ver los bloques de scaffold CSS=Tailwind en templates/.agents/code-style/css-architecture.md, component-structure.md y templates/.agents/architecture/folder-structure.md.
2. Librería UI: @kikita-labs/ui, Taiga UI, PrimeNG, o ninguna (crear un conjunto UI local basado en tokens)?
   • Si se elige una librería: buscar si tiene un schematic ng add y/o un servidor MCP. Preferir el schematic. Si tiene MCP, instalarlo (ver plan.md paso 4).
3. Pruebas: ¿ninguna, solo unitarias, solo e2e, o ambas? ¿Qué ejecutor (Vitest/Jasmine+Karma está obsoleto en Angular nuevo — preferir Vitest; Playwright para e2e)?
4. SSR: ¿esta aplicación se renderiza en servidor (Angular SSR / hidratación) o solo cliente?
   • Determina si se genera .agents/architecture/platform-adapter.md.
5. i18n: ¿este proyecto necesita múltiples locales (@angular/localize o una librería i18n en tiempo de ejecución)? En caso afirmativo, ¿qué enfoque?
   • Determina si se genera .agents/i18n.md.
6. JSDoc en API pública: ¿exigir JSDoc obligatorio en todo símbolo exportado, u omitirlo?
   • Determina si se genera .agents/agent-surface.md (recomendación por defecto: sí).
7. Prefijo del proyecto: prefijo corto en kebab-case para selectores de componentes/directivas.
8. Política Git: ¿puede el agente hacer commit y push sin preguntar cada vez, o cada commit/push debe ser confirmado?
9. Gestor de paquetes: ¿npm, pnpm o yarn? Recomendación por defecto: pnpm (más rápido, eficiente en disco mediante almacén compartido direccionable por contenido, resolución de dependencias más estricta). Solo cambiar la recomendación por defecto si el usuario lo solicita.
10. Repositorio remoto: ¿el usuario ya tiene una URL de repositorio a la que hacer push? En caso afirmativo, registrarla — git remote add origin <url> se ejecuta justo después de git init (ver plan.md paso 9). Si no se proporciona URL, omitir esto; el usuario configura el remoto más tarde por su cuenta.

Registrar cada respuesta — dirigen tanto el scaffold como los archivos de documentación que se generan. Nunca asumir un valor por defecto en silencio; si el usuario omite una pregunta, preguntar de nuevo por esa. Esta habilidad apunta a un solo proyecto Angular, no a un monorepo — si el usuario quiere un monorepo/espacio de trabajo Nx, decir que esta habilidad no cubre eso y detenerse en lugar de improvisar.

2. Generar

Seguir plan.md. Copiar archivos de templates/ al proyecto destino, incluyendo los archivos punto (.gitignore, .editorconfig, .prettierrc, .prettierignore, .nvmrc, .vscode/extensions.json).

Dos cosas diferentes ocurren con las respuestas del cuestionario, no confundirlas:

• Marcadores de posición de texto: buscar y reemplazar cada {{TOKEN}} con el valor real, sin dejar ninguno: {{PREFIX}}, {{PROJECT_NAME}}, {{CSS}}, {{CSS_EXT}}, {{UI_LIB}}, {{UI_LIB_MCP_NAME}}, {{UI_LIB_MCP_PURPOSE}}, {{TESTS}}, {{GIT_POLICY}}, {{PACKAGE_MANAGER}}, {{NODE_VERSION}}, {{I18N_APPROACH}}, {{DATE}}.
• Puertas de inclusión: las respuestas de SSR, i18n, JSDoc obligatorio, librería UI, y motor CSS no llenan un marcador de posición; deciden si un archivo completo (o un bloque marcado con <!-- SCAFFOLD --> dentro de uno) se copia o no. Una respuesta "no" (o, para CSS, los dos motores no elegidos) significa que el archivo/bloque se elimina, no que se llena con una cadena vacía. Los archivos condicionales aún deben enlazarse desde AGENTS.md / el README correspondiente cuando se mantienen, y sus enlaces eliminarse cuando se omiten.

3. Verificar

Ejecutar checklist.md completo antes de reportar éxito.

Notas sobre la estructura de documentación (leer una vez, luego seguir las plantillas literalmente)

• CLAUDE.md es siempre un stub de una línea que apunta a AGENTS.md.
• AGENTS.md es el punto de entrada obligatorio: una lista corta de "Lectura obligatoria" más reglas innegociables, en la raíz del proyecto.
• .agents/README.md es un índice plano de todo lo que hay en .agents/ — el equivalente del barrel index.ts para el árbol de documentación. Cada documento raíz y cada README de subcarpeta se enlaza desde aquí. Mantenerlo sincronizado cuando se añade u omite un archivo condicional (i18n, agent-surface, platform-adapter).
• Los temas que son genuinamente un documento corto se mantienen planos en .agents/*.md (workflow, git-policy, documentation, mcp, testing-and-quality, agent-surface, refactoring, progress, i18n, accessibility).
• Los temas que se ramifican en varios documentos pequeños obtienen una subcarpeta con su propio README.md central: .agents/code-style/, .agents/architecture/, .agents/shared/, .agents/core/, .agents/decisions/. Esto es una desviación deliberada de kikita-ui/-docs (que se mantuvo completamente plano) porque la especificación de esta habilidad requiere documentos de reutilización por componente y por preocupación que seguirán creciendo después del scaffold.
• .agents/shared/README.md registra todo lo que hay en src/app/shared/, dividido por forma de dependencia: shared/ui/ (componente/directiva/pipe, decorado con Angular) y shared/utilities/ (funciones simples, cero imports de Angular — forzado por una regla ESLint de import-restricted). Los mixins SCSS, si se eligió SCSS, viven en styles/mixins/, no bajo shared/ en absoluto. .agents/core/README.md registra singletons de toda la aplicación (servicios/guardas/interceptores) bajo src/app/core/. Ninguno se llama "components" — ambos cubren más que componentes, de ahí la nomenclatura.
• .agents/decisions/README.md explica cuándo se requiere un ADR corto (dirección de capa, propiedad de estado, estrategia de enrutamiento, esquema de alias público) — siempre se genera, comienza sin archivos ADR. AGENTS.md lo enlaza bajo un grupo condicional "para cambios estructurales", no en la lista de lectura obligatoria — mismo patrón que el grupo shared//core/ "para trabajo en componentes".
• Todo el contenido de los archivos rastreados — incluyendo JSDoc — es solo en inglés. Sin cirílico, sin mojibake.
• Todos los documentos en .agents/ deben leerse como angular-code-style.md en kikita-ui: imperativos, cortos, con ejemplos, terminando en una lista de verificación de revisión/validación.