# IMPLEMENTACIÓN DEL ESTÁNDAR TROPIKAL PROJECT PACKAGE (TPP) 1.0

## 1. MISIÓN

Quiero evolucionar Tropikal mediante la creación e implementación de un estándar propio denominado:

**Tropikal Project Package (TPP)**

TPP será el formato oficial de especificación, organización, empaquetado, validación, intercambio y reutilización de proyectos diseñados para ser construidos por agentes de Inteligencia Artificial.

No queremos crear simplemente otro formato de prompts ni un generador convencional de plantillas de código.

Queremos establecer una estructura de ingeniería que permita describir integralmente cualquier proyecto y proporcionar a una IA toda la información necesaria para construirlo con el menor margen posible de ambigüedad.

Un paquete TPP debe poder contener, relacionar y organizar:

- Visión y objetivos del proyecto.
- Requerimientos funcionales y no funcionales.
- Reglas de negocio.
- Arquitectura.
- Componentes y módulos.
- Modelo de datos.
- Flujos de trabajo.
- Diseño visual y sistema de diseño.
- Mockups, wireframes y referencias visuales.
- Stack tecnológico.
- Estructura de archivos.
- Pseudocódigo.
- Prompts e instrucciones.
- Agentes y roles especializados.
- Skills y procedimientos.
- Herramientas y recursos externos.
- Pruebas y criterios de aceptación.
- Restricciones y estándares de calidad.
- Documentación y referencias.

El resultado debe ser un estándar modular, extensible, portable, versionable, validable y comprensible por diferentes agentes de IA.

## 2. PRIMERA REGLA: INSPECCIONAR TROPIKAL ANTES DE MODIFICARLO

Antes de implementar cualquier cosa:

1. Inspecciona la arquitectura actual de Tropikal.
2. Identifica cómo se crean actualmente las plantillas de proyecto.
3. Identifica cómo se almacenan prompts, instrucciones, pseudocódigo, skills, mockups, recursos y configuraciones.
4. Identifica los formularios, asistentes, configuradores y procesos de generación existentes.
5. Identifica qué formatos y estructuras utiliza actualmente el sistema.
6. Identifica las funcionalidades que ya están resueltas y deben conservarse.
7. Identifica las limitaciones actuales y las inconsistencias entre los distintos artefactos.
8. Elabora un diagnóstico de compatibilidad entre la arquitectura actual y el estándar TPP.

No reconstruyas Tropikal desde cero.

No sustituyas funcionalidades existentes sin una justificación técnica.

No elimines información ni artefactos actuales durante la migración.

El objetivo es evolucionar lo construido, no desecharlo.

## 3. DISEÑAR LA ESPECIFICACIÓN FORMAL TPP 1.0

Crea una especificación técnica formal del estándar.

Debe incluir como mínimo:

### 3.1 Identidad y metadatos

Cada paquete debe disponer de:

- Identificador único.
- Nombre.
- Descripción.
- Autor.
- Versión del paquete.
- Versión del estándar TPP.
- Fecha de creación y modificación.
- Categoría de proyecto.
- Tipo de proyecto.
- Estado de publicación.
- Etiquetas.
- Licencia.
- Dependencias.
- Compatibilidad con agentes y herramientas.

### 3.2 Arquitectura del paquete

Diseña una estructura de directorios normalizada, modular y extensible.

Utiliza como punto de partida conceptual:

mi-proyecto.tpp/

    manifest.json

    01-intent/
        vision.md
        objectives.md
        scope.md
        stakeholders.md

    02-requirements/
        functional.yaml
        non-functional.yaml
        business-rules.yaml
        acceptance-criteria.yaml

    03-blueprint/
        architecture.json
        components.json
        workflows.json
        data-model.json
        dependencies.json
        decisions.md

    04-design/
        design-system.json
        ui-guidelines.md
        mockups/
        wireframes/
        assets/

    05-agents/
        agent-roles.yaml
        AGENTS.md
        skills/

    06-implementation/
        tech-stack.yaml
        folder-structure.json
        pseudocode/
        implementation-rules.md

    07-validation/
        test-plan.yaml
        acceptance-tests/
        quality-gates.yaml

    08-resources/
        documentation/
        examples/
        references/
        libraries/

    schemas/
        manifest.schema.json
        architecture.schema.json
        requirements.schema.json

Esta estructura es orientativa. Perfecciónala con criterios de ingeniería.

No obligues a todos los proyectos a contener todos los directorios.

Define qué artefactos son obligatorios, opcionales y condicionales.

### 3.3 Manifiesto central

El archivo manifest.json será el punto de entrada del paquete.

