docs(copilot): clarify tooling governance

Author: 2-Coatl

.github/agents/README.md

@@ -75,5 +75,20 @@ Cada agente cuenta con una ficha `.agent.md` que describe propósito, responsabi
 - **Documentación**: crear ADRs para decisiones arquitectónicas; comentar lógicas no obvias.
 - **Estándares**: Python (Black 100 chars, isort, flake8), JS (ESLint + Prettier), infra (Terraform fmt, ansible-lint), docs (markdownlint, Vale opcional).
 
+### Lineamientos para la propiedad `tools`
+- Declara explícitamente las herramientas que cada agente puede usar: `read`, `search` y `edit` cubren las capacidades básicas del runtime de Copilot.
+- Si omites `tools`, Copilot habilita **todas las herramientas disponibles**, incluidos los endpoints expuestos por servidores MCP declarados en el repositorio o en el propio perfil.
+- Para agentes de inspección/validación, limita el set a `"read"` y `"search"`; reserva `"edit"` para roles que realmente deban modificar archivos.
+- Cuando necesites capacidades MCP específicas, referencia cada herramienta con el formato `"alias/tool"` (por ejemplo, `"playwright/browser"`). Documenta en la ficha `.agent.md` por qué el agente requiere ese permiso.
+- Revisa este README al agregar o quitar herramientas para asegurarte de que las automatizaciones y auditores conozcan la justificación.
+
+### Ciclo de pruebas y liberación de agentes
+1. **Laboratorio privado**: crea o reutiliza el repositorio organizacional `.github-private` y agrega la carpeta `.github/agents/`. Los perfiles alojados ahí solo son visibles para quienes tengan acceso a ese repositorio.
+2. **Creación/actualización**: redacta el `.agent.md` en el laboratorio (puedes duplicar un perfil existente) y haz merge a la rama por defecto para generar una versión candidata.
+3. **Validación**: abre `https://github.com/copilot/agents`, selecciona el repositorio privado en el desplegable, elige el agente y ejecuta prompts reales. Usa la sección **Recent sessions** para revisar logs, herramientas utilizadas y resultados.
+4. **Iteración**: ajusta instrucciones, `tools`, prompts base o servidores MCP hasta que el agente cumpla los estándares de desempeño y cumplimiento.
+5. **Promoción**: mueve el archivo `.agent.md` desde `.github-private/.github/agents/` al repositorio público (`agents/`) y fusiona el cambio. A partir de ese momento, el agente queda disponible para toda la organización.
+6. **Monitoreo**: consulta el audit log filtrando por `actor:Copilot` o los paneles de actividad del enterprise para verificar adopción, detectar fallos y respaldar auditorías.
+
 ## Referencia de Meta-Prompting
 Consulta [`META_PROMPTS_LIBRARY.md`](META_PROMPTS_LIBRARY.md) para los 10 bloques solicitados (generación, optimización, anti-alucinación, evaluaciones, A/B testing, debugging, variaciones multi-LLM y validación). Estos patrones deben acompañar cualquier ficha que guíe a un agente Copilot o a los scripts en `scripts/coding/ai/`.

.github/agents/api-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: ApiAgent
+description: Coordinar las automatizaciones del backend para que cada entrega preserve los acuerdos de arquitectura, seguridad y trazabilidad del proyecto.
+tools: ["read", "search", "edit"]
+---
+
 # ApiAgent
 
 <Goals>

.github/agents/automation-business-rules-validator-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: AutomationBusinessRulesValidatorAgent
+description: Verificar que los procesos automatizados respeten las reglas de negocio declaradas por el dominio y que los cambios no rompan los contratos establecidos.
+tools: ["read", "search"]
+---
+
 # AutomationBusinessRulesValidatorAgent
 
 <Goals>

.github/agents/automation-ci-pipeline-orchestrator-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: AutomationCIPipelineOrchestratorAgent
+description: Orquestar los pipelines de integración continua asegurando que cada etapa ejecute las validaciones y despliegues planificados sin interrupciones.
+tools: ["read", "search", "edit"]
+---
+
 # AutomationCIPipelineOrchestratorAgent
 
 <Goals>

.github/agents/automation-coherence-analyzer-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: AutomationCoherenceAnalyzerAgent
+description: Analizar la coherencia entre requisitos, implementaciones y documentación, detectando divergencias tempranas en flujos automatizados.
+tools: ["read", "search"]
+---
+
 # AutomationCoherenceAnalyzerAgent
 
 <Goals>

.github/agents/automation-compliance-validator-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: AutomationComplianceValidatorAgent
+description: Corroborar que las automatizaciones cumplan políticas corporativas, normativas regulatorias y estándares internos de auditoría.
+tools: ["read", "search"]
+---
+
 # AutomationComplianceValidatorAgent
 
 <Goals>

.github/agents/automation-constitution-validator-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: AutomationConstitutionValidatorAgent
+description: Asegurar que las automatizaciones basadas en IA respeten los principios éticos, de seguridad y gobernanza definidos para el proyecto.
+tools: ["read", "search"]
+---
+
 # AutomationConstitutionValidatorAgent
 
 <Goals>

.github/agents/automation-devcontainer-validator-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: AutomationDevContainerValidatorAgent
+description: Revisar que los entornos de desarrollo reproducibles funcionen correctamente y ofrezcan la experiencia esperada para el equipo.
+tools: ["read", "search"]
+---
+
 # AutomationDevContainerValidatorAgent
 
 <Goals>

.github/agents/automation-metrics-collector-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: AutomationMetricsCollectorAgent
+description: Centralizar métricas de automatización y calidad para facilitar decisiones basadas en datos y detectar tendencias tempranas.
+tools: ["read", "search"]
+---
+
 # AutomationMetricsCollectorAgent
 
 <Goals>

.github/agents/automation-pdca-agent.agent.md

@@ -1,3 +1,9 @@
+---
+name: AutomationPDAAgent
+description: Aplicar el ciclo Plan-Do-Check-Act sobre automatizaciones, asegurando mejora continua y documentación de resultados.
+tools: ["read", "search", "edit"]
+---
+
 # AutomationPDAAgent
 
 <Goals>