diff --git a/.claude/commands/init-proyecto.md b/.claude/commands/init-proyecto.md index 1ffc91e..279054a 100644 --- a/.claude/commands/init-proyecto.md +++ b/.claude/commands/init-proyecto.md @@ -30,7 +30,8 @@ Ejecuta el checklist de "Inicialización del proyecto" de `CLAUDE.md`: y "Qué NO hacer". Borra los comentarios que ya no apliquen y la sección de inicialización del proyecto (ya no hace falta) junto con la referencia a este comando. **El "Protocolo de MCPs" se queda**: sigue aplicando cada vez que entre una integración nueva. -3. `LICENSE` — sustituye `[YEAR]` y `[AUTHOR]`. +3. `LICENSE` — sustituye la línea de copyright de la plantilla por el año actual y el + titular de este proyecto. 4. `.env.example` — deja solo las variables del stack real. 5. MCPs — pregunta qué servidores MCP quiere y con qué alcance, siguiendo el "Protocolo de MCPs" de `CLAUDE.md`. Si prefieres tratarlo aparte, lanza `/mcp-setup`. diff --git a/.template/changelog/2026-08-18_15-09_readme-con-badges-y-licencia-rellena.md b/.template/changelog/2026-08-18_15-09_readme-con-badges-y-licencia-rellena.md new file mode 100644 index 0000000..697273a --- /dev/null +++ b/.template/changelog/2026-08-18_15-09_readme-con-badges-y-licencia-rellena.md @@ -0,0 +1,55 @@ +# README con cabecera, diagrama y tabla de comandos; licencia con titular real + +**Fecha:** 2026-08-18 15:09 +**Tipo:** Documentación +**Requisitos:** Ninguno (cambio sobre el andamiaje de la plantilla) + +## Qué se hizo + +**Licencia.** `LICENSE` llevaba desde el primer commit con los placeholders `[YEAR]` y +`[AUTHOR]` sin rellenar, lo que dejaba la plantilla en un limbo: dice MIT pero sin titular, que +es como no decir nada. Ahora es `Copyright (c) 2026 Pol Marzà` — 2026 por el primer commit del +repositorio, del 7 de mayo. + +Eso obligaba a tocar tres sitios más: el checklist de inicialización de `CLAUDE.md`, el comando +`/init-proyecto` y la tabla de adaptación del README pedían "sustituye `[YEAR]` y `[AUTHOR]`", +y esos marcadores ya no existen. Ahora dicen lo que toca: la plantilla se distribuye con el +copyright de su autor y cada proyecto pone el suyo al inicializar. + +**README.** Cabecera centrada con cuatro badges (estado del workflow de cobertura, licencia, +pnpm v11 y agnosticismo de stack) y un enlace directo a *Usar esta plantilla*, que hasta ahora +solo se mencionaba de pasada en el paso 1. + +Añadido un diagrama Mermaid del ciclo completo —requisito con criterio → ficha Acordada → En +construcción → tests sobre el código real → Verificada → PR con la cobertura verificada en CI— +como resumen visual antes de los diez puntos del protocolo, que se leían como un muro. + +Y una tabla de comandos: los seis slash commands estaban enterrados dentro de un bullet de la +sección "¿Qué hay dentro?", donde no los encontraba nadie. + +## Qué se modificó + +- `LICENSE` — titular y año reales +- `README.md` — cabecera con badges y llamada a la acción; diagrama Mermaid del ciclo de feature; + nueva sección "Comandos"; fila de `LICENSE` en la tabla de adaptación reescrita; pie con el + copyright +- `CLAUDE.md` — paso 3 del checklist de inicialización (copyright en vez de placeholders); aviso + en el paso 1 de que los badges apuntan al repositorio de la plantilla y hay que quitarlos o + repuntarlos +- `.claude/commands/init-proyecto.md` — mismo cambio en su paso 3 + +## Por qué + +Lo de la licencia no era cosmético: un MIT sin titular no concede permisos a nadie con claridad, +y este repositorio es público y está pensado para que la gente lo copie. + +Lo del README, en cambio, sí es presentación — pero de la clase que importa en un repositorio +plantilla, donde la página de inicio es el producto. Los badges elegidos son los cuatro que dicen +algo cierto y comprobable; no hay ninguno decorativo del tipo "PRs welcome" ni métricas de +paquetes que este repositorio no publica. + +## Verificado + +- Las cuatro URLs de badge devuelven `200` con `image/svg+xml`. +- El badge del workflow refleja el estado real del último run en `main`. +- `node scripts/verificar-cobertura.mjs` sigue saliendo limpio. diff --git a/CLAUDE.md b/CLAUDE.md index 4335603..b57d464 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,14 +87,16 @@ Puedes lanzar el proceso completo con `/init-proyecto`. una línea, qué problema resuelve, requisitos previos, variables de entorno (referencia a `.env.example`), instalación y desarrollo (`pnpm install`, `pnpm dev`), estructura de carpetas, cómo contribuir (referencia a `CLAUDE.md` y al protocolo) y estado del proyecto. + Los badges de la cabecera apuntan al repositorio de la plantilla: quítalos o repóntalos al + tuyo, o quedarán enseñando el estado de un repo que no es este. 2. **`CLAUDE.md`** — rellena los placeholders de este mismo archivo: nombre, descripción, estado, stack tecnológico, estructura de carpetas, convenciones de código y "Qué NO hacer". Borra los comentarios `` que ya no apliquen, esta sección de inicialización (deja de tener sentido una vez hecha), el comando `.claude/commands/init-proyecto.md` y las referencias a `.template/` del arranque y del protocolo de changelog. El "Protocolo de MCPs" se queda: sigue aplicando cada vez que entre una integración nueva. -3. **`LICENSE`** — sustituye `[YEAR]` y `[AUTHOR]` por los valores reales. Pregunta el nombre - del autor si no lo sabes. +3. **`LICENSE`** — la plantilla se distribuye con el copyright de su autor. Sustituye esa línea + por el año actual y el titular de *este* proyecto. Pregunta el nombre si no lo sabes. 4. **`.env.example`** — deja solo las variables que el stack elegido necesita de verdad. 5. **MCPs** — con el stack ya decidido, pregunta al usuario qué servidores MCP quiere y con qué alcance, siguiendo el "Protocolo de MCPs" (o lanza `/mcp-setup`). diff --git a/LICENSE b/LICENSE index ff9e90f..29f439a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) [YEAR] [AUTHOR] +Copyright (c) 2026 Pol Marzà Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 21fa856..b0cc62d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,20 @@ -# project-template +