Debe permitir descubrir:

- Identidad y versión.
- Tipo de proyecto.
- Descripción.
- Artefactos incluidos.
- Ubicación de cada artefacto.
- Tipo de artefacto.
- Obligatoriedad.
- Dependencias entre artefactos.
- Compatibilidad.
- Extensiones utilizadas.
- Requisitos mínimos para procesar el paquete.

Define su JSON Schema oficial.

El manifiesto debe funcionar como índice verificable del paquete.

### 3.4 Catálogo de tipos de artefactos

Define un registro formal de tipos de artefactos.

Como mínimo:

- project-vision
- project-objectives
- requirements
- business-rules
- architecture
- component-model
- workflow
- data-model
- design-system
- mockup
- wireframe
- visual-asset
- prompt
- agent-instructions
- agent-role
- agent-skill
- tool-definition
- tech-stack
- folder-structure
- pseudocode
- api-contract
- test-plan
- acceptance-criteria
- quality-gate
- documentation
- reference

Cada artefacto debe tener:

- Identificador.
- Tipo.
- Versión.
- Descripción.
- Ubicación.
- Formato.
- Dependencias.
- Estado de validación.

El catálogo debe permitir incorporar nuevos tipos sin modificar el núcleo del estándar.

### 3.5 Relaciones y consistencia

Este apartado es crítico.

Los artefactos no deben ser documentos aislados.

Diseña un sistema de relaciones que permita conectar:

- Requerimientos con componentes.
- Requerimientos con pruebas.
- Componentes con módulos.
- Módulos con entidades de datos.
- Flujos con pantallas.
- Pantallas con mockups.
- Skills con roles de agentes.
- Roles con tareas.
- Tareas con entregables.
- Decisiones arquitectónicas con componentes afectados.

Cada elemento importante debe poder identificarse mediante un ID estable.

Define mecanismos para detectar:

- Referencias inexistentes.
- Dependencias circulares.
- Artefactos faltantes.
- Inconsistencias entre versiones.
- Requerimientos sin pruebas.
- Componentes sin especificación.
- Pantallas sin correspondencia funcional.
- Skills sin rol o contexto de utilización.

## 4. COMPATIBILIDAD CON ESTÁNDARES EXISTENTES

No reinventes convenciones que ya estén suficientemente resueltas.

Investiga e incorpora compatibilidad cuando corresponda con:

- JSON Schema 2020-12.
- YAML.
- Markdown.
- Agent Skills (agentskills.io).
- AGENTS.md.
- C4 Model.
- Structurizr DSL.
- OpenAPI.
- AsyncAPI.
- MCP.
- Git y Semantic Versioning.
- Mermaid.

Define una matriz de compatibilidad.

Distingue claramente:

1. Compatibilidad nativa.
2. Importación.
3. Exportación.
4. Adaptación mediante conversores.
5. Elementos que requieren extensiones propias de TPP.

No declares compatibilidad si no existe una implementación real.

Los estándares externos deben ser aprovechados, no copiados innecesariamente.

## 5. SEPARAR TRES NIVELES DE INFORMACIÓN

TPP debe distinguir formalmente:

### Nivel A. Project Blueprint

Define qué se quiere construir y cómo debe funcionar.

Contiene requisitos, arquitectura, diseño, componentes, datos, procesos y criterios de aceptación.

### Nivel B. Agent Execution Package

Define cómo los agentes deben trabajar para construir el proyecto.

Contiene roles, skills, instrucciones, herramientas, prompts, permisos y procedimientos.

### Nivel C. Implementation Package

Contiene el resultado de la construcción.

Incluye código fuente, pruebas, configuraciones, dependencias y entregables.

Estos tres niveles deben poder evolucionar independientemente.

Una misma especificación funcional debe poder utilizarse para producir diferentes implementaciones.

Por ejemplo:

- PHP + MariaDB.
- Flutter + SQLite.
- PWA.
- C# Desktop.
- Aplicaciones móviles.
- Videojuegos.

No mezcles los requerimientos funcionales con decisiones tecnológicas que solamente correspondan a una implementación particular.

## 6. SISTEMA DE PERFILES DE PROYECTO

Diseña perfiles reutilizables para diferentes familias de proyectos.

Ejemplos:

- Web Application.
- Mobile Application.
- Desktop Application.
- SaaS.
- E-commerce.
- CRM.
- ERP.
- API.
- AI Agent.
- Video Game.
- Educational Platform.
- Automation.
- Infrastructure.

Cada perfil debe definir:

