From b35bc7a607a32cf88f1aef5c3cd668cf0e1d205d Mon Sep 17 00:00:00 2001 From: Toni Ramiro Date: Sun, 18 Oct 2026 13:34:20 +0200 Subject: [PATCH] feat: paquete pi-new-project con la skill new-project --- CHANGELOG.md | 27 ++++ INSTALL.md | 102 ++++++++++++++ README.md | 55 ++++++++ TODO.md | 24 ++++ package.json | 14 ++ skills/new-project/SKILL.md | 57 ++++++++ skills/new-project/references/plantillas.md | 32 +++++ skills/new-project/scripts/new-project.sh | 125 ++++++++++++++++++ skills/new-project/templates/.gitignore.tmpl | 27 ++++ skills/new-project/templates/AGENTS.md.tmpl | 73 ++++++++++ .../new-project/templates/CHANGELOG.md.tmpl | 24 ++++ skills/new-project/templates/INSTALL.md.tmpl | 79 +++++++++++ skills/new-project/templates/README.md.tmpl | 56 ++++++++ skills/new-project/templates/TODO.md.tmpl | 21 +++ 14 files changed, 716 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 INSTALL.md create mode 100644 README.md create mode 100644 TODO.md create mode 100644 package.json create mode 100644 skills/new-project/SKILL.md create mode 100644 skills/new-project/references/plantillas.md create mode 100755 skills/new-project/scripts/new-project.sh create mode 100644 skills/new-project/templates/.gitignore.tmpl create mode 100644 skills/new-project/templates/AGENTS.md.tmpl create mode 100644 skills/new-project/templates/CHANGELOG.md.tmpl create mode 100644 skills/new-project/templates/INSTALL.md.tmpl create mode 100644 skills/new-project/templates/README.md.tmpl create mode 100644 skills/new-project/templates/TODO.md.tmpl diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..4300479 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,27 @@ +# Changelog + +Todos los cambios relevantes de este proyecto se documentan en este fichero. + +El formato sigue [*Keep a Changelog*](https://keepachangelog.com/es-ES/1.1.0/) +y el proyecto usa [Versionado Semántico](https://semver.org/lang/es/). + +## [No publicado] + +### Pendiente + +- Fijar las reglas de modelo y de funcionamiento que la skill escribirá en el + `AGENTS.md` de cada proyecto generado (hoy quedan como `PENDIENTE`). + +## [0.1.0] - 2026-10-18 + +### Añadido + +- Paquete pi `pi-new-project` con la skill `new-project`. +- `scripts/new-project.sh`: andamiaje en bash con `--nombre`, `--descripcion`, + `--autor`, `--git`, `--force` y `--dry-run`. +- Plantillas de `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TODO.md`, `INSTALL.md` + y `.gitignore`, con marcadores `{{PROYECTO}}`, `{{DESCRIPCION}}`, `{{AUTOR}}` + y `{{FECHA}}`. +- `AGENTS.md` generado con las secciones reservadas `## Reglas de modelo` y + `## Reglas de funcionamiento`. +- Documentación de instalación, exportación a otro ordenador y verificación. diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..504fe31 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,102 @@ +# INSTALL — pi-new-project + +Instalación del paquete/skill `new-project` en pi, en este ordenador o en +cualquier otro. + +## 1. Requisitos + +| Componente | Versión mínima | Notas | +| --- | --- | --- | +| pi | 1.3.0 | Hace falta soporte de skills y de paquetes (`pi install`). | +| bash | 4.0 | El script usa arrays y `${var//}`. | +| git | cualquiera | Opcional: `--git` y autor por defecto. | +| shellcheck | opcional | Para validar el script (`shellcheck new-project.sh`). | + +## 2. Opción A — instalarlo como paquete de pi (recomendado) + +Desde el directorio que contiene `pi-new-project/`: + +```bash +pi install ./pi-new-project +``` + +O desde git/npm cuando se publique: + +```bash +pi install git:github.com//pi-new-project@v0.1.0 +``` + +Comprueba con `pi list` y arranca pi: la skill aparecerá como `new-project`. +Para una prueba puntual sin instalarlo: `pi -e ./pi-new-project`. + +## 3. Opción B — copiar la skill + +Copia el directorio de la skill a una de las rutas que pi descubre: + +```bash +mkdir -p ~/.agents/skills +cp -r pi-new-project/skills/new-project ~/.agents/skills/ +``` + +o enlázalo para mantenerlo actualizado con el repositorio: + +```bash +ln -s "$PWD/pi-new-project/skills/new-project" ~/.agents/skills/new-project +``` + +Rutas equivalentes: `~/.pi/agent/skills/` y, por proyecto, `.agents/skills/`. + +## 4. Opción C — exportar a otro ordenador + +No hay más que copiar el directorio; no tiene dependencias. + +```bash +# en el ordenador origen +tar -czf pi-new-project-0.1.0.tar.gz pi-new-project/ + +# en el ordenador destino +tar -xzf pi-new-project-0.1.0.tar.gz +pi install ./pi-new-project # o la opción B +``` + +Alternativa sin `tar`: publicar el repositorio y usar `pi install `. + +## 5. Verificación + +```bash +bash -n pi-new-project/skills/new-project/scripts/new-project.sh +pi-new-project/skills/new-project/scripts/new-project.sh --dry-run --nombre Demo /tmp/demo + +# prueba real en un directorio temporal +pi-new-project/skills/new-project/scripts/new-project.sh \ + --nombre Demo --descripcion "Proyecto de prueba" --git /tmp/demo +ls -A /tmp/demo +``` + +Deben aparecer `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TODO.md`, `INSTALL.md` +y `.gitignore`, sin marcadores `{{...}}` pendientes. + +## 6. Actualización + +```bash +git pull +pi update --extensions # si se instaló como paquete +``` + +## 7. Desinstalación + +```bash +pi remove ./pi-new-project # si se instaló como paquete +rm -rf ~/.agents/skills/new-project # si se copió o enlazó +``` + +La skill no deja estado propio: no hay caché ni configuración que limpiar. + +## 8. Resolución de problemas + +| Síntoma | Causa probable | Solución | +| --- | --- | --- | +| La skill no aparece | Ruta no descubierta | Comprueba la ruta con `pi list` o colócala en `~/.agents/skills/`. | +| `no encuentro las plantillas` | Falta `templates/` | Reinstala el paquete completo, no solo el script. | +| `no puedo deducir el nombre` | Destino `.` o `/` | Pasa `--nombre`. | +| No sobreescribe mis ficheros | Protección por defecto | Usa `--force` tras revisar `--dry-run`. | diff --git a/README.md b/README.md new file mode 100644 index 0000000..a507f48 --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# pi-new-project + +Paquete de [pi](https://pi.dev) que genera la base documental de un proyecto +nuevo: `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TODO.md`, `INSTALL.md` y +`.gitignore`, listos para versionar y con las secciones de reglas reservadas +para acordarlas después. + +## Contenido + +```text +pi-new-project/ +├── package.json # manifiesto de paquete pi +├── README.md # este documento +├── INSTALL.md # instalación en otro ordenador +├── CHANGELOG.md +├── TODO.md +└── skills/ + └── new-project/ + ├── SKILL.md # instrucciones para el agente + ├── scripts/new-project.sh # andamiaje (bash, sin dependencias) + ├── templates/ # plantillas con {{MARCADORES}} + └── references/plantillas.md # qué es cada documento +``` + +## Uso + +En una sesión de pi, pide crear un proyecto nuevo; la skill `new-project` se +activa sola. También puedes forzarla: + +```text +/skill:new-project crea el proyecto "gestor-gastos" en ~/src/gestor-gastos +``` + +O ejecutar el script directamente: + +```bash +skills/new-project/scripts/new-project.sh --help +skills/new-project/scripts/new-project.sh \ + --nombre "Gestor de gastos" \ + --descripcion "API para registrar y consultar gastos personales" \ + --git ~/src/gestor-gastos +``` + +El script nunca sobreescribe ficheros existentes salvo con `--force`, y admite +`--dry-run` para revisar antes. + +## Instalación + +Ver [`INSTALL.md`](INSTALL.md). Resumen: copia (o enlaza) el directorio en +`~/.pi/agent/skills/` o instálalo como paquete con `pi install ./pi-new-project`. + +## Requisitos + +- `bash` 4+ y `git` (opcional, solo para `--git` y el autor por defecto). +- No usa Python, Node ni dependencias externas: es `bash` con biblioteca estándar. diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..8fbe87e --- /dev/null +++ b/TODO.md @@ -0,0 +1,24 @@ +# TODO — pi-new-project + +## En curso + +- [ ] _(nada en curso)_ + +## Pendiente + +- [ ] Definir las **reglas de modelo** (modelo, contexto, criterio de selección) + y volcarlas en `templates/AGENTS.md.tmpl`. +- [ ] Definir las **reglas de funcionamiento** comunes y volcarlas en + `templates/AGENTS.md.tmpl`. +- [ ] Decidir si las reglas se configuran por parámetros del script + (p. ej. `--modelo`, `--contexto`, `--stack`) o ficheros de perfil. +- [ ] Detectar y completar el stack automáticamente (¿`--stack python|node|rust`?) + para prellenar `INSTALL.md` y los comandos de verificación. +- [ ] Valorar soporte multiidioma (`--lang es|en`) en plantillas y script. +- [ ] Publicar el paquete (git o npm) para instalarlo con `pi install `. +- [ ] Prueba automática del script (golden test de los ficheros generados). + +## Hecho + +- [x] 2026-10-18 — estructura del paquete, skill, script y plantillas. +- [x] 2026-10-18 — `INSTALL.md` con exportación a otro ordenador. diff --git a/package.json b/package.json new file mode 100644 index 0000000..73982ed --- /dev/null +++ b/package.json @@ -0,0 +1,14 @@ +{ + "name": "pi-new-project", + "version": "0.1.0", + "private": true, + "description": "Paquete de pi con la skill new-project: genera la base documental de un proyecto (AGENTS.md, README, CHANGELOG, TODO, INSTALL).", + "keywords": [ + "pi-package" + ], + "pi": { + "skills": [ + "./skills" + ] + } +} diff --git a/skills/new-project/SKILL.md b/skills/new-project/SKILL.md new file mode 100644 index 0000000..d345b2d --- /dev/null +++ b/skills/new-project/SKILL.md @@ -0,0 +1,57 @@ +--- +name: new-project +description: Genera la base documental de un proyecto nuevo (AGENTS.md, README.md, CHANGELOG.md, TODO.md, INSTALL.md y .gitignore) a partir de plantillas. Úsala cuando el usuario pida crear un proyecto, repositorio o directorio nuevo, inicializar su documentación o "montar el esqueleto" de un repo. +license: MIT +--- + +# new-project + +Genera el esqueleto documental de un proyecto. Todas las plantillas están en +`templates/` y el andamiaje lo hace `scripts/new-project.sh`. + +## Procedimiento + +1. **Recoge los datos** que falten antes de ejecutar nada: + - ruta de destino (obligatoria); + - nombre del proyecto (por defecto, el nombre del directorio destino); + - descripción en una frase (obligatoria: se usa en README y AGENTS); + - autor (opcional; por defecto `git config user.name`); + - si hay que inicializar un repositorio git (`--git`). + No inventes la descripción: si el usuario no la da, pregúntala o propón una + y confírmala. +2. **Ejecuta el script** desde este directorio de skill: + + ```bash + scripts/new-project.sh --nombre "Mi Proyecto" --descripcion "Qué hace" \ + --git /ruta/al/proyecto + ``` + + El script no sobreescribe ficheros existentes salvo con `--force` y muestra + un resumen de lo creado. Usa `--dry-run` para revisar antes. +3. **Revisa el resultado**: abre `README.md` y `AGENTS.md` del proyecto generado + y completa lo que quede como `PENDIENTE` (objetivos, stack, comandos de + verificación reales). No dejes marcadores de plantilla ni secciones vacías. +4. **Ajusta** `INSTALL.md` con los requisitos y pasos reales del stack elegido. +5. **Commit inicial** si se creó repo git: + + ```bash + git add -A && git commit -m "docs: base documental inicial" + ``` +6. Informa al usuario de la ruta creada, los ficheros y del commit. + +## Reglas + +- No ejecutes el script sobre un directorio que ya tiene `AGENTS.md` o `README.md` + sin avisar y confirmar (usaría `--force`). +- Las secciones `## Reglas de modelo` y `## Reglas de funcionamiento` de + `AGENTS.md` se dejan como `PENDIENTE` a propósito: se acuerdan después, por + proyecto. No las rellenes con suposiciones. +- Idioma de los documentos generados: español. +- Rutas relativas siempre desde este directorio de skill. + +## Referencia + +- `scripts/new-project.sh --help` — todas las opciones. +- `templates/` — plantillas con marcadores `{{PROYECTO}}`, `{{DESCRIPCION}}`, + `{{AUTOR}}`, `{{FECHA}}`, `{{FECHA_ISO}}`. +- `references/plantillas.md` — qué contiene cada documento y cuándo tocarlo. diff --git a/skills/new-project/references/plantillas.md b/skills/new-project/references/plantillas.md new file mode 100644 index 0000000..b2c882b --- /dev/null +++ b/skills/new-project/references/plantillas.md @@ -0,0 +1,32 @@ +# Plantillas de la base documental + +Qué genera `new-project.sh` y cuándo hay que tocar cada documento. + +| Documento | Para qué sirve | Cuándo actualizarlo | +| --- | --- | --- | +| `AGENTS.md` | Reglas de trabajo para agentes y colaboradores: flujo, commits, verificación y las futuras reglas de modelo y de funcionamiento. | Al cambiar el flujo, las reglas, los comandos de verificación o al fijar las reglas de modelo. | +| `README.md` | Puerta de entrada: qué es el proyecto, estado, instalación rápida, uso y estructura. | Al cambiar el propósito, el uso o la estructura. | +| `INSTALL.md` | Instalación reproducible: requisitos, dependencias, configuración, verificación, arranque, actualización y desinstalación. | Al añadir dependencias, variables de entorno o cambiar pasos de instalación. | +| `CHANGELOG.md` | Historial *Keep a Changelog*: `Añadido` / `Cambiado` / `Corregido` / `Eliminado`. | En cada cambio, sin excepción. | +| `TODO.md` | Tareas en curso, pendientes y hechas, incluida la deuda técnica. | Al abrir o cerrar tareas. | +| `.gitignore` | Exclusiones básicas: secretos, dependencias descargadas, artefactos de build, logs. | Al detectar ficheros que no deben versionarse. | + +## Marcadores + +El script sustituye estos marcadores en todas las plantillas: + +| Marcador | Valor | +| --- | --- | +| `{{PROYECTO}}` | `--nombre` o, si falta, el nombre del directorio destino. | +| `{{DESCRIPCION}}` | `--descripcion` o un `PENDIENTE` explícito. | +| `{{AUTOR}}` | `--autor` o `git config user.name`. | +| `{{FECHA}}` y `{{FECHA_ISO}}` | Fecha de ejecución en formato `AAAA-MM-DD`. | + +## Secciones reservadas + +`AGENTS.md` incluye a propósito dos secciones con `PENDIENTE`: + +- `## Reglas de modelo` — modelo de pi, contexto y criterio de selección. +- `## Reglas de funcionamiento` — estándares, ramas, revisión y automatización. + +No se rellenan al generar el proyecto: se acuerdan después, proyecto a proyecto. diff --git a/skills/new-project/scripts/new-project.sh b/skills/new-project/scripts/new-project.sh new file mode 100755 index 0000000..eab632b --- /dev/null +++ b/skills/new-project/scripts/new-project.sh @@ -0,0 +1,125 @@ +#!/usr/bin/env bash +# Genera la base documental de un proyecto a partir de las plantillas de la skill. +set -euo pipefail + +# bash >= 5.2 sustituye '&' del reemplazo por el patrón encontrado; lo desactivamos +# para que los valores con '&' o '\' se inserten literales. +shopt -u patsub_replacement 2>/dev/null || true + +SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" +TEMPLATES_DIR="$SCRIPT_DIR/../templates" + +PROYECTO="" +DESCRIPCION="" +AUTOR="" +DESTINO="" +INIT_GIT=0 +FORCE=0 +DRY_RUN=0 +FECHA_ISO="$(date +%Y-%m-%d)" + +uso() { + cat <<'EOF' +Uso: new-project.sh [opciones] + +Genera AGENTS.md, README.md, CHANGELOG.md, TODO.md, INSTALL.md y .gitignore. + +Opciones: + -n, --nombre NOMBRE Nombre del proyecto (por defecto: nombre del directorio). + -d, --descripcion TEXTO Descripción en una frase (por defecto: PENDIENTE). + -a, --autor NOMBRE Autor (por defecto: git config user.name). + -g, --git Inicializa un repositorio git en el destino. + -f, --force Sobreescribe ficheros que ya existan. + --dry-run Muestra lo que haría sin escribir nada. + -h, --help Muestra esta ayuda. +EOF +} + +die() { printf 'error: %s\n' "$*" >&2; exit 1; } +aviso() { printf 'aviso: %s\n' "$*" >&2; } + +while [[ $# -gt 0 ]]; do + case "$1" in + -n | --nombre) PROYECTO="${2:-}"; shift 2 ;; + -d | --descripcion) DESCRIPCION="${2:-}"; shift 2 ;; + -a | --autor) AUTOR="${2:-}"; shift 2 ;; + -g | --git) INIT_GIT=1; shift ;; + -f | --force) FORCE=1; shift ;; + --dry-run) DRY_RUN=1; shift ;; + -h | --help) uso; exit 0 ;; + --) shift; break ;; + -*) die "opción desconocida: $1 (usa --help)" ;; + *) break ;; + esac +done + +[[ $# -ge 1 ]] || { uso >&2; exit 2; } +DESTINO="$1" +[[ $# -eq 1 ]] || die "solo se admite un directorio destino" + +[[ -d "$TEMPLATES_DIR" ]] || die "no encuentro las plantillas en $TEMPLATES_DIR" + +if [[ -z "$PROYECTO" ]]; then + PROYECTO="$(basename -- "${DESTINO%/}")" +fi +[[ -n "$PROYECTO" ]] || die "no puedo deducir el nombre del proyecto; usa --nombre" + +if [[ -z "$DESCRIPCION" ]]; then + DESCRIPCION="PENDIENTE: describir $PROYECTO en una frase." + aviso "sin --descripcion; se deja un PENDIENTE en README.md y AGENTS.md" +fi + +if [[ -z "$AUTOR" ]]; then + AUTOR="$(git config user.name 2>/dev/null || true)" + [[ -n "$AUTOR" ]] || AUTOR="PENDIENTE" +fi + +FICHEROS=(AGENTS.md README.md CHANGELOG.md TODO.md INSTALL.md .gitignore) + +render() { + local plantilla="$1" salida="$2" contenido + contenido="$(<"$plantilla")" + contenido="${contenido//'{{PROYECTO}}'/$PROYECTO}" + contenido="${contenido//'{{DESCRIPCION}}'/$DESCRIPCION}" + contenido="${contenido//'{{AUTOR}}'/$AUTOR}" + contenido="${contenido//'{{FECHA}}'/$FECHA_ISO}" + contenido="${contenido//'{{FECHA_ISO}}'/$FECHA_ISO}" + printf '%s\n' "$contenido" > "$salida" +} + +destino_abs="$(cd -- "$DESTINO" 2>/dev/null && pwd || true)" +[[ -n "$destino_abs" ]] || destino_abs="$DESTINO" + +creados=() +omitidos=() + +for fichero in "${FICHEROS[@]}"; do + ruta="$DESTINO/$fichero" + if [[ -e "$ruta" && $FORCE -eq 0 ]]; then + omitidos+=("$fichero") + aviso "$fichero ya existe; se omite (usa --force para sobreescribir)" + continue + fi + if [[ $DRY_RUN -eq 1 ]]; then + printf 'dry-run: escribiría %s\n' "$ruta" + else + mkdir -p -- "$DESTINO" + render "$TEMPLATES_DIR/$fichero.tmpl" "$ruta" + fi + creados+=("$fichero") +done + +if [[ $INIT_GIT -eq 1 && $DRY_RUN -eq 0 ]]; then + if [[ -d "$DESTINO/.git" ]]; then + aviso "$DESTINO ya es un repositorio git" + else + git -C "$DESTINO" init -q + printf 'git: repositorio inicializado en %s\n' "$destino_abs" + fi +fi + +printf '\nproyecto: %s\n' "$PROYECTO" +printf 'destino: %s\n' "$destino_abs" +printf 'creados: %s\n' "${creados[*]:-ninguno}" +[[ ${#omitidos[@]} -eq 0 ]] || printf 'omitidos: %s\n' "${omitidos[*]}" +[[ $DRY_RUN -eq 1 ]] || printf 'siguiente: revisa README.md, INSTALL.md y las secciones PENDIENTE de AGENTS.md\n' diff --git a/skills/new-project/templates/.gitignore.tmpl b/skills/new-project/templates/.gitignore.tmpl new file mode 100644 index 0000000..0b3be00 --- /dev/null +++ b/skills/new-project/templates/.gitignore.tmpl @@ -0,0 +1,27 @@ +# Secretos y configuración local +.env +.env.* +!.env.example + +# Dependencias descargadas +node_modules/ +vendor/ +venv/ +.venv/ +__pycache__/ +*.py[cod] + +# Artefactos de build +dist/ +build/ +target/ +out/ +*.log +logs/ + +# Sistema operativo y editores +.DS_Store +Thumbs.db +.idea/ +.vscode/ +*.swp diff --git a/skills/new-project/templates/AGENTS.md.tmpl b/skills/new-project/templates/AGENTS.md.tmpl new file mode 100644 index 0000000..58c534c --- /dev/null +++ b/skills/new-project/templates/AGENTS.md.tmpl @@ -0,0 +1,73 @@ +# AGENTS.md + +Guía para agentes y colaboradores que trabajen en **{{PROYECTO}}**. +Léela antes de tocar cualquier fichero y respétala en cada cambio. + +## Propósito del proyecto + +{{DESCRIPCION}} + +## Contenido del repositorio + +| Ruta | Descripción | +| --- | --- | +| `AGENTS.md` | Este documento: reglas de trabajo. | +| `README.md` | Visión general y puesta en marcha. | +| `INSTALL.md` | Instalación detallada y dependencias. | +| `CHANGELOG.md` | Historial de cambios (*Keep a Changelog*). | +| `TODO.md` | Tareas pendientes y deuda técnica. | +| _(completar)_ | Añade aquí el código y los recursos del proyecto. | + +## Reglas de modelo + +PENDIENTE: definir qué modelo de pi se usa en este proyecto, con qué contexto y +con qué criterio de selección (coste, VRAM, ventana, velocidad). Se acuerda +tarea por tarea; hasta entonces, no fijar valores aquí. + +## Reglas de funcionamiento + +PENDIENTE: definir flujo de trabajo, estándares de código, comandos obligatorios, +política de ramas y de revisión, y cualquier automatización propia del proyecto. + +## Reglas obligatorias + +1. **Todo cambio se documenta y se commitea.** Cada vez que se modifique + cualquier fichero del repositorio: + - Añadir una entrada en `CHANGELOG.md` (fecha, versión y tipo: + `Añadido` / `Cambiado` / `Corregido` / `Eliminado`). + - Actualizar `TODO.md` si el cambio abre, cierra o modifica tareas. + - Actualizar `README.md`, `INSTALL.md` o los documentos que correspondan si + cambia el comportamiento, la instalación o el uso. + - Crear **un commit de git** con mensaje claro en imperativo. +2. **Nunca dejar documentación desfasada.** Si el código y los documentos no + coinciden, el cambio está incompleto. +3. **No commitear** secretos, binarios, artefactos de build, logs ni dependencias + descargadas (`.gitignore` cubre lo básico; amplíalo según el stack). +4. **Idioma: español** para documentación, mensajes de commit y comentarios. + +## Verificación antes de commitear + +PENDIENTE: sustituir por los comandos reales del stack (formato, tipos, tests, +lint). Ningún commit sin verificación en verde. + +```bash +# ejemplo +# make check +``` + +## Flujo de trabajo + +1. Editar los ficheros necesarios. +2. Ejecutar las verificaciones anteriores. +3. Actualizar `CHANGELOG.md`, `TODO.md` y la documentación afectada. +4. `git add -A && git commit -m "tipo(alcance): descripción breve"`. +5. Informar del cambio y del hash del commit. + +## Convención de mensajes de commit + +`tipo(alcance): resumen` — tipos: `feat`, `fix`, `docs`, `chore`, `refactor`, +`test`, `build`, `perf`. + +Ejemplos: +- `docs: documentar instalación y puesta en marcha` +- `feat(api): añadir búsqueda paginada` diff --git a/skills/new-project/templates/CHANGELOG.md.tmpl b/skills/new-project/templates/CHANGELOG.md.tmpl new file mode 100644 index 0000000..9d4f615 --- /dev/null +++ b/skills/new-project/templates/CHANGELOG.md.tmpl @@ -0,0 +1,24 @@ +# Changelog + +Todos los cambios relevantes de este proyecto se documentan en este fichero. + +El formato sigue [*Keep a Changelog*](https://keepachangelog.com/es-ES/1.1.0/) +y el proyecto usa [Versionado Semántico](https://semver.org/lang/es/). + +## [No publicado] + +### Añadido + +- Base documental inicial del proyecto ({{FECHA}}): `AGENTS.md`, `README.md`, + `INSTALL.md`, `CHANGELOG.md`, `TODO.md` y `.gitignore`. + + diff --git a/skills/new-project/templates/INSTALL.md.tmpl b/skills/new-project/templates/INSTALL.md.tmpl new file mode 100644 index 0000000..9175d5c --- /dev/null +++ b/skills/new-project/templates/INSTALL.md.tmpl @@ -0,0 +1,79 @@ +# INSTALL — {{PROYECTO}} + +Instalación, configuración y puesta en marcha de **{{PROYECTO}}**. + +{{DESCRIPCION}} + +## 1. Requisitos + +PENDIENTE: completar con el stack real. + +| Componente | Versión mínima | Notas | +| --- | --- | --- | +| Sistema operativo | PENDIENTE | | +| Lenguaje / runtime | PENDIENTE | | +| Gestor de paquetes | PENDIENTE | | +| Otros | PENDIENTE | | + +Comprueba lo instalado: + +```bash +# PENDIENTE: comandos de comprobación (p. ej. python3 --version) +``` + +## 2. Obtener el código + +```bash +git clone +cd {{PROYECTO}} +``` + +## 3. Dependencias + +```bash +# PENDIENTE: instalación de dependencias +``` + +## 4. Configuración + +PENDIENTE: variables de entorno, ficheros de configuración y secretos. Indica +qué ficheros hay que crear y de dónde copiarlos (`.env.example`, etc.). + +```bash +# PENDIENTE: cp .env.example .env y editar +``` + +| Variable | Obligatoria | Descripción | +| --- | --- | --- | +| PENDIENTE | | | + +## 5. Verificación de la instalación + +```bash +# PENDIENTE: comando de humo que demuestre que funciona +``` + +## 6. Arranque + +```bash +# PENDIENTE: comando de arranque en desarrollo y en producción +``` + +## 7. Actualización + +```bash +git pull +# PENDIENTE: reinstalar dependencias y aplicar migraciones si las hay +``` + +## 8. Desinstalación + +PENDIENTE: qué borrar y qué dejar. + +## 9. Resolución de problemas + +| Síntoma | Causa probable | Solución | +| --- | --- | --- | +| PENDIENTE | | | + +Documento creado el {{FECHA}} por {{AUTOR}}. diff --git a/skills/new-project/templates/README.md.tmpl b/skills/new-project/templates/README.md.tmpl new file mode 100644 index 0000000..1a05b62 --- /dev/null +++ b/skills/new-project/templates/README.md.tmpl @@ -0,0 +1,56 @@ +# {{PROYECTO}} + +{{DESCRIPCION}} + +## Estado + +- Versión: `0.1.0` +- Fecha de creación: {{FECHA}} +- Autor: {{AUTOR}} +- Estado: en desarrollo + +## Requisitos + +PENDIENTE: lenguajes, versiones y dependencias del sistema. Ver `INSTALL.md`. + +## Instalación rápida + +```bash +# PENDIENTE: sustituir por los comandos reales +git clone +cd {{PROYECTO}} +``` + +Instrucciones completas en [`INSTALL.md`](INSTALL.md). + +## Uso + +PENDIENTE: ejemplo mínimo de uso o de arranque. + +```bash +# PENDIENTE +``` + +## Estructura + +```text +{{PROYECTO}}/ +├── AGENTS.md # reglas de trabajo para agentes y colaboradores +├── README.md # este documento +├── INSTALL.md # instalación y dependencias +├── CHANGELOG.md # historial de cambios +└── TODO.md # tareas pendientes +``` + +## Documentación + +| Documento | Contenido | +| --- | --- | +| [`AGENTS.md`](AGENTS.md) | Reglas, flujo de trabajo y convenciones. | +| [`INSTALL.md`](INSTALL.md) | Instalación, configuración y desinstalación. | +| [`CHANGELOG.md`](CHANGELOG.md) | Qué cambió y cuándo. | +| [`TODO.md`](TODO.md) | Qué falta y qué está en curso. | + +## Licencia + +PENDIENTE: indicar licencia del proyecto. diff --git a/skills/new-project/templates/TODO.md.tmpl b/skills/new-project/templates/TODO.md.tmpl new file mode 100644 index 0000000..99e2e61 --- /dev/null +++ b/skills/new-project/templates/TODO.md.tmpl @@ -0,0 +1,21 @@ +# TODO — {{PROYECTO}} + +Tareas pendientes y deuda técnica. Al cerrar una tarea, muévela a *Hecho* y +anota el cambio en `CHANGELOG.md`. + +## En curso + +- [ ] _(nada en curso)_ + +## Pendiente + +- [ ] Definir las **reglas de modelo** del proyecto en `AGENTS.md`. +- [ ] Definir las **reglas de funcionamiento** del proyecto en `AGENTS.md`. +- [ ] Completar los `PENDIENTE` de `README.md` e `INSTALL.md`. +- [ ] Fijar los comandos de verificación reales en `AGENTS.md`. +- [ ] Elegir licencia. + +## Hecho + +- [x] {{FECHA}} — base documental inicial (`AGENTS.md`, `README.md`, `INSTALL.md`, + `CHANGELOG.md`, `TODO.md`, `.gitignore`).