Añadida documentación para agentes IA y definición de skills

AGENTS.md

@@ -0,0 +1,155 @@
+# AGENTS.md
+
+Este archivo proporciona contexto y reglas para agentes de IA que trabajan sobre este repositorio.
+
+## Propósito
+
+FacturaScripts es un software ERP y CRM de código abierto escrito en PHP. Permite gestionar facturación, contabilidad,
+inventario, clientes, proveedores, informes y análisis. La aplicación está diseñada con una arquitectura modular y
+extensible mediante plugins.
+
+---
+
+## Stack técnico
+
+Backend
+
+- PHP >= 8.0
+- MySQL, MariaDB o PostgreSQL
+- Composer
+
+Frontend
+
+- Bootstrap 5
+- Twig (plantillas)
+- jQuery
+- Select2
+- Chart.js
+
+Herramientas de desarrollo
+
+- PHPUnit (tests)
+- PHPStan (análisis estático)
+- PHPCS (estándares de código)
+
+---
+
+## Estructura del proyecto
+
+Código principal:
+
+Core/
+
+Directorios más importantes:
+
+- Core/Controller/ → controladores de páginas
+- Core/Model/ → modelos de datos (entidades de base de datos)
+- Core/Lib/ → lógica de negocio y utilidades
+- Core/Table/ → definición XML de tablas de base de datos
+- Core/XMLView/ → definición XML de formularios y listados
+- Core/View/ → plantillas Twig
+- Core/Worker/ → tareas en segundo plano
+- Core/Translation/ → traducciones
+
+Otros directorios:
+
+- Dinamic/ → clases generadas automáticamente
+- Test/ → pruebas automatizadas
+- vendor/ → dependencias PHP
+- node_modules/ → dependencias JavaScript
+
+---
+
+## Arquitectura general
+
+Controladores  
+→ gestionan las peticiones y acciones de las páginas.
+
+Modelos  
+→ representan entidades de base de datos.
+
+Lib  
+→ contiene la lógica de negocio y servicios reutilizables.
+
+XMLView  
+→ define formularios y listados de forma declarativa.
+
+Tablas XML
+→ define la estructura de las tablas de base de datos.
+
+---
+
+## Reglas de arquitectura
+
+Los agentes deben seguir estas reglas:
+
+- La lógica de negocio debe ir en Core/Lib.
+- Los controladores deben ser ligeros.
+- Los modelos representan tablas de base de datos.
+- La estructura de la base de datos se define en Core/Table mediante XML.
+- Los formularios y listados se definen en Core/XMLView.
+- Las plantillas de interfaz usan Twig en Core/View.
+- No modificar código dentro de vendor/ o node_modules/.
+
+---
+
+## Código generado
+
+El directorio Dinamic/ contiene clases generadas automáticamente. Los agentes nunca deben modificar archivos dentro de
+Dinamic/.
+
+---
+
+## Sistema de plugins
+
+FacturaScripts está diseñado para ser extendido mediante plugins.
+
+Los plugins pueden:
+
+- añadir controladores
+- extender modelos
+- modificar vistas XML
+- añadir campos a tablas
+- modificar comportamiento del sistema
+
+Siempre que sea posible, se debe preferir crear o modificar un plugin en lugar de modificar el núcleo del sistema.
+Además, los plugins deben usar extensiones principalmente, antes que usar herencia.
+
+---
+
+## Flujo de trabajo recomendado
+
+Cuando se implementa una funcionalidad o se corrige un error:
+
+1. Identificar el módulo afectado (Controlador, Modelo o Lib).
+2. Implementar la lógica en Core/Lib si es lógica de negocio.
+3. Modificar o crear modelos si se necesita acceso a base de datos.
+4. Modificar XMLView si hay cambios en formularios o listados.
+5. Actualizar la estructura de base de datos mediante XML en Core/Table.
+6. Añadir o actualizar pruebas en Test/.
+
+---
+
+## Comandos y desarrollo
+
+Los comandos de desarrollo se documentan en:
+
+`ia/DEVELOPMENT.md`
+
+Este archivo contiene cómo instalar dependencias, ejecutar tests, verificar estilo y usar `fsmaker` para generar
+plugins.
+
+---
+
+## Skills
+
+Consultar el siguiente archivo para ver todas las skills disponibles:
+`ai/skills.yaml`
+
+Skills más utilizadas:
+
+- use-tools → uso de la clase Tools
+- use-translator → uso del traductor (Translator)
+- api-usage → uso de la API (Endpoints, tokens)
+- use-http → uso de la clase Http (Peticiones externas)
+- extensions-and-hooks → uso de pipes (PHP) y ganchos (Twig) para extensiones

ai/DEVELOPMENT.md