- Artefactos obligatorios.
- Artefactos recomendados.
- Artefactos condicionales.
- Validaciones particulares.
- Información necesaria para su construcción.

El sistema debe admitir perfiles personalizados.

No conviertas los perfiles en plantillas rígidas. Deben ser configuraciones que ayuden a generar el paquete correcto según la naturaleza del proyecto.

## 7. IMPLEMENTAR TPP DENTRO DE TROPIKAL

Una vez definida la especificación, implementa el estándar en la aplicación existente.

Adapta el sistema actual para que las plantillas de proyecto sean instancias del estándar TPP.

La implementación debe incluir:

### A. Creación de paquetes

- Crear paquetes TPP.
- Seleccionar perfiles.
- Configurar sus características.
- Agregar, editar y eliminar artefactos.
- Incorporar archivos y recursos.
- Gestionar dependencias.
- Versionar paquetes.

### B. Editor de artefactos

Permitir editar los diferentes tipos de contenido mediante interfaces adecuadas.

No utilices un editor de texto genérico para absolutamente todo.

Por ejemplo:

- Requisitos: editor estructurado.
- Arquitectura: editor visual y estructurado.
- Skills: editor compatible con Agent Skills.
- Prompts: editor especializado.
- Mockups: visualizador de imágenes.
- Datos: editor de modelos.
- Configuraciones: formularios.
- Documentación: Markdown.

### C. Validación

Implementa un validador TPP que revise:

- Integridad del manifiesto.
- Conformidad con JSON Schema.
- Existencia de archivos.
- Estructura del paquete.
- Dependencias.
- Referencias.
- Consistencia.
- Artefactos obligatorios.
- Compatibilidad declarada.

Debe ofrecer un informe comprensible con errores, advertencias y recomendaciones.

### D. Importación y exportación

Implementa:

- Importación de paquetes TPP.
- Exportación a ZIP con extensión .tpp.
- Inspección de paquetes.
- Validación previa a importación.
- Exportación de documentación.
- Exportación de Agent Skills.
- Exportación de AGENTS.md.
- Exportación de estructuras compatibles con herramientas externas.

El paquete debe ser portable y no depender de una instalación de Tropikal para poder inspeccionarse.

### E. Generación para agentes

Prepara una función que transforme el Blueprint y el Execution Package en un contexto de construcción organizado para la IA.

Debe poder generar:

- Contexto general.
- Instrucciones maestras.
- Plan de construcción.
- Tareas ordenadas.
- Contexto específico por tarea.
- Referencias a los artefactos relevantes.
- Criterios de aceptación.
- Restricciones.
- Procedimientos de validación.

Evita enviar indiscriminadamente todos los documentos a todos los agentes.

El sistema debe seleccionar el contexto pertinente para cada tarea y preservar las relaciones y referencias.

## 8. MIGRACIÓN DE LAS PLANTILLAS EXISTENTES

Adapta las plantillas que actualmente está creando Tropikal.

No las descartes.

Implementa un mecanismo de migración que:

1. Identifique los elementos actuales.
2. Los clasifique según el catálogo TPP.
3. Los asigne a los directorios correspondientes.
4. Genere identificadores.
5. Establezca las relaciones posibles.
6. Detecte información incompleta.
7. Preserve el contenido original.
8. Genere manifiestos.
9. Valide el resultado.

Cuando no exista información suficiente para completar un artefacto, no inventes contenido.

Marca los elementos como pendientes, incompletos o sujetos a revisión.

La migración debe poder repetirse sin duplicar artefactos ni perder información.

## 9. VERSIONADO Y EVOLUCIÓN DEL ESTÁNDAR

Diseña mecanismos para:

- Versionar paquetes.
- Versionar artefactos.
- Versionar el estándar.
- Detectar incompatibilidades.
- Migrar versiones anteriores.
- Registrar cambios.
- Mantener compatibilidad cuando sea posible.

Utiliza Semantic Versioning y define claramente las reglas de cambios mayores, menores y correctivos.

El estándar debe poder evolucionar sin hacer incompatibles innecesariamente los paquetes anteriores.

## 10. SEGURIDAD Y CONFIANZA

Considera que los paquetes pueden contener instrucciones para agentes, scripts y herramientas.

Define:

- Procedencia de los paquetes.
- Integridad mediante hashes.
- Opciones de firma.
- Licencias.
- Permisos.
- Clasificación de recursos ejecutables.
- Advertencias sobre scripts.
- Separación entre instrucciones confiables y contenido externo no confiable.

Importar un paquete nunca debe ejecutar automáticamente scripts ni otorgar permisos a agentes.

## 11. DOCUMENTACIÓN OFICIAL

