aitormf/agent-skills

Contexto del proyecto

Ayuda a la persona a decidir y redactar las reglas estables del proyecto, cada una en el archivo que le corresponde. La persona toma las decisiones: tú lees, propones opciones concretas y redactas.

Reemplaza el constitution.md de Spec Kit. Todo su contenido tiene un hogar mejor:

Contenido	Archivo	Leído por
Pila tecnológica, capas, reglas de dependencias, principios no negociables, glosario	docs/ARCHITECTURE.md	Personas y agentes; spec-to-plan y review-spec verifican los principios
Calidad, ramas, commits, PRs, revisión, uso de IA	CONTRIBUTING.md	Personas (y agentes, mediante enlace)
El porqué de cada decisión estructural y las alternativas descartadas	docs/adr/NNNN-*.md	Ambos, bajo demanda
Comandos, límites, convenciones no obvias, mapa de documentación	AGENTS.md (+ CLAUDE.md con @AGENTS.md)	Agentes, en cada sesión
Cómo reportar vulnerabilidades, política de agentes	SECURITY.md	Personas

Plantillas en assets/en/ (inglés) y assets/es/ (español). Usa el idioma en el que está documentado el proyecto; pregunta si no está claro. Cada plantilla explica en su comentario inicial cómo rellenarla.

Reglas

• No dupliques. Si algo ya está en pyproject.toml, en CI o en un linter, enlázalo; no lo copies. Si un principio aparece en dos archivos, terminarán contradiciéndose: los principios solo viven en ARCHITECTURE.md.
• AGENTS.md breve: menos de 150 líneas. Es un mapa que enlaza; no contiene. Por cada línea: "si la elimino, ¿el agente se equivocaría?". Si no, fuera.
• Lo que se puede verificar con una herramienta se verifica con una herramienta. Por cada principio, pregunta cómo se verifica (lint, import-linter, test, CI, revisión) y anótalo en su columna.
• Nada volátil: sin estado del sprint ni TODOs. Esos van al gestor de tareas o a docs/plans/.
• Muestra cada archivo completo (o el diff, si ya existe) y escribe solo después de que la persona lo apruebe.

Proceso

1. Leer el proyecto

Antes de preguntar nada, lee: manifiestos (pyproject.toml, package.json, go.mod…), README.md, cualquier archivo de contexto existente, .github/workflows/, configuración de linter y la estructura de carpetas. Usa lo que encuentres para proponer respuestas en lugar de hacer preguntas abiertas.

Decide el modo e infórmaselo a la persona:

• Greenfield (poco o ningún código): ARCHITECTURE.md es prescriptivo, cómo será.
• Brownfield: ARCHITECTURE.md es descriptivo, cómo es hoy. El ideal va a los ADRs y a las trancas de las herramientas. Si ya existen archivos de contexto, solo pregunta por los huecos y propone diffs.
• Migración desde un constitution.md: distribuye su contenido según la tabla anterior y propón eliminarlo o reducirlo a un enlace.

2. Entrevista por rondas

Una categoría a la vez. Por cada pregunta, ofrece opciones concretas (A, B, "dejar abierto", "otro"). Si los archivos ya responden a la pregunta, pide confirmación en lugar de preguntar. Si una categoría no aplica (por ejemplo, no hay base de datos), sáltala y dilo. Al final de cada ronda, resume lo decidido.

Ronda	Qué se decide	Destino
1. Propósito	Qué es el proyecto y qué queda fuera; tipo (aplicación, servicio, librería, CLI)	ARCHITECTURE.md §1, README.md
2. Pila y arquitectura	Lenguaje, framework, persistencia, infraestructura; capas o módulos y qué puede importar qué	ARCHITECTURE.md §2–4, un ADR por decisión estructural
3. Principios no negociables	5–10 reglas estables y verificables: por qué y cómo se comprueba cada una	ARCHITECTURE.md §5
4. Calidad	Test primero o después, cobertura mínima, tipado, qué nunca se mockea	CONTRIBUTING.md §5; si es no negociable, también un principio
5. Seguridad	Autenticación, datos sensibles, validación de entrada, cumplimiento normativo	ARCHITECTURE.md §10, SECURITY.md
6. Proceso	Ramas, Conventional Commits, merge o squash, aprobaciones, tamaño del PR, herramientas de IA permitidas	CONTRIBUTING.md §4, §6–7
7. Dependencias	Política para añadirlas, librerías prohibidas, construir o comprar	Principio (si es no negociable) o CONTRIBUTING.md
8. Para el agente	Comandos (el de verificación es obligatorio), convenciones no obvias, áreas críticas o frágiles (brownfield), límites (siempre / preguntar / nunca)	AGENTS.md

En la ronda 8, el comando de verificación es el contrato con las otras habilidades (plan-to-tasks, implement, review). Si no existe, propon setup-guardrails-python (o un equivalente para el lenguaje) o déjalo como pregunta abierta en AGENTS.md. Si el proyecto va a usar review-prepush o review-pr, ofrece también la sección opcional ## Code review (plantilla en review-context/assets/AGENTS-code-review.md): rama base, rutas de alto riesgo, idioma del informe…

3. Redactar y escribir

Orden: ARCHITECTURE.md → ADRs → CONTRIBUTING.md → SECURITY.md → AGENTS.md. AGENTS.md va al final porque enlaza a todos ellos.

• Empieza desde la plantilla en assets/. Elimina las secciones que aún no apliquen; no las dejes vacías.
• ADRs: copia ADR.md como docs/adr/0000-template.md (0000-plantilla.md en español) y adr-README.md como docs/adr/README.md. Crea un ADR por cada decisión estructural de las rondas 2–3. Brownfield: solo 3–5 retroactivos, para lo más cuestionado, con las alternativas descartadas.
• AGENTS.md debe incluir:
  • la línea "Planificación": verificar el plan contra los principios en docs/ARCHITECTURE.md antes de implementar;
  • un enlace a CONTRIBUTING.md para el proceso.
• CLAUDE.md contiene solo @AGENTS.md, a menos que ya tenga contenido. En ese caso, propón moverlo a AGENTS.md.
• pull_request_template.md va en .github/. Ofrécelo, no lo impongas.

4. Cierre

Enumera los archivos creados o modificados y las preguntas que quedaron abiertas. Recuerda a la persona:

• AGENTS.md se revisa mensualmente y se poda, especialmente al cambiar de modelo.
• ARCHITECTURE.md se compara con el código cada trimestre.
• Cada error que el agente repite se convierte en una regla de herramienta o, como último recurso, en una línea bajo "Errores conocidos".