@@ -0,0 +1,67 @@
+# Guía de desarrollo - FacturaScripts
+
+Este archivo contiene los comandos más importantes para el desarrollo y mantenimiento del proyecto.
+
+---
+
+## Instalación de dependencias
+
+- Instalar las dependencias de PHP con Composer:
+
+  ```
+  composer install
+  ```
+
+- Instalar las dependencias de JavaScript con npm:
+
+  ```
+  npm install
+  ```
+
+## Ejecutar tests
+
+Para ejecutar las pruebas unitarias del proyecto, utiliza:
+
+```
+vendor/bin/phpunit
+```
+
+## Análisis estático
+
+Para realizar un análisis estático del código en el directorio `Core` con PHPStan:
+
+```
+vendor/bin/phpstan analyse Core
+```
+
+## Verificar y corregir estilo de código
+
+- Verificar el estilo de código con PHP_CodeSniffer:
+
+  ```
+  vendor/bin/phpcs
+  ```
+
+- Corregir automáticamente los errores de estilo:
+
+  ```
+  vendor/bin/phpcbf
+  ```
+
+---
+
+## Instalación de fsmaker
+
+`fsmaker` es una herramienta CLI diseñada para acelerar el desarrollo de plugins para FacturaScripts.
+
+Para instalar `fsmaker` globalmente con Composer, ejecuta:
+
+```
+composer global require facturascripts/fsmaker
+```
+
+Luego, asegúrate de que el binario esté en tu PATH creando un enlace simbólico:
+
+```
+sudo ln -s ~/.config/composer/vendor/bin/fsmaker /usr/local/bin/fsmaker
+```

ai/README.md

@@ -0,0 +1,25 @@
+# AI Docs
+
+Esta carpeta contiene documentación breve y operativa para asistentes de IA.
+
+## Estructura
+- `../AGENTS.md`: contexto general del proyecto
+- `./skills.yaml`: índice de skills disponibles
+- `./DEVELOPMENT.md`: guía para desarrolladores
+- `./skills/*.md`: instrucciones específicas por tipo de tarea
+
+## Regla práctica
+- Lo global y estable va en `AGENTS.md`
+- Lo específico de una tarea va en una skill
+- No duplicar reglas en demasiados archivos
+
+## Cómo añadir una nueva skill
+1. Crear un archivo en `skills/`
+2. Añadir su entrada en `skills.yaml`
+3. Mantenerla corta, concreta y accionable
+
+## Cuándo crear una skill nueva
+Crear una skill nueva si:
+- una tarea se repite a menudo,
+- requiere pasos específicos,
+- los agentes suelen equivocarse en ese tipo de cambio.

ai/skills.yaml

@@ -0,0 +1,77 @@
+version: 1
+
+skills:
+  - id: use-tools
+    title: Uso de la clase Tools
+    file: ai/skills/use-tools.md
+    when_to_use:
+      - formatear fechas, números o dinero
+      - operaciones con archivos y carpetas
+      - obtener configuraciones o ajustes
+    tags: [tools, utilities, format]
+
+  - id: use-translator
+    title: Uso del traductor (Translator)
+    file: ai/skills/use-translator.md
+    when_to_use:
+      - traducir textos o cadenas
+      - gestionar idiomas y traducciones
+    tags: [translation, i18n]
+
+  - id: model-management
+    title: Gestión de Modelos (ModelClass)
+    file: ai/skills/model-management.md
+    when_to_use:
+      - operaciones CRUD (Crear, Leer, Actualizar, Borrar)
+      - buscar registros en la base de datos
+      - persistencia de datos
+    tags: [model, crud, database]
+
+  - id: table-definition
+    title: Definición de Tablas (XML)
+    file: ai/skills/table-definition.md
+    when_to_use:
+      - crear o modificar tablas de base de datos
+      - definir columnas y restricciones
+    tags: [table, xml, database, schema]
+
+  - id: xml-view-definition
+    title: Definición de Vistas (XMLView)
+    file: ai/skills/xml-view-definition.md
+    when_to_use:
+      - crear o modificar listados y formularios
+      - definir widgets y visualización
+    tags: [view, xml, ui, forms, list]
+
+  - id: plugin-development
+    title: Extensión mediante Plugins
+    file: ai/skills/plugin-development.md
+    when_to_use:
+      - crear nuevos plugins
+      - extender modelos o controladores del núcleo
+      - modularidad y extensibilidad
+    tags: [plugin, extension, modularity]
+
+  - id: api-usage
+    title: Uso de la API
+    file: ai/skills/api-usage.md
+    when_to_use:
+      - interactuar con FacturaScripts desde aplicaciones externas
+      - crear nuevos endpoints de API
+    tags: [api, rest, json, authentication]
+
+  - id: use-http
+    title: Uso de la clase Http
+    file: ai/skills/use-http.md
+    when_to_use:
+      - realizar peticiones HTTP externas desde FacturaScripts
+      - consumir servicios web de terceros
+    tags: [http, curl, request, client]
+  - id: extensions-and-hooks
+    title: Extensiones y Ganchos (Pipes/Hooks)
+    file: ai/skills/extensions-and-hooks.md
+    when_to_use:
+      - extender funcionalidad sin usar herencia
+      - añadir contenido dinámico en plantillas Twig
+      - interceptar acciones del núcleo
+    tags: [extension, pipe, hook, twig, plugin]