project-template

-Plantilla para empezar proyectos cuando trabajas con agentes de código (Claude Code, Cursor y compañía) sin que se pongan a escribir antes de entender qué estás construyendo. +

+ Plantilla para empezar proyectos cuando trabajas con agentes de código
+ sin que se pongan a escribir antes de entender qué estás construyendo. +

+ +

+ Cobertura + Licencia MIT + pnpm v11 + Agnóstica al stack +

+ +

+ Usar esta plantilla → +

--- @@ -28,7 +42,7 @@ Es agnóstica al stack. El protocolo funciona igual con Next.js, Astro, FastAPI - **`docs/features/`** — Una ficha por unidad de trabajo acordada: qué se construye, qué requisitos cierra y **cómo se va a comprobar cada uno**. Es el contrato que se firma antes de escribir código. **Llega vacía**. - **`changelog/`** — Registro estructurado de cada cambio importante: qué, cuándo, por qué y qué requisitos cierra. **Llega vacío**: solo con el archivo que explica el formato. - **`mejoras/`** — Backlog de ideas que no entran en el sprint actual pero no se quieren perder. -- **`.claude/`** — Configuración de Claude Code con permisos sensatos y slash commands custom (`/feature`, `/changelog`, `/mejora`, `/doctor`, `/mcp-setup`, `/init-proyecto`) para no tener que recordar el protocolo de memoria. +- **`.claude/`** — Configuración de Claude Code con permisos sensatos y slash commands custom, para no tener que recordar el protocolo de memoria. - **`scripts/`** — Una verificación ejecutable: comprueba que ninguna ficha deje un requisito sin validar y que los tests prometidos existan de verdad. Node sin dependencias. - **`.github/`** — Plantillas de pull request e issues alineadas con el protocolo, y el workflow que ejecuta esa verificación en cada PR. El PR pide **evidencia pegada**, no casillas marcadas. - **`.template/`** — Historial de la plantilla en sí. Se borra al inicializar tu proyecto, así no arrastras cambios que no son tuyos. @@ -38,6 +52,17 @@ Es agnóstica al stack. El protocolo funciona igual con Next.js, Astro, FastAPI ## ¿Cómo funciona el protocolo? +```mermaid +flowchart LR + A["Requisito en docs/prd.md
con criterio de aceptación"] + B["Ficha de feature
Acordada"] + C["En construcción"] + D["Tests escritos
sobre el código real"] + E["Verificada"] + F["PR con evidencia
CI verifica la cobertura"] + A --> B --> C --> D --> E --> F +``` + 1. **Cualquier sesión empieza leyendo `docs/`.** Si están vacíos o incompletos, el agente pregunta antes de actuar. Y no pide los ocho documentos: pide los que correspondan al tamaño del proyecto. 2. **Cada funcionalidad del PRD lleva ID y criterio de aceptación comprobable.** "Dado…, cuando…, entonces…", con un resultado que se pueda mirar. Ese criterio es el que después se convierte en test. 3. **Antes de construir una feature se escribe su ficha** en `docs/features/`, con una tabla que dice cómo se validará cada requisito. Ningún requisito se queda sin tercera columna: o lleva la ruta de su test, o lleva la razón concreta por la que no se puede testear así. **Y esto no es honor system**: un script lo verifica en cada PR, y falla si un test prometido no existe. @@ -51,9 +76,22 @@ Es agnóstica al stack. El protocolo funciona igual con Next.js, Astro, FastAPI --- +## Comandos + +| Comando | Qué hace | +|---------|----------| +| `/feature` | Crea la ficha de una feature **antes** de construirla, con su tabla de cobertura | +| `/changelog` | Registra un cambio con el formato del proyecto | +| `/mejora` | Añade una idea al backlog sin romper el flujo de trabajo | +| `/doctor` | Parte del estado: documentación, fichas a medias, entorno, variables, MCPs y tests | +| `/mcp-setup` | Configura los servidores MCP del stack, preguntando alcance y credenciales | +| `/init-proyecto` | Convierte la plantilla en el repositorio de tu proyecto (una sola vez) | + +--- + ## ¿Cómo empezar? -1. Usa este repo como plantilla en GitHub (botón **"Use this template"**) o clónalo directamente. +1. Pulsa **[Usar esta plantilla](https://github.com/polmarza/project-template/generate)** en GitHub, o clona el repo directamente. 2. Abre el proyecto en Claude Code, Cursor o el agente que prefieras. 3. Cuando el agente lea `CLAUDE.md` por primera vez, te preguntará qué quieres construir y para quién. Responde y deja que vaya completando los docs contigo, uno a uno. 4. Con los docs rellenos, el agente **inicializa el proyecto**: reescribe este README para tu producto, rellena los datos de `CLAUDE.md`, ajusta la licencia y `.env.example`, borra los documentos que tu proyecto no necesite y `.template/`, y deja el changelog con su primera entrada real. Lo hace solo; si quieres forzarlo, usa `/init-proyecto`. @@ -76,13 +114,13 @@ No tienes que hacerlo a mano: el agente lo hace en la inicialización, siguiendo | Archivo | Qué pasa con él | |---------|-----------------| -| `README.md` | Se reescribe entero para tu producto (este texto desaparece) | +| `README.md` | Se reescribe entero para tu producto (este texto y sus badges desaparecen) | | `CLAUDE.md` | Se rellenan nombre, stack, estructura y convenciones | -| `LICENSE` | Se sustituyen `[YEAR]` y `[AUTHOR]` | +| `LICENSE` | El copyright pasa a ser el tuyo | | `.env.example` | Se queda solo con las variables de tu stack | | `docs/` | Se borran los documentos que tu proyecto no necesita, según su tamaño | -| `scripts/` | Se queda tal cual: la verificación no depende del stack | | `docs/features/` | Se queda vacía, lista para la primera ficha | +| `scripts/` | Se queda tal cual: la verificación no depende del stack | | `changelog/` | Recibe la primera entrada real del proyecto | | `mejoras/backlog.md` | Se limpia el ejemplo | | `.template/` | Se borra | @@ -93,4 +131,4 @@ El criterio es simple: cuando termina la inicialización, **ningún archivo del ## Licencia -MIT. Ver [`LICENSE`](./LICENSE). +MIT © 2026 Pol Marzà. Ver [`LICENSE`](./LICENSE).