Crea dentro del proyecto una documentación formal de TPP.

Como mínimo:

- TPP Specification 1.0.
- TPP Manifest Specification.
- TPP Artifact Registry.
- TPP Directory Structure.
- TPP Validation Rules.
- TPP Compatibility Matrix.
- TPP Extension Mechanism.
- TPP Versioning Policy.
- TPP Migration Guide.
- TPP Developer Guide.
- TPP Examples.

La documentación debe ser suficientemente precisa para que otro desarrollador pueda implementar un lector o generador TPP sin utilizar Tropikal.

## 12. PROYECTO DE REFERENCIA

Crea un paquete de ejemplo completo y realista.

Debe representar una aplicación de negocio, por ejemplo, un CRM.

Incluye:

- Visión.
- Requisitos.
- Reglas de negocio.
- Arquitectura.
- Modelo de datos.
- Componentes.
- Flujos.
- Diseño visual.
- Mockups.
- Stack tecnológico.
- Roles de agentes.
- Al menos una skill compatible.
- Prompts.
- Pseudocódigo.
- Plan de pruebas.
- Criterios de aceptación.

El paquete debe superar todas las validaciones implementadas.

## 13. PRUEBAS DE ACEPTACIÓN

No consideres terminada la implementación hasta demostrar que:

1. Se puede crear un paquete TPP desde Tropikal.
2. Se puede editar su manifiesto.
3. Se pueden agregar diferentes tipos de artefactos.
4. Se pueden relacionar los artefactos.
5. Se puede validar el paquete.
6. Se detectan errores intencionalmente introducidos.
7. Se puede exportar como .tpp.
8. Se puede importar nuevamente.
9. No se pierde información durante el ciclo.
10. Se puede inspeccionar sin Tropikal.
11. Se pueden exportar las skills en formato compatible.
12. Se puede generar contexto organizado para agentes.
13. Se pueden migrar las plantillas existentes.
14. Se conserva el funcionamiento actual de Tropikal.

Incluye pruebas automatizadas y un informe de resultados.

## 14. PRINCIPIOS DE IMPLEMENTACIÓN

Respeta estos principios:

- Modularidad.
- Portabilidad.
- Interoperabilidad.
- Extensibilidad.
- Validación estricta.
- Identificadores estables.
- Separación entre contenido y presentación.
- Separación entre especificación e implementación.
- Compatibilidad con agentes diferentes.
- Evitar dependencias propietarias innecesarias.
- No duplicar información sin establecer cuál es la fuente de verdad.
- Mantener la arquitectura actual de Tropikal siempre que sea razonable.

No agregues complejidad por razones meramente teóricas.

La solución debe ser implementable, mantenible y útil en el trabajo cotidiano.

## 15. FORMA DE TRABAJO

Trabaja por fases:

FASE 1: Auditoría de Tropikal y diagnóstico.

FASE 2: Investigación y definición formal del estándar TPP 1.0.

FASE 3: Creación de esquemas JSON, catálogo de artefactos y validadores.

FASE 4: Implementación del modelo de datos y servicios.

FASE 5: Adaptación de la interfaz de Tropikal.

FASE 6: Migración de plantillas existentes.

FASE 7: Importación, exportación e interoperabilidad.

FASE 8: Generación de contexto para agentes.

FASE 9: Pruebas, documentación y paquete de referencia.

Al concluir cada fase:

- Registra qué se implementó.
- Identifica archivos afectados.
- Ejecuta pruebas.
- Documenta problemas.
- Identifica decisiones pendientes.

No detengas el trabajo después de presentar una propuesta conceptual. Debes avanzar hasta implementar las funcionalidades dentro de los límites del proyecto y entorno disponibles.

Si encuentras decisiones arquitectónicas importantes que no puedes resolver con evidencia suficiente, documenta las alternativas y elige una solución conservadora que no comprometa la información existente.

## 16. ENTREGABLE FINAL

Quiero recibir:

1. Especificación formal TPP 1.0.
2. Arquitectura implementada.
3. Esquemas JSON Schema.
4. Catálogo de artefactos.
5. Validador funcional.
6. Importador y exportador.
7. Interfaz integrada en Tropikal.
8. Migración de plantillas existentes.
9. Generador de contexto para agentes.
10. Documentación.
11. Paquete CRM de referencia.
12. Pruebas automatizadas y resultados.

**CRITERIO FINAL DE ÉXITO**

Tropikal debe dejar de considerar una plantilla como una simple colección de prompts y archivos.

Debe tratarla como un paquete de ingeniería estructurado, verificable, versionable y portable, capaz de transmitir a cualquier agente compatible todo el conocimiento necesario para construir un proyecto con claridad, coherencia y criterios objetivos de calidad.

TPP debe convertirse en la estructura fundamental de las plantillas de proyecto de Tropikal.

## 17. ENMIENDA TPP 1.1: EL PAQUETE ES EL PROYECTO (ADITIVA)

Esta enmienda es **aditiva sobre 1.0**: ningún paquete 1.0 válido deja de serlo, y ningún lector 1.0 pierde acceso al contenido que ya sabía leer. Lo nuevo se declara, se valida y se degrada con honestidad.

### 17.1 Versión y compatibilidad

- `tpp_version` acepta `1.1` (patrón `^1\.[0-9]+(\.[0-9]+)?$`). Los paquetes 1.0 reales del portal siguen importándose sin migración.
- `package.compatibility.min_reader_version` pasa a `1.1` sólo cuando el paquete usa las extensiones de proyecto; el resto sigue declarando `1.0`.
- Un lector que sólo conoce 1.0 marca los tipos nuevos como `artifact.unknown_type` (advertencia) y puede inspeccionar todo lo demás: la degradación es informativa, no destructiva.

### 17.2 Tipos de artefacto nuevos

- `tropikal-project` en `tropikal/project.json`: el documento PromptProject completo del proyecto, no una entrada de catálogo. Contenido: `{kind: "tropikal-project", schema_version: 1, project: {name, description}, document}`. Es obligatorio dentro de su propio paquete y se declara en `manifest.extensions` como `tropikal-project`.
- `mockup-document` en `04-design/mockups/<id>.json`: la pantalla **entregada**, con `{mockup_id, name, screen, notes, document, resolved}`. `document` es el árbol editable tal como lo guarda el núcleo; `resolved` es el layout con coordenadas resueltas por el núcleo (auto-layout incluido). Ambos viajan juntos: editar y ver no son representaciones distintas del mismo objeto.

### 17.3 Reglas de perfil y honestidad

- Equivalencia de perfil: un `mockup-document` satisface el requisito `mockup` de los perfiles que lo exigen y queda sujeto a la prohibición `mockup` de los perfiles que no lo admiten (api, backend, cli, automation, infrastructure).
- Mockup referenciado ≠ mockup entregado: si el documento referencia una pantalla que no existe en la base local, el paquete la exporta como tipo `mockup` con `validation.status: incomplete` y la lista en `manifest.incomplete`. Nunca se inventa una pantalla para rellenar el paquete.

### 17.4 Integridad por artefacto

- Cada artefacto puede declarar `sha256` (64 hexadecimales) sobre su contenido textual UTF-8. El validador lo compara y emite `artifact.hash_mismatch` con el id del artefacto afectado, además del `security.hash_mismatch` de paquete.
- El campo es opcional: su ausencia reproduce exactamente el comportamiento 1.0 (hash global de contenido).
- El sellado de validación (`validation.status`) se asigna por id de artefacto o por área del evaluador mapeada a rutas, nunca por heurísticas sobre el texto de los mensajes. Los artefactos incompletos no se sellan como válidos.

### 17.5 Importación de proyecto completo

- La importación valida el paquete entero **antes** de escribir nada: con errores no se crea ninguna entidad.
- Se recrean proyecto, PromptProject y mockups. Los ids se reasignan localmente y todas las referencias del documento (`mockup_id` y ligas `mockup:<id>` en requerimientos y procesos) se remapean; el `project_id` del documento se reancla al proyecto nuevo.
- Las notas y descripciones de pantalla que el usuario escribió sobre las referencias de diseño se conservan a través de la sincronización existente del núcleo; la importación no duplica referencias.
- Un fallo a mitad de la recreación limpia lo creado y reporta el error: no quedan proyectos a medias.
- Un paquete de proyecto no es una plantilla: sin `tropikal/template.json` la importación como plantilla lo dice con `import.no_template`, y un paquete de plantilla sin `tropikal/project.json` no es importable como proyecto (`project.missing`).

### 17.6 Visor web

- El visor gratuito añade la pestaña **Pantallas** cuando el paquete trae `mockup-document`: render vectorial (SVG) del layout resuelto, generado en el navegador, con el documento editable inspeccionable al lado. Es una aproximación de lectura etiquetada como tal; la edición real vive en Tropikal Studio.
- La pestaña Blueprint prefiere `tropikal/project.json` cuando existe y declara la fuente en pantalla; si no, usa `tropikal/template.json` como en 1.0.
- El visor verifica también el `sha256` individual de cada artefacto que lo